@skitterbyte/skitterspec 2.0.1 → 7.0.0

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,

package/assets/skills/spec-env/SKILL.md

@@ -1,63 +0,0 @@
----
-name: spec-env
-description: Provision an isolated environment for a spec — a git worktree on its own branch + a namespaced Docker stack (isolated containers/networks/volumes + a reserved port block), plus an optional editor/terminal opener. Runs `skitterspec spec-env up` and executes the printed git/docker/open commands. Opt-in — needs specs/.core/env.config.json. Use when the user says "/spec-env", "spin up an environment for <spec>", "give this spec its own worktree/stack", or "isolate <spec>".
----
-
-# /spec-env — provision an isolated environment for a spec
-
-Give an in-progress spec its own **git worktree** (a sibling directory on its own
-branch, no stashing) + a **namespaced Docker stack** (`COMPOSE_PROJECT_NAME`
-isolates containers/networks/volumes; `PORT_OFFSET` reserves a port block), so N
-specs run side by side and `main` stays clean. An optional `open.command` then
-opens the worktree however you like.
-
-This skill is **opt-in**: it only works when `specs/.core/env.config.json` exists
-(copy `env.config.json.example` to adopt it). If it's absent, tell the user how
-to enable it and stop.
-
-## 1. Identify the target spec
-
-- Use the spec named as an argument, else the spec **currently in context**. If
-  neither is clear, ask which spec.
-
-## 2. Plan the environment
-
-Run the engine — it allocates the slot (idempotent), persists the registry, and
-**prints** the plan (worktree path, branch, project name, port block, the exact
-commands, the `.env` contents, and the opener):
-
-```
-skitterspec spec-env up <spec>
-```
-
-If it reports the feature isn't enabled, relay that and stop — do not hand-roll a
-worktree/stack.
-
-## 3. Execute the printed side effects
-
-Run the printed commands **in order**, exactly as printed:
-
-1. **`git worktree add …`** — creates the sibling worktree on its branch. It is a
-   **sibling** of this checkout, **never nested** inside it. If the worktree
-   already exists, the engine prints the *attach* form (no `-b`) — do not clobber
-   an existing worktree/branch.
-2. **Write the `.env`** — write the printed `.env` contents into the new
-   worktree's env file (default `.env`). Do this *after* the worktree exists.
-3. **`docker compose … up -d`** — only printed when Docker is enabled. Brings the
-   namespaced stack up in the spec's reserved port block.
-4. **Opener** — if an `open.command` line was printed, run it (e.g. opens the
-   worktree in your editor/terminal). Skipped silently when unset.
-5. **Trust the worktree root for this session** — the engine already wrote the
-   printed `trusted:` root into `.claude/settings.local.json` (gitignored, so it
-   persists for future sessions). That file likely won't hot-reload mid-session,
-   so also run `/add-dir <trusted root>` now to lift `Edit`/`Write` prompts for
-   the **current** session. (If the engine printed a `trusted: ! …` warning,
-   `settings.local.json` isn't valid JSON — fix it, then re-run.)
-
-## 4. Report
-
-Echo the summary: worktree path, branch, project name, the allocated slot + port
-block, and whether the stack was brought up. **Idempotent** — re-running attaches
-to the existing slot/worktree and never reallocates.
-
-Tear down later with `/spec-env-down <spec>`.

package/assets/skills/spec-env-down/SKILL.md

@@ -1,64 +0,0 @@
----
-name: spec-env-down
-description: Tear down a spec's isolated environment — stop and remove its namespaced Docker stack (optionally backing up + dropping volumes), remove its git worktree, and free its slot. Guards refuse teardown on a dirty or unpushed worktree unless --force. Runs `skitterspec spec-env down` and executes the printed commands. Opt-in — needs specs/.core/env.config.json. Use when the user says "/spec-env-down", "tear down <spec>'s environment", "clean up the worktree/stack for <spec>", or "reclaim <spec>'s slot".
----
-
-# /spec-env-down — tear down a spec's isolated environment
-
-Reverse `/spec-env`: stop + remove the spec's Docker stack, remove its git
-worktree, and free its slot so the ports/slot are reclaimed. **Volumes are the
-only destructive part** — dropped by default (to reclaim disk) unless
-`--keep-volumes`, and always backed up first when `docker.backupCommand` is set.
-
-Opt-in: only works when `specs/.core/env.config.json` exists. If absent, say so
-and stop.
-
-## 1. Identify the target spec
-
-- Use the spec named as an argument, else the spec **currently in context**. If
-  neither is clear, ask which spec.
-
-## 2. Plan the teardown
-
-Run the engine — it checks the guards, frees the slot, and **prints** the plan:
-
-```
-skitterspec spec-env down <spec> [--keep-volumes] [--force]
-```
-
-- **`--keep-volumes`** — keep the stack's data (plain `down`, no backup, no drop).
-- **`--force`** — override the guards below.
-
-## 3. Handle a guard block
-
-If the CLI reports **blocked** (the worktree has uncommitted changes, or unpushed
-commits that aren't yet merged into the base branch), **relay the reason and
-stop** — do not destroy unreviewed work. Offer the user `--force` (and suggest
-committing/pushing first). Only re-run with `--force` when the user explicitly
-asks. **A branch already merged into the base needs no `--force`** — the unpushed
-guard treats "landed on base" as safe, so a completed spec (post-`/spec-complete`
-integrate) tears down cleanly even with no remote.
-
-## 4. Execute the printed side effects
-
-When not blocked, run the printed commands **in order**, exactly as printed:
-
-1. **Backup** (only when a `docker.backupCommand` is configured and volumes are
-   being dropped) — writes a dump under `.spec-env/backups/` before anything is
-   destroyed.
-2. **`docker compose … down`** — with `--volumes` unless `--keep-volumes`.
-3. **`git worktree remove …`** — removes the sibling worktree.
-4. **`git branch -d <branch>`** — deletes the spec's branch (freed by the worktree
-   removal above). It's `-d` (merged-only), never `-D`: if it reports the branch
-   isn't fully merged, **relay that and stop** — don't `-D` it. That only happens
-   on a `--force` teardown of unmerged work; the user can delete it by hand if
-   they're sure.
-
-The slot is already freed by the CLI.
-
-## 5. Report
-
-Confirm what happened: worktree removed, branch deleted, containers down, volumes
-**dropped|kept**, slot freed, and the backup path (if any). If a `git branch -d`
-was refused (unmerged), say so. If the spec wasn't provisioned / was already torn
-down, the CLI reports a clean **no-op** — relay that; it's not an error.

package/assets/skills/spec-ready/SKILL.md

@@ -1,50 +0,0 @@
----
-name: spec-ready
-description: Mark a Draft spec as Ready — confirm it's groomed (no unresolved open questions, phases and per-phase tests defined, decisions captured) and flip its status to Ready so it's a candidate for /spec-go. Stays in specs/backlog/. Targets a spec by name (arg) or the spec in context. Use when the user says "/spec-ready", "this spec is ready", or "mark <spec> ready to start".
----
-
-# /spec-ready — promote a Draft spec to Ready
-
-A grooming gate between authoring (`/spec`, status `Draft`) and implementation
-(`/spec-go`, status `In Progress`). It does **not** move the spec — it stays in
-`specs/backlog/`; it only confirms quality and flips the status to `Ready` so
-you can see at a glance which backlog specs are good to start.
-
-## 1. Identify the target spec
-
-- Use the name/path argument if given, else the spec **in context**. If unclear,
-  ask which spec.
-- Locate the spec folder under `specs/backlog/`. Entry point is its
-  `00-overview.md`; phases are separate files (`01-<slug>.md`, `02-…`) listed in
-  its phase index (legacy specs may be a bare `<name>.md`).
-
-## 2. Check it's actually ready — don't rubber-stamp
-
-Review the spec against the readiness bar. If any of these fail, **stop and tell
-the user what's missing** rather than marking it Ready:
-
-- **Open questions resolved** — the `## Open questions` section is empty or
-  reads "None". Unresolved branches mean it isn't ready.
-- **Decisions captured** — the chosen solution and key trade-offs are recorded.
-- **Phased with clear tasks** — work is broken into phases, and **every phase in
-  the `00-overview.md` index has a matching phase file** (`0N-<slug>.md`) with
-  verb-first `- [ ]` tasks granular enough for one session. No index row without
-  a file, no orphan file without an index row.
-- **Tests baked into every phase** — each phase file ends with a
-  create-and-run-tests task (a phase isn't done until green).
-- **Concise and current** — no stale/contradictory sections.
-
-Offer to fix small gaps inline if the user wants; otherwise leave it `Draft`.
-
-## 3. Mark Ready
-
-- Set the **Status** header in the entry point:
-  `> **Status:** Ready (<YYYY-MM-DD>)`.
-- Append a **State log** row: `| <YYYY-MM-DD> | Ready | backlog | <git user.name> |`
-  (no folder change — Ready stays in `backlog`).
-- Optionally add a **Changelog** note if grooming changed anything substantive.
-
-## 4. Report
-
-Confirm it's Ready and note it stays in `backlog` until `/spec-go` picks it up.
-If you blocked it, list exactly what needs resolving first.