bare-operating-system/docs/reference/package-bare-os-seeder.md

Package: bare-os-seeder

Former DOCUMENTATION.md §11. Reference index →

11. Package: bare-os-seeder

11.1 packages/bare-os-seeder/package.json

• main — ./index.js
• scripts.start / dev — bare index.js (Pear/Bare entry)
• dependencies — bare-os-protocol (workspace *), bare-fs, bare-path, b4a, compact-encoding, corestore, hyperdrive, hyperswarm, protomux, safety-catch
• engines.bare — >=2.0.0
• pear.name — bare-os-seeder
• pear.stage.include — ../../node_modules (hoisted workspace deps) and kernel (vendored tree under the package). The seeder reads kernel/ only at runtime via **readdir/readFile** (no static imports), so Pear’s static analyzer would otherwise omit it from released bundles — kernel directory missing at runtime means pear stage did not ship kernel/; fix by keeping kernel in include and re-staging after rsync / verify-kernel-seeder-parity. With pear stage --compact, include is required for non-traced assets (Pear configuration uses the heading “includes”; the manifest field is include).
• pear.stage.ignore — .git, test, coverage, .DS_Store, node_modules/.bin, node_modules/.package-lock.json
• imports — #host-fs, #host-path, #host-fs-promises (preferred in first-party sources); legacy keys fs, fs/promises, path, url, node:url — Bare vs Node shims

11.2 packages/bare-os-seeder/lib/paths.js

Pear-safe path resolution (same idea as Holepunch pear-rti MOUNT / swapDir):

• packageRootDir(metaUrl) — If import.meta.url is file:, path.dirname(fileURLToPath(...)) via node:url. If pear: / other, tries RTI.mount, Pear.config.swapDir, **Pear.app.dir / Pear.config.dir**, RTI.dir, then **process.cwd()** (with **bare-os os.cwd()** fallback when **process.cwd()** is empty) — first directory that contains a kernel/ subfolder wins; otherwise the first candidate (see paths.js).
• defaultKernelRoot(pkgRoot, metaUrl) — BARE_OS_KERNEL_ROOT or path.join(pkgRoot, 'kernel') (vendored copy under the seeder package for Pear bundles).
• defaultSeedCorestorePath(pkgRoot, metaUrl) — BARE_OS_SEED_STORE or path.join(hostDataRoot(), 'corestore', 'seeder') where hostDataRoot() is BARE_OS_HOST_DATA (resolved) or ~/.bare-os. Signature keeps pkgRoot / metaUrl for callers; defaults do not use them.

11.3 packages/bare-os-seeder/index.js

Paths — Uses ./lib/paths.js for _pkg, corestorePath(), and kernelRoot (no fileURLToPath(import.meta.url) on the hot path for pear:).

stageKernelTree(drive, kernelRoot)

• Recursive walk(rel) using #host-fs-promises (readdir + readFile).
• Drive path mapping:
  • init.js → /boot/init.js
  • bin/<name> → /bin/<name> (POSIX slashes)
  • etc/... → /etc/...
  • Any other file → /<subRel> with slashes normalized
• drive.put(drivePath, b4a.from(raw)) for each file.

main()

1. Optional console.clear().
2. maybeBuildCoreutilsFromSource() — only when import.meta.url starts with file: (Node / node index.js): dynamic import of ../bare-os-coreutils/build.mjs and await build(). Under Pear (pear:// URLs) this is skipped; the bundle must include an up-to-date vendored kernel/ (run npm run build -w bare-os-coreutils before pear run).
3. Corestore(corestorePath(), bareOsCorestoreConstructOpts()) — lib/corestore-opts.js forwards treeCache (maxSize: 8192) to Hypercore 7.12+ storage — then Hyperdrive(store), ready().
4. stageKernelTree.
5. localRAM = Map, buildMbr(drive.key), localRAM.set(0, mbr).
6. Hyperswarm, on connection: Protomux(socket), setupSeedChannel(mux, localRAM, stream => drive.replicate(stream), { manifestPaths, searchMaxMatches }) — manifestPaths lists every staged drive path so peers can search and RPC against the live manifest.
7. swarm.join(topicKey()), swarm.join(drive.discoveryKey), flush().
8. Logs topic prefix hex, full drive key hex, Corestore path.

Entry: main().catch(safetyCatch).