@naxodev/apnea 0.1.0

package/extension/cli/format.ts

@@ -0,0 +1,44 @@
+import { toolToVerb } from "../registry.ts"
+import type { ToolResult } from "../result.ts"
+
+/** 0 ready · 1 refusal/error · 2 usage · 3 wait budget spent, call again. */
+export const EXIT_OK = 0
+export const EXIT_ERROR = 1
+export const EXIT_USAGE = 2
+export const EXIT_PENDING = 3
+
+export function exitCodeFor(r: ToolResult): number {
+  if (!r.ok) return EXIT_ERROR
+  return r.data?.pending === true ? EXIT_PENDING : EXIT_OK
+}
+
+/**
+ * Canonical tool name → the command a shell caller actually runs, or `null`
+ * when `tool` isn't a runnable command: either it's already a human-readable
+ * hint (contains whitespace, e.g. "dispatch_role with allowed kind") that
+ * should render unchanged, or it's a bug — a tool-name-shaped string with no
+ * CLI verb behind it (e.g. a tool that was deleted from `LEGAL_TOOLS` but
+ * left in some error's `legal_next`). Returning `null` for the latter instead
+ * of the raw string keeps a dangling tool name from silently reaching
+ * rendered output.
+ */
+function asCommand(tool: string): string | null {
+  const verb = toolToVerb(tool)
+  if (verb) return `apnea ${verb}`
+  return /\s/.test(tool) ? tool : null
+}
+
+export function renderHuman(r: ToolResult): string {
+  const mapped = (r.legal_next ?? [])
+    .map(asCommand)
+    .filter((c): c is string => c !== null)
+  const next = mapped.length ? `\nnext: ${mapped.join(" | ")}` : ""
+  const extra = r.data ? `\n${JSON.stringify(r.data, null, 2)}` : ""
+  return r.ok
+    ? `OK: ${r.message}${next}${extra}`
+    : `ERROR: ${r.error}${next}${extra}`
+}
+
+export function renderJson(r: ToolResult): string {
+  return JSON.stringify(r)
+}

package/extension/cli/human-gate.ts

@@ -0,0 +1,44 @@
+export type HumanGateDeps = {
+  isTty: () => boolean
+  prompt: (question: string) => Promise<string>
+}
+
+export const prodHumanGateDeps: HumanGateDeps = {
+  isTty: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  prompt: async (question) => {
+    process.stdout.write(question)
+    for await (const line of console) return line.trim()
+    return ""
+  },
+}
+
+/**
+ * Human-only confirmation for cap reset. An agent shelling out has captured
+ * pipes, so the TTY check fails closed. `--i-am-human` remains available for
+ * scripts and remote shells: the property this buys is auditability — the
+ * bypass is named in the transcript — not prevention.
+ */
+export async function confirmHuman(
+  gate: string,
+  deps: HumanGateDeps,
+  override: boolean,
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+  if (override) return { ok: true }
+  if (!deps.isTty()) {
+    return {
+      ok: false,
+      reason:
+        "reset-rounds is human-only and stdin/stdout are not a terminal. " +
+        "Run it yourself in a shell, or pass --i-am-human to override.",
+    }
+  }
+  const answer = await deps.prompt(
+    `Type the gate key to confirm reset (${gate}): `,
+  )
+  return answer === gate
+    ? { ok: true }
+    : {
+        ok: false,
+        reason: `confirmation did not match "${gate}"; nothing reset`,
+      }
+}

package/extension/cli/main.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env bun
+import { parseFlags, parseNumFlag } from "./parse.ts"
+import {
+  EXIT_ERROR,
+  EXIT_USAGE,
+  exitCodeFor,
+  renderHuman,
+  renderJson,
+} from "./format.ts"
+import { confirmHuman, prodHumanGateDeps } from "./human-gate.ts"
+import { OPERATIONS, executeOperation, findByVerb } from "../registry.ts"
+import { DISPATCH_KINDS } from "../domain/state-machine.ts"
+import type { ToolResult } from "../result.ts"
+
+function usage(): string {
+  return [
+    "apnea — multi-role workflow driver",
+    "",
+    "Usage: apnea <command> [args] [--json]",
+    "",
+    ...OPERATIONS.map(
+      (o) => `  ${`${o.verb} ${o.usage ?? ""}`.trim().padEnd(38)} ${o.summary}`,
+    ),
+    "  resume | abandon   actions on an existing run",
+    "",
+    "apnea reset-rounds also accepts [--i-am-human] (CLI only — skips the TTY",
+    "confirmation prompt that only this surface has; see README.md).",
+    "",
+    `dispatch kinds: ${DISPATCH_KINDS.join(" | ")}`,
+    "",
+    "Exit codes: 0 ok · 1 refused/error · 2 usage · 3 still waiting (call again)",
+  ].join("\n")
+}
+
+/**
+ * Renders a usage failure through the same `renderJson`/`renderHuman` split
+ * as every other exit path, so a `--json` caller gets parseable output on
+ * exit 2 too instead of a plain-text message that breaks its parser. The
+ * full command listing is only useful to a human reading a terminal, so it's
+ * appended after the rendered error and only outside `--json` mode.
+ */
+function printUsageError(message: string, json: boolean): void {
+  const result: ToolResult = { ok: false, error: message }
+  console.error(
+    json ? renderJson(result) : `${renderHuman(result)}\n\n${usage()}`,
+  )
+}
+
+export async function main(argv: string[]): Promise<number> {
+  const [verbRaw, ...rest] = argv
+  const { flags, values, rest: positional } = parseFlags(rest)
+  const json = flags.has("json")
+
+  if (!verbRaw) {
+    printUsageError("usage: apnea <command> [args] [--json]", json)
+    return EXIT_USAGE
+  }
+  if (verbRaw === "help" || verbRaw === "--help") {
+    console.log(usage())
+    return 0
+  }
+
+  // `resume` and `abandon` are actions on the start operation.
+  const isAction = verbRaw === "resume" || verbRaw === "abandon"
+  const op = findByVerb(isAction ? "start" : verbRaw)
+  if (!op) {
+    printUsageError(`unknown command: ${verbRaw}`, json)
+    return EXIT_USAGE
+  }
+
+  const built = buildParams(
+    op.verb,
+    isAction ? verbRaw : null,
+    flags,
+    values,
+    positional,
+  )
+  if (!built.ok) {
+    printUsageError(
+      built.message ?? `usage: apnea ${op.verb} ${op.usage}`.trim(),
+      json,
+    )
+    return EXIT_USAGE
+  }
+
+  if (op.humanOnly) {
+    const gate = String(built.params.gate ?? "")
+    const confirmed = await confirmHuman(
+      gate,
+      prodHumanGateDeps,
+      flags.has("i-am-human"),
+    )
+    if (!confirmed.ok) {
+      const result: ToolResult = { ok: false, error: confirmed.reason }
+      console.error(json ? renderJson(result) : renderHuman(result))
+      return EXIT_ERROR
+    }
+  }
+
+  const result = await executeOperation(op.verb, built.params)
+  const text = json ? renderJson(result) : renderHuman(result)
+  if (result.ok) console.log(text)
+  else console.error(text)
+  return exitCodeFor(result)
+}
+
+export type BuildParamsResult =
+  | { ok: true; params: Record<string, unknown> }
+  | { ok: false; message?: string }
+
+export function buildParams(
+  verb: string,
+  action: string | null,
+  flags: Set<string>,
+  values: Map<string, string>,
+  positional: string[],
+): BuildParamsResult {
+  switch (verb) {
+    case "start": {
+      if (action) return { ok: true, params: { action } }
+      const goal = positional.join(" ").trim()
+      if (!goal) {
+        return {
+          ok: false,
+          message: "usage: apnea start <goal> [--allow-dirty] [--slug=name]",
+        }
+      }
+      return {
+        ok: true,
+        params: {
+          action: "start",
+          goal,
+          slug: values.get("slug"),
+          allow_dirty: flags.has("allow-dirty") || undefined,
+        },
+      }
+    }
+    case "dispatch": {
+      const kind = positional[0]
+      if (!kind || !DISPATCH_KINDS.includes(kind as never)) {
+        return {
+          ok: false,
+          message: `usage: apnea dispatch <${DISPATCH_KINDS.join("|")}> [--rework]`,
+        }
+      }
+      return {
+        ok: true,
+        params: { kind, rework: flags.has("rework") || undefined },
+      }
+    }
+    case "wait": {
+      // `--timeout` and `--budget` are the same knob: how long THIS call
+      // blocks. The role's deadline comes from config, stamped at dispatch.
+      const poll = parseNumFlag(values, "poll")
+      if (!poll.ok) {
+        return {
+          ok: false,
+          message: `usage: apnea wait [--poll=<ms>] (got --poll=${poll.raw})`,
+        }
+      }
+      const budget = parseNumFlag(values, "budget")
+      if (!budget.ok) {
+        return {
+          ok: false,
+          message: `usage: apnea wait [--budget=<ms>] (got --budget=${budget.raw})`,
+        }
+      }
+      const timeout = parseNumFlag(values, "timeout")
+      if (!timeout.ok) {
+        return {
+          ok: false,
+          message: `usage: apnea wait [--timeout=<ms>] (got --timeout=${timeout.raw})`,
+        }
+      }
+      return {
+        ok: true,
+        params: {
+          poll_ms: poll.value,
+          budget_ms: budget.value ?? timeout.value,
+        },
+      }
+    }
+    case "commit": {
+      const message = positional.join(" ").trim()
+      return {
+        ok: true,
+        params: {
+          message: message || undefined,
+          no_remaining_phases: flags.has("done") || undefined,
+        },
+      }
+    }
+    case "status":
+      return { ok: true, params: {} }
+    case "reset-rounds": {
+      const gate = positional[0]
+      if (!gate) {
+        return { ok: false, message: "usage: apnea reset-rounds <gate>" }
+      }
+      return { ok: true, params: { gate } }
+    }
+    case "setup":
+      return {
+        ok: true,
+        params: {
+          project: flags.has("project") || undefined,
+          force: flags.has("force") || undefined,
+          agents_md: flags.has("agents-md") || undefined,
+        },
+      }
+    default:
+      return { ok: false }
+  }
+}
+
+if (import.meta.main) {
+  process.exit(await main(process.argv.slice(2)))
+}

package/extension/cli/parse.ts

@@ -0,0 +1,48 @@
+/**
+ * Split `--bare` switches from `--key=value` options; everything else is
+ * positional. `values` matters: `rest` never sees a `--`-prefixed token, so
+ * `--key=value` options are only reachable through the map.
+ */
+export function parseFlags(tokens: string[]): {
+  flags: Set<string>
+  values: Map<string, string>
+  rest: string[]
+} {
+  const flags = new Set<string>()
+  const values = new Map<string, string>()
+  const rest: string[] = []
+  for (const t of tokens) {
+    if (!t.startsWith("--")) {
+      rest.push(t)
+      continue
+    }
+    const body = t.slice(2)
+    const eq = body.indexOf("=")
+    if (eq > 0) values.set(body.slice(0, eq), body.slice(eq + 1))
+    else flags.add(body)
+  }
+  return { flags, values, rest }
+}
+
+/** Reading a `--key=value` numeric flag either yields the parsed number (or
+ * `undefined` when the caller didn't pass it) or the raw token that failed
+ * to parse, so the caller can name exactly what it received. */
+export type NumFlag =
+  { ok: true; value: number | undefined } | { ok: false; raw: string }
+
+/**
+ * Shared by `/apnea` and the CLI so a mistyped `--budget=abc` is refused the
+ * same way on both surfaces instead of silently falling back to a default —
+ * a scripting agent needs a signal, not a quietly-wrong value. `--key=`
+ * (empty string) counts as "not provided": a caller who writes it almost
+ * certainly forgot the value, not asked for zero.
+ */
+export function parseNumFlag(
+  values: Map<string, string>,
+  key: string,
+): NumFlag {
+  const raw = values.get(key)
+  if (raw === undefined || raw === "") return { ok: true, value: undefined }
+  const n = Number(raw)
+  return Number.isFinite(n) ? { ok: true, value: n } : { ok: false, raw }
+}

package/extension/domain/artifact-kind.ts

@@ -0,0 +1,26 @@
+import { Result } from "effect"
+import { ArtifactInvalid } from "../errors.ts"
+import type { DispatchKind } from "./state-machine.ts"
+
+/** Infer the dispatch kind an artifact path corresponds to. Ordering matters:
+ * plan-review must be checked before the bare plan.md suffix check. */
+export function inferKind(
+  artifactRel: string,
+): Result.Result<DispatchKind, ArtifactInvalid> {
+  if (artifactRel.endsWith("plan.md") && !artifactRel.includes("plan-review"))
+    return Result.succeed("plan")
+  if (artifactRel.includes("plan-review")) return Result.succeed("plan_review")
+  if (artifactRel.endsWith("phase-package.md"))
+    return Result.succeed("phase_package")
+  if (artifactRel.endsWith("coder-result.md")) return Result.succeed("code")
+  if (artifactRel.endsWith("code-review.md"))
+    return Result.succeed("code_review")
+  if (artifactRel.endsWith("pr-description.md"))
+    return Result.succeed("pr_description")
+  return Result.fail(
+    new ArtifactInvalid({
+      artifact: artifactRel,
+      message: `cannot infer dispatch kind from ${artifactRel}`,
+    }),
+  )
+}

package/extension/domain/frontmatter.ts

@@ -0,0 +1,69 @@
+import type { FrontMatter, Verdict } from "./types.ts"
+
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/
+
+export function parseFrontMatter(text: string): FrontMatter | null {
+  const m = text.match(FM_RE)
+  if (!m) return null
+  const raw = m[1] ?? ""
+  const body = m[2] ?? ""
+  const fields: Record<string, string> = {}
+  let currentKey: string | null = null
+  let currentVal: string[] = []
+
+  const flush = () => {
+    if (currentKey) {
+      fields[currentKey] = currentVal
+        .join("\n")
+        .replace(/^\s*\|\s*\n?/, "")
+        .trimEnd()
+    }
+    currentKey = null
+    currentVal = []
+  }
+
+  for (const line of raw.split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z0-9_]+):\s*(.*)$/)
+    if (kv) {
+      flush()
+      currentKey = kv[1]!
+      const rest = kv[2] ?? ""
+      if (rest === "|" || rest === ">") {
+        currentVal = []
+      } else {
+        currentVal = [rest]
+      }
+    } else if (
+      currentKey &&
+      (line.startsWith("  ") || line.startsWith("\t") || line === "")
+    ) {
+      currentVal.push(line.replace(/^\s{2}/, ""))
+    }
+  }
+  flush()
+
+  return {
+    status: fields.status,
+    verdict: fields.verdict,
+    nits: fields.nits,
+    rework: fields.rework,
+    raw,
+    body,
+  }
+}
+
+export function isCompleteArtifact(
+  fm: FrontMatter | null,
+  opts: { requireVerdict?: boolean } = {},
+): boolean {
+  if (!fm || fm.status !== "done") return false
+  if (opts.requireVerdict) {
+    return fm.verdict === "APPROVED" || fm.verdict === "CHANGES_REQUIRED"
+  }
+  return true
+}
+
+export function asVerdict(v: string | undefined): Verdict | null {
+  if (v === "APPROVED" || v === "CHANGES_REQUIRED") return v
+  return null
+}

package/extension/domain/herdr.ts

@@ -0,0 +1,109 @@
+import type { PaneStyle, Role } from "./types.ts"
+
+/** Parse `herdr X.Y.Z` (or noisy multi-line) into a numeric tuple. */
+export function parseHerdrVersion(
+  raw: string,
+): [number, number, number] | null {
+  const m = raw.match(/(\d+)\.(\d+)\.(\d+)/)
+  if (!m) return null
+  return [Number(m[1]), Number(m[2]), Number(m[3])]
+}
+
+export function versionGte(
+  a: [number, number, number],
+  b: [number, number, number],
+): boolean {
+  const [a0, a1, a2] = a
+  const [b0, b1, b2] = b
+  if (a0 !== b0) return a0 > b0
+  if (a1 !== b1) return a1 > b1
+  return a2 >= b2
+}
+
+/**
+ * Floating popups need herdr ≥ 0.7.4. Fail closed on unparseable versions so an
+ * unattended run never hangs on a CLI that rejects `--placement popup`.
+ */
+export function supportsFloating(
+  version: [number, number, number] | null,
+): boolean {
+  return version != null && versionGte(version, [0, 7, 4])
+}
+
+/**
+ * Configured style vs effective style. Floating is only for planner/reviewer
+ * (oneshot-eligible artifact producers); interactive roles always stay regular.
+ */
+export function effectivePaneStyle(
+  configured: PaneStyle,
+  role: Role,
+): { style: PaneStyle; effective: string } {
+  if (configured === "regular") {
+    return { style: "regular", effective: "regular" }
+  }
+  if (role === "planner" || role === "reviewer") {
+    return { style: "floating", effective: "floating" }
+  }
+  return { style: "regular", effective: "regular (interactive role)" }
+}
+
+export function shellJoin(parts: string[]): string {
+  return parts
+    .map((p) => {
+      if (p === "&&" || p === "|" || p === "exec" || p === "env") return p
+      if (/^[A-Za-z0-9_./:=,@+-]+$/.test(p)) return p
+      return `'${p.replace(/'/g, `'\\''`)}'`
+    })
+    .join(" ")
+}
+
+/** True when every foreground process name looks like a bare shell prompt. */
+export function looksLikeShellOnly(names: string[]): boolean {
+  if (names.length === 0) return false
+  return names.every((n) => {
+    const t = n.trim()
+    return (
+      /^(zsh|bash|sh|fish)$/i.test(t) ||
+      t === "-zsh" ||
+      t === "-bash" ||
+      t === "-sh"
+    )
+  })
+}
+
+/** Parse a floating task's exit-file contents; null if not a finished exit code. */
+export function parseFloatingExit(text: string): number | null {
+  const t = text.trim()
+  const n = Number.parseInt(t, 10)
+  return Number.isFinite(n) ? n : null
+}
+
+/**
+ * Self-contained bash script body that cds to root, runs cmd + prompt as a
+ * child (not exec — so EXIT trap still fires), and always records the exit
+ * code for workflow_wait. Popups have no pane id; the exit file is the
+ * liveness signal.
+ */
+export function floatingTaskScriptBody(opts: {
+  root: string
+  resolvedCmd: string[]
+  prompt: string
+  exitFileAbs: string
+}): string {
+  return [
+    "#!/bin/bash",
+    "set -uo pipefail",
+    `EXIT_FILE=${shellJoin([opts.exitFileAbs])}`,
+    "write_exit() {",
+    "  local st=$?",
+    `  printf '%s\n' "$st" > "$EXIT_FILE" 2>/dev/null || true`,
+    "}",
+    "trap write_exit EXIT",
+    "trap 'exit 129' HUP",
+    "trap 'exit 130' INT",
+    "trap 'exit 143' TERM",
+    shellJoin(["cd", opts.root]),
+    shellJoin([...opts.resolvedCmd, "--", opts.prompt]),
+    "",
+  ].join("\n")
+}

package/extension/domain/paths.ts

@@ -0,0 +1,139 @@
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const APNEA_DIR = ".apnea"
+
+export function cwd(): string {
+  return process.cwd()
+}
+
+export function apneaRoot(root = cwd()): string {
+  return path.join(root, APNEA_DIR)
+}
+
+export function statePath(root = cwd()): string {
+  return path.join(apneaRoot(root), "state.json")
+}
+
+export function projectConfigPath(root = cwd()): string {
+  return path.join(apneaRoot(root), "config.json")
+}
+
+function homedir(): string {
+  // Env first so an overridden HOME still wins (Bun's os.homedir() reads the
+  // passwd entry and ignores $HOME), then the passwd entry as the floor.
+  // Never "": an empty home makes globalConfigPath() cwd-relative, i.e. the
+  // *project* repo would be read as the trusted global config — the one place
+  // profiles/cmd_interactive are honoured. node:os is a pure read here.
+  return process.env.HOME || process.env.USERPROFILE || os.homedir()
+}
+
+export function globalConfigPath(): string {
+  return path.join(homedir(), ".config", "apnea", "config.json")
+}
+
+export function artifactsDir(root = cwd()): string {
+  return path.join(apneaRoot(root), "artifacts")
+}
+
+export function tasksDir(root = cwd()): string {
+  return path.join(apneaRoot(root), "tasks")
+}
+
+export function phaseDir(
+  phaseIndex: number,
+  round: number,
+  root = cwd(),
+): string {
+  const n = String(phaseIndex).padStart(2, "0")
+  return path.join(artifactsDir(root), `phase-${n}`, `round-${round}`)
+}
+
+export function planPath(root = cwd()): string {
+  return path.join(artifactsDir(root), "plan.md")
+}
+
+export function planReviewPath(round: number, root = cwd()): string {
+  return path.join(artifactsDir(root), "plan-review", `round-${round}.md`)
+}
+
+export function prDescriptionPath(root = cwd()): string {
+  return path.join(artifactsDir(root), "pr-description.md")
+}
+
+export function rel(p: string, root = cwd()): string {
+  return path.relative(root, p) || p
+}
+
+export function abs(p: string, root = cwd()): string {
+  return path.isAbsolute(p) ? p : path.join(root, p)
+}
+
+export const PACKAGE_NAME = "@naxodev/apnea"
+
+/**
+ * The package-root search, with the starting directory as a parameter.
+ *
+ * Returns `null` when it cannot find us. An earlier version guessed two levels
+ * up instead — the exact wrong answer for the bundled and installed layouts
+ * this function exists to handle, handed back as if it were a real result.
+ * Callers can now tell "not found" from "found", and `dispatch` turns it into
+ * a refusal naming the paths it tried.
+ *
+ * Split out from `packageRoot()` so a test can supply the layout rather than
+ * inheriting whichever one the test runner happens to use. Testing
+ * `packageRoot()` directly only ever exercises the source tree, where the old
+ * two-levels-up rule was also correct — a test written that way passes against
+ * the bug.
+ */
+export function findPackageRootFrom(startDir: string): string | null {
+  let dir = startDir
+  for (let up = 0; up < 10; up++) {
+    try {
+      const manifest = fs.readFileSync(path.join(dir, "package.json"), "utf8")
+      if ((JSON.parse(manifest) as { name?: string }).name === PACKAGE_NAME) {
+        return dir
+      }
+    } catch {
+      // No package.json here, or it is not readable JSON. Keep walking.
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * Package root — the directory holding `briefs/`, `herdr-plugin/`, and our
+ * own `package.json`.
+ *
+ * Found by walking up and reading each `package.json`, NOT by counting
+ * directory levels. The level count differs for every way this code runs, and
+ * a wrong root is silent: `dispatch` still launches a pane, and the role sits
+ * there having been told to read a brief that does not exist.
+ *
+ *   from source   extension/domain/paths.ts  -> 2 up
+ *   from bundle   dist/cli.js                -> 1 up
+ *   from npm      node_modules/@naxodev/apnea/dist/cli.js -> 1 up
+ *
+ * The old two-up rule was right only for source. `bun build` emits one file at
+ * `dist/cli.js`, so the CLI resolved the repo's PARENT and every brief path it
+ * printed was wrong — found by running the CLI against this repo, not by any
+ * test, because the tests fake this function and the Pi extension happens to
+ * load from source.
+ *
+ * Matching on the package NAME rather than on the presence of `package.json`
+ * matters once this is installed as a dependency: the first `package.json`
+ * above `node_modules/...` belongs to the consumer, not to us.
+ *
+ * The source-layout guess remains only as a last resort for a fork or rename,
+ * where the name will never match. `dispatch` checks the brief exists before
+ * launching, so a wrong guess surfaces as a refusal rather than a stalled role.
+ */
+export function packageRoot(): string {
+  const here = path.dirname(fileURLToPath(import.meta.url))
+  return findPackageRootFrom(here) ?? path.resolve(here, "..", "..")
+}