bare-operating-system/docs/reference/repo-layout-and-root.md

Repository layout and root metadata

Former monolith DOCUMENTATION.md §§1–8. Reference index →

1. Repository tree (source only)

bare-operating-system/
├── package.json                 # Root workspace manifest
├── package-lock.json            # Locked dependency tree (npm, all workspaces)
├── README.md                    # User-facing overview and doc map
├── DOCUMENTATION.md             # Stub → docs/reference (former monolith)
├── docs/
│   ├── README.md                # Docs hub (reference + themes + catalog)
│   ├── bare-holepunch-catalog.json
│   ├── reference/               # File-level reference; index: docs/reference/README.md
│   └── themes/
├── handbook/                    # Narrative handbook (chapters + diagrams)
│   ├── README.md                # Index + links to chapters
│   ├── 00-preface.md, 01-introduction.md … 10-manpages-and-online-help.md
├── developer-guide/             # How-to: in-image JS, ctx, coreutils, testing
│   ├── README.md                # Index + reading order
│   ├── 01-two-runtimes-host-vs-image.md … 12-bare-modules-and-pear-ecosystem.md
├── LICENSE                      # Apache-2.0 notice (HoneyPeer, LLC)
├── patches/                     # patch-package deltas (applied post-install; see § patches below)
├── .gitignore                   # Ignore rules
├── .prettierrc                  # Prettier formatting defaults
├── .github/
│   └── workflows/
│       └── ci.yml               # GitHub Actions CI
├── kernel/                      # Files staged into the system Hyperdrive
│   ├── init.js
│   ├── bin/                     # Tier-1 utilities (built from bare-os-coreutils)
│   ├── lib/bare/                # Optional ctx.bare drive bundles + manifest (bare-os-bare-libs)
│   └── etc/
│       └── os-release
└── packages/
    ├── bare-os-protocol/        # Shared protocol + MBR + seed channel
    │   ├── package.json
    │   ├── index.js
    │   ├── constants.js
    │   ├── test.js
    │   └── lib/
    │       ├── messages.js
    │       ├── channel.js
    │       └── kernel-feature-bits.js
    ├── bare-os-bare-libs/       # esbuild → kernel/lib/bare/bundles + manifest.json (seeder mirror)
    │   ├── package.json
    │   └── build.mjs
    ├── bare-os-coreutils/       # Sources + build → kernel/bin/* and seeder copy
    │   ├── package.json
    │   ├── build.mjs
    │   ├── lib/runtime.js
    │   ├── lib/sed-engine.js, lib/awk-engine.js   ← prepended for sed/awk (see build preamble)
    │   └── src/*.js
    ├── bare-os-seeder/         # Publishes OS drive + MBR
    │   ├── package.json
    │   ├── index.js
    │   ├── kernel/              # Vendored for Pear (sync from repo kernel/)
    │   └── lib/
    │       └── paths.js
    └── bare-os-booter/         # Boots from swarm peers only (TTY splash + timeout)
        ├── package.json
        ├── CHANGELOG.md            # ctx API version history
        ├── index.js
        ├── test.js
        └── lib/
            ├── paths.js
            ├── swarm-disk.js
            ├── kernel-runner.js
            ├── bare-os-abort.js
            ├── bare-os-http-policy.js
            ├── bare-os-ctx-api.js
            ├── bare-os-ctx-bare.js   # ctx.bare host import + drive bundle merge
            ├── bare-module-manifest.json
            ├── bare-os-ctx.d.ts
            ├── git-cli.js              # isomorphic-git; booter delegates `git`
            ├── curl-cli.js             # Fetch HTTP client; booter delegates `curl`
            ├── wget-cli.js             # Fetch downloads; booter delegates `wget`
            ├── identity-account.js   # Ed25519 account blob (bare-crypto PBKDF2 + ChaCha20-Poly1305)
            ├── identity-session.js   # Guest vs unlocked env, vault save, ctx hooks
            ├── vfs.js                # Two-drive path routing ($HOME → personal drive)
            ├── shell.js              # POSIX-ish line parser + builtins (incl. login/logout)
            ├── fish-readline.js      # TTY editor; per-USER REPL history; tab menu + ghost
            ├── completion-engine.js  # Async completion: man/PATH/VFS/proc, ranking, registry
            ├── repl-session.js
            └── …

---

2. Root: package.json

• name — bare-operating-system
• private — true — not published as a single npm package
• type — module — ESM
• workspaces — ["packages/*"] — npm workspaces (protocol, coreutils, seeder, booter, …)
• scripts.pretest — Runs bare-os-coreutils + bare-os-bare-libs builds, kernel/seeder parity, smoke:bare-manifest
• scripts.gen:bare-catalog — Refresh docs/bare-holepunch-catalog.json from GitHub + npm (see Chapter 12)
• scripts.sync:bare-manifest — Apply catalog → bare-module-manifest.json entries (preserves curated pearEntries) + booter optionalDependencies
• scripts.test — Runs npm run test --workspaces --if-present
• scripts.format — prettier --write .
• scripts.lint — prettier --check .
• engines.node — >=20
• devDependencies — prettier@^3.4.2

No runtime dependencies at the root; all stack deps live in workspace packages.

---

3. Root: package-lock.json

• Format: npm lockfile v3 (lockfileVersion: 3).
• Role: Pins exact versions of the full install graph (root + packages/bare-os-protocol, bare-os-seeder, bare-os-booter and all transitive dependencies: hyperdrive, corestore, hyperswarm, protomux, brittle, Bare-related packages, native addons such as rocksdb-native, etc.).
• Workspaces: Lists workspace package paths and links workspace packages to "node_modules/bare-os-protocol" etc.
• Not reproduced here line-by-line — it is thousands of lines; use npm ls or open the file for the exact tree.

---

4. Root: README.md

User-oriented documentation: project goal, layout table, prerequisites (Node 20+, Pear/Bare), npm ci, npm test, how to run seeder and booter with node index.js, environment variables, Corestore path semantics (~/.bare-os defaults), placeholder pear:// table, protocol summary (bare-os-v1, MBR layout), license pointer.

Runtime drift guard:

• Run npm run verify:bare-runtime before bare-only workflows.
• Minimum supported host runtime for this repo is bare v1.28.0.
• If bare --version is lower, upgrade host tools with:
  • npm i -g bare-runtime pear
• Quick rollback (if needed) to prior known versions on your machine:
  • npm i -g bare-runtime@<previous> pear@<previous>
  • then re-run npm run verify:bare-runtime and npm run test:bare.

Narrative handbook (architecture diagrams, chapter walkthrough): handbook/README.md. Per-workspace overviews: packages/bare-os-protocol/README.md, packages/bare-os-coreutils/README.md, packages/bare-os-seeder/README.md, packages/bare-os-booter/README.md, kernel/README.md, scripts/README.md.

---

5. Root: LICENSE

Apache License, Version 2.0 header: copyright year 2026, HoneyPeer, LLC ownership statement, standard AS-IS disclaimer, link to http://www.apache.org/licenses/LICENSE-2.0, and pointer to third-party vendor licenses.

---

6. Root: .gitignore

Ignores:

• node_modules/
• data/ (legacy; optional local Corestore if you still keep trees here — defaults now use ~/.bare-os)
• coverage/
• .DS_Store
• *.log
• .pear/
• packages/*/.test-data/ (brittle test Corestore dirs)

---

7. Root: .prettierrc

JSON: semi: false, singleQuote: true, trailingComma: "none".

---

8. CI: .github/workflows/ci.yml

• Triggers: push and pull_request to main.
• Job test: ubuntu-latest, checkout, actions/setup-node@v4 with Node 20 and npm cache on package-lock.json, then npm ci, install a modern Bare runtime (bare-runtime) for brittle-bare / bare smoke tests, and run npm test.

---

9. Root: patches/ (patch-package)

The repo may ship patches/*.patch files in patch-package format (for example patches/autopass+3.4.0.patch) so maintainers can apply small upstream dependency fixes during development. They are not staged into the guest Hyperdrive. patch-package is a root devDependency; wire a postinstall script if you want patches applied automatically after npm ci. Document why each patch exists in the commit message and keep diffs minimal.