bare-operating-system/scripts

scripts

Small monorepo-level helpers used by npm scripts and maintainers.

Documentation hub: User manual · Handbook · docs/reference.

Maintainer build order (kernel image + parity)

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/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).

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).

Seeder host logging: packages/bare-os-seeder uses lib/host-logger.mjs. Set BARE_OS_SEED_LOG_LEVEL (debug, info, warn, error) and optional BARE_OS_SEED_LOG_FORMAT=ndjson (or json) for one JSON object per line on stdout—useful in CI and log shippers. See handbook ch.7.

---

On this page

Verifiers and generators are listed in the order they typically appear in root pretest. Jump to a script by searching this file for its filename.

---

ensure-pear-node-modules.mjs

Usage: node scripts/ensure-pear-node-modules.mjs packages/<app>

Recreates packages/<app>/node_modules by symlinking each top-level package from the repo root node_modules (matching npm’s flat hoist). Pear’s dev bundle often does not resolve a single nested node_modules tree correctly; this makes pear run --dev . reliable after npm ci at the root.

Invoked automatically by:

• Root npm run os:seeder / npm run os:booter
• Package start / dev / pear:dev scripts where configured

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 set of files with identical contents. Invoked from the root pretest hook after npm run build -w bare-os-coreutils.

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/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.

bundle-kernel-init.mjs

Usage: node scripts/bundle-kernel-init.mjs (also npm run bundle:kernel)

Concatenates sorted kernel/lib/boot/*.js + kernel/lib/init/init-main.js → kernel/init.js. Run after editing boot fragments; root pretest invokes it automatically.

verify-feature-roadmap-canonical.mjs

Usage: node scripts/verify-feature-roadmap-canonical.mjs

Ensures docs/data/feature-roadmap-canonical.json aligns with the batch B table in feature-roadmap.md. Root pretest.

verify-no-new-giant-phase-identifiers.mjs

Usage: node scripts/verify-no-new-giant-phase-identifiers.mjs

Blocks new giant_phase / giantPhase identifiers outside an explicit allowlist (legacy proc compatibility only). Root pretest.

gen-kernel-extensions-index.mjs

Usage: node scripts/gen-kernel-extensions-index.mjs

Regenerates docs/reference/kernel-extensions-generated-toc.md. Root pretest.

integration-lab-smoke.mjs

Usage: node scripts/integration-lab-smoke.mjs

Developer-only smoke path for local mirror plus synthetic peer checks; extend with Holepunch fixtures (see developer guide).

benchmark-boot-sketch.mjs

Usage: node scripts/benchmark-boot-sketch.mjs

Appends one NDJSON trend row (schema: 1) to BARE_OS_BENCHMARK_TREND_NDJSON or $TMPDIR/bare-os-benchmark-trend.ndjson.

verify-naming-alias-matrix.mjs

Usage: node scripts/verify-naming-alias-matrix.mjs

Ensures docs/reference/naming-alias-matrix.md lists canonical ctx boot-hook names and boot-policy key aliases. Root pretest.

verify-booter-boot-steps-alignment.mjs

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.

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 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.

gen-ctx-client-helper.mjs

Usage: node scripts/gen-ctx-client-helper.mjs

Writes docs/reference/ctx-client-helper.generated.ts with BARE_OS_CTX_API_CLIENT_VERSION, DTS path hints, and schema pointers. Root pretest.

sanitize-bare-bundles.mjs

Usage: imported from packages/bare-os-bare-libs/build.mjs (not run standalone in CI).

Post-processes esbuild IIFE output so verify-bundle-markers / verify-bundle-throws stay green and bareDev.js uses bare-* instead of node: requires.

verify-extension-manifest-schema.mjs

Usage: node scripts/verify-extension-manifest-schema.mjs

Validates docs/schemas/kernel-extension-manifest.schema.json root shape. Root pretest.

verify-boot-policy-extension-signer-pins.mjs

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.

verify-ctx-api-feature-bits.mjs

Usage: node scripts/verify-ctx-api-feature-bits.mjs

Checks that packages/bare-os-booter/lib/bare-os-ctx-api.js documents a BARE_OS_CTX_API_VERSION that matches the contract surface (semver discipline) and that stock kernel feature words (BARE_OS_KERNEL_FEATURES_STOCK_WORD_*) in bare-os-protocol stay referenced from the booter (including kernelCapabilityWords / ctx maps for wire v2). Invoked from the root pretest hook.

verify-kernel-capabilities-contract.mjs

Usage: node scripts/verify-kernel-capabilities-contract.mjs

Static checks for capability wire v2 (kernelCapabilityWords): stock mask constants in kernel-feature-bits.js, seed capabilities in channel.js, booter index.js strict checks, boot policy schema keys, kernel init.js enforcement, and seed-rpc-methods.js wiring. Root pretest.

verify-kernel-capabilities-word-6.mjs

Usage: node scripts/verify-kernel-capabilities-word-6.mjs

Asserts 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.

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.

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.

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.

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.

gen-posix-dashboard.mjs

Usage: node scripts/gen-posix-dashboard.mjs

Writes docs/reference/posix-dashboard.md from posix-compliance-matrix.json. Root pretest.

verify-posix-dashboard.mjs

Usage: node scripts/verify-posix-dashboard.mjs

Fails when the dashboard is stale relative to the matrix. Root pretest.

verify-posix-compliance-matrix.mjs

Usage: node scripts/verify-posix-compliance-matrix.mjs

Ensures docs/reference/posix-compliance-matrix.json profileId matches BARE_OS_POSIX_PROFILE_ID in the protocol package, and kernel/etc/bare-os/syscalls.example.json ctxApiVersion matches BARE_OS_CTX_API_VERSION. Root pretest.

verify-pear-no-static-node-import.mjs

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.

verify-ctx-dts.mjs

Usage: node scripts/verify-ctx-dts.mjs

Ensures bare-os-ctx.d.ts lists documented ctx fields (including bareOsAdvertisedKernelCapabilityWords / bareOsSeedKernelCapabilityWords, Bare runtime semver, protocol/Pear runtime semver, subprocess snapshot, profile reload, delegate fairness, IPC audit, Pear / bundlebee / diagnostics / hrpc / structured-clone / wave9–11 stubs, …) that exist in packages/bare-os-booter/index.js. Root pretest.

verify-doc-links.mjs

Usage: node scripts/verify-doc-links.mjs

Scans docs/, handbook/, developer-guide/, and scripts/*.md for relative .md links and fails when the target file is missing. Root pretest.

verify-man-coverage.mjs

Usage: node scripts/verify-man-coverage.mjs

Asserts every Tier-1 name in packages/bare-os-coreutils/lib/commands.mjs has a matching name entry in kernel/share/man/man.json. Root pretest.

verify-compat-matrix.mjs

Usage: node scripts/verify-compat-matrix.mjs

Checks docs/reference/compatibility-matrix.md lists the current BARE_OS_CTX_API_VERSION, BARE_OS_KERNEL_FEATURE_BITS_DOC, BARE_OS_LIFECYCLE_SCHEMA_VERSION, and mentions bits5 … bits10. Root pretest.

verify-doc-contracts.mjs

Usage: node scripts/verify-doc-contracts.mjs

Ensures BARE_OS_CTX_API_VERSION and BARE_OS_POSIX_PROFILE_VERSION appear in the compatibility matrix and declared POSIX profile doc, and that /proc/bare_os/syscalls.json schemaVersion matches kernel/etc/bare-os/syscalls.example.json and docs/schemas/bare-os-syscalls.schema.json. Root pretest (after verify-compat-matrix).

verify-bundle-health.mjs

Usage: node scripts/verify-bundle-health.mjs

Asserts 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

Usage: node scripts/verify-bundle-markers.mjs

Scans vendored kernel/lib/bare/bundles/*.js for TODO / FIXME / XXX / NOT_IMPLEMENTED / ###TODO### unless the basename is listed in docs/audit/bundle-marker-allowlist.json. Complements verify-runtime-no-incomplete-markers.mjs (hand-authored sources only). Root pretest.

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).

Writes docs/audit/holepunch-clone-sync-report.json 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 (run git fetch origin main in clones so origin/main is meaningful), and packageJsonVersion. The same run appends one NDJSON line per manifest row to docs/audit/holepunch-clone-sync-summary.ndjson (machine-readable delta feed; commit or regenerate at release). 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

Usage: npm run audit:holepunch-clones (includes this step) or node scripts/report-holepunch-lockfile-drift.mjs

Compares hoisted package-lock.json versions (node_modules/<pkg>) against lockfilePackages in docs/audit/holepunch-drift-repos.json and local clone package.json versions. Writes docs/audit/holepunch-lockfile-drift.json and holepunch-lockfile-drift-summary.ndjson. Informational only (not a failing CI gate).

audit-placeholder-baseline.mjs

Usage: npm run audit:placeholder-baseline

Emits docs/audit/placeholder-baseline-scan.json — TODO/stub-phrase sweep over first-party kernel, booter, protocol, and coreutils src trees (excludes vendored bundles).

verify-posix-profile-triplet.mjs

Usage: root pretest

Fails when BARE_OS_POSIX_PROFILE_VERSION / BARE_OS_POSIX_PROFILE_ID diverge between bare-os-posix-profile.js, POSIX_DECLARED_PROFILE.md, and posix-compliance-matrix.json, or when the matrix note omits the profile version string.

verify-holepunch-clone-drift.mjs

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, checks that origin/main is an ancestor of HEAD (clone not behind remote). With an empty repos array, the script is a no-op. The same file carries suggestedCriticalRepos (wire stack hints); copy those into repos when you maintain local clones and want CI to enforce freshness. 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.

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)

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, and writes 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 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 is empty by policy. Root pretest.

verify-kernel-program-doc.mjs

Usage: node scripts/verify-kernel-program-doc.mjs

Ensures developer-guide/kernel-program.md exists and references the 100-item program, kernel_program proc path, and operatorSketches. Root pretest.

verify-kernel-program-proc-schema.mjs

Usage: node scripts/verify-kernel-program-proc-schema.mjs

Asserts buildKernelProgramProcJson returns schema / programVersion matching KERNEL_PROGRAM_PROC_SCHEMA / KERNEL_PROGRAM_PROC_VERSION and that an operatorSketches object is present. Root pretest.

verify-kernel-program-roadmap-table.mjs

Usage: node scripts/verify-kernel-program-roadmap-table.mjs

Asserts 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

Usage: node scripts/fuzz-boot-policy-json.mjs

Host-side noise generator for JSON.parse resilience; does not load the stock kernel.

kernel-program-release-gate.mjs

Usage: node scripts/kernel-program-release-gate.mjs --baseline a.json --current b.json [--max-regression-pct 10]

Compares bootMs fields from two benchmark JSON files; exits 1 when regression exceeds the threshold.

kernel-microbench.mjs

Usage: node scripts/kernel-microbench.mjs [--list] [--suite boot|vfs|crypto|syscall] [--all]

Host-side microbench driver used as a regression-shaped workload (not a literal cold-boot timer). The boot suite prints JSON with bootMs suitable for kernel-program-release-gate.mjs. The vfs suite adds warmReplicationPathClassify (synthetic /bin / /lib/bare path classification). Example baseline fixture: fixtures/kernel-microbench-release-gate-baseline.example.json.

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.

kernel-program-benchmark-harness.mjs

Usage: node scripts/kernel-program-benchmark-harness.mjs [--list|--help|--sample-boot-ms N]

Synthetic bootMs JSON for kernel-program-release-gate.mjs fixtures when you need a deterministic sample without running kernel-microbench.mjs.

validate-example-schemas.mjs

Usage: node scripts/validate-example-schemas.mjs

Validates representative JSON under kernel/etc/bare-os/ (e.g. boot.policy.example.json, boot-trace and telemetry samples, otel-jsonl.example.json) against docs/schemas/ using Ajv draft 2020-12. Invoked from the root pretest hook after verify-ctx-api-feature-bits.mjs.

stage-release.sh

Maintainer helper for release/staging workflows (see script header for intended use).

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).

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 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.
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.
7. scripts/gen-ctx-client-helper.mjs — Regenerates the TS helper when BARE_OS_CTX_API_VERSION changes (packages/bare-os-booter/lib/bare-os-ctx-api.js).
8. Extension manifest + boot policy + capability contract verifiers — verify-extension-manifest-schema, signer pins, verify-ctx-api-feature-bits, verify-kernel-capabilities-contract.mjs, capability-word 6–11 table depth scripts, verify-ctx-dts.mjs.
9. scripts/validate-example-schemas.mjs — Ajv check for kernel/etc/bare-os/*.example.json vs docs/schemas/.
10. Doc link + man coverage + compatibility matrix + doc contracts.
11. Bundle health / markers / throws — Upstream bundle hygiene gates.
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. npm run smoke:bare-manifest — Manifest import smoke.

Commit expectation: check in every regenerated artifact pretest produces (kernel init bundle, seeder mirror, generated markdown/JSON, dashboard) in the same change set as the source edit.

See also

• Root README.md — Pear + workspaces note
• Handbook — Building and releasing