Further Updates to MD
This commit is contained in:
Raven Scott
+38
-38
@@ -11,11 +11,11 @@ Small **monorepo-level** helpers used by npm scripts and maintainers.
|
||||
Root **`pretest`** already enforces this sequence; follow the same order when changing the guest image or stdlib bundles:
|
||||
|
||||
1. **`npm run build -w bare-os-coreutils`** — emit `/bin` sources into **`kernel/bin`** (and man pages).
|
||||
2. **`npm run build -w bare-os-bare-libs**` — esbuild Holepunch **`bare-*`** IIFEs into **`kernel/lib/bare/`**, refresh **`docs/audit/bundle-health.json`**.
|
||||
3. **`npm run bundle:kernel**` (part of **`pretest`**) — concatenate **`kernel/lib/boot/*.js`** + **`kernel/lib/init/fragments/*.js`** + **`kernel/lib/init/init-main.js`** → **`kernel/init.js`**.
|
||||
4. **`node scripts/verify-kernel-seeder-parity.mjs**` — **`kernel/`** must match **`packages/bare-os-seeder/kernel/`** byte-for-byte (rsync or seeder copy after edits).
|
||||
2. **`npm run build -w bare-os-bare-libs`** — esbuild Holepunch **`bare-*`** IIFEs into **`kernel/lib/bare/`**, refresh **`docs/audit/bundle-health.json`**.
|
||||
3. **`npm run bundle:kernel`** (part of **`pretest`**) — concatenate **`kernel/lib/boot/*.js`** + **`kernel/lib/init/fragments/*.js`** + **`kernel/lib/init/init-main.js`** → **`kernel/init.js`**.
|
||||
4. **`node scripts/verify-kernel-seeder-parity.mjs`** — **`kernel/`** must match **`packages/bare-os-seeder/kernel/`** byte-for-byte (rsync or seeder copy after edits).
|
||||
|
||||
**Shortcut:** **`npm run maintainer:sync-kernel-seeder**` runs `**rsync -a --delete**` then **`verify-kernel-seeder-parity`**. `**npm run maintainer:sync-kernel-seeder:bundle**` rebundles **`/boot/init.js`** first. See **`sync-kernel-to-seeder.mjs`**.
|
||||
**Shortcut:** **`npm run maintainer:sync-kernel-seeder`** runs **`rsync -a --delete`** then **`verify-kernel-seeder-parity`**. **`npm run maintainer:sync-kernel-seeder:bundle`** rebundles **`/boot/init.js`** first. See **`sync-kernel-to-seeder.mjs`**.
|
||||
|
||||
If **`verify-kernel-seeder-parity`** fails after bare-libs or init changes, sync the seeder tree before committing (see **`kernel/lib/bare/README.md`** / **`packages/bare-os-bare-libs/README.kernel-lib-bare.md`**).
|
||||
|
||||
@@ -60,31 +60,31 @@ Invoked automatically by:
|
||||
|
||||
**Usage:** `node scripts/vendor-bare-node-shims.mjs` (also **`npm run vendor:bare-node-shims -w bare-os-openssh`**)
|
||||
|
||||
Copies **`bare-net`** and the **`bare-node-*`** packages **`bare-ssh2`** needs from the root **`node_modules`** into **`packages/bare-os-openssh/vendor/bare-node-shims/`** (no nested **`node_modules`**), rewrites **intra-vendor** deps to **`file:../<pkg>`**, and writes **`README.md`**. **Commit** that directory so clones include **`bare-node-net`** etc. even when the npm registry is unreachable. **`bare-os-booter`** depends on those paths via **`file:`**; run `**npm install**` at the root after changing versions so **`package-lock.json`** stays consistent.
|
||||
Copies **`bare-net`** and the **`bare-node-*`** packages **`bare-ssh2`** needs from the root **`node_modules`** into **`packages/bare-os-openssh/vendor/bare-node-shims/`** (no nested **`node_modules`**), rewrites **intra-vendor** deps to **`file:../<pkg>`**, and writes **`README.md`**. **Commit** that directory so clones include **`bare-node-net`** etc. even when the npm registry is unreachable. **`bare-os-booter`** depends on those paths via **`file:`**; run **`npm install`** at the root after changing versions so **`package-lock.json`** stays consistent.
|
||||
|
||||
## `sync-kernel-to-seeder.mjs`
|
||||
|
||||
**Usage:** `npm run maintainer:sync-kernel-seeder` · `npm run maintainer:sync-kernel-seeder:bundle`
|
||||
|
||||
Runs **`rsync -a --delete kernel/ packages/bare-os-seeder/kernel/**` then **`verify-kernel-seeder-parity.mjs`**. **`--bundle`** regenerates **`kernel/init.js`** first. Requires **`rsync`** on **`PATH`**.
|
||||
Runs **`rsync -a --delete kernel/ packages/bare-os-seeder/kernel/`** then **`verify-kernel-seeder-parity.mjs`**. **`--bundle`** regenerates **`kernel/init.js`** first. Requires **`rsync`** on **`PATH`**.
|
||||
|
||||
## `verify-kernel-seeder-parity.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-kernel-seeder-parity.mjs`
|
||||
|
||||
Exits **0** only when **`kernel/`** and **`packages/bare-os-seeder/kernel/`** contain the **same recursive file set** with **byte-identical** contents (full mirror parity, not a spot check on **`init.js`** alone). Requires **`init.js`**, **`lib/init/init-main.js`**, **`lib/init/fragments/*.js`**, **`lib/boot/*.js`**, **`lib/bare/manifest.json`**, **`lib/bare/bare-module-manifest.json`**, and asserts **`kernel/init.js`** matches the bundle recipe via **`scripts/lib/kernel-init-bundle.mjs`**. Every **`kernel/bin/*`** must include **`BARE_OS_BIN_API`**. Invoked from the root **`pretest`** hook after `**npm run build -w bare-os-coreutils`**. **Sync:** `rsync -a --delete kernel/ packages/bare-os-seeder/kernel/` (after **`bundle:kernel`** when **`init.js`** is generated).
|
||||
Exits **0** only when **`kernel/`** and **`packages/bare-os-seeder/kernel/`** contain the **same recursive file set** with **byte-identical** contents (full mirror parity, not a spot check on **`init.js`** alone). Requires **`init.js`**, **`lib/init/init-main.js`**, **`lib/init/fragments/*.js`**, **`lib/boot/*.js`**, **`lib/bare/manifest.json`**, **`lib/bare/bare-module-manifest.json`**, and asserts **`kernel/init.js`** matches the bundle recipe via **`scripts/lib/kernel-init-bundle.mjs`**. Every **`kernel/bin/*`** must include **`BARE_OS_BIN_API`**. Invoked from the root **`pretest`** hook after **`npm run build -w bare-os-coreutils`**. **Sync:** `rsync -a --delete kernel/ packages/bare-os-seeder/kernel/` (after **`bundle:kernel`** when **`init.js`** is generated).
|
||||
|
||||
## `verify-init-bundle-recipe.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-init-bundle-recipe.mjs` (also **`npm run verify:init-bundle`**)
|
||||
|
||||
Fails when **`kernel/init.js`** does not match the bundle recipe (sorted **`kernel/lib/boot/*.js`** + **`kernel/lib/init/fragments/*.js`** + **`kernel/lib/init/init-main.js`**). Shared logic lives in **`scripts/lib/kernel-init-bundle.mjs`**. Also invoked from `**npm run release-checklist`**.
|
||||
Fails when **`kernel/init.js`** does not match the bundle recipe (sorted **`kernel/lib/boot/*.js`** + **`kernel/lib/init/fragments/*.js`** + **`kernel/lib/init/init-main.js`**). Shared logic lives in **`scripts/lib/kernel-init-bundle.mjs`**. Also invoked from **`npm run release-checklist`**.
|
||||
|
||||
## `verify-banned-terminology.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-banned-terminology.mjs`
|
||||
|
||||
Fails when banned governance tokens (**`Wave N**`, `**wave N**`, **`tranche`**, **`mega-phase`**, `**multi-stage` / `multi stage**`) appear in tracked `**md` / `js` / `mjs` / `json`** files (excluding `node_modules`, **`kernel/lib/bare/`** vendored trees, `share/man/man.json`, and this script). Root **`pretest`**.
|
||||
Fails when banned governance tokens (**`Wave N`**, **`wave N`**, **`tranche`**, **`mega-phase`**, `**multi-stage` / `multi stage**`) appear in tracked `**md` / `js` / `mjs` / `json`** files (excluding `node_modules`, **`kernel/lib/bare/`** vendored trees, `share/man/man.json`, and this script). Root **`pretest`**.
|
||||
|
||||
## `bundle-kernel-init.mjs`
|
||||
|
||||
@@ -132,19 +132,19 @@ Ensures [docs/reference/naming-alias-matrix.md](../docs/reference/naming-alias-m
|
||||
|
||||
**Usage:** `node scripts/verify-booter-boot-steps-alignment.mjs`
|
||||
|
||||
Ensures every **`emitBooterBootPhase('…')**` in **`packages/bare-os-booter/index.js`** matches **`BARE_OS_BOOTER_BOOT_STEPS`** in **`packages/bare-os-booter/lib/bare-os-boot-phases.js`** (no drift). Root **`pretest`**.
|
||||
Ensures every **`emitBooterBootPhase('…')`** in **`packages/bare-os-booter/index.js`** matches **`BARE_OS_BOOTER_BOOT_STEPS`** in **`packages/bare-os-booter/lib/bare-os-boot-phases.js`** (no drift). Root **`pretest`**.
|
||||
|
||||
## `verify-runtime-no-incomplete-markers.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-runtime-no-incomplete-markers.mjs`
|
||||
|
||||
Fails on incomplete-runtime markers (**`TODO`**, **`FIXME`**, **`HACK`**, **`XXX`**, or `**throw new Error(\"Not implemented\")**`) in hand-authored **`kernel/init.js`**, **`kernel/lib/init/`**, **`kernel/lib/boot/`**, **`kernel/bin/*.js`**, and **`packages/bare-os-booter/`** (excludes vendored bundles and tests). Optional path prefixes in **[`docs/audit/runtime-marker-excludes.json`](../docs/audit/runtime-marker-excludes.json)** are skipped. Root **`pretest`**.
|
||||
Fails on incomplete-runtime markers (**`TODO`**, **`FIXME`**, **`HACK`**, **`XXX`**, or **`throw new Error(\"Not implemented\")`**) in hand-authored **`kernel/init.js`**, **`kernel/lib/init/`**, **`kernel/lib/boot/`**, **`kernel/bin/*.js`**, and **`packages/bare-os-booter/`** (excludes vendored bundles and tests). Optional path prefixes in **[`docs/audit/runtime-marker-excludes.json`](../docs/audit/runtime-marker-excludes.json)** are skipped. Root **`pretest`**.
|
||||
|
||||
## `verify-bare-imports.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-bare-imports.mjs`
|
||||
|
||||
Forbids **`node:`** in static **`from`**, dynamic `**import()**`, and `**require()**` for **`kernel/init.js`**, **`kernel/lib/init/`**, **`kernel/lib/boot/`** (excluding **`bundles/`** subtree via walk rules), **`packages/bare-os-booter/index.js`**, **`packages/bare-os-booter/lib/**`/*.js`** (skips **`*.node.js`** shims), **`packages/bare-os-protocol/lib/**`/*.js`**, and **`kernel/lib/bare/bundles/*.js`**. Does not scan **`scripts/`** (Node tooling may use **`node:fs`**). Root **`pretest`**.
|
||||
Forbids **`node:`** in static **`from`**, dynamic **`import()`**, and **`require()`** for **`kernel/init.js`**, **`kernel/lib/init/`**, **`kernel/lib/boot/`** (excluding **`bundles/`** subtree via walk rules), **`packages/bare-os-booter/index.js`**, **`packages/bare-os-booter/lib/`**/*.js**` (skips **`*.node.js`** shims), **`packages/bare-os-protocol/lib/`**/*.js**`, and **`kernel/lib/bare/bundles/*.js`**. Does not scan **`scripts/`** (Node tooling may use **`node:fs`**). Root **`pretest`**.
|
||||
|
||||
## `gen-ctx-client-helper.mjs`
|
||||
|
||||
@@ -168,7 +168,7 @@ Validates [docs/schemas/kernel-extension-manifest.schema.json](../docs/schemas/k
|
||||
|
||||
**Usage:** `node scripts/verify-boot-policy-extension-signer-pins.mjs`
|
||||
|
||||
Ensures **`boot.policy`** documents **`extensionSignerPinsV2`**…**`V5`** and **`kernel/lib/init/init-main.js`** still assigns **`BARE_OS_BOOT_POLICY_EXTENSION_SIGNER_PINS_V*_JSON`**. Root **`pretest`**.
|
||||
Ensures **`boot.policy`** documents **`extensionSignerPinsV2`**…`**V5**` and **`kernel/lib/init/init-main.js`** still assigns **`BARE_OS_BOOT_POLICY_EXTENSION_SIGNER_PINS_V*_JSON`**. Root **`pretest`**.
|
||||
|
||||
## `verify-ctx-api-feature-bits.mjs`
|
||||
|
||||
@@ -198,37 +198,37 @@ Static checks for capability wire **v2** (**`kernelCapabilityWords`**): stock ma
|
||||
|
||||
**Usage:** `node scripts/verify-kernel-capabilities-word-6.mjs`
|
||||
|
||||
Asserts **[`docs/reference/feature-roadmap.md`](../docs/reference/feature-roadmap.md)** contains **`## Capability word 6 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
|
||||
Asserts **[`docs/reference/feature-roadmap.md`](../docs/reference/feature-roadmap.md)** contains **`## Capability word 6 checklist (100-item mega kernel)`** with at least **100** numbered table rows. Root **`pretest`**.
|
||||
|
||||
## `verify-kernel-capabilities-word-7.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-kernel-capabilities-word-7.mjs`
|
||||
|
||||
Asserts **`feature-roadmap.md`** contains `**## Capability word 7 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
|
||||
Asserts **`feature-roadmap.md`** contains **`## Capability word 7 checklist (100-item mega kernel)`** with at least **100** numbered table rows. Root **`pretest`**.
|
||||
|
||||
## `verify-kernel-capabilities-word-8.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-kernel-capabilities-word-8.mjs`
|
||||
|
||||
Asserts **`feature-roadmap.md`** contains `**## Capability word 8 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
|
||||
Asserts **`feature-roadmap.md`** contains **`## Capability word 8 checklist (100-item mega kernel)`** with at least **100** numbered table rows. Root **`pretest`**.
|
||||
|
||||
## `verify-kernel-capabilities-word-9.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-kernel-capabilities-word-9.mjs`
|
||||
|
||||
Asserts **`feature-roadmap.md`** contains `**## Capability word 9 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
|
||||
Asserts **`feature-roadmap.md`** contains **`## Capability word 9 checklist (100-item mega kernel)`** with at least **100** numbered table rows. Root **`pretest`**.
|
||||
|
||||
## `verify-kernel-capabilities-word-10.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-kernel-capabilities-word-10.mjs`
|
||||
|
||||
Asserts **`feature-roadmap.md`** contains `**## Capability word 10 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
|
||||
Asserts **`feature-roadmap.md`** contains **`## Capability word 10 checklist (100-item mega kernel)`** with at least **100** numbered table rows. Root **`pretest`**.
|
||||
|
||||
## `verify-kernel-capabilities-word-11.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-kernel-capabilities-word-11.mjs`
|
||||
|
||||
Asserts **`feature-roadmap.md`** contains `**## Capability word 11 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
|
||||
Asserts **`feature-roadmap.md`** contains **`## Capability word 11 checklist (100-item mega kernel)`** with at least **100** numbered table rows. Root **`pretest`**.
|
||||
|
||||
## `gen-posix-dashboard.mjs`
|
||||
|
||||
@@ -252,7 +252,7 @@ Ensures [docs/reference/posix-compliance-matrix.json](../docs/reference/posix-co
|
||||
|
||||
**Usage:** `node scripts/verify-pear-no-static-node-import.mjs`
|
||||
|
||||
Fails on **`from 'node:…'**` static imports, on `**require('node:…')**` / `**import('node:…')**` in those same trees, and on bare `**from 'fs'**` / `**from 'path'**` / `**from 'fs/promises'**` under **`packages/bare-os-booter/index.js`**, **`packages/bare-os-booter/lib/**`/*.js`**, **`packages/bare-os-seeder/index.js`**, and **`packages/bare-os-seeder/lib/**`/*.js`** (excluding **`bare-os-boot-manifest-sig.node.js`** from the walk). Use package **`imports`** aliases `**#host-fs**`, `**#host-path**`, `**#host-fs-promises**` (seeder) instead. Root **`pretest`**.
|
||||
Fails on **`from 'node:…'`** static imports, on **`require('node:…')`** / **`import('node:…')`** in those same trees, and on bare **`from 'fs'`** / **`from 'path'`** / **`from 'fs/promises'`** under **`packages/bare-os-booter/index.js`**, **`packages/bare-os-booter/lib/`**/*.js**`, **`packages/bare-os-seeder/index.js`**, and **`packages/bare-os-seeder/lib/`**/*.js**` (excluding **`bare-os-boot-manifest-sig.node.js`** from the walk). Use package **`imports`** aliases **`#host-fs`**, **`#host-path`**, **`#host-fs-promises`** (seeder) instead. Root **`pretest`**.
|
||||
|
||||
## `verify-ctx-dts.mjs`
|
||||
|
||||
@@ -270,7 +270,7 @@ Scans **`docs/`**, **`handbook/`**, **`developer-guide/`**, **`users-manual/`**,
|
||||
|
||||
**Usage:** `BARE_OS_VALIDATE_MERMAID=1 node scripts/validate-mermaid-syntax.mjs` · workflow **[`.github/workflows/docs-mermaid-smoke.yml`](../.github/workflows/docs-mermaid-smoke.yml)** (**`workflow_dispatch`** + weekly **`cron`**)
|
||||
|
||||
Renders every **```mermaid** fenced block (under **`docs/`**, **`handbook/`**, **`developer-guide/`**, **`users-manual/`**, **`packages/`**, **`scripts/`**, plus root **`README.md`** / **`DOCUMENTATION.md`**) via a one-off `**@mermaid-js/mermaid-cli**` install in a temp directory. **Not** part of root **`pretest`**. Locally **skips** unless **`BARE_OS_VALIDATE_MERMAID=1`**; GitHub Actions sets **`GITHUB_ACTIONS=true`** so scheduled / manual runs validate diagrams without slowing every clone.
|
||||
Renders every **```mermaid** fenced block (under **`docs/`**, **`handbook/`**, **`developer-guide/`**, **`users-manual/`**, **`packages/`**, **`scripts/`**, plus root **`README.md`** / **`DOCUMENTATION.md`**) via a one-off **`@mermaid-js/mermaid-cli`** install in a temp directory. **Not** part of root **`pretest`**. Locally **skips** unless **`BARE_OS_VALIDATE_MERMAID=1`**; GitHub Actions sets **`GITHUB_ACTIONS=true`** so scheduled / manual runs validate diagrams without slowing every clone.
|
||||
|
||||
## `verify-man-coverage.mjs`
|
||||
|
||||
@@ -300,7 +300,7 @@ Ensures **`BARE_OS_CTX_API_VERSION`** and **`BARE_OS_POSIX_PROFILE_VERSION`** ap
|
||||
|
||||
**Usage:** `node scripts/verify-bundle-health.mjs`
|
||||
|
||||
Asserts **[`docs/audit/bundle-health.json`](../docs/audit/bundle-health.json)** (regenerated by **`npm run build -w bare-os-bare-libs**`) matches **`kernel/lib/bare/manifest.json`** and on-disk **`kernel/lib/bare/bundles/*.js`** byte sizes. Detects orphan bundle files. Root **`pretest`**.
|
||||
Asserts **[`docs/audit/bundle-health.json`](../docs/audit/bundle-health.json)** (regenerated by **`npm run build -w bare-os-bare-libs`**) matches **`kernel/lib/bare/manifest.json`** and on-disk **`kernel/lib/bare/bundles/*.js`** byte sizes. Detects orphan bundle files. Root **`pretest`**.
|
||||
|
||||
## `verify-bundle-markers.mjs`
|
||||
|
||||
@@ -310,9 +310,9 @@ Scans vendored **`kernel/lib/bare/bundles/*.js`** for `**TODO` / `FIXME` / `XXX`
|
||||
|
||||
## `sync-holepunch-clones.mjs`
|
||||
|
||||
**Usage:** `node scripts/sync-holepunch-clones.mjs` — chained by **`npm run audit:holepunch-clones**` with **`report-holepunch-lockfile-drift.mjs`** (repo root).
|
||||
**Usage:** `node scripts/sync-holepunch-clones.mjs` — chained by **`npm run audit:holepunch-clones`** with **`report-holepunch-lockfile-drift.mjs`** (repo root).
|
||||
|
||||
Writes **[`docs/audit/holepunch-clone-sync-report.json`](../docs/audit/holepunch-clone-sync-report.json)** (**schema 3**) for every distinct **`package`** name in **`packages/bare-os-booter/lib/bare-module-manifest.json`** (also honors legacy **`name`** / **`packageName`** if present). After **`sync:bare-manifest`** or hand-edits to that JSON, run `**npm run verify:manifest-data**` so **`bare-module-manifest.data.mjs`** stays aligned before `**pear stage**`. Scoped npm names (`**@scope/pkg**`) are mapped to the **`pkg`** directory expected under **`holepunchto_repos`**. Each row records **`cloneExists`**, **`gitHead`**, **`originMainHead`**, **`originMainResolvable`**, **`commitsBehindOriginMain`**, **`commitsAheadOfOriginMain`** (run `**git fetch origin main**` in clones so **`origin/main`** is meaningful), and **`packageJsonVersion`**. The report also includes **`goldenPathRows`** from **`goldenPathRepos`** in **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)** (maintainer review only) and **`goldenPathGaps`** when a golden-path basename has no resolvable clone or **`origin/main`**. The same run appends one NDJSON line per manifest row to **[`docs/audit/holepunch-clone-sync-summary.ndjson`](../docs/audit/holepunch-clone-sync-summary.ndjson)** (**schema 2** lines). Set **`BARE_OS_HOLEPUNCH_CLONES_ROOT`** when your checkout is not **`$HOME/dev/pearcli/holepunch-repos/holepunchto_repos`**. Operator-maintained; not in default CI.
|
||||
Writes **[`docs/audit/holepunch-clone-sync-report.json`](../docs/audit/holepunch-clone-sync-report.json)** (**schema 3**) for every distinct **`package`** name in **`packages/bare-os-booter/lib/bare-module-manifest.json`** (also honors legacy **`name`** / **`packageName`** if present). After **`sync:bare-manifest`** or hand-edits to that JSON, run **`npm run verify:manifest-data`** so **`bare-module-manifest.data.mjs`** stays aligned before **`pear stage`**. Scoped npm names (**`@scope/pkg`**) are mapped to the **`pkg`** directory expected under **`holepunchto_repos`**. Each row records **`cloneExists`**, **`gitHead`**, **`originMainHead`**, **`originMainResolvable`**, **`commitsBehindOriginMain`**, **`commitsAheadOfOriginMain`** (run **`git fetch origin main`** in clones so **`origin/main`** is meaningful), and **`packageJsonVersion`**. The report also includes **`goldenPathRows`** from **`goldenPathRepos`** in **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)** (maintainer review only) and **`goldenPathGaps`** when a golden-path basename has no resolvable clone or **`origin/main`**. The same run appends one NDJSON line per manifest row to **[`docs/audit/holepunch-clone-sync-summary.ndjson`](../docs/audit/holepunch-clone-sync-summary.ndjson)** (**schema 2** lines). Set **`BARE_OS_HOLEPUNCH_CLONES_ROOT`** when your checkout is not **`$HOME/dev/pearcli/holepunch-repos/holepunchto_repos`**. Operator-maintained; not in default CI.
|
||||
|
||||
## `report-holepunch-lockfile-drift.mjs`
|
||||
|
||||
@@ -336,25 +336,25 @@ Fails when **`BARE_OS_POSIX_PROFILE_VERSION`** / **`BARE_OS_POSIX_PROFILE_ID`**
|
||||
|
||||
**Usage:** `node scripts/verify-holepunch-clone-drift.mjs` (root **`pretest`**)
|
||||
|
||||
Runs on every **`pretest`**. For each repo basename listed in **`repos`** inside **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)**, checks that **`origin/main`** is an ancestor of **`HEAD`** (clone not behind remote). With an empty **`repos`** array, the script is a no-op unless **`BARE_OS_HOLEPUNCH_DRIFT_TIER1=1`**, in which case it checks `**tier1Repos[]**` (hypercore, hyperdrive, hyperswarm, protomux, pear, pear-runtime, bare-fs, bare-process) instead. The same file carries **`suggestedCriticalRepos`** and optional **`goldenPathRepos`** (wire stack + runtime hints); copy **`suggestedCriticalRepos`** into **`repos`** when you maintain local clones and want CI to enforce freshness. **`goldenPathRepos`** is informational only (surfaced in **`holepunch-clone-sync-report.json`**). Set **`BARE_OS_HOLEPUNCH_DRIFT_CHECK=0`** to skip the script entirely (e.g. offline sandboxes). **`sync-holepunch-clones.mjs`** echoes **`suggestedCriticalRepos`** into **`holepunch-clone-sync-report.json`** for review.
|
||||
Runs on every **`pretest`**. For each repo basename listed in **`repos`** inside **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)**, checks that **`origin/main`** is an ancestor of **`HEAD`** (clone not behind remote). With an empty **`repos`** array, the script is a no-op unless **`BARE_OS_HOLEPUNCH_DRIFT_TIER1=1`**, in which case it checks **`tier1Repos[]`** (hypercore, hyperdrive, hyperswarm, protomux, pear, pear-runtime, bare-fs, bare-process) instead. The same file carries **`suggestedCriticalRepos`** and optional **`goldenPathRepos`** (wire stack + runtime hints); copy **`suggestedCriticalRepos`** into **`repos`** when you maintain local clones and want CI to enforce freshness. **`goldenPathRepos`** is informational only (surfaced in **`holepunch-clone-sync-report.json`**). Set **`BARE_OS_HOLEPUNCH_DRIFT_CHECK=0`** to skip the script entirely (e.g. offline sandboxes). **`sync-holepunch-clones.mjs`** echoes **`suggestedCriticalRepos`** into **`holepunch-clone-sync-report.json`** for review.
|
||||
|
||||
## `verify-holepunch-clone-freshness.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-holepunch-clone-freshness.mjs` (chained in root **`pretest`** after drift)
|
||||
|
||||
Reads **[`docs/audit/holepunch-freshness-gate.json`](../docs/audit/holepunch-freshness-gate.json)**. Default **`enabled: false**` — the script logs and exits **0** so offline CI never needs local clones. When **`enabled`** is **`true`**, listed repos under **`BARE_OS_HOLEPUNCH_CLONES_ROOT`** (default **`~/dev/pearcli/holepunch-repos/holepunchto_repos`**) that exceed **`maxCommitsBehind`** vs **`origin/main`** cause a **warning**; set **`BARE_OS_HOLEPUNCH_FRESHNESS_STRICT=1`** to **fail** **`pretest`**. Requires `**git fetch origin main`** in each clone for meaningful counts.
|
||||
Reads **[`docs/audit/holepunch-freshness-gate.json`](../docs/audit/holepunch-freshness-gate.json)**. Default **`enabled: false`** — the script logs and exits **0** so offline CI never needs local clones. When **`enabled`** is **`true`**, listed repos under **`BARE_OS_HOLEPUNCH_CLONES_ROOT`** (default **`~/dev/pearcli/holepunch-repos/holepunchto_repos`**) that exceed **`maxCommitsBehind`** vs **`origin/main`** cause a **warning**; set **`BARE_OS_HOLEPUNCH_FRESHNESS_STRICT=1`** to **fail** **`pretest`**. Requires **`git fetch origin main`** in each clone for meaningful counts.
|
||||
|
||||
## `gen-bare-holepunch-catalog.mjs`
|
||||
|
||||
**Usage:** `node scripts/gen-bare-holepunch-catalog.mjs` (also **`npm run gen:bare-catalog**` / `**npm run gen:bare-catalog:check`** from the repo root)
|
||||
**Usage:** `node scripts/gen-bare-holepunch-catalog.mjs` (also **`npm run gen:bare-catalog`** / **`npm run gen:bare-catalog:check`** from the repo root)
|
||||
|
||||
Scans a local Holepunch mirror ( **`HOLEPUNCH_MIRROR`** or default under the repo) for **`holepunchto/bare-*`** repos, merges npm **`latest`** metadata and **[`scripts/bare-catalog-overrides.json`](bare-catalog-overrides.json)**, and writes **[`docs/bare-holepunch-catalog.json`](../docs/bare-holepunch-catalog.json)**. Follow with **`npm run sync:bare-manifest**` and `**npm install`** so **[`packages/bare-os-booter/lib/bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json)** and booter **`optionalDependencies`** stay aligned. CI **`gen:bare-catalog:check`** ensures the committed catalog does not drift.
|
||||
Scans a local Holepunch mirror ( **`HOLEPUNCH_MIRROR`** or default under the repo) for **`holepunchto/bare-*`** repos, merges npm **`latest`** metadata and **[`scripts/bare-catalog-overrides.json`](bare-catalog-overrides.json)**, and writes **[`docs/bare-holepunch-catalog.json`](../docs/bare-holepunch-catalog.json)**. Follow with **`npm run sync:bare-manifest`** and **`npm install`** so **[`packages/bare-os-booter/lib/bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json)** and booter **`optionalDependencies`** stay aligned. CI **`gen:bare-catalog:check`** ensures the committed catalog does not drift.
|
||||
|
||||
## `verify-bundle-throws.mjs`
|
||||
|
||||
**Usage:** `node scripts/verify-bundle-throws.mjs`
|
||||
|
||||
Scans vendored **`kernel/lib/bare/bundles/*.js`** for `**new Error("…")**` string arguments whose message matches incomplete-implementation phrases (`**not implemented**`, `**not yet implemented**`, `**abstract method … not implemented**`), regardless of whether the call is **`throw`**, `**cb(…)**`, or `**emit("error", …)**`. Known-upstream stream and ICO messages are rewritten in **`scripts/sanitize-bare-bundles.mjs`** during **`bare-os-bare-libs`** build; **[`docs/audit/bundle-throw-allowlist.json`](../docs/audit/bundle-throw-allowlist.json)** is **empty** by policy. Root **`pretest`**.
|
||||
Scans vendored **`kernel/lib/bare/bundles/*.js`** for **`new Error("…")`** string arguments whose message matches incomplete-implementation phrases (**`not implemented`**, **`not yet implemented`**, **`abstract method … not implemented`**), regardless of whether the call is **`throw`**, **`cb(…)`**, or **`emit("error", …)`**. Known-upstream stream and ICO messages are rewritten in **`scripts/sanitize-bare-bundles.mjs`** during **`bare-os-bare-libs`** build; **[`docs/audit/bundle-throw-allowlist.json`](../docs/audit/bundle-throw-allowlist.json)** is **empty** by policy. Root **`pretest`**.
|
||||
|
||||
## `verify-kernel-program-doc.mjs`
|
||||
|
||||
@@ -372,7 +372,7 @@ Asserts **`buildKernelProgramProcJson`** returns **`schema`** / **`programVersio
|
||||
|
||||
**Usage:** `node scripts/verify-kernel-program-roadmap-table.mjs`
|
||||
|
||||
Asserts **[`docs/reference/feature-roadmap.md`](../docs/reference/feature-roadmap.md)** contains **`## Kernel program backlog — batch B (100 items)**` with at least **100** numbered table rows. Root **`pretest`**.
|
||||
Asserts **[`docs/reference/feature-roadmap.md`](../docs/reference/feature-roadmap.md)** contains **`## Kernel program backlog — batch B (100 items)`** with at least **100** numbered table rows. Root **`pretest`**.
|
||||
|
||||
## `fuzz-boot-policy-json.mjs`
|
||||
|
||||
@@ -394,7 +394,7 @@ Host-side microbench driver used as a **regression-shaped** workload (not a lite
|
||||
|
||||
## `kernel-vfs-simulated-host-bench.mjs` / `kernel-net-deterministic-bench.mjs` / `kernel-bare-crypto-microbench.mjs`
|
||||
|
||||
Single-purpose host benchmarks: deterministic VFS-shaped CPU loop (**`kernel-vfs-simulated-host-bench.mjs`** output `**schema: 2**`: warm **`/lib/bare`** path classification), socket-bridge readiness sketch for DGRAM/TCP (**`kernel-net-deterministic-bench.mjs`**, `**schema: 2**`), and SHA-256 regression loop via Node **`crypto`**. Also surfaced under **`kernel-microbench.mjs`** suites **`vfs`** / **`crypto`**.
|
||||
Single-purpose host benchmarks: deterministic VFS-shaped CPU loop (**`kernel-vfs-simulated-host-bench.mjs`** output **`schema: 2`**: warm **`/lib/bare`** path classification), socket-bridge readiness sketch for DGRAM/TCP (**`kernel-net-deterministic-bench.mjs`**, **`schema: 2`**), and SHA-256 regression loop via Node **`crypto`**. Also surfaced under **`kernel-microbench.mjs`** suites **`vfs`** / **`crypto`**.
|
||||
|
||||
## `kernel-program-benchmark-harness.mjs`
|
||||
|
||||
@@ -414,15 +414,15 @@ Maintainer helper for release/staging workflows (see script header for intended
|
||||
|
||||
## Root `npm run test:bare`
|
||||
|
||||
Runs **`bare-os-protocol`** tests, **`bare-os-booter`** **`test:bare`** (**`brittle-bare`** identity slice), and **`bare-os-seeder`** `**node --test**` helpers. Full workspace coverage remains `**npm test**` (includes **`brittle-node`** booter harness + coreutils).
|
||||
Runs **`bare-os-protocol`** tests, **`bare-os-booter`** **`test:bare`** (**`brittle-bare`** identity slice), and **`bare-os-seeder`** **`node --test`** helpers. Full workspace coverage remains **`npm test`** (includes **`brittle-node`** booter harness + coreutils).
|
||||
|
||||
## Maintainer: `pretest` generator runbook
|
||||
|
||||
Root **`npm run pretest**` is the canonical doc/code gate. Run it before pushing when you touch booter **`ctx`**, POSIX artifacts, bundles, or the kernel image. Order (mirrors [`package.json`](../package.json) **`pretest`**):
|
||||
Root **`npm run pretest`** is the canonical doc/code gate. Run it before pushing when you touch booter **`ctx`**, POSIX artifacts, bundles, or the kernel image. Order (mirrors [`package.json`](../package.json) **`pretest`**):
|
||||
|
||||
1. **`npm run build -w bare-os-coreutils**` — Refreshes staged **`kernel/bin`** and **`kernel/share/man/man.json`** from **`packages/bare-os-coreutils`** (`ensure-man-pages` + `build.mjs`).
|
||||
2. **`npm run build -w bare-os-bare-libs**` — Rebuilds **`kernel/lib/bare/bundles/*.js`** and related audit JSON; invokes **`sanitize-bare-bundles`** as configured in that workspace.
|
||||
3. **`npm run bundle:kernel**` — **`scripts/bundle-kernel-init.mjs`** → **`kernel/init.js`** from **`kernel/lib/boot/*.js`** + **`kernel/lib/init/init-main.js`**.
|
||||
1. **`npm run build -w bare-os-coreutils`** — Refreshes staged **`kernel/bin`** and **`kernel/share/man/man.json`** from **`packages/bare-os-coreutils`** (`ensure-man-pages` + `build.mjs`).
|
||||
2. **`npm run build -w bare-os-bare-libs`** — Rebuilds **`kernel/lib/bare/bundles/*.js`** and related audit JSON; invokes **`sanitize-bare-bundles`** as configured in that workspace.
|
||||
3. **`npm run bundle:kernel`** — **`scripts/bundle-kernel-init.mjs`** → **`kernel/init.js`** from **`kernel/lib/boot/*.js`** + **`kernel/lib/init/init-main.js`**.
|
||||
4. **`scripts/gen-kernel-extensions-index.mjs`** — Regenerates **`docs/reference/kernel-extensions-generated-toc.md`**.
|
||||
5. **`scripts/verify-kernel-seeder-parity.mjs`** — **`kernel/`** must match **`packages/bare-os-seeder/kernel/`** (rsync after kernel edits).
|
||||
6. **Policy / terminology / roadmap verifiers** — Banned tokens, naming matrix, feature-roadmap canonical JSON, giant-phase guard, runtime incomplete-marker scan, bare imports, boot-step alignment.
|
||||
@@ -434,8 +434,8 @@ Root **`npm run pretest**` is the canonical doc/code gate. Run it before pushing
|
||||
12. **Kernel program doc / proc schema / roadmap table verifiers**.
|
||||
13. **`scripts/verify-pear-no-static-node-import.mjs`**.
|
||||
14. **`scripts/gen-posix-dashboard.mjs`** + **`verify-posix-dashboard.mjs`** + **`verify-posix-profile-triplet.mjs`** + **`verify-posix-compliance-matrix.mjs`**.
|
||||
15. **`scripts/verify-holepunch-clone-drift.mjs`** — No-op when **`holepunch-drift-repos.json`** `**repos[]`** is empty; optional release gate when populated.
|
||||
16. **`scripts/verify-holepunch-clone-freshness.mjs`** — Optional lag gate from **`holepunch-freshness-gate.json`** (`**enabled: false**` by default); strict mode via **`BARE_OS_HOLEPUNCH_FRESHNESS_STRICT=1`**.
|
||||
15. **`scripts/verify-holepunch-clone-drift.mjs`** — No-op when **`holepunch-drift-repos.json`** **`repos[]`** is empty; optional release gate when populated.
|
||||
16. **`scripts/verify-holepunch-clone-freshness.mjs`** — Optional lag gate from **`holepunch-freshness-gate.json`** (**`enabled: false`** by default); strict mode via **`BARE_OS_HOLEPUNCH_FRESHNESS_STRICT=1`**.
|
||||
17. **`npm run smoke:bare-manifest`** — Manifest import smoke.
|
||||
18. **`npm run smoke:agent-web-fetch:bare`** (optional) — Runs [`scripts/smoke-agent-web-fetch-bare.mjs`](smoke-agent-web-fetch-bare.mjs) under the **Bare** runtime: exercises **`lib/agent-web-fetch.js`** timeout/abort contract and a live **`https://example.com`** fetch when network is available.
|
||||
19. **`npm run sample:agent-workspace`** — Runs [`print-agent-workspace-sample.mjs`](print-agent-workspace-sample.mjs): prints a concatenated **agent workspace** system prompt sample from [`packages/bare-os-coreutils/share/agent-workspace/`](../packages/bare-os-coreutils/share/agent-workspace/) (host Node; no booter).
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
#!/usr/bin/env node
|
||||
import { readdir, readFile, writeFile } from 'node:fs/promises'
|
||||
import path from 'node:path'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import process from 'node:process'
|
||||
import { marked } from 'marked'
|
||||
|
||||
const __filename = fileURLToPath(import.meta.url)
|
||||
const __dirname = path.dirname(__filename)
|
||||
const repoRoot = path.resolve(__dirname, '..')
|
||||
|
||||
const args = new Set(process.argv.slice(2))
|
||||
const shouldWrite = args.has('--write')
|
||||
|
||||
const skipDirs = new Set(['.git', 'node_modules'])
|
||||
|
||||
const fixers = [
|
||||
// `**token**` -> **`token`**
|
||||
[/(?<!`)`\*\*((?:(?!\*\*)[^`\n])+)\*\*`/g, '**`$1`**'],
|
||||
// `**token`** -> **`token`**
|
||||
[/(?<!`)`\*\*((?:(?!`\*\*)[^`\n])+?)`\*\*/g, '**`$1`**'],
|
||||
// **`token**` -> **`token`**
|
||||
[/\*\*`((?:(?!\*\*`)[^`\n])+)\*\*`/g, '**`$1`**'],
|
||||
// **`[link](path)`** -> **[link](path)**
|
||||
[/\*\*`\[([^\]\n]+)\]\(([^)\n]+)\)`\*\*/g, '**[$1]($2)**'],
|
||||
// `**[link](path)**` -> **[link](path)**
|
||||
[/`\*\*\[([^\]\n]+)\]\(([^)\n]+)\)\*\*`/g, '**[$1]($2)**'],
|
||||
// `**[ctx` API changelog](path)** -> **[ctx API changelog](path)**
|
||||
[/`\*\*\[([^\]`\n]+)`([^\]\n]*)\]\(([^)\n]+)\)\*\*`/g, '**[$1$2]($3)**'],
|
||||
// **`[ctx API changelog](path)`** -> **[ctx API changelog](path)**
|
||||
[/\*\*`\[([^\]\n]+)\]\(([^)\n]+)\)`\*\*/g, '**[$1]($2)**']
|
||||
]
|
||||
|
||||
const suspiciousPatterns = [
|
||||
/(?<!`)`\*\*((?:(?!\*\*)[^`\n])+)\*\*`/,
|
||||
/(?<!`)`\*\*((?:(?!`\*\*)[^`\n])+?)`\*\*/,
|
||||
/\*\*`((?:(?!\*\*`)[^`\n])+)\*\*`/
|
||||
]
|
||||
|
||||
async function collectMarkdownFiles(dir) {
|
||||
const entries = await readdir(dir, { withFileTypes: true })
|
||||
const files = []
|
||||
for (const entry of entries) {
|
||||
const full = path.join(dir, entry.name)
|
||||
if (entry.isDirectory()) {
|
||||
if (skipDirs.has(entry.name)) continue
|
||||
files.push(...(await collectMarkdownFiles(full)))
|
||||
continue
|
||||
}
|
||||
if (entry.isFile() && entry.name.endsWith('.md')) files.push(full)
|
||||
}
|
||||
return files
|
||||
}
|
||||
|
||||
function renderedTextContainsDoubleAsterisk(markdown) {
|
||||
const html = marked.parse(markdown)
|
||||
const text = String(html).replace(/<[^>]+>/g, ' ')
|
||||
return text.includes('**')
|
||||
}
|
||||
|
||||
function applyFixers(markdown) {
|
||||
let out = markdown
|
||||
for (const [pattern, replacement] of fixers) {
|
||||
out = out.replace(pattern, replacement)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
function hasSuspiciousSourcePattern(markdown) {
|
||||
return suspiciousPatterns.some((pattern) => pattern.test(markdown))
|
||||
}
|
||||
|
||||
const files = await collectMarkdownFiles(repoRoot)
|
||||
const changed = []
|
||||
const flagged = []
|
||||
|
||||
for (const filePath of files) {
|
||||
const original = await readFile(filePath, 'utf8')
|
||||
const fixed = applyFixers(original)
|
||||
const hasRenderedDoubleAsterisk = renderedTextContainsDoubleAsterisk(fixed)
|
||||
const hasSuspiciousPatternRemaining = hasSuspiciousSourcePattern(fixed)
|
||||
|
||||
if (shouldWrite && fixed !== original) {
|
||||
await writeFile(filePath, fixed, 'utf8')
|
||||
changed.push(path.relative(repoRoot, filePath))
|
||||
}
|
||||
|
||||
if (hasRenderedDoubleAsterisk && hasSuspiciousPatternRemaining) {
|
||||
flagged.push(path.relative(repoRoot, filePath))
|
||||
}
|
||||
}
|
||||
|
||||
if (changed.length) {
|
||||
console.log(`Updated ${changed.length} markdown files:`)
|
||||
for (const file of changed) console.log(`- ${file}`)
|
||||
}
|
||||
|
||||
if (flagged.length) {
|
||||
console.log('\nRendered output plus suspicious source pattern still found in:')
|
||||
for (const file of flagged) console.log(`- ${file}`)
|
||||
console.log('\nInspect these manually or extend fixers in scripts/fix-markdown-rendered-asterisks.mjs.')
|
||||
process.exitCode = 1
|
||||
} else {
|
||||
console.log('No rendered literal "**" remains after checks.')
|
||||
}
|
||||
Reference in New Issue
Block a user