@skitterbyte/skitterspec 2.0.1 → 3.0.0

package/src/cli.js

@@ -22,6 +22,9 @@ const { ensureWorktreeDirTrusted } = require('./env/trust.js')
 const { planUp } = require('./env/provision.js')
 const { planDown } = require('./env/teardown.js')
 const { planIntegrate } = require('./env/integrate.js')
+const { planDev } = require('./env/dev.js')
+const { startProcess, stopProcess, waitHealthy } = require('./env/supervise.js')
+const { renderRoutes, portsInUse, waitListening } = require('./env/proxy.js')
 
 const pkg = require('../package.json')
 
@@ -36,6 +39,9 @@ Usage:
                               specs/.core/env.config.json). Subcommands:
                                 up <spec>         plan a worktree + Docker stack + opener
                                 down <spec>       tear down (guards; --keep-volumes, --force)
+                                dev up <spec>     start host dev servers on the spec's ports
+                                dev down <spec>   stop the spec's host dev servers
+                                connect <spec>    expose a spec on the canonical ports (main = off)
                                 integrate <spec>  plan rebase + fast-forward onto the base branch
                                 status            list provisioned specs + port blocks
                                 resolve <spec>    print resolved slug/type/branch/paths
@@ -401,9 +407,171 @@ function specEnvResolve(dir, config, specArg) {
   )
 }
 
+// Start/stop a spec's host dev servers on its reserved port block. Host dev
+// servers (e.g. `pnpm dev`) need a block even on a worktree-only spec, so `up`
+// allocates a slot if the spec has none (idempotent). The planner is pure
+// (dev.js); the spawning/killing lives in supervise.js.
+async function specEnvDev(dir, config, positional) {
+  const action = positional[0]
+  const specArg = positional[1]
+  if ((action !== 'up' && action !== 'down') || !specArg) {
+    process.stdout.write('Usage: skitterspec spec-env dev <up|down> <spec>\n')
+    return
+  }
+  const spec = resolveSpec(specArg, dir, config)
+  if (!config.dev.length) {
+    process.stdout.write(
+      'spec-env dev: no dev processes configured — set "dev": [...] in env.config.json.\n',
+    )
+    return
+  }
+
+  const registry = readRegistry(dir, config)
+  let slot
+  if (action === 'up') {
+    // Ensure a slot (idempotent) so the port block is reserved even worktree-only.
+    const alloc = allocateSlot(registry, spec.folder)
+    slot = alloc.slot
+    writeRegistry(dir, config, alloc.registry)
+  } else {
+    // Teardown only needs the pid-file paths (keyed by folder, not slot), so the
+    // slot value is immaterial — use the existing one, or 0 as a placeholder.
+    slot = Object.prototype.hasOwnProperty.call(registry.slots, spec.folder)
+      ? registry.slots[spec.folder]
+      : 0
+  }
+
+  const plan = planDev(spec, slot, config)
+
+  if (action === 'up') {
+    const out = [`spec-env dev up: ${spec.folder}  slot ${slot}  (ports from ${plan.portOffset})`]
+    for (const proc of plan.procs) {
+      const res = startProcess(proc, { cwd: spec.worktreePath, rootDir: dir })
+      let health = ''
+      if (proc.health) {
+        health = (await waitHealthy(proc.health)) ? '  health: ok' : '  health: TIMEOUT'
+      }
+      out.push(
+        `  ${proc.name}: port ${proc.port}  pid ${res.pid}  ` +
+          `${res.started ? 'started' : 'already running'}${health}`,
+      )
+    }
+    out.push('')
+    out.push(`  logs: ${stateDirLabel(config)}/logs/`)
+    process.stdout.write(out.join('\n') + '\n')
+  } else {
+    const out = [`spec-env dev down: ${spec.folder}`]
+    for (const proc of plan.procs) {
+      const res = await stopProcess(proc, { rootDir: dir })
+      out.push(`  ${proc.name}: ${res.stopped ? `stopped (pid ${res.pid})` : 'not running'}`)
+    }
+    process.stdout.write(out.join('\n') + '\n')
+  }
+}
+
+// The `.spec-env`-style state dir label for user-facing messages.
+function stateDirLabel(config) {
+  return path.posix.dirname(config.registry) || '.spec-env'
+}
+
+// The supervised proxy process descriptor (paths relative to the checkout root).
+function proxyProcFor(config, routesFileAbs) {
+  const sdir = stateDirLabel(config)
+  return {
+    name: 'proxy',
+    command: `node ${path.join(__dirname, 'env', 'proxy.js')} ${routesFileAbs}`,
+    env: {},
+    logFile: `${sdir}/logs/proxy.log`,
+    pidFile: `${sdir}/pids/proxy.pid`,
+  }
+}
+
+// Connect the canonical origin to ONE spec (exclusive model): (re)start the
+// bundled proxy pointing at that spec's warm dev servers. `connect main` stops
+// the proxy so the primary checkout owns the canonical ports again.
+async function specEnvConnect(dir, config, specArg) {
+  const sdir = stateDirLabel(config)
+  const abs = (rel) => path.resolve(dir, rel)
+  const routesFile = `${sdir}/proxy.json`
+  const connectedFile = `${sdir}/connected`
+  const proxyProc = proxyProcFor(config, abs(routesFile))
+  const target = specArg || 'main'
+
+  if (target === 'main') {
+    const res = await stopProcess(proxyProc, { rootDir: dir })
+    for (const f of [connectedFile, routesFile]) {
+      try {
+        fs.unlinkSync(abs(f))
+      } catch {
+        /* not connected */
+      }
+    }
+    process.stdout.write(
+      res.stopped
+        ? 'spec-connect: disconnected — the primary checkout owns the canonical ports again.\n'
+        : 'spec-connect: nothing was connected — the primary checkout already owns the ports.\n',
+    )
+    return
+  }
+
+  const spec = resolveSpec(target, dir, config)
+  const registry = readRegistry(dir, config)
+  if (!Object.prototype.hasOwnProperty.call(registry.slots, spec.folder)) {
+    process.stdout.write(
+      `spec-connect: ${spec.folder} has no reserved ports yet — ` +
+        `run \`skitterspec spec-env dev up ${spec.folder}\` first.\n`,
+    )
+    return
+  }
+
+  const plan = planDev(spec, registry.slots[spec.folder], config)
+  const routes = renderRoutes(plan.procs)
+  if (!routes.length) {
+    process.stdout.write(
+      'spec-connect: no dev process declares a frontPort — nothing to expose.\n',
+    )
+    return
+  }
+
+  // Stop any proxy we already run (a previous connect), freeing the canonical
+  // ports, then refuse if the primary checkout still holds one of them.
+  await stopProcess(proxyProc, { rootDir: dir })
+  const busy = await portsInUse(routes.map((r) => r.frontPort), config.proxy.host)
+  if (busy.length) {
+    process.stdout.write(
+      `spec-connect: canonical port(s) ${busy.join(', ')} are in use (your main dev server?).\n` +
+        'Stop main on those ports, then re-run spec-connect.\n',
+    )
+    return
+  }
+
+  fs.mkdirSync(abs(sdir), { recursive: true })
+  fs.writeFileSync(abs(routesFile), JSON.stringify(routes, null, 2) + '\n')
+  const res = startProcess(proxyProc, { cwd: dir, rootDir: dir })
+  fs.writeFileSync(abs(connectedFile), spec.folder + '\n')
+
+  const ready = await waitListening(
+    routes.map((r) => r.frontPort),
+    { host: config.proxy.host },
+  )
+
+  const out = [
+    `spec-connect: ${spec.folder} → canonical ports (proxy pid ${res.pid})` +
+      (ready ? '' : '  [WARNING: proxy did not come up — see .spec-env/logs/proxy.log]'),
+  ]
+  for (const r of routes) {
+    out.push(
+      `  http://${config.proxy.host}:${r.frontPort}  →  ${r.name} (127.0.0.1:${r.targetPort})`,
+    )
+  }
+  out.push('')
+  out.push('  Disconnect with: skitterspec spec-env connect main')
+  process.stdout.write(out.join('\n') + '\n')
+}
+
 // 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).
-function specEnv(rest) {
+async function specEnv(rest) {
   const [sub, ...args] = rest
   let dir = process.cwd()
   const positional = []
@@ -432,6 +600,12 @@ function specEnv(rest) {
     case 'down':
       specEnvDown(dir, config, positional[0], flags)
       break
+    case 'dev':
+      await specEnvDev(dir, config, positional)
+      break
+    case 'connect':
+      await specEnvConnect(dir, config, positional[0])
+      break
     case 'integrate':
       specEnvIntegrate(dir, config, positional[0])
       break
@@ -443,7 +617,7 @@ function specEnv(rest) {
       break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|integrate|status|resolve> [spec] [--keep-volumes] [--force]\n',
+        'Usage: skitterspec spec-env <up|down|dev|connect|integrate|status|resolve> [spec] [--keep-volumes] [--force]\n',
       )
   }
 }
@@ -461,7 +635,7 @@ async function run(argv) {
   const [cmd, ...rest] = argv
 
   if (cmd === 'spec-env') {
-    specEnv(rest)
+    await specEnv(rest)
     return
   }
 

package/src/env/config.js

@@ -16,6 +16,9 @@
  *     worktree: { root, folderPattern },
  *     docker:   { enabled, composeFile, projectNamePattern, portBase,
  *                 portsPerSpec, envFile, backupCommand },
+ *     dev:      [ { name, command, portVar, health?, frontPort? } ],  // host dev
+ *               // servers started on the spec's port block (empty = none)
+ *     proxy:    { enabled, host },  // bundled front-door proxy (spec-env connect)
  *     open:     { command },   // optional, editor/terminal-agnostic opener
  *     registry: ".spec-env/registry.json",
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
@@ -40,6 +43,12 @@ const DEFAULT_CONFIG = Object.freeze({
     envFile: '.env',
     backupCommand: '',
   }),
+  // Host dev servers started on the spec's port block by `spec-env dev up`.
+  // Each: { name, command, portVar, health?, frontPort? }. Default: none.
+  dev: Object.freeze([]),
+  // Front-door proxy (`spec-env connect`): a bundled Node reverse proxy that
+  // exposes one connected spec's frontPort processes on the canonical ports.
+  proxy: Object.freeze({ enabled: true, host: '127.0.0.1' }),
   open: Object.freeze({ command: '' }),
   registry: '.spec-env/registry.json',
   // Git branch naming, provider-neutral. `pattern` expands {type}/{slug} and,
@@ -61,6 +70,8 @@ function defaults() {
   return {
     worktree: { ...DEFAULT_CONFIG.worktree },
     docker: { ...DEFAULT_CONFIG.docker },
+    dev: [],
+    proxy: { ...DEFAULT_CONFIG.proxy },
     open: { ...DEFAULT_CONFIG.open },
     registry: DEFAULT_CONFIG.registry,
     branch: { ...DEFAULT_CONFIG.branch },
@@ -85,6 +96,30 @@ function assign(base, parsed, key, type) {
   }
 }
 
+/**
+ * Normalise a parsed `dev` array into well-formed process entries. Each entry
+ * needs non-empty string `name`, `command`, and `portVar`; `health` (string) and
+ * `frontPort` (finite number) are optional. Malformed entries are dropped
+ * (lenient, like the rest of the loader) so a stray entry can't crash provisioning.
+ */
+function normalizeDev(parsed) {
+  const out = []
+  for (const raw of parsed) {
+    if (!isObject(raw)) continue
+    const name = typeof raw.name === 'string' ? raw.name.trim() : ''
+    const command = typeof raw.command === 'string' ? raw.command.trim() : ''
+    const portVar = typeof raw.portVar === 'string' ? raw.portVar.trim() : ''
+    if (!name || !command || !portVar) continue
+    const entry = { name, command, portVar }
+    if (typeof raw.health === 'string' && raw.health.trim()) entry.health = raw.health.trim()
+    if (typeof raw.frontPort === 'number' && Number.isFinite(raw.frontPort)) {
+      entry.frontPort = raw.frontPort
+    }
+    out.push(entry)
+  }
+  return out
+}
+
 /**
  * Merge a parsed config over the defaults. Only known keys are copied (unknown
  * keys ignored for forward-compat). Nested objects are merged field-by-field.
@@ -107,6 +142,15 @@ function mergeConfig(base, parsed) {
     assign(base.docker, parsed.docker, 'backupCommand', 'string?')
   }
 
+  if (Array.isArray(parsed.dev)) {
+    base.dev = normalizeDev(parsed.dev)
+  }
+
+  if (isObject(parsed.proxy)) {
+    assign(base.proxy, parsed.proxy, 'enabled', 'boolean')
+    assign(base.proxy, parsed.proxy, 'host', 'string')
+  }
+
   if (isObject(parsed.open)) {
     // command may be intentionally empty (no auto-open)
     assign(base.open, parsed.open, 'command', 'string?')

package/src/env/dev.js

@@ -0,0 +1,63 @@
+'use strict'
+
+/**
+ * Pure planner for host dev-process supervision (`spec-env dev up|down`).
+ *
+ * Given a resolved spec and its allocated slot, `planDev` computes — for each
+ * configured `dev` process — its resolved port, the env var to inject, the log
+ * and pid file paths, the expanded health URL, and the canonical `frontPort` a
+ * later proxy (Phase 2) routes to it. No side effects: the CLI's `supervise.js`
+ * does the spawning/killing; this stays unit-testable with no processes.
+ *
+ * Port math: process `i` in the slot's block gets `portBase + slot*portsPerSpec
+ * + i` (reusing the same block the Docker stack draws from — see registry.js).
+ * So host dev servers get a reserved block even on a worktree-only spec.
+ *
+ * Log/pid files live beside the registry (default `.spec-env/`) and are keyed by
+ * the spec **folder** (not the bare slug) so a `feat-foo`/`bug-foo` pair can't
+ * collide — matching how the registry keys slots.
+ */
+
+const path = require('node:path')
+const { portOffset } = require('./registry.js')
+const { expandTokens } = require('./resolve.js')
+
+// The state dir (logs + pids) sits beside the registry file, e.g. `.spec-env`.
+function stateDir(config) {
+  return path.posix.dirname(config.registry) || '.spec-env'
+}
+
+/**
+ * Plan the host dev processes for `spec` at `slot`.
+ *
+ * @returns {object} { slot, portOffset, procs: [{ name, command, port, portVar,
+ *   env, frontPort, logFile, pidFile, health }] } — logFile/pidFile are paths
+ *   relative to the primary checkout root (the CLI resolves them).
+ */
+function planDev(spec, slot, config) {
+  const base = portOffset(slot, config)
+  const dir = stateDir(config)
+  const procs = (config.dev || []).map((entry, i) => {
+    const port = base + i
+    const tokens = {
+      [entry.portVar]: String(port),
+      port: String(port),
+      slug: spec.slug,
+      name: entry.name,
+    }
+    return {
+      name: entry.name,
+      command: expandTokens(entry.command, tokens),
+      port,
+      portVar: entry.portVar,
+      env: { [entry.portVar]: String(port) },
+      frontPort: typeof entry.frontPort === 'number' ? entry.frontPort : null,
+      logFile: `${dir}/logs/${spec.folder}-${entry.name}.log`,
+      pidFile: `${dir}/pids/${spec.folder}-${entry.name}.pid`,
+      health: entry.health ? expandTokens(entry.health, tokens) : null,
+    }
+  })
+  return { slot, portOffset: base, procs }
+}
+
+module.exports = { planDev, stateDir }

package/src/env/proxy.js

@@ -0,0 +1,159 @@
+'use strict'
+
+/**
+ * Front-door reverse proxy for `spec-env connect` — a small, dependency-free
+ * Node proxy that exposes the ONE connected spec's warm dev servers on the
+ * canonical ports (exclusive model: no cookie, one target at a time).
+ *
+ * `renderRoutes` is pure (procs → routes). `startProxy` builds one `http` server
+ * per route, forwarding HTTP and `upgrade` (WebSocket/HMR) to the spec's port.
+ * Run directly (`node proxy.js <routesFile>`) it becomes the long-lived,
+ * detached proxy process the CLI supervises with the Phase 1 seam.
+ */
+
+const http = require('node:http')
+const net = require('node:net')
+const fs = require('node:fs')
+
+/**
+ * The connected spec's `dev` processes that declare a `frontPort` → proxy routes.
+ * @param {Array} procs  from `planDev(...).procs`
+ * @returns {Array<{name, frontPort, targetPort}>}
+ */
+function renderRoutes(procs) {
+  return (procs || [])
+    .filter((p) => typeof p.frontPort === 'number')
+    .map((p) => ({ name: p.name, frontPort: p.frontPort, targetPort: p.port }))
+}
+
+// Build (but don't listen on) one proxy server: frontPort → targetPort. Forwards
+// regular requests and transparently pipes `upgrade` (WebSocket) connections.
+function createRouteServer(route, host = '127.0.0.1') {
+  const { targetPort } = route
+
+  const server = http.createServer((req, res) => {
+    const upstream = http.request(
+      { host, port: targetPort, method: req.method, path: req.url, headers: req.headers },
+      (ur) => {
+        res.writeHead(ur.statusCode || 502, ur.headers)
+        ur.pipe(res)
+      },
+    )
+    upstream.on('error', () => {
+      if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain' })
+      res.end(`spec-connect: upstream 127.0.0.1:${targetPort} not reachable\n`)
+    })
+    req.pipe(upstream)
+  })
+
+  // WebSocket / HTTP upgrade passthrough — reconstruct the request line + headers
+  // onto a raw TCP connection to the upstream, then pipe both ways.
+  server.on('upgrade', (req, socket, head) => {
+    const upstream = net.connect(targetPort, host, () => {
+      let raw = `${req.method} ${req.url} HTTP/1.1\r\n`
+      for (let i = 0; i < req.rawHeaders.length; i += 2) {
+        raw += `${req.rawHeaders[i]}: ${req.rawHeaders[i + 1]}\r\n`
+      }
+      raw += '\r\n'
+      upstream.write(raw)
+      if (head && head.length) upstream.write(head)
+      socket.pipe(upstream)
+      upstream.pipe(socket)
+    })
+    upstream.on('error', () => socket.destroy())
+    socket.on('error', () => upstream.destroy())
+  })
+
+  return server
+}
+
+/**
+ * Start every route's server listening. Returns `{ servers, close() }` where
+ * `close()` resolves once all servers are shut. Rejects (via the returned
+ * promise on the server 'error') if a port can't be bound.
+ */
+function startProxy(routes, { host = '127.0.0.1' } = {}) {
+  const servers = routes.map((route) => {
+    const server = createRouteServer(route, host)
+    server.listen(route.frontPort, host)
+    return server
+  })
+  return {
+    servers,
+    close() {
+      return Promise.all(
+        servers.map((s) => new Promise((resolve) => s.close(() => resolve()))),
+      )
+    },
+  }
+}
+
+/**
+ * Which of `ports` are already bound (so `connect` can tell the operator to stop
+ * main first). Resolves to the list of busy ports. `host` scopes the check.
+ */
+function portsInUse(ports, host = '127.0.0.1') {
+  return Promise.all(
+    ports.map(
+      (port) =>
+        new Promise((resolve) => {
+          const tester = net
+            .createServer()
+            .once('error', () => resolve(port)) // EADDRINUSE → busy
+            .once('listening', () => tester.close(() => resolve(null)))
+            .listen(port, host)
+        }),
+    ),
+  ).then((results) => results.filter((p) => p !== null))
+}
+
+// Does `port` accept a TCP connection right now?
+function checkListening(port, host) {
+  return new Promise((resolve) => {
+    const sock = net.connect(port, host)
+    sock.once('connect', () => {
+      sock.destroy()
+      resolve(true)
+    })
+    sock.once('error', () => {
+      sock.destroy()
+      resolve(false)
+    })
+  })
+}
+
+/**
+ * Poll until every port in `ports` accepts a connection (the detached proxy has
+ * finished binding), or `timeoutMs` elapses. Resolves true when all are up.
+ * `now`/`wait` are injectable for tests.
+ */
+async function waitListening(
+  ports,
+  { host = '127.0.0.1', timeoutMs = 3000, intervalMs = 50, now = () => Date.now(), wait } = {},
+) {
+  const sleep = wait || ((ms) => new Promise((r) => setTimeout(r, ms)))
+  const deadline = now() + timeoutMs
+  while (now() < deadline) {
+    const results = await Promise.all(ports.map((p) => checkListening(p, host)))
+    if (results.every(Boolean)) return true
+    await sleep(intervalMs)
+  }
+  return false
+}
+
+module.exports = { renderRoutes, createRouteServer, startProxy, portsInUse, waitListening }
+
+// Entry point: run as a detached process by the CLI. Reads its routes from a
+// file so a re-`connect` just rewrites the file and restarts this (tiny) process.
+if (require.main === module) {
+  const routesFile = process.argv[2]
+  if (!routesFile) {
+    process.stderr.write('proxy: usage: node proxy.js <routesFile>\n')
+    process.exit(1)
+  }
+  const routes = JSON.parse(fs.readFileSync(routesFile, 'utf-8'))
+  const { close } = startProxy(routes)
+  const shutdown = () => close().then(() => process.exit(0))
+  process.on('SIGTERM', shutdown)
+  process.on('SIGINT', shutdown)
+}

package/src/env/supervise.js

@@ -0,0 +1,150 @@
+'use strict'
+
+/**
+ * Process-supervision IO for host dev servers — the side-effecting seam the CLI
+ * drives (the planning lives in the pure `dev.js`). Keeps `cli.js` thin and lets
+ * start/stop/health be exercised against a fixture server in tests.
+ *
+ * A "proc" here is one entry from `planDev(...).procs` (it carries `command`,
+ * `env`, `logFile`, `pidFile`, `health`). Log/pid paths are relative to the
+ * primary checkout root, resolved against `rootDir`.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawn } = require('node:child_process')
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+function resolveState(rootDir, rel) {
+  return path.resolve(rootDir, rel)
+}
+
+// Is `pid` a live process? `kill(pid, 0)` probes without signalling.
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    // EPERM → exists but not ours; still "alive" for our purposes.
+    return err.code === 'EPERM'
+  }
+}
+
+// Signal a detached process's whole group (its leader pid is `pid`, so the group
+// id is `-pid`) — reaches children like vite/tsc that a bare `pnpm dev` spawns.
+// Falls back to signalling just the leader if the group send fails.
+function signalGroup(pid, sig) {
+  try {
+    process.kill(-pid, sig)
+  } catch {
+    try {
+      process.kill(pid, sig)
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+// Read a pid from its file (absolute path). null when missing/malformed.
+function readPid(pidFileAbs) {
+  try {
+    const n = Number(fs.readFileSync(pidFileAbs, 'utf-8').trim())
+    return Number.isInteger(n) && n > 0 ? n : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Start one planned process detached, appending stdout+stderr to its log and
+ * writing its pid file. Idempotent: if the pid file already names a live
+ * process, nothing is spawned — returns `{ started: false, pid }`.
+ *
+ * `spawnImpl` is injectable for tests; defaults to child_process.spawn.
+ */
+function startProcess(proc, { cwd, rootDir, spawnImpl = spawn }) {
+  const logAbs = resolveState(rootDir, proc.logFile)
+  const pidAbs = resolveState(rootDir, proc.pidFile)
+
+  const existing = readPid(pidAbs)
+  if (existing && isAlive(existing)) {
+    return { started: false, pid: existing, logFile: logAbs, pidFile: pidAbs }
+  }
+
+  fs.mkdirSync(path.dirname(logAbs), { recursive: true })
+  fs.mkdirSync(path.dirname(pidAbs), { recursive: true })
+
+  const out = fs.openSync(logAbs, 'a')
+  try {
+    const child = spawnImpl('sh', ['-c', proc.command], {
+      cwd,
+      env: { ...process.env, ...proc.env },
+      detached: true,
+      stdio: ['ignore', out, out],
+    })
+    child.unref()
+    fs.writeFileSync(pidAbs, `${child.pid}\n`)
+    return { started: true, pid: child.pid, logFile: logAbs, pidFile: pidAbs }
+  } finally {
+    fs.closeSync(out)
+  }
+}
+
+/**
+ * Stop one planned process: SIGTERM its pid, wait up to `graceMs` for it to
+ * exit, then SIGKILL if still alive. Removes the pid file either way. Idempotent
+ * — a missing/dead pid is a clean no-op. Returns `{ stopped, pid }`.
+ */
+async function stopProcess(proc, { rootDir, graceMs = 3000, now = () => Date.now(), wait = sleep } = {}) {
+  const pidAbs = resolveState(rootDir, proc.pidFile)
+  const pid = readPid(pidAbs)
+  let stopped = false
+
+  if (pid && isAlive(pid)) {
+    signalGroup(pid, 'SIGTERM')
+    const deadline = now() + graceMs
+    while (now() < deadline && isAlive(pid)) await wait(100)
+    if (isAlive(pid)) signalGroup(pid, 'SIGKILL')
+    stopped = true
+  }
+
+  try {
+    fs.unlinkSync(pidAbs)
+  } catch {
+    /* no pid file → nothing to clean */
+  }
+  return { stopped, pid }
+}
+
+/**
+ * Poll `url` until it answers (any HTTP status counts as "up") or `timeoutMs`
+ * elapses. Returns true when reachable, false on timeout. A null/empty url means
+ * "no health gate" → true immediately. `fetchImpl`/`now`/`wait` are injectable
+ * for deterministic tests.
+ */
+async function waitHealthy(
+  url,
+  { timeoutMs = 30000, intervalMs = 500, fetchImpl = fetch, now = () => Date.now(), wait = sleep } = {},
+) {
+  if (!url) return true
+  const deadline = now() + timeoutMs
+  while (now() < deadline) {
+    try {
+      const ctrl = new AbortController()
+      const t = setTimeout(() => ctrl.abort(), intervalMs)
+      try {
+        await fetchImpl(url, { signal: ctrl.signal })
+        return true
+      } finally {
+        clearTimeout(t)
+      }
+    } catch {
+      /* not up yet */
+    }
+    await wait(intervalMs)
+  }
+  return false
+}
+
+module.exports = { startProcess, stopProcess, waitHealthy, isAlive, readPid }

package/src/init.js

@@ -275,8 +275,8 @@ function printReport(dir, mode) {
     : 'Per-spec isolation is opt-in: re-run with --isolation (or copy' +
       ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
   process.stdout.write(
-    '\nDone. Skills resolve as /spec, /spec-ready, /spec-go, /spec-complete,' +
-      ' /spec-cancel, /spec-bug, /spec-init, /spec-env, /spec-env-down.\n' +
+    '\nDone. Skills resolve as /spec, /spec-go, /spec-complete, /spec-cancel,' +
+      ' /spec-bug, /spec-review, /spec-init, /spec-connect.\n' +
       'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
       " project's stack, then run /spec.\n" +
       isolationNote,