@skitterbyte/skitterspec-linear 3.4.0 → 5.0.0

package/src/cli.js

@@ -3,7 +3,7 @@
 const fs = require('fs')
 const path = require('path')
 const { execFileSync } = require('child_process')
-const { init } = require('./init.js')
+const { init, resync, reset, isExistingSetup } = require('./init.js')
 const {
   detectReleaseTooling,
   removeReleaseTooling,
@@ -21,10 +21,21 @@ const {
   resolveSpec,
   resolveBaseBranch,
   resolvePrimaryCheckout,
+  assertPrimaryOnMain,
   repoInfo,
   expandTokens,
   splitPrefix,
 } = require('./env/resolve.js')
+const {
+  readReceipt,
+  writeReceipt,
+  clearReceipt,
+  summarizeReceipt,
+  migrationsHit,
+  planTake,
+  planRelease,
+  planAbort,
+} = require('./env/live.js')
 const { ensureWorktreeDirTrusted } = require('./env/trust.js')
 const { planUp } = require('./env/provision.js')
 const { planDown } = require('./env/teardown.js')
@@ -39,9 +50,12 @@ const HELP = `skitterspec — spec-driven-development for Claude Code
 
 Usage:
   skitterspec init [dir]      Install the spec lifecycle skills, rule, and specs/
-                              folders into a project
-  skitterspec update [dir]    Re-copy skills + rule (overwrites), leaves specs/
-                              and specs/.core/ config alone
+                              folders. On an already-set-up repo it detects that
+                              and offers resync / start-again / leave (interactive)
+                              — non-interactively it just adds anything missing.
+  skitterspec update [dir]    Resync managed files to the latest, keeping your
+                              edits (--force to overwrite). Leaves specs/ + live
+                              .core config alone.
   skitterspec spec-env <cmd>  Per-spec isolation engine (opt-in; needs
                               specs/.core/env.config.json). Subcommands:
                                 up <spec>         plan a worktree + Docker stack + opener
@@ -56,6 +70,9 @@ Usage:
   skitterspec --version       Print version
 
 Options (init / update):
+  --resync                 (init) Update managed files to latest, keep your edits
+  --reset                  (init) Start again: reset managed scaffolding fresh
+                           (needs --yes; never touches your specs or config)
   --force                  Overwrite skill/rule/script files that already exist
   --dir <path>             Target project dir (default: positional arg or cwd)
   --no-claude-md           Skip creating/patching CLAUDE.md
@@ -80,6 +97,8 @@ function parse(argv) {
     yes: false,
     isolation: undefined,
     removeReleaseTooling: false,
+    resync: false,
+    reset: false,
   }
   const positional = []
   for (let i = 0; i < argv.length; i++) {
@@ -90,6 +109,8 @@ function parse(argv) {
     else if (a === '--isolation') opts.isolation = true
     else if (a === '--no-isolation') opts.isolation = false
     else if (a === '--remove-release-tooling') opts.removeReleaseTooling = true
+    else if (a === '--resync') opts.resync = true
+    else if (a === '--reset') opts.reset = true
     else if (a === '--dir') opts.dir = argv[++i]
     else if (a.startsWith('--')) throw new Error(`unknown option: ${a}`)
     else positional.push(a)
@@ -348,21 +369,43 @@ function specEnvIntegrate(dir, config, specArg) {
 
   // `dir` is already anchored on the primary checkout by the dispatch, so it is
   // both where the spec resolves and the target of the fast-forward — /spec-complete
-  // can run this from inside the worktree and still land on main.
-  //
-  // A spec authored entirely on its branch may not exist in the primary
-  // checkout's specs/** (it was never committed to base) — but its worktree
-  // does, and the worktree path is derivable from config without the folder.
-  // Offer it as a fallback search location so integrate can still find the spec.
-  const { slug } = splitPrefix(path.basename(specArg))
-  const { repo, repoSlug } = repoInfo(dir)
-  const wtTokens = { repo, repoSlug, slug }
-  const worktreeGuess = path.resolve(
-    dir,
-    expandTokens(config.worktree.root, wtTokens),
-    expandTokens(config.worktree.folderPattern, wtTokens),
-  )
-  const spec = resolveSpec(specArg, dir, config, { searchDirs: [worktreeGuess] })
+  // can run this from inside the worktree and still land on main. A spec authored
+  // entirely on its branch may not exist in the primary checkout's specs/** —
+  // resolveSpecWithWorktree offers its worktree as a fallback search location.
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
+  const base = resolveBaseBranch(config, gitReader(dir))
+
+  // Live-aware: if this spec is live on the primary checkout (branch-switched by
+  // `live take`), end the live session first — release back to base, re-isolate the
+  // branch, clear the receipt — so the normal rebase→ff plan below applies
+  // unchanged. Refuse if a *different* spec holds the primary checkout.
+  const primary = assertPrimaryOnMain(config, gitReader(dir))
+  if (!primary.onBase) {
+    if (primary.branch !== spec.branch) {
+      process.stdout.write(
+        `spec-env integrate: blocked — another spec (${primary.branch}) holds the ` +
+          'primary checkout; release it with `/spec-live main` first.\n',
+      )
+      return
+    }
+    const pstatus = gitReader(dir)(['status', '--porcelain'])
+    if (pstatus === null || pstatus.length > 0) {
+      process.stdout.write(
+        `spec-env integrate: blocked — commit your live fixes to ${spec.branch} first.\n`,
+      )
+      return
+    }
+    const co = runGit(dir, ['checkout', base])
+    if (!co.ok) {
+      process.stdout.write(`spec-env integrate: could not check out ${base} — ${co.err}\n`)
+      return
+    }
+    if (fs.existsSync(spec.worktreePath)) runGit(spec.worktreePath, ['switch', spec.branch])
+    clearReceipt(dir, config)
+    process.stdout.write(
+      `spec-env integrate: ended live session — ${spec.folder} released to its worktree.\n`,
+    )
+  }
 
   if (!fs.existsSync(spec.worktreePath)) {
     process.stdout.write(
@@ -371,7 +414,6 @@ function specEnvIntegrate(dir, config, specArg) {
     return
   }
 
-  const base = resolveBaseBranch(config, gitReader(dir))
   const wtGit = gitReader(spec.worktreePath)
   const status = wtGit(['status', '--porcelain'])
   const dirty = status !== null && status.length > 0
@@ -588,6 +630,276 @@ async function specEnvConnect(dir, config, specArg) {
 
 // Dispatch `skitterspec spec-env <sub> [args] [--dir path]`. No-ops with a clear
 // message when the feature isn't enabled (no specs/.core/env.config.json).
+// Run a mutating git command; return { ok, err } (stderr captured, not swallowed).
+function runGit(cwd, args) {
+  try {
+    execFileSync('git', ['-C', cwd, ...args], { stdio: ['ignore', 'pipe', 'pipe'] })
+    return { ok: true, err: '' }
+  } catch (error) {
+    const err = (error.stderr && error.stderr.toString().trim()) || error.message
+    return { ok: false, err }
+  }
+}
+
+// Lockfiles/manifests whose change means a dev server needs a restart, not HMR.
+const DEPS_RE = /(^|\/)(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.lock)$/
+
+// Live overlay: test a spec on the already-running instance by checking its
+// branch out in the primary checkout, so the running dev server hot-reloads the
+// feature. The branch that's checked out IS the lock (assertPrimaryOnMain); the
+// receipt is advisory metadata. `status` is read-only; `take` performs the switch
+// (release/abort land in a later phase).
+async function specEnvLive(dir, config, positional) {
+  const action = positional[0] || 'status'
+  switch (action) {
+    case 'status':
+      specEnvLiveStatus(dir, config)
+      break
+    case 'take':
+      await specEnvLiveTake(dir, config, positional[1])
+      break
+    case 'release':
+      await specEnvLiveRelease(dir, config, positional[1])
+      break
+    case 'abort':
+      await specEnvLiveAbort(dir, config)
+      break
+    default:
+      process.stdout.write('Usage: skitterspec spec-env live <take|release|abort|status> [spec]\n')
+  }
+}
+
+// Resolve a spec, offering its worktree as a fallback search dir — a spec authored
+// on its own branch may not exist in the primary checkout's specs/**.
+function resolveSpecWithWorktree(dir, config, specArg) {
+  const { slug } = splitPrefix(path.basename(specArg))
+  const { repo, repoSlug } = repoInfo(dir)
+  const wtTokens = { repo, repoSlug, slug }
+  const worktreeGuess = path.resolve(
+    dir,
+    expandTokens(config.worktree.root, wtTokens),
+    expandTokens(config.worktree.folderPattern, wtTokens),
+  )
+  return resolveSpec(specArg, dir, config, { searchDirs: [worktreeGuess] })
+}
+
+// Take the running instance: rebase the spec's branch onto base, free it from its
+// worktree, and check it out in the primary checkout so the dev server reloads it.
+async function specEnvLiveTake(dir, config, specArg) {
+  if (!specArg) {
+    process.stdout.write('Usage: skitterspec spec-env live take <spec>\n')
+    return
+  }
+
+  const spec = resolveSpecWithWorktree(dir, config, specArg)
+
+  // Probe the primary checkout's git state (IO stays here; the planner is pure).
+  const primaryGit = gitReader(dir)
+  const primary = assertPrimaryOnMain(config, primaryGit)
+  const base = resolveBaseBranch(config, primaryGit)
+  const status = primaryGit(['status', '--porcelain'])
+  const clean = status !== null && status.length === 0
+  const worktreeExists = fs.existsSync(spec.worktreePath)
+  const baseMainCommit = primaryGit(['rev-parse', 'HEAD'])
+
+  // Diff base...branch to spot migration / dependency changes (best-effort).
+  const changed = primaryGit(['diff', '--name-only', `${base}...${spec.branch}`])
+  const files = changed ? changed.split('\n').filter(Boolean) : []
+  const depsChanged = files.some((f) => DEPS_RE.test(f))
+
+  // Verify-only: probe the declared canonical (frontPort) ports. None declared →
+  // no health gate (serverUp = null); the switch proceeds with a warning.
+  const canonicalPorts = config.dev.map((d) => d.frontPort).filter((p) => typeof p === 'number')
+  let serverUp = null
+  if (canonicalPorts.length) {
+    const up = await portsInUse(canonicalPorts, config.proxy.host)
+    serverUp = up.length === canonicalPorts.length
+  }
+
+  const plan = planTake(spec, config, {
+    primary,
+    primaryPath: dir,
+    clean,
+    worktreeExists,
+    base,
+    baseMainCommit,
+    serverUp,
+    canonicalPorts,
+    migrationsHit: migrationsHit(files, config.live.migrations),
+    depsChanged,
+    holder: primaryGit(['config', 'user.name']) || 'unknown',
+    heldSince: new Date().toISOString(),
+  })
+
+  if (plan.blocked) {
+    process.stdout.write(`spec-env live take: blocked — ${plan.reason}.\n`)
+    return
+  }
+
+  // Execute the switch. Rebase first; on conflict, abort and bail (state untouched).
+  const reb = runGit(spec.worktreePath, ['rebase', base])
+  if (!reb.ok) {
+    runGit(spec.worktreePath, ['rebase', '--abort'])
+    process.stdout.write(
+      `spec-env live take: rebase of ${spec.branch} onto ${base} hit conflicts — ` +
+        `resolve them in ${spec.worktreePath}, then retry.\n`,
+    )
+    return
+  }
+  const det = runGit(spec.worktreePath, ['switch', '--detach'])
+  if (!det.ok) {
+    process.stdout.write(`spec-env live take: could not detach the worktree — ${det.err}\n`)
+    return
+  }
+  const co = runGit(dir, ['checkout', spec.branch])
+  if (!co.ok) {
+    // Roll the detach back so the worktree keeps its branch.
+    runGit(spec.worktreePath, ['switch', spec.branch])
+    process.stdout.write(
+      `spec-env live take: could not check out ${spec.branch} in the primary ` +
+        `checkout — ${co.err}\n`,
+    )
+    return
+  }
+  const receipt = writeReceipt(dir, config, plan.receipt)
+
+  const out = [`spec-env live take: ${spec.folder} is live on the primary checkout`]
+  out.push('')
+  out.push(`  primary:   now on ${receipt.branch} (was ${base} @ ${receipt.baseMainCommit.slice(0, 7)})`)
+  out.push(`  worktree:  ${spec.worktreePath} (detached — branch handed to the primary checkout)`)
+  for (const w of plan.warnings) out.push(`  ! ${w}`)
+  out.push('')
+  out.push('  Test at your canonical URL; release with: /spec-live main')
+  process.stdout.write(out.join('\n') + '\n')
+}
+
+// Release the running instance: hand the primary checkout back to base and
+// re-isolate the spec's branch into its worktree. With no spec arg, the live spec
+// is read from the receipt (this is what `/spec-live main` runs).
+async function specEnvLiveRelease(dir, config, specArg) {
+  const receipt = readReceipt(dir, config)
+  const target = specArg || (receipt && receipt.spec)
+  if (!target) {
+    const primaryGit = gitReader(dir)
+    const primary = assertPrimaryOnMain(config, primaryGit)
+    process.stdout.write(
+      primary.onBase
+        ? `spec-env live release: nothing is live — the primary checkout is on ${primary.baseBranch}.\n`
+        : `spec-env live release: no receipt, but the primary checkout is on ${primary.branch} — ` +
+            'use `spec-env live abort` to recover.\n',
+    )
+    return
+  }
+
+  const spec = resolveSpecWithWorktree(dir, config, target)
+  const primaryGit = gitReader(dir)
+  const primary = assertPrimaryOnMain(config, primaryGit)
+  const base = resolveBaseBranch(config, primaryGit)
+  const status = primaryGit(['status', '--porcelain'])
+  const clean = status !== null && status.length === 0
+  const worktreeExists = fs.existsSync(spec.worktreePath)
+
+  const plan = planRelease(spec, config, {
+    primary,
+    primaryPath: dir,
+    base,
+    clean,
+    worktreeExists,
+  })
+
+  if (plan.noop) {
+    process.stdout.write(`spec-env live release: ${plan.reason}.\n`)
+    return
+  }
+  if (plan.blocked) {
+    process.stdout.write(`spec-env live release: blocked — ${plan.reason}.\n`)
+    return
+  }
+
+  const co = runGit(dir, ['checkout', base])
+  if (!co.ok) {
+    process.stdout.write(`spec-env live release: could not check out ${base} — ${co.err}\n`)
+    return
+  }
+  if (worktreeExists) runGit(spec.worktreePath, ['switch', spec.branch])
+  clearReceipt(dir, config)
+
+  process.stdout.write(
+    `spec-env live release: ${spec.folder} released — primary back on ${base}, ` +
+      `${spec.branch} re-isolated to its worktree.\n`,
+  )
+}
+
+// Crash recovery: force the primary checkout back to base from the receipt and
+// re-isolate, without discarding uncommitted work (it refuses on a dirty tree).
+async function specEnvLiveAbort(dir, config) {
+  const receipt = readReceipt(dir, config)
+  const primaryGit = gitReader(dir)
+  const primary = assertPrimaryOnMain(config, primaryGit)
+  const base = resolveBaseBranch(config, primaryGit)
+  const status = primaryGit(['status', '--porcelain'])
+  const clean = status !== null && status.length === 0
+
+  // Resolve the worktree from the receipt (best-effort — may be gone/unresolvable).
+  let worktreePath = null
+  if (receipt) {
+    try {
+      worktreePath = resolveSpecWithWorktree(dir, config, receipt.spec).worktreePath
+    } catch {
+      worktreePath = null
+    }
+  }
+  const worktreeExists = worktreePath !== null && fs.existsSync(worktreePath)
+
+  const plan = planAbort(config, {
+    receipt,
+    primary,
+    primaryPath: dir,
+    base,
+    clean,
+    worktreeExists,
+    worktreePath,
+  })
+
+  if (plan.noop) {
+    process.stdout.write(`spec-env live abort: ${plan.reason}.\n`)
+    return
+  }
+  if (plan.blocked) {
+    process.stdout.write(`spec-env live abort: blocked — ${plan.reason}.\n`)
+    return
+  }
+
+  if (!primary.onBase) {
+    const co = runGit(dir, ['checkout', base])
+    if (!co.ok) {
+      process.stdout.write(`spec-env live abort: could not check out ${base} — ${co.err}\n`)
+      return
+    }
+  }
+  if (worktreeExists) runGit(worktreePath, ['switch', plan.branch])
+  clearReceipt(dir, config)
+
+  process.stdout.write(
+    `spec-env live abort: recovered — primary back on ${base}` +
+      (worktreeExists ? `, ${plan.branch} re-isolated to its worktree` : '') +
+      '.\n',
+  )
+}
+
+function specEnvLiveStatus(dir, config) {
+  const { onBase, branch, baseBranch } = assertPrimaryOnMain(config, gitReader(dir))
+  const receipt = readReceipt(dir, config)
+  const state = onBase
+    ? 'on base — free'
+    : `feature in control — not on ${baseBranch}`
+  process.stdout.write(
+    'spec-env live:\n' +
+      `  primary:   ${branch || '(detached)'}  (${state})\n` +
+      `  receipt:   ${summarizeReceipt(receipt)}\n`,
+  )
+}
+
 async function specEnv(rest) {
   const [sub, ...args] = rest
   let dir = process.cwd()
@@ -635,9 +947,12 @@ async function specEnv(rest) {
     case 'resolve':
       specEnvResolve(dir, config, positional[0])
       break
+    case 'live':
+      await specEnvLive(dir, config, positional)
+      break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|dev|connect|integrate|status|resolve> [spec] [--keep-volumes] [--force]\n',
+        'Usage: skitterspec spec-env <up|down|dev|connect|integrate|live|status|resolve> [spec] [--keep-volumes] [--force]\n',
       )
   }
 }
@@ -664,21 +979,54 @@ async function run(argv) {
 
   switch (cmd) {
     case 'init': {
-      // Isolation defaults OFF; a flag or an interactive "yes" opts in.
-      let isolation = opts.isolation === true
-
       const interactive = Boolean(process.stdin.isTTY) && !opts.yes
-      if (interactive) {
-        const { promptSetup } = require('./prompts.js')
-        const result = await promptSetup({ isolationSeed: isolation })
-        isolation = result.isolation
+
+      // Already set up? Route to resync / reset / leave instead of a silent
+      // create-missing (safer-init). A fresh repo falls straight through.
+      if (isExistingSetup(dir)) {
+        let action
+        if (opts.reset) {
+          if (!opts.yes) {
+            process.stdout.write('init: --reset overwrites managed files — re-run with --yes. Left unchanged.\n')
+            break
+          }
+          action = 'reset'
+        } else if (opts.resync) action = 'resync'
+        else if (opts.force) action = 'resync' // --force resyncs, clobbering customized
+        else if (interactive) {
+          const { promptExistingSetup } = require('./prompts.js')
+          action = await promptExistingSetup()
+        } else action = 'create-missing' // non-interactive default: add missing, never clobber
+
+        if (action === 'leave') {
+          process.stdout.write('init: existing setup left unchanged.\n')
+          break
+        }
+        if (action === 'reset') {
+          reset(dir, { claudeMd: opts.claudeMd })
+          break
+        }
+        if (action === 'resync') {
+          resync(dir, { claudeMd: opts.claudeMd, force: opts.force })
+          break
+        }
+        // action === 'create-missing' → fall through to a normal (skip-existing) init.
       }
 
+      // Fresh repo (or create-missing): isolation defaults OFF; a flag or an
+      // interactive "yes" opts in. Only prompt for isolation on a fresh repo.
+      let isolation = opts.isolation === true
+      if (interactive && !isExistingSetup(dir)) {
+        const { promptSetup } = require('./prompts.js')
+        isolation = (await promptSetup({ isolationSeed: isolation })).isolation
+      }
       await init({ dir, force: opts.force, claudeMd: opts.claudeMd, mode: 'init', isolation })
       break
     }
     case 'update':
-      await init({ dir, force: true, claudeMd: opts.claudeMd, mode: 'update' })
+      // `update` is a resync — refresh managed files, keep customized ones
+      // (--force to overwrite). Leaves specs/ and live .core config alone.
+      resync(dir, { claudeMd: opts.claudeMd, force: opts.force })
       await cleanupReleaseTooling(dir, opts)
       break
     default:

package/src/env/config.js

@@ -28,7 +28,9 @@
  *     registry: ".spec-env/registry.json",
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
  *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
- *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed }
+ *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
+ *     live:     { migrations: [ "glob", ... ] }  // migration globs → `live take`
+ *               // refuses a branch that changes them (code-only v1)
  *   }
  */
 
@@ -74,6 +76,10 @@ const DEFAULT_CONFIG = Object.freeze({
   // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
   baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
+  // Live overlay (`spec-env live`). `migrations` is a list of globs marking
+  // migration files; a branch that changes any of them is treated as stateful and
+  // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
+  live: Object.freeze({ migrations: Object.freeze([]) }),
 })
 
 function isObject(value) {
@@ -94,6 +100,7 @@ function defaults() {
     branch: { ...DEFAULT_CONFIG.branch },
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
+    live: { migrations: [] },
   }
 }
 
@@ -237,6 +244,10 @@ function mergeConfig(base, parsed) {
     assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
   }
 
+  if (isObject(parsed.live) && Array.isArray(parsed.live.migrations)) {
+    base.live.migrations = normalizeFileList(parsed.live.migrations)
+  }
+
   return base
 }