From 6fbd6329b486d8f4e160568acf1e7a7a0da33252 Mon Sep 17 00:00:00 2001 From: ZenchantLive Date: Mon, 2 Mar 2026 20:46:18 -0800 Subject: [PATCH] docs(ci): finalize global install runtime docs and smoke coverage --- .github/workflows/installer-smoke.yml | 49 +++++++++++++++++++ README.md | 32 ++++++++++++ ...26-03-03-runtime-manager-global-install.md | 7 ++- docs/ops/global-install-rollout.md | 31 ++++++++++++ .../installer-quickstart-contract.test.ts | 21 ++++++++ tests/scripts/installer-ci-contract.test.ts | 18 +++++++ 6 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/installer-smoke.yml create mode 100644 docs/ops/global-install-rollout.md create mode 100644 tests/docs/installer-quickstart-contract.test.ts create mode 100644 tests/scripts/installer-ci-contract.test.ts diff --git a/.github/workflows/installer-smoke.yml b/.github/workflows/installer-smoke.yml new file mode 100644 index 0000000..c68d2bb --- /dev/null +++ b/.github/workflows/installer-smoke.yml @@ -0,0 +1,49 @@ +name: Installer Smoke + +on: + pull_request: + push: + branches: + - main + - master + +jobs: + installer-smoke-ubuntu: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + - run: npm ci + - run: npm link + - run: bash ./install/install.sh + - run: beadboard doctor --json + - run: node --import tsx --test tests/scripts/beadboard-launcher.test.ts + - run: node --import tsx --test tests/scripts/install-wrappers-contract.test.ts + - run: node --import tsx --test tests/scripts/install-sh-smoke.test.ts + - run: node --import tsx --test tests/skills/beadboard-driver/resolve-bb.test.ts + + installer-smoke-windows: + runs-on: windows-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + - run: npm ci + - run: npm link + - name: Run PowerShell installer wrapper + shell: pwsh + run: .\install\install.ps1 + - name: Run installer doctor + shell: pwsh + run: beadboard doctor --json + - name: Verify installed shims + shell: pwsh + run: | + $shimDir = Join-Path $HOME ".beadboard\bin" + if (!(Test-Path (Join-Path $shimDir "bb.cmd"))) { throw "Missing bb.cmd shim" } + if (!(Test-Path (Join-Path $shimDir "beadboard.cmd"))) { throw "Missing beadboard.cmd shim" } diff --git a/README.md b/README.md index 76805ea..cf7d86d 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,38 @@ cd beadboard npm install ``` +### Global CLI Install (Optional) +Primary install path: + +```bash +npm i -g beadboard +``` + +Fallback wrappers from repo root: + +POSIX (Linux/macOS): +```bash +bash ./install/install.sh +``` + +Windows (PowerShell): +```powershell +powershell -ExecutionPolicy Bypass -File .\install\install.ps1 +``` + +Both wrappers install shims at: +- `~/.beadboard/bin/bb` +- `~/.beadboard/bin/beadboard` + +Runtime home: +- `~/.beadboard/runtime/` +- `~/.beadboard/runtime/current.json` + +Launcher commands: +- `beadboard start` +- `beadboard open` +- `beadboard status` + --- ## Quick Start diff --git a/docs/adr/2026-03-03-runtime-manager-global-install.md b/docs/adr/2026-03-03-runtime-manager-global-install.md index 064b4de..8bf5344 100644 --- a/docs/adr/2026-03-03-runtime-manager-global-install.md +++ b/docs/adr/2026-03-03-runtime-manager-global-install.md @@ -41,9 +41,14 @@ Legacy repo-bound shim migration is required: - Rewrite shims to runtime-managed targets atomically. - Preserve user-facing command names and shell compatibility. +## Supported Platforms + +- Linux: npm-global primary, POSIX wrapper fallback. +- macOS: npm-global primary, POSIX wrapper fallback. +- Windows: npm-global primary, PowerShell wrapper fallback. + ## Failure Modes and Rollback - Missing runtime metadata: launcher reports actionable remediation and install mode. - Corrupt runtime target: launcher falls back to previous known-good metadata when present. - Partial install: installer leaves active runtime unchanged and exits non-zero. - diff --git a/docs/ops/global-install-rollout.md b/docs/ops/global-install-rollout.md new file mode 100644 index 0000000..f56baea --- /dev/null +++ b/docs/ops/global-install-rollout.md @@ -0,0 +1,31 @@ +# Global Install Rollout: Runtime Manager + +## Objective +Roll out npm-global-first install behavior with runtime metadata and backward-compatible shim migration. + +## Operator Install Paths +1. Primary: `npm i -g beadboard` +2. Fallback (POSIX): `bash ./install/install.sh` +3. Fallback (Windows): `powershell -ExecutionPolicy Bypass -File .\\install\\install.ps1` + +## Runtime Layout +- Shim directory: `~/.beadboard/bin` +- Runtime versions: `~/.beadboard/runtime/` +- Active runtime metadata: `~/.beadboard/runtime/current.json` + +## Migration +When existing repo-bound shims are found, installers rewrite them to runtime-aware shims that resolve runtime root from `current.json` first. + +## Recovery Playbook +1. Run `beadboard doctor --json`. +2. If metadata missing/corrupt, rerun installer fallback for your platform. +3. If PATH missing, add `~/.beadboard/bin` to PATH. +4. If repo-bound shim remains, rerun installer to force shim rewrite. + +## Platform Matrix +- Linux: Supported +- macOS: Supported +- Windows: Supported + +## CI Validation +Installer smoke workflow validates wrapper execution and `beadboard doctor --json` in Ubuntu and Windows jobs. diff --git a/tests/docs/installer-quickstart-contract.test.ts b/tests/docs/installer-quickstart-contract.test.ts new file mode 100644 index 0000000..2e3fc4a --- /dev/null +++ b/tests/docs/installer-quickstart-contract.test.ts @@ -0,0 +1,21 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs/promises'; +import path from 'node:path'; + +const readmePath = path.resolve('README.md'); + +test('README documents installer one-liners for windows and posix', async () => { + const raw = await fs.readFile(readmePath, 'utf8'); + assert.match(raw, /npm i -g beadboard/i); + assert.match(raw, /install\/install\.sh/i); + assert.match(raw, /install[\\/]+install\.ps1/i); + assert.match(raw, /~\/\.beadboard\/runtime/i); +}); + +test('README documents beadboard launcher commands', async () => { + const raw = await fs.readFile(readmePath, 'utf8'); + assert.match(raw, /\bbeadboard start\b/i); + assert.match(raw, /\bbeadboard open\b/i); + assert.match(raw, /\bbeadboard status\b/i); +}); diff --git a/tests/scripts/installer-ci-contract.test.ts b/tests/scripts/installer-ci-contract.test.ts new file mode 100644 index 0000000..5243bd9 --- /dev/null +++ b/tests/scripts/installer-ci-contract.test.ts @@ -0,0 +1,18 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs/promises'; +import path from 'node:path'; + +const workflowPath = path.resolve('.github/workflows/installer-smoke.yml'); + +test('installer smoke CI workflow exists', async () => { + const raw = await fs.readFile(workflowPath, 'utf8'); + assert.match(raw, /name:\s*Installer Smoke/i); +}); + +test('installer smoke CI includes ubuntu and windows jobs', async () => { + const raw = await fs.readFile(workflowPath, 'utf8'); + assert.match(raw, /ubuntu-latest/i); + assert.match(raw, /windows-latest/i); + assert.match(raw, /beadboard doctor --json/i); +});