feat: kernel roadmap wave — bits4, policy v4, Pear/Bare compatibility

- protocol/booter: bits4 handshake, proc surfaces, boot policy v4, telemetry v4
- coreutils: nohup + ensure-man-pages; seed-man-pages fixes for extra pages
- kernel-runner: no static node:module (Pear); bare-module createRequire
- docs: handbook, reference, ADR, compatibility matrix, verify scripts
This commit is contained in:
Raven Scott
2026-04-04 02:51:33 -04:00
parent d775fb0628
commit f8a0dad897
190 changed files with 2717 additions and 1822 deletions
@@ -51,6 +51,7 @@ const POSIX_TITLE = {
mkfifo: 'make FIFO special files',
mv: 'move or rename files',
nl: 'line numbering utility',
nohup: 'run command (hangup is a no-op in Bare OS)',
od: 'octal dump',
pathchk: 'check pathname portability',
printenv: 'print environment variables',
@@ -256,6 +257,12 @@ EXAMPLES.mv = [
{ caption: 'rename', code: 'mv old.txt new.txt' },
{ caption: 'into dir', code: 'mv *.txt ~/inbox/' }
]
EXAMPLES.nohup = [
{
caption: 'run utility (no real SIGHUP in guest)',
code: 'nohup long-job.sh'
}
]
EXAMPLES.nl = [{ caption: 'number all lines', code: 'nl README.md' }]
EXAMPLES.od = [{ caption: 'hex dump vibe', code: 'od -c file.bin | head' }]
EXAMPLES.pathchk = [
@@ -798,6 +805,79 @@ function wgetPage() {
}
}
function ctxBarePage() {
return {
name: 'bare-os-ctx-bare',
section: 7,
title: 'ctx.bare library and drive bundles',
synopsis: ['# reference — not a shell command'],
description:
'Documents BARE_OS_BARE_MODULES and BARE_OS_BARE_DRIVE_BUNDLES for the booter ctx.bare registry. In-image scripts (AsyncFunction) use ctx.bare.<key> instead of import(). Keys come from host dynamic import of packages listed in packages/bare-os-booter/lib/bare-module-manifest.json, then optional merge from trusted IIFE bundles under /lib/bare/bundles/ on the system image (see manifest.json there). Set BARE_OS_BARE_MODULES=0 to omit ctx.bare entirely. Set BARE_OS_BARE_DRIVE_BUNDLES=0 to skip executing drive bundles (host imports only). Rebuild bundles with npm run build -w bare-os-bare-libs.',
options: [],
keywords: [
'BARE_OS_BARE_MODULES',
'BARE_OS_BARE_DRIVE_BUNDLES',
'ctx.bare',
'bare-module-manifest',
'bare-os-bare-libs'
],
environment: [
'BARE_OS_BARE_MODULES — set to 0 or false to disable ctx.bare (hardened sessions).',
'BARE_OS_BARE_DRIVE_BUNDLES — set to 0 or false to skip loading /lib/bare/bundles/*.js into ctx.bare.'
],
seeAlso: [{ name: 'bare-os-developer-guide', section: 7 }],
bareOsNotes:
'See developer-guide/05-modules-and-imports.md and 12-bare-modules-and-pear-ecosystem.md.',
examples: []
}
}
function systemctlPage() {
return {
name: 'systemctl',
section: 1,
title: 'bare-initd service control (systemd-like subset)',
synopsis: [
'systemctl list|list-units',
'systemctl status [UNIT] [--lines N]',
'systemctl logs UNIT [--lines N]',
'systemctl start|stop|restart UNIT',
'systemctl enable|disable UNIT',
'systemctl is-enabled UNIT',
'systemctl is-active UNIT',
'journalctl -u UNIT [--lines N]'
],
description:
'Lists and manages session-scoped bare-initd units (kernel-logger, bare-cron, …). Implemented by the booter (kernel-runner); /bin stubs exist for PATH and man(1). enable/disable toggle the personal-drive preset file ~/.config/bare-os/initd/disabled.txt for future boots in the same image. is-enabled reports enabled or disabled; is-active reports active vs inactive from runtime phase (exit 0 vs 3). Logs live under /var/log/bare-os/ when the unit defines a logPath. The legacy name bare-initctl is still accepted by the booter as an alias.',
options: [
{
flag: '--lines N',
meaning: 'Tail N lines from the unit log (status, logs, journalctl)'
}
],
aliases: ['bare-initctl'],
keywords: [
'bare-initd',
'initctl',
'service',
'supervisor',
'cron',
'systemd'
],
bareOsNotes:
'journalctl only supports -u UNIT and optional --lines / -n. Unknown systemd verbs are not implemented.',
seeAlso: [
{ name: 'crontab', section: 1 },
{ name: 'bare-os-shell', section: 1 }
],
examples: [
{ caption: 'list units', code: 'systemctl list-units' },
{ caption: 'restart scheduler', code: 'systemctl restart bare-cron' },
{ caption: 'tail cron errors', code: 'journalctl -u bare-cron --lines 20' }
]
}
}
function shellPage() {
return {
name: 'bare-os-shell',
@@ -912,7 +992,17 @@ async function main() {
? curlPage()
: name === 'wget'
? wgetPage()
: shellPage()
: name === 'bare-os-ctx-bare'
? ctxBarePage()
: name === 'systemctl'
? systemctlPage()
: name === 'bare-os-shell'
? shellPage()
: (() => {
throw new Error(
`seed-man-pages: unknown MAN_EXTRA_PAGES entry: ${name}`
)
})()
await writeFile(
join(pagesDir, `${name}.json`),
JSON.stringify(p, null, 2) + '\n'