opencode-starterkit 1.0.4 → 1.0.5

package/docs/reports/2026-03-18-beads-cli-installer-gap-patch-proposal.md

@@ -0,0 +1,249 @@
+# Patch proposal: close the beads CLI installer gap in `install-global.mjs`
+
+## Problem statement
+`npx opencode-starterkit install` currently installs the **global baseline files** only:
+- agents
+- skills
+- plugins
+- commands
+- tools
+- templates/docs
+- merged `opencode.json`
+- `ocp` shim
+
+However, multiple baseline skills/commands operationally depend on **`br` (beads_rust CLI)**, especially:
+- `baseline/skill/beads/SKILL.md`
+- `baseline/skill/beads-bridge/SKILL.md`
+- `baseline/command/create.md`
+- `baseline/command/plan.md`
+- `baseline/command/resume.md`
+- `baseline/command/ship.md`
+- `baseline/command/status.md`
+- `baseline/command/verify.md`
+
+Today the installer does **not**:
+- detect whether `br` exists
+- install it
+- fail fast when it is missing
+- or print a clear remediation path
+
+This creates a broken onboarding path:
+1. user runs `npx opencode-starterkit install`
+2. baseline appears installed
+3. user invokes beads workflow
+4. runtime fails because `br` is missing
+
+## Desired outcome
+After global install, one of these must be true:
+1. `br` is available on PATH, or
+2. installer exits non-zero with a clear, OS-specific remediation message
+
+## Recommended policy
+Use a **2-tier strategy**:
+
+### Tier A — default safe behavior
+- Detect whether `br` is present.
+- If present: continue and print version.
+- If missing: **fail fast** by default with exact install instructions.
+
+### Tier B — opt-in auto-install
+Add optional flag later, e.g.:
+- `--install-beads`
+
+Only when this flag is passed should the installer attempt automatic installation.
+This avoids surprising system mutations during a global bootstrap.
+
+## Why fail-fast first?
+Because automatic installation is OS/package-manager specific and can be fragile:
+- macOS may need `brew`
+- Linux may need package manager or cargo
+- some environments may prefer pinned binary releases
+- CI/devbox/sandbox shells may not allow package manager writes
+
+Fail-fast is the minimum viable fix that closes the onboarding ambiguity.
+
+---
+
+# Proposed implementation
+
+## New helper functions in `src/install-global.mjs`
+
+### 1) `checkBeadsCli()`
+Purpose:
+- detect whether `br` exists
+- capture version if available
+
+Pseudo-code:
+
+```js
+import { spawnSync } from 'node:child_process'
+
+function checkBeadsCli() {
+  const whichResult = spawnSync('bash', ['-lc', 'command -v br'], { encoding: 'utf8' })
+  const found = whichResult.status === 0 && whichResult.stdout.trim().length > 0
+  if (!found) {
+    return { ok: false, path: null, version: null }
+  }
+
+  const versionResult = spawnSync('bash', ['-lc', 'br --version || br version'], { encoding: 'utf8' })
+  const version = `${versionResult.stdout || ''}${versionResult.stderr || ''}`.trim() || null
+  return { ok: true, path: whichResult.stdout.trim(), version }
+}
+```
+
+### 2) `getBeadsInstallHint()`
+Purpose:
+- print platform-appropriate remediation guidance
+
+Pseudo-code:
+
+```js
+function getBeadsInstallHint() {
+  const platform = process.platform
+  if (platform === 'darwin') {
+    return [
+      'Beads CLI (br) is required by the baseline but is not installed.',
+      'Suggested next steps on macOS:',
+      '  1. Install Homebrew if missing',
+      '  2. Install beads_rust / br using the project-approved method',
+      '  3. Re-run: npx opencode-starterkit install',
+      'If your team standard is a specific install command, document it here explicitly.'
+    ].join('\n')
+  }
+
+  if (platform === 'linux') {
+    return [
+      'Beads CLI (br) is required by the baseline but is not installed.',
+      'Suggested next steps on Linux:',
+      '  1. Install br using the team-approved package/binary method',
+      '  2. Re-run: npx opencode-starterkit install'
+    ].join('\n')
+  }
+
+  return [
+    'Beads CLI (br) is required by the baseline but is not installed.',
+    'Install it using the team-approved method, then re-run the installer.'
+  ].join('\n')
+}
+```
+
+### 3) `ensureBeadsCliOrExit()`
+Purpose:
+- enforce hard precondition before claiming global install success
+
+Pseudo-code:
+
+```js
+function ensureBeadsCliOrExit() {
+  const check = checkBeadsCli()
+  if (!check.ok) {
+    console.error('[opencode-starterkit] ERROR: beads CLI (br) not found on PATH')
+    console.error(getBeadsInstallHint())
+    process.exitCode = 1
+    throw new Error('Missing required dependency: br')
+  }
+
+  console.log(`[opencode-starterkit] beads CLI found: ${check.path}`)
+  if (check.version) {
+    console.log(`[opencode-starterkit] beads CLI version: ${check.version}`)
+  }
+}
+```
+
+---
+
+# Minimal patch placement
+Insert the dependency gate near the top of `installGlobal()` before printing success.
+
+## Current flow
+```js
+export async function installGlobal({ cwd }) {
+  console.log('[opencode-starterkit] Global install starting')
+  ...
+  installPackageRuntime()
+  copyMarkdownAgents()
+  copySkills()
+  ...
+  installOcpShim()
+  console.log('[opencode-starterkit] Installed ...')
+}
+```
+
+## Proposed flow
+```js
+export async function installGlobal({ cwd }) {
+  console.log('[opencode-starterkit] Global install starting')
+  console.log(`cwd=${cwd}`)
+  console.log(`baseline=${MRC_OPC_BASELINE_ROOT}`)
+
+  installPackageRuntime()
+  copyMarkdownAgents()
+  copySkills()
+  copyPlugins()
+  copyCommands()
+  copyTools()
+  copyTemplatesAndDocs()
+
+  const mergeResult = mergeGlobalOpencodeJson()
+  installOcpShim()
+
+  // NEW: hard dependency check
+  ensureBeadsCliOrExit()
+
+  console.log(`[opencode-starterkit] Installed package runtime at ${GLOBAL_PACKAGE_ROOT}`)
+  ...
+}
+```
+
+---
+
+# Optional phase-2 enhancement: `--install-beads`
+If the project wants auto-install later, extend `cli.mjs` args with:
+- `--install-beads`
+
+Then implement a guarded install function:
+
+```js
+function installBeadsCliIfRequested(options) {
+  if (!options.installBeads) return
+  // platform-specific install attempts here
+}
+```
+
+Important:
+- do **not** auto-install silently by default
+- only run with explicit operator intent
+- log exact command executed
+- fail if command is unavailable
+
+---
+
+# Additional UX improvement
+Update README install section to state clearly:
+
+```md
+Global install installs the baseline files and validates required operational CLIs.
+If `br` (beads CLI) is missing, the installer will stop with a remediation message.
+```
+
+This removes the false impression that "install completed" implies the full workflow backend is ready.
+
+---
+
+# Acceptance criteria
+1. Running `npx opencode-starterkit install` on a machine **without** `br`:
+   - exits non-zero
+   - prints clear remediation
+   - does not claim success
+2. Running on a machine **with** `br`:
+   - succeeds
+   - prints detected path/version
+3. README and help text mention the validation behavior.
+4. No hidden package-manager mutation occurs without explicit opt-in.
+
+---
+
+# Recommendation to team
+Ship the **fail-fast dependency validation** first.
+Do not block on auto-install implementation.
+That closes the onboarding ambiguity immediately with minimal risk.

package/docs/reports/2026-03-18-beads-cli-installer-patch-proposal-v2.md

@@ -0,0 +1,253 @@
+# Patch proposal v2: interactive beads CLI detection + suggested install in `install-global.mjs`
+
+## Goal
+Close the current onboarding gap where:
+- `npx opencode-starterkit install` installs the global baseline
+- baseline workflows assume `br` exists
+- but installer does not detect/install/help the user obtain `br`
+
+This v2 proposal follows the product rule:
+1. detect `br`
+2. if missing, detect OS
+3. suggest the correct install command
+4. ask user for confirmation in interactive mode
+5. install only if user agrees
+6. verify `br --version`
+7. continue only when the dependency is satisfied (or exit clearly)
+
+---
+
+## Source-backed install commands to use
+The repo itself does not define an official beads installer command, so we should not invent one.
+From public upstream sources we can support explicit provider choices:
+
+### Option A — `beads-rs` (delightful-ai)
+Source indicates:
+```bash
+curl -fsSL https://raw.githubusercontent.com/delightful-ai/beads-rs/main/scripts/install.sh | bash
+```
+Alternative:
+```bash
+cargo install beads-rs
+```
+Binary there is primarily `bd`.
+
+### Option B — `beads_rust` / `br` (Dicklesworthstone)
+Source indicates:
+```bash
+curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh?$(date +%s)" | bash
+```
+This one explicitly installs `br`.
+
+## Recommendation
+Because the baseline docs explicitly refer to **`br`**, the installer should prefer the `beads_rust` / `br` install path first.
+
+---
+
+## Proposed UX
+
+### Interactive shell
+If `br` is missing:
+
+```text
+[opencode-starterkit] beads CLI (br) is required by the baseline but was not found.
+Detected OS: macOS
+Recommended install command:
+  curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh?$(date +%s)" | bash
+Install now? [y/N]
+```
+
+If user says yes:
+- run the command
+- verify `command -v br`
+- verify `br --version`
+- continue install
+
+If user says no:
+- exit non-zero
+- print a short message that beads-based workflows will not function until `br` is installed
+
+### Non-interactive / CI
+If `br` is missing:
+- print the recommended install command
+- exit non-zero
+- do **not** attempt silent install
+
+---
+
+## Proposed implementation sketch
+
+### New helpers in `src/install-global.mjs`
+
+```js
+import { spawnSync } from 'node:child_process'
+import readline from 'node:readline'
+```
+
+### 1) Detect `br`
+```js
+function checkBeadsCli() {
+  const whichResult = spawnSync('bash', ['-lc', 'command -v br'], { encoding: 'utf8' })
+  const found = whichResult.status === 0 && whichResult.stdout.trim()
+  if (!found) return { ok: false, path: null, version: null }
+
+  const versionResult = spawnSync('bash', ['-lc', 'br --version || br version'], { encoding: 'utf8' })
+  const version = `${versionResult.stdout || ''}${versionResult.stderr || ''}`.trim() || null
+  return { ok: true, path: whichResult.stdout.trim(), version }
+}
+```
+
+### 2) Detect OS and choose install command
+```js
+function getSuggestedBeadsInstall() {
+  const platform = process.platform
+
+  const primary = 'curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh?$(date +%s)" | bash'
+  const fallback = 'cargo install beads-rs'
+
+  if (platform === 'darwin') {
+    return {
+      osLabel: 'macOS',
+      primary,
+      fallback,
+    }
+  }
+
+  if (platform === 'linux') {
+    return {
+      osLabel: 'Linux',
+      primary,
+      fallback,
+    }
+  }
+
+  if (platform === 'win32') {
+    return {
+      osLabel: 'Windows',
+      primary: 'Use WSL and run: ' + primary,
+      fallback: 'Use a supported Rust/cargo install path inside WSL',
+    }
+  }
+
+  return {
+    osLabel: process.platform,
+    primary,
+    fallback,
+  }
+}
+```
+
+### 3) Ask user
+```js
+async function askYesNo(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  return await new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close()
+      const normalized = String(answer || '').trim().toLowerCase()
+      resolve(normalized === 'y' || normalized === 'yes')
+    })
+  })
+}
+```
+
+### 4) Install if approved
+```js
+function runShellCommand(command) {
+  return spawnSync('bash', ['-lc', command], { stdio: 'inherit', encoding: 'utf8' })
+}
+```
+
+### 5) Main gate
+```js
+async function ensureBeadsCliInteractive() {
+  const check = checkBeadsCli()
+  if (check.ok) {
+    console.log(`[opencode-starterkit] beads CLI found: ${check.path}`)
+    if (check.version) console.log(`[opencode-starterkit] beads CLI version: ${check.version}`)
+    return
+  }
+
+  const install = getSuggestedBeadsInstall()
+  console.warn('[opencode-starterkit] beads CLI (br) is required by the baseline but was not found.')
+  console.warn(`[opencode-starterkit] Detected OS: ${install.osLabel}`)
+  console.warn(`[opencode-starterkit] Recommended install command:\n  ${install.primary}`)
+  console.warn(`[opencode-starterkit] Fallback command:\n  ${install.fallback}`)
+
+  if (!process.stdin.isTTY) {
+    throw new Error('Missing beads CLI (br). Non-interactive mode cannot auto-install; run the suggested install command and retry.')
+  }
+
+  const approved = await askYesNo('Install beads CLI now? [y/N] ')
+  if (!approved) {
+    throw new Error('User declined beads CLI installation. Beads-based workflows will not function until br is installed.')
+  }
+
+  const result = runShellCommand(install.primary)
+  if (result.status !== 0) {
+    throw new Error(`Automatic beads install failed. Try manually: ${install.primary}`)
+  }
+
+  const verify = checkBeadsCli()
+  if (!verify.ok) {
+    throw new Error('beads install command completed but br is still not available on PATH.')
+  }
+
+  console.log(`[opencode-starterkit] beads CLI installed: ${verify.path}`)
+  if (verify.version) console.log(`[opencode-starterkit] beads CLI version: ${verify.version}`)
+}
+```
+
+---
+
+## Required code shape change
+Because the new gate is async, `installGlobal()` should await it.
+
+### Before
+```js
+export async function installGlobal({ cwd }) {
+  ...
+  installOcpShim()
+  console.log('done')
+}
+```
+
+### After
+```js
+export async function installGlobal({ cwd }) {
+  ...
+  installOcpShim()
+  await ensureBeadsCliInteractive()
+  console.log('done')
+}
+```
+
+---
+
+## README change required
+Update install docs to say:
+
+```md
+Global install validates the beads CLI (`br`) because several baseline workflows depend on it.
+If `br` is missing, the installer will suggest the correct install command for your OS and ask whether to install it.
+```
+
+---
+
+## Acceptance criteria
+1. On a machine with `br` already installed:
+   - installer prints path/version and continues
+2. On a machine without `br` in interactive mode:
+   - installer detects OS
+   - prints install command
+   - asks user
+   - installs only after explicit approval
+   - verifies `br --version`
+3. On a machine without `br` in non-interactive mode:
+   - installer exits non-zero with remediation text
+4. No silent package-manager mutation occurs without user approval.
+
+---
+
+## Recommendation
+Implement this interactive detection/suggest/install path now, and keep the command source explicit and documented.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-starterkit",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "private": false,
   "type": "module",
   "description": "Global baseline + thin project overlay installer for OpenCode.",

package/src/install-global.mjs

@@ -1,5 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import readline from 'node:readline'
 import {
   GLOBAL_AGENTS_DIR,
   GLOBAL_BIN_DIR,
@@ -54,7 +56,7 @@ function copyTemplatesAndDocs() {
 
 function installOcpShim() {
   ensureDir(GLOBAL_BIN_DIR)
-  const shim = `#!/usr/bin/env bash\nnode \"${path.join(GLOBAL_PACKAGE_ROOT, 'bin', 'ocp.mjs')}\" \"$@\"\n`
+  const shim = `#!/usr/bin/env bash\nnode "${path.join(GLOBAL_PACKAGE_ROOT, 'bin', 'ocp.mjs')}" "$@"\n`
   writeText(GLOBAL_OCP_SHIM, shim)
   fs.chmodSync(GLOBAL_OCP_SHIM, 0o755)
 }
@@ -73,6 +75,86 @@ function mergeGlobalOpencodeJson() {
   return { merged: true, globalPath }
 }
 
+function checkBeadsCli() {
+  const whichResult = spawnSync('bash', ['-lc', 'command -v br'], { encoding: 'utf8' })
+  const found = whichResult.status === 0 && whichResult.stdout.trim().length > 0
+  if (!found) {
+    return { ok: false, path: null, version: null }
+  }
+  const versionResult = spawnSync('bash', ['-lc', 'br --version || br version'], { encoding: 'utf8' })
+  const version = `${versionResult.stdout || ''}${versionResult.stderr || ''}`.trim() || null
+  return { ok: true, path: whichResult.stdout.trim(), version }
+}
+
+function getSuggestedBeadsInstall() {
+  const platform = process.platform
+  const primary = 'curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/beads_rust/main/install.sh | bash'
+  const fallback = 'cargo install beads-rs'
+
+  if (platform === 'darwin') {
+    return { osLabel: 'macOS', primary, fallback }
+  }
+  if (platform === 'linux') {
+    return { osLabel: 'Linux', primary, fallback }
+  }
+  if (platform === 'win32') {
+    return { osLabel: 'Windows', primary: 'Use WSL and run: ' + primary, fallback: 'Use a supported Rust/cargo install path inside WSL' }
+  }
+  return { osLabel: platform, primary, fallback }
+}
+
+async function askYesNo(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  return await new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close()
+      const normalized = String(answer || '').trim().toLowerCase()
+      resolve(normalized === 'y' || normalized === 'yes')
+    })
+  })
+}
+
+function runShellCommand(command) {
+  return spawnSync('bash', ['-lc', command], { stdio: 'inherit', encoding: 'utf8' })
+}
+
+async function ensureBeadsCliInteractive() {
+  const check = checkBeadsCli()
+  if (check.ok) {
+    console.log(`[opencode-starterkit] beads CLI found: ${check.path}`)
+    if (check.version) console.log(`[opencode-starterkit] beads CLI version: ${check.version}`)
+    return
+  }
+
+  const install = getSuggestedBeadsInstall()
+  console.warn('[opencode-starterkit] beads CLI (br) is required by the baseline but was not found.')
+  console.warn(`[opencode-starterkit] Detected OS: ${install.osLabel}`)
+  console.warn(`[opencode-starterkit] Recommended install command:\n  ${install.primary}`)
+  console.warn(`[opencode-starterkit] Fallback command:\n  ${install.fallback}`)
+
+  if (!process.stdin.isTTY) {
+    throw new Error('Missing beads CLI (br). Non-interactive mode cannot auto-install; run the suggested install command and retry.')
+  }
+
+  const approved = await askYesNo('Install beads CLI now? [y/N] ')
+  if (!approved) {
+    throw new Error('User declined beads CLI installation. Beads-based workflows will not function until br is installed.')
+  }
+
+  const result = runShellCommand(install.primary)
+  if (result.status !== 0) {
+    throw new Error(`Automatic beads install failed. Try manually: ${install.primary}`)
+  }
+
+  const verify = checkBeadsCli()
+  if (!verify.ok) {
+    throw new Error('beads install command completed but br is still not available on PATH.')
+  }
+
+  console.log(`[opencode-starterkit] beads CLI installed: ${verify.path}`)
+  if (verify.version) console.log(`[opencode-starterkit] beads CLI version: ${verify.version}`)
+}
+
 export async function installGlobal({ cwd }) {
   console.log('[opencode-starterkit] Global install starting')
   console.log(`cwd=${cwd}`)
@@ -86,6 +168,7 @@ export async function installGlobal({ cwd }) {
   copyTemplatesAndDocs()
   const mergeResult = mergeGlobalOpencodeJson()
   installOcpShim()
+  await ensureBeadsCliInteractive()
   console.log(`[opencode-starterkit] Installed package runtime at ${GLOBAL_PACKAGE_ROOT}`)
   console.log(`[opencode-starterkit] Synced agents -> ${GLOBAL_AGENTS_DIR}`)
   console.log(`[opencode-starterkit] Synced skills -> ${GLOBAL_SKILLS_DIR}`)