snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
b23cc661a0b6249ab6239669c24d681c7fa5c396
bare-operating-system/docs/reference/repo-layout-and-root.md
T
Raven Scott 7171618c74
Release rolling / release (push) Successful in 9m59s
Details
Update Docs
2026-08-12 21:10:14 -04:00

174 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Repository layout and root metadata
Former monolith **DOCUMENTATION.md** §§1–8. [Reference index →](README.md)
## 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](../../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/smoke-bare-manifest-imports.mjs)
- `scripts.gen:bare-catalog` — Refresh [`docs/bare-holepunch-catalog.json`](../bare-holepunch-catalog.json) from GitHub + npm (see [Chapter 12](../../developer-guide/12-bare-modules-and-pear-ecosystem.md))
- `scripts.sync:bare-manifest` — Apply catalog → [`bare-module-manifest.json`](../../packages/bare-os-booter/lib/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](../../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](../../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`](../../package.json) 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](../../handbook/README.md). Per-workspace overviews: [packages/bare-os-protocol/README.md](../../packages/bare-os-protocol/README.md), [packages/bare-os-coreutils/README.md](../../packages/bare-os-coreutils/README.md), [packages/bare-os-seeder/README.md](../../packages/bare-os-seeder/README.md), [packages/bare-os-booter/README.md](../../packages/bare-os-booter/README.md), [kernel/README.md](../../kernel/README.md), [scripts/README.md](../../scripts/README.md).
---
## 5. Root: [LICENSE](../../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](../../.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](../../.prettierrc)
JSON: `semi: false`, `singleQuote: true`, `trailingComma: "none"`.
---
## 8. CI: [.github/workflows/ci.yml](../../.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](https://github.com/ds300/patch-package))
The repo may ship **`patches/*.patch`** files in **patch-package** format (for example [`patches/autopass+3.4.0.patch`](../../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.
Reference in New Issue View Git Blame Copy Permalink