plumbbob 0.1.3 → 0.2.1

package/src/verbs/revert.ts

@@ -1,110 +0,0 @@
-// `plumbbob revert [--to n]` — git reset --hard to a checkpoint SHA (the most
-// recent step, or `--to n`, with the baseline as fallback), then remove untracked
-// files under the SEAM only. The sidecar is git-excluded (D17), so the reset
-// never touches it — park lines and intent edits survive the revert (C4).
-
-import { readFileSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
-import { findRepoRoot, resetHard, untrackedPaths } from '../lib/git.ts'
-import { checkpointsPath, hasSession, seamPath, stepPath, writeState } from '../lib/sidecar.ts'
-import { matchesSeam } from '../lib/intent.ts'
-
-export function revert(cwd: string, args: ReadonlyArray<string>): number {
-  const root = findRepoRoot(cwd)
-  if (root === null || !hasSession(root)) {
-    process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n')
-    return 1
-  }
-
-  const to = parseTo(args)
-  if (to === 'invalid') {
-    process.stderr.write('plumbbob: revert --to needs a step number. Try: plumbbob revert --to 2.\n')
-    return 1
-  }
-
-  const checkpoints = readCheckpoints(root)
-  let sha: string | undefined
-  if (to === null) {
-    sha = checkpoints.steps.at(-1)?.sha ?? checkpoints.baseline
-  } else {
-    const entry = checkpoints.steps.find((e) => e.n === to)
-    if (entry === undefined) {
-      process.stderr.write(`plumbbob: no checkpoint recorded for step ${to}.\n`)
-      return 1
-    }
-    sha = entry.sha
-  }
-  if (sha === undefined) {
-    process.stderr.write('plumbbob: no baseline recorded in checkpoints — cannot revert.\n')
-    return 1
-  }
-
-  // Compute untracked-in-seam BEFORE the reset (reset --hard leaves untracked and
-  // ignored files alone, so they must be removed explicitly afterward).
-  const seam = readSeamTokens(root)
-  const toRemove = untrackedPaths(root).filter((p) => matchesSeam(p, seam))
-
-  resetHard(root, sha)
-  for (const rel of toRemove) {
-    rmSync(join(root, rel), { force: true, recursive: true })
-  }
-  rmSync(seamPath(root), { force: true })
-  rmSync(stepPath(root), { force: true })
-  writeState(root, 'DESIGN')
-
-  process.stdout.write(
-    `plumbbob: reverted to ${sha.slice(0, 9)} — STATE=DESIGN. Park lines and intent edits were preserved.\n`,
-  )
-  return 0
-}
-
-function parseTo(args: ReadonlyArray<string>): number | null | 'invalid' {
-  const idx = args.indexOf('--to')
-  if (idx === -1) {
-    return null
-  }
-  const raw = args[idx + 1]
-  if (raw === undefined || !/^\d+$/.test(raw)) {
-    return 'invalid'
-  }
-  return Number(raw)
-}
-
-type Checkpoints = {
-  readonly baseline: string | undefined
-  readonly steps: ReadonlyArray<{ readonly n: number; readonly sha: string }>
-}
-
-function readCheckpoints(root: string): Checkpoints {
-  let content = ''
-  try {
-    content = readFileSync(checkpointsPath(root), 'utf8')
-  } catch {
-    return { baseline: undefined, steps: [] }
-  }
-  let baseline: string | undefined
-  const steps: Array<{ readonly n: number; readonly sha: string }> = []
-  for (const line of content.split('\n')) {
-    const baselineMatch = /^baseline\s+(\S+)/.exec(line)
-    if (baselineMatch) {
-      baseline = baselineMatch[1]
-      continue
-    }
-    const stepMatch = /^step\s+(\d+)\s+(\S+)/.exec(line)
-    if (stepMatch) {
-      steps.push({ n: Number(stepMatch[1]), sha: stepMatch[2] ?? '' })
-    }
-  }
-  return { baseline, steps }
-}
-
-function readSeamTokens(root: string): ReadonlyArray<string> {
-  try {
-    return readFileSync(seamPath(root), 'utf8')
-      .split('\n')
-      .map((l) => l.trim())
-      .filter((l) => l.length > 0)
-  } catch {
-    return []
-  }
-}

package/src/verbs/review.ts

@@ -1,30 +0,0 @@
-// `plumbbob review` — run the heavy check from BUILD. Green flips to REVIEW (the
-// muzzle goes back on so reading the diff can't slide into editing). Red stays in
-// BUILD. The state only advances on a green check.
-
-import { findRepoRoot } from '../lib/git.ts'
-import { hasSession, readState, writeState } from '../lib/sidecar.ts'
-import { runCheck } from '../lib/check.ts'
-
-export function review(cwd: string): number {
-  const root = findRepoRoot(cwd)
-  if (root === null || !hasSession(root)) {
-    process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n')
-    return 1
-  }
-  if (readState(root) !== 'BUILD') {
-    process.stderr.write(`plumbbob: review runs from BUILD (current state is ${readState(root) ?? 'UNKNOWN'}). Run \`plumbbob build <n>\` first.\n`)
-    return 1
-  }
-
-  if (runCheck(root) !== 0) {
-    process.stderr.write('plumbbob: check failed (red) — staying in BUILD. Fix it and re-run `review` (or `done` once green).\n')
-    return 1
-  }
-
-  writeState(root, 'REVIEW')
-  process.stdout.write(
-    'plumbbob: check green — STATE=REVIEW. Read the diff against intent.md (edits muzzled). `build <n>` to re-enter and fix, or `done` to checkpoint.\n',
-  )
-  return 0
-}

package/src/verbs/setup.ts

@@ -1,95 +0,0 @@
-// `plumbbob setup` — the production installer (D27, replacing dev-install.sh).
-// Copies the hooks to ~/.claude/plumbbob/hooks/ and the skills to
-// ~/.claude/skills/, then merges the hook registration into the settings file the
-// chosen scope selects:
-//   (default)   ~/.claude/settings.json            — global, this machine
-//   --project   <repo>/.claude/settings.json       — committable, enrolls the team
-//   --local     <repo>/.claude/settings.local.json — personal, untracked
-// Hooks and skills always install once under ~/.claude/; only the registration's
-// location and command-path form vary by scope. `--uninstall` strips the
-// registration (the installed files are left in place). The hooks are
-// session-gated, so a global registration is safe in every repo (C7).
-
-import { chmodSync, cpSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { findRepoRoot } from '../lib/git.ts'
-import { mergeRegistration, readSettings, stripRegistration, writeSettings } from '../lib/settings.ts'
-
-const HOOK_FILES: ReadonlyArray<string> = ['pre-edit.sh', 'bash-guard.sh', 'post-edit.sh']
-
-type Scope = 'global' | 'project' | 'local'
-
-export function setup(cwd: string, args: ReadonlyArray<string>): number {
-  const scope = pickScope(args)
-  const home = process.env.HOME ?? homedir()
-
-  const settingsFile = resolveSettingsFile(scope, cwd, home)
-  if (settingsFile === null) {
-    process.stderr.write(
-      `plumbbob: --${scope} writes <repo>/.claude/, but this is not a git repository. Run setup from inside the repo, or use the default global scope.\n`,
-    )
-    return 1
-  }
-
-  if (args.includes('--uninstall')) {
-    writeSettings(settingsFile, stripRegistration(readSettings(settingsFile)))
-    process.stdout.write(
-      `plumbbob: removed the hook registration from ${settingsFile}. The installed hooks/skills under ~/.claude/ were left in place.\n`,
-    )
-    return 0
-  }
-
-  // Hooks + skills install once under ~/.claude/ regardless of scope.
-  const installedHooksDir = join(home, '.claude', 'plumbbob', 'hooks')
-  const installedSkillsDir = join(home, '.claude', 'skills')
-  cpSync(packageDir('hooks'), installedHooksDir, { recursive: true })
-  for (const file of HOOK_FILES) {
-    chmodSync(join(installedHooksDir, file), 0o755)
-  }
-  cpSync(packageDir('skills'), installedSkillsDir, { recursive: true })
-
-  // D27: global registers absolute command paths (its settings file is itself
-  // under ~); the repo-scoped files register `~`-prefixed paths so committed
-  // settings carry no machine-absolute home dir.
-  const commandDir = scope === 'global' ? installedHooksDir : '~/.claude/plumbbob/hooks'
-  writeSettings(settingsFile, mergeRegistration(readSettings(settingsFile), commandDir))
-
-  process.stdout.write(
-    `plumbbob: installed hooks → ${installedHooksDir}, skills → ${installedSkillsDir}.\n` +
-      `plumbbob: registered the hooks in ${settingsFile} (${scope} scope).\n` +
-      'plumbbob: restart Claude Code (or reload settings) for the hooks to take effect.\n' +
-      "plumbbob: installed from npm, `plumbbob` (and its `pb` alias) is already on your PATH; from a dev checkout add `alias plumbbob='node <repo>/src/cli.ts'` so the skills' status pre-injection resolves.\n",
-  )
-  return 0
-}
-
-function pickScope(args: ReadonlyArray<string>): Scope {
-  if (args.includes('--project')) {
-    return 'project'
-  }
-  if (args.includes('--local')) {
-    return 'local'
-  }
-  return 'global'
-}
-
-// The settings file the scope writes. Global lives under ~; the repo scopes need
-// a git root and return null outside one so the verb can refuse with a clear note.
-function resolveSettingsFile(scope: Scope, cwd: string, home: string): string | null {
-  if (scope === 'global') {
-    return join(home, '.claude', 'settings.json')
-  }
-  const root = findRepoRoot(cwd)
-  if (root === null) {
-    return null
-  }
-  return scope === 'project' ? join(root, '.claude', 'settings.json') : join(root, '.claude', 'settings.local.json')
-}
-
-// hooks/ and skills/ ship beside src/ in the package; resolve them off this
-// module's URL the way `start` resolves templates/.
-function packageDir(name: string): string {
-  return fileURLToPath(new URL(`../../${name}/`, import.meta.url))
-}

package/src/verbs/spike.ts

@@ -1,129 +0,0 @@
-// `plumbbob spike` (D18) — the spike lifecycle for a genuine fork the design
-// phase couldn't settle. `spike "<slug>" [opt…]` creates a sibling git worktree +
-// `spike/<slug>-<opt>` branch per option OUTSIDE the repo root (default opts a/b)
-// and sets STATE=SPIKE; the main tree stays DESIGN-locked while you experiment in
-// the worktrees, which are hook-dormant by construction — the untracked sidecar
-// (D17) doesn't exist in a fresh checkout, so the hooks find no STATE there.
-// `spike done` removes every spike worktree + branch and returns to DESIGN.
-//
-// Worktree git calls run directly here rather than via lib/git.ts (which holds the
-// shared additive read/commit helpers): worktree management is spike-local, and
-// this is the only place Plumbbob creates branches.
-
-import { execFileSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { basename, dirname, join } from 'node:path'
-import { findRepoRoot } from '../lib/git.ts'
-import { hasSession, readState, writeState } from '../lib/sidecar.ts'
-
-const DEFAULT_OPTIONS: ReadonlyArray<string> = ['a', 'b']
-
-export function spike(cwd: string, args: ReadonlyArray<string>): number {
-  const root = findRepoRoot(cwd)
-  if (root === null || !hasSession(root)) {
-    process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n')
-    return 1
-  }
-  const positionals = args.filter((a) => !a.startsWith('--'))
-  if (positionals[0] === 'done') {
-    return spikeDone(root)
-  }
-  return spikeStart(root, positionals)
-}
-
-function spikeStart(root: string, positionals: ReadonlyArray<string>): number {
-  const state = readState(root)
-  if (state === 'SPIKE') {
-    process.stderr.write('plumbbob: already in a spike. Run `plumbbob spike done` to close it first.\n')
-    return 1
-  }
-  if (state !== 'DESIGN') {
-    process.stderr.write(
-      `plumbbob: spike starts from DESIGN (current state is ${state ?? 'UNKNOWN'}). ` +
-        'A spike is a deliberate fork — close the current step first with `done`.\n',
-    )
-    return 1
-  }
-  const slug = sanitize(positionals[0] ?? '')
-  if (slug.length === 0) {
-    process.stderr.write('plumbbob: spike needs a slug. Try: plumbbob spike "auth-store" a b.\n')
-    return 1
-  }
-  const explicit = positionals.slice(1).map(sanitize).filter((o) => o.length > 0)
-  const options = explicit.length > 0 ? explicit : DEFAULT_OPTIONS
-
-  const created: string[] = []
-  for (const opt of options) {
-    const path = join(dirname(root), `${basename(root)}-spike-${slug}-${opt}`)
-    if (existsSync(path)) {
-      process.stderr.write(`plumbbob: ${path} already exists — remove it or run \`plumbbob spike done\` first.\n`)
-      return 1
-    }
-    git(root, ['worktree', 'add', '-b', `spike/${slug}-${opt}`, path, 'HEAD'])
-    created.push(path)
-  }
-
-  writeState(root, 'SPIKE')
-  process.stdout.write(
-    `plumbbob: STATE=SPIKE — the main tree stays DESIGN-locked. Experiment in the throwaway worktrees:\n${created
-      .map((p) => `  ${p}`)
-      .join('\n')}\nWhen you've decided, record the verdict in intent.md and run \`plumbbob spike done\`.\n`,
-  )
-  return 0
-}
-
-function spikeDone(root: string): number {
-  const state = readState(root)
-  if (state !== 'SPIKE') {
-    process.stderr.write(`plumbbob: no active spike (state is ${state ?? 'UNKNOWN'}).\n`)
-    return 1
-  }
-  for (const path of spikeWorktrees(root)) {
-    git(root, ['worktree', 'remove', '--force', path])
-  }
-  git(root, ['worktree', 'prune'])
-  for (const branch of spikeBranches(root)) {
-    git(root, ['branch', '-D', branch])
-  }
-  writeState(root, 'DESIGN')
-  process.stdout.write(
-    'plumbbob: spike closed — STATE=DESIGN, worktrees and branches removed. ' +
-      'Record the verdict (which option won, and why) in intent.md before you `build`.\n',
-  )
-  return 0
-}
-
-// Worktree paths whose checked-out branch is under spike/ — parsed from the
-// porcelain output (blank-line-separated `worktree <path>` / `branch <ref>` blocks).
-function spikeWorktrees(root: string): ReadonlyArray<string> {
-  const out = git(root, ['worktree', 'list', '--porcelain'])
-  const paths: string[] = []
-  let current: string | null = null
-  for (const line of out.split('\n')) {
-    if (line.startsWith('worktree ')) {
-      current = line.slice('worktree '.length)
-    } else if (current !== null && line.startsWith('branch refs/heads/spike/')) {
-      paths.push(current)
-    }
-  }
-  return paths
-}
-
-function spikeBranches(root: string): ReadonlyArray<string> {
-  const out = git(root, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/spike/'])
-  return out.length === 0 ? [] : out.split('\n').filter((b) => b.length > 0)
-}
-
-function sanitize(raw: string): string {
-  return raw
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-}
-
-function git(root: string, args: ReadonlyArray<string>): string {
-  return execFileSync('git', ['-C', root, ...args], {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'inherit'],
-  }).trim()
-}

package/src/verbs/start.ts

@@ -1,103 +0,0 @@
-// `plumbbob start "<title>"` — scaffold the sidecar, record the baseline, enter
-// DESIGN. Refuses on a dirty tree (D22), an existing session, or a non-git dir.
-
-import { fileURLToPath } from 'node:url'
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
-import { join } from 'node:path'
-import { findRepoRoot, hasCommit, headSha, isDirty } from '../lib/git.ts'
-import {
-  sidecarDir,
-  checkpointsPath,
-  configPath,
-  intentPath,
-  buildLogPath,
-  writeState,
-  hasSession,
-  excludeSidecar,
-} from '../lib/sidecar.ts'
-
-const DEFAULT_CHECK = 'pnpm run check'
-
-export function start(cwd: string, args: ReadonlyArray<string>): number {
-  const positionals = args.filter((a) => !a.startsWith('--'))
-  const allowDirty = args.includes('--allow-dirty')
-  const title = (positionals[0] ?? '').trim()
-
-  if (title.length === 0) {
-    process.stderr.write('plumbbob: start needs a title. Try: plumbbob start "what you are building".\n')
-    return 1
-  }
-
-  const root = findRepoRoot(cwd)
-  if (root === null) {
-    process.stderr.write(
-      'plumbbob: not a git repository. Plumbbob records a baseline commit — run `git init` and make an initial commit first.\n',
-    )
-    return 1
-  }
-  if (!hasCommit(root)) {
-    process.stderr.write(
-      'plumbbob: this repository has no commits yet. Make an initial commit so `start` can record a baseline.\n',
-    )
-    return 1
-  }
-  if (hasSession(root)) {
-    process.stderr.write(
-      'plumbbob: a session is already active here. Run `plumbbob finish` to close it before starting another.\n',
-    )
-    return 1
-  }
-  if (isDirty(root)) {
-    if (!allowDirty) {
-      process.stderr.write(
-        'plumbbob: the working tree is dirty. Commit or stash first, or `plumbbob start --allow-dirty "<title>"` to record the current HEAD as the baseline.\n',
-      )
-      return 1
-    }
-    process.stderr.write(
-      'plumbbob: WARNING --allow-dirty: recording HEAD as baseline with a dirty tree. A later revert-to-baseline will DISCARD the uncommitted work.\n',
-    )
-  }
-
-  const sha = headSha(root)
-  const check = detectCheck(root)
-
-  mkdirSync(sidecarDir(root), { recursive: true })
-  writeState(root, 'DESIGN')
-  writeFileSync(checkpointsPath(root), `baseline ${sha}\n`)
-  writeFileSync(configPath(root), `check=${check.command}\n`)
-  writeFileSync(intentPath(root), stamp(readTemplate('intent.md'), title, check.command))
-  writeFileSync(buildLogPath(root), stamp(readTemplate('build-log.md'), title, check.command))
-  excludeSidecar(root)
-
-  if (check.warn) {
-    process.stderr.write(
-      `plumbbob: WARNING the heavy check '${check.command}' is not defined in this repo's package.json. Edit .plumbbob/config (check=...) to set the real gate before \`review\`/\`done\`.\n`,
-    )
-  }
-  process.stdout.write(
-    `plumbbob: started "${title}" — STATE=DESIGN, baseline ${sha.slice(0, 9)}. Frame and decide in .plumbbob/intent.md; flip to BUILD only once the decisions are made.\n`,
-  )
-  return 0
-}
-
-// D24: default the heavy check to `pnpm run check`; warn (but still record it)
-// when the target repo has no such script, so a non-pnpm repo gets a clear nudge.
-function detectCheck(root: string): { readonly command: string; readonly warn: boolean } {
-  try {
-    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as {
-      scripts?: Record<string, string>
-    }
-    return { command: DEFAULT_CHECK, warn: pkg.scripts?.check === undefined }
-  } catch {
-    return { command: DEFAULT_CHECK, warn: true }
-  }
-}
-
-function readTemplate(name: string): string {
-  return readFileSync(fileURLToPath(new URL(`../../templates/${name}`, import.meta.url)), 'utf8')
-}
-
-function stamp(template: string, title: string, check: string): string {
-  return template.split('{{TITLE}}').join(title).split('{{CHECK}}').join(check)
-}

package/src/verbs/status.ts

@@ -1,15 +0,0 @@
-// `plumbbob status` — print the session state, or NO ACTIVE SESSION. Read-only,
-// always exits 0. Skills pre-inject this output to gate their own behavior.
-
-import { findRepoRoot } from '../lib/git.ts'
-import { hasSession, readState } from '../lib/sidecar.ts'
-
-export function status(cwd: string): number {
-  const root = findRepoRoot(cwd)
-  if (root === null || !hasSession(root)) {
-    process.stdout.write('NO ACTIVE SESSION\n')
-    return 0
-  }
-  process.stdout.write(`STATE: ${readState(root) ?? 'UNKNOWN'}\n`)
-  return 0
-}

package/src/verbs/wrap.ts

@@ -1,34 +0,0 @@
-// `plumbbob wrap` (D19/D28) — the FINISH-entry verb. Sets STATE=FINISH so
-// /plumbbob-report can write report.md and /plumbbob-docs can touch docs/.
-// `finish` stays the closing gate; wrap just opens the one state where
-// documentation may be projected. A transition verb, so dispatch refuses it under
-// CLAUDECODE (D21).
-
-import { findRepoRoot } from '../lib/git.ts'
-import { hasSession, readState, writeState } from '../lib/sidecar.ts'
-
-export function wrap(cwd: string): number {
-  const root = findRepoRoot(cwd)
-  if (root === null || !hasSession(root)) {
-    process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n')
-    return 1
-  }
-  const state = readState(root)
-  if (state === 'FINISH') {
-    process.stdout.write('plumbbob: already in FINISH. Run `/plumbbob-report`, then `plumbbob finish` to close.\n')
-    return 0
-  }
-  if (state !== 'DESIGN') {
-    process.stderr.write(
-      `plumbbob: wrap enters FINISH from DESIGN (current state is ${state ?? 'UNKNOWN'}). ` +
-        'Close the current step first — `done` from BUILD/REVIEW, or `spike done` from SPIKE.\n',
-    )
-    return 1
-  }
-  writeState(root, 'FINISH')
-  process.stdout.write(
-    'plumbbob: STATE=FINISH. Now `/plumbbob-report` writes the report (and `/plumbbob-docs` may touch docs/); ' +
-      'then `plumbbob finish` archives and closes.\n',
-  )
-  return 0
-}