106 lines
6.7 KiB
Markdown
106 lines
6.7 KiB
Markdown
# Chapter 7 — Troubleshooting and operations
|
||
|
||
**Prerequisites:** earlier chapters of this manual. **Time to read:** about eight minutes.
|
||
|
||
---
|
||
|
||
## On this page
|
||
|
||
- [Boot and swarm issues](#boot-and-swarm-issues)
|
||
- [Missing binaries or stale image](#missing-binaries-or-stale-image)
|
||
- [Environment variables](#environment-variables)
|
||
- [Themes and terminals](#themes-and-terminals)
|
||
- [CI and contributing](#ci-and-contributing)
|
||
- [Pretest and verifier failures](#pretest-and-verifier-failures)
|
||
- [Pear and module resolution](#pear-and-module-resolution)
|
||
- [Documentation link checks](#documentation-link-checks)
|
||
|
||
---
|
||
|
||
## Boot and swarm issues
|
||
|
||
**Symptom: booter exits on timeout.** The booter could not replicate the system drive in time. Typical causes:
|
||
|
||
- the **seeder** is not running or not reachable on the network;
|
||
- bootstrap nodes are wrong or blocked—review **`HYPERSWARM_BOOTSTRAP`** and firewall rules;
|
||
- you are using **offline LKG** mode without a valid local system drive (advanced; see reference docs).
|
||
|
||
Start the seeder first, wait until it is advertising, then start the booter. For protocol-level failure modes, read [Handbook — Chapter 3](../handbook/03-protocol-and-disk.md).
|
||
|
||
**Symptom: “no peers” or empty replication.** Confirm both processes use compatible **bootstrap** configuration (**`HYPERSWARM_BOOTSTRAP`**, corporate VPNs, and local firewalls frequently block DHT traffic). Try a clean Corestore path only after you are sure networking is not the root cause, or you may chase ghosts while the real issue was connectivity.
|
||
|
||
**Symptom: boot reaches shell but `/proc` looks empty or wrong.** Some **`/proc`** nodes require a minimum **ctx API** or capability words. Compare **`/proc/bare_os_features`** (when present) with the [compatibility matrix](../docs/reference/compatibility-matrix.md) and the versions printed by **`bare_os.capabilities`** during seeding.
|
||
|
||
---
|
||
|
||
## Missing binaries or stale image
|
||
|
||
**Symptom: a `/bin` tool is missing or obviously old under Pear.** The **`bare-os-coreutils`** workspace must be **built** before staging or seeding. From the repo root:
|
||
|
||
```bash
|
||
npm run build -w bare-os-coreutils
|
||
```
|
||
|
||
If you changed **`kernel/`** but the seeder still ships an old tree, CI’s **`verify-kernel-seeder-parity`** error means **`packages/bare-os-seeder/kernel/`** is out of sync with **`kernel/`**—copy or sync per maintainer workflow before release.
|
||
|
||
---
|
||
|
||
## Environment variables
|
||
|
||
There are **many** **`BARE_OS_*`** toggles. Host-side variables are often copied into the guest session so kernels and scripts see a consistent environment.
|
||
|
||
For a **complete list** and POSIX-related notes, use [Environment variables and POSIX appendix](../docs/reference/environment-and-posix-appendix.md). For a shorter **operator cheat sheet** grouped by component, see [Handbook — Chapter 7](../handbook/07-operations-and-development.md#environment-variables-cheat-sheet).
|
||
|
||
When debugging, ask whether the variable was set on the **host** before launching the booter, because the guest only sees what the booter forwards into **`shellEnv`**.
|
||
|
||
---
|
||
|
||
## Themes and terminals
|
||
|
||
**Symptom: colors or `ls --color` look wrong.** Themes interact with **`LS_COLORS`**, **`~/.barerc`**, and the **truecolor** versus **256-color** capability of your terminal emulator. Read the themes documentation and handbook notes rather than chasing random color codes:
|
||
|
||
- [docs/themes/README.md](../docs/themes/README.md)
|
||
- [Handbook — Chapter 7: Themes, LS_COLORS, and real terminals](../handbook/07-operations-and-development.md#themes-ls_colors-and-real-terminals)
|
||
|
||
---
|
||
|
||
## CI and contributing
|
||
|
||
Root **`npm test`** runs workspace tests after **`pretest`**, which builds artifacts and runs repository verifiers (kernel or seeder parity, ctx API alignment, capability contracts, documentation links, man coverage, compatibility matrix strings, kernel program governance + proc schema + roadmap table checks, Pear import rules, bare manifest smoke).
|
||
|
||
If **`gen:bare-catalog:check`** fails, regenerate the catalog with **`npm run gen:bare-catalog`** and commit the JSON. If **`verify-doc-links`** fails, fix broken relative **`.md`** links in the walked trees.
|
||
|
||
For a full maintainer-oriented walkthrough, [Handbook — Chapter 7](../handbook/07-operations-and-development.md) remains the authoritative operations chapter.
|
||
|
||
---
|
||
|
||
## Pretest and verifier failures
|
||
|
||
**`verify-kernel-seeder-parity`** — **`kernel/`** and **`packages/bare-os-seeder/kernel/`** must match **byte-for-byte**. Copy the canonical tree into the package (maintainer scripts or **`cp -R`**) after editing **`kernel/`**, then re-run **`pretest`**.
|
||
|
||
**`verify-kernel-capabilities-word-*`** — The [feature roadmap](../docs/reference/feature-roadmap.md) keeps **`## Capability word 6`…`11`** checklists as pipe tables with fixed row counts. Do not shrink those tables without updating the matching script under **`scripts/`**.
|
||
|
||
**`verify-ctx-api-feature-bits` / `verify-ctx-dts`** — The **`ctx` API** semver and **kernel capability** documentation must agree with **`packages/bare-os-protocol`** and **`packages/bare-os-booter`**. Start from the compatibility matrix when bumping versions.
|
||
|
||
**`verify-man-coverage`** — Every **`kernel/bin/*`** file must include the **`BARE_OS_BIN_API`** pragma and have a **`man`** page. Regenerate coreutils outputs after adding a command.
|
||
|
||
**`verify-compat-matrix`** — Strings in [compatibility-matrix.md](../docs/reference/compatibility-matrix.md) must mention current versions; the script is substring-based, not structural.
|
||
|
||
**`verify-pear-no-static-node-import`** — Pear bundles must not embed forbidden static **`node:`** imports; follow patterns in the booter’s Pear entry code.
|
||
|
||
---
|
||
|
||
## Pear and module resolution
|
||
|
||
If **`pear run`** fails with missing modules but **`npm ci` at the repo root succeeded**, run the **`npm run os:seeder`** / **`os:booter`** scripts from the **root** so **`scripts/ensure-pear-node-modules.mjs`** mirrors hoisted dependencies into the package **`node_modules`** Pear expects. Running **`pear run`** manually from a clean package directory without that step is a common source of **`Cannot find package`** errors.
|
||
|
||
---
|
||
|
||
## Documentation link checks
|
||
|
||
**`verify-doc-links`** walks **`docs/`**, **`handbook/`**, **`developer-guide/`**, **`scripts/`**, **`users-manual/`**, **`packages/`**, **`kernel/`**, and root **`README.md`**, **`DOCUMENTATION.md`**, **`PEAR-RUN.md`**. It skips **`packages/bare-os-seeder/kernel/**`** because that tree is identical to **`kernel/**`**; fix links in **`kernel/**`** only. Use **relative** `something.md` targets in links so CI can resolve them from each file’s directory.
|
||
|
||
---
|
||
|
||
_Previous: [Chapter 6](06-help-man-and-documentation-map.md)_ · _Next: [Chapter 8 — Further reading](08-further-reading.md)_
|