@naxodev/apnea 0.1.0 → 0.2.1

package/extension/cli/parse.ts

@@ -11,7 +11,16 @@ export function parseFlags(tokens: string[]): {
   const flags = new Set<string>()
   const values = new Map<string, string>()
   const rest: string[] = []
+  let positionalOnly = false
   for (const t of tokens) {
+    if (positionalOnly) {
+      rest.push(t)
+      continue
+    }
+    if (t === "--") {
+      positionalOnly = true
+      continue
+    }
     if (!t.startsWith("--")) {
       rest.push(t)
       continue
@@ -24,6 +33,162 @@ export function parseFlags(tokens: string[]): {
   return { flags, values, rest }
 }
 
+type OperationArgSpec = {
+  switches: readonly string[]
+  values: readonly string[]
+  minPositionals: number
+  maxPositionals: number
+}
+
+const OPERATION_ARGS: Readonly<Record<string, OperationArgSpec>> = {
+  setup: {
+    switches: ["project", "force", "agents-md"],
+    values: [],
+    minPositionals: 0,
+    maxPositionals: 0,
+  },
+  start: {
+    switches: ["allow-dirty"],
+    values: ["slug"],
+    minPositionals: 1,
+    maxPositionals: Number.POSITIVE_INFINITY,
+  },
+  resume: { switches: [], values: [], minPositionals: 0, maxPositionals: 0 },
+  abandon: { switches: [], values: [], minPositionals: 0, maxPositionals: 0 },
+  help: { switches: [], values: [], minPositionals: 0, maxPositionals: 0 },
+  status: { switches: [], values: [], minPositionals: 0, maxPositionals: 0 },
+  wait: {
+    switches: [],
+    values: ["poll", "budget", "timeout"],
+    minPositionals: 0,
+    maxPositionals: 0,
+  },
+  dispatch: {
+    switches: ["rework", "redeliver"],
+    values: [],
+    minPositionals: 1,
+    maxPositionals: 1,
+  },
+  commit: {
+    switches: ["done"],
+    values: [],
+    minPositionals: 0,
+    maxPositionals: Number.POSITIVE_INFINITY,
+  },
+  "reset-rounds": {
+    switches: [],
+    values: [],
+    minPositionals: 1,
+    maxPositionals: 1,
+  },
+}
+
+export type ParsedOperationArgs =
+  | {
+      ok: true
+      flags: Set<string>
+      values: Map<string, string>
+      positional: string[]
+    }
+  | { ok: false; message: string }
+
+/**
+ * Parse and validate one human-facing Apnea invocation. This is the shared
+ * strict boundary for the standalone CLI and Pi's `/apnea` command.
+ */
+export function parseOperationArgs(
+  verb: string,
+  tokens: string[],
+  options: { surface?: "cli" | "slash" } = {},
+): ParsedOperationArgs {
+  const spec = OPERATION_ARGS[verb]
+  if (!spec) return { ok: false, message: `unknown command: ${verb}` }
+
+  const allowedSwitches = new Set(spec.switches)
+  if (options.surface === "cli") {
+    allowedSwitches.add("json")
+    if (verb === "reset-rounds") allowedSwitches.add("i-am-human")
+  }
+  const allowedValues = new Set(spec.values)
+  const numericValues = new Set(["poll", "budget", "timeout"])
+  const flags = new Set<string>()
+  const values = new Map<string, string>()
+  const positional: string[] = []
+  let positionalOnly = false
+
+  for (const token of tokens) {
+    if (positionalOnly) {
+      positional.push(token)
+      continue
+    }
+    if (token === "--") {
+      positionalOnly = true
+      continue
+    }
+    if (!token.startsWith("--")) {
+      positional.push(token)
+      continue
+    }
+
+    const body = token.slice(2)
+    const equals = body.indexOf("=")
+    const key = equals >= 0 ? body.slice(0, equals) : body
+    const value = equals >= 0 ? body.slice(equals + 1) : undefined
+
+    if (allowedSwitches.has(key)) {
+      if (value !== undefined)
+        return { ok: false, message: `option --${key} does not take a value` }
+      if (flags.has(key))
+        return {
+          ok: false,
+          message: `option --${key} was provided more than once`,
+        }
+      flags.add(key)
+      continue
+    }
+    if (allowedValues.has(key)) {
+      if (value === undefined)
+        return { ok: false, message: `option --${key} requires =<value>` }
+      if (numericValues.has(key)) {
+        const numeric = Number(value)
+        if (
+          value === "" ||
+          value.trim() !== value ||
+          !Number.isSafeInteger(numeric) ||
+          numeric <= 0
+        ) {
+          return {
+            ok: false,
+            message: `invalid numeric option --${key}=${value}`,
+          }
+        }
+      }
+      if (values.has(key))
+        return {
+          ok: false,
+          message: `option --${key} was provided more than once`,
+        }
+      values.set(key, value)
+      continue
+    }
+    return { ok: false, message: `unknown option --${key} for ${verb}` }
+  }
+
+  if (
+    positional.length < spec.minPositionals ||
+    positional.length > spec.maxPositionals
+  ) {
+    return { ok: false, message: `invalid positional arguments for ${verb}` }
+  }
+  if (values.has("budget") && values.has("timeout")) {
+    return {
+      ok: false,
+      message: "--budget and --timeout are aliases; provide only one",
+    }
+  }
+  return { ok: true, flags, values, positional }
+}
+
 /** 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. */
@@ -33,16 +198,18 @@ export type NumFlag =
 /**
  * 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.
+ * a scripting agent needs a signal, not a quietly-wrong value. This exported
+ * boundary rejects empty and padded values even when called directly.
  */
 export function parseNumFlag(
   values: Map<string, string>,
   key: string,
 ): NumFlag {
   const raw = values.get(key)
-  if (raw === undefined || raw === "") return { ok: true, value: undefined }
+  if (raw === undefined) return { ok: true, value: undefined }
+  if (raw === "" || raw.trim() !== raw) return { ok: false, raw }
   const n = Number(raw)
-  return Number.isFinite(n) ? { ok: true, value: n } : { ok: false, raw }
+  return Number.isSafeInteger(n) && n > 0
+    ? { ok: true, value: n }
+    : { ok: false, raw }
 }

package/extension/domain/herdr.ts

@@ -1,52 +1,3 @@
-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) => {
@@ -70,40 +21,3 @@ export function looksLikeShellOnly(names: string[]): boolean {
     )
   })
 }
-
-/** 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

@@ -21,17 +21,8 @@ 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 globalConfigPath(home = os.homedir()): string {
+  return path.join(home, ".config", "apnea", "config.json")
 }
 
 export function artifactsDir(root = cwd()): string {
@@ -107,8 +98,7 @@ export function findPackageRootFrom(startDir: string): string | null {
 }
 
 /**
- * Package root — the directory holding `briefs/`, `herdr-plugin/`, and our
- * own `package.json`.
+ * Package root — the directory holding `briefs/` 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

package/extension/domain/setup.ts

@@ -21,19 +21,6 @@ export function deepMergeProfiles(
   return out
 }
 
-/**
- * Carry a valid user pane_style preference forward. Setup never writes the
- * key when absent, and never invents values — only preserves exact "regular"
- * or "floating". Invalid prev values are dropped.
- */
-export function preservePaneStyle(
-  prev: Record<string, unknown>,
-): "regular" | "floating" | undefined {
-  const v = prev.pane_style
-  if (v === "regular" || v === "floating") return v
-  return undefined
-}
-
 export function buildProfiles(has: Detected): Record<string, unknown> {
   const profiles: Record<string, unknown> = {}
 
@@ -119,8 +106,6 @@ export function buildGlobalConfig(opts: {
     )
   }
 
-  const preservedPaneStyle = preservePaneStyle(prev)
-
   const globalConfig: Record<string, unknown> = {
     profiles: nextProfiles,
     roles: force || !prev.roles ? roles : prev.roles,
@@ -133,11 +118,6 @@ export function buildGlobalConfig(opts: {
           // values wait/commit actually use cannot drift apart.
           { ...DEFAULT_TIMEOUTS },
   }
-  // Preserve user opt-in only — never introduce pane_style when absent.
-  if (preservedPaneStyle !== undefined) {
-    globalConfig.pane_style = preservedPaneStyle
-  }
-
   return globalConfig
 }
 

package/extension/domain/timeouts.ts

@@ -16,6 +16,10 @@ const STEP_KEY: Record<DispatchKind, string> = {
 
 export const DEFAULT_TIMEOUT_MS = 900_000
 
+export function deadlineAfter(start: number, duration: number): number {
+  return Math.min(Number.MAX_SAFE_INTEGER, start + duration)
+}
+
 export function timeoutMsForKind(
   kind: DispatchKind,
   timeouts: Record<string, number>,

package/extension/domain/types.ts

@@ -12,12 +12,59 @@ export type Role = "orchestrator" | "planner" | "reviewer" | "coder"
 
 export type RoleMode = "oneshot" | "interactive"
 
-export type PaneStyle = "regular" | "floating"
+export type PendingDelivery = "manual" | "interactive"
 
 export type Verdict = "APPROVED" | "CHANGES_REQUIRED"
 
 export type ReworkTarget = "code" | "phase_package"
 
+export type RequiredReworkTarget = "plan" | ReworkTarget
+
+/** Fields every pending commit carries regardless of backend. */
+export interface PendingCommitCore {
+  /** Transaction id; appears in the commit message as `Apnea-Transaction: <id>`. */
+  id: string
+  /** Phase whose completion this transaction commits. */
+  phase_index: number
+  /** Full commit message including the `Apnea-Transaction:` trailer line. */
+  message: string
+  /** Whether completion advances to finishing instead of the next phase. */
+  no_remaining_phases: boolean
+  /** Repo-relative `.apnea/` path of the verify log for this phase. */
+  verify_log: string
+}
+
+/** Git anchor captured before any ref moves: the exact commit to create. */
+export interface GitPendingCommit extends PendingCommitCore {
+  backend: "git"
+  /** Full ref (e.g. `refs/heads/apnea/slug`) the commit must land on. */
+  branch: string
+  /** Expected HEAD when completion starts; also the created commit's parent. */
+  parent_commit: string
+  /** Prepared tree id (staged with `.apnea` excluded). */
+  tree_id: string
+}
+
+/** jj anchor captured right after describing `@`. */
+export interface JjPendingCommit extends PendingCommitCore {
+  backend: "jj"
+  /** Change id of the described working-copy change. */
+  change_id: string
+  /** Fingerprint of the change's non-.apnea diff at preparation time. */
+  content_fingerprint: string
+}
+
+/**
+ * Durable record of an in-flight commit. Written after VCS preparation and
+ * before completion, so a crash anywhere afterwards can recognize and finish
+ * the transaction exactly once.
+ */
+export type PendingCommit = GitPendingCommit | JjPendingCommit
+
+/** Internal decode marker for ambiguous version-1 planning state. */
+export const LEGACY_PLAN_REWORK = Symbol("apnea.legacy-plan-rework")
+export const LEGACY_CODE_REWORK = Symbol("apnea.legacy-code-rework")
+
 export type VcsBackend = "jj" | "git"
 
 export interface Profile {
@@ -34,11 +81,10 @@ export interface ApneaConfig {
   roles: Record<string, RoleBinding>
   review_round_cap: number
   timeouts_ms: Record<string, number>
-  pane_style: PaneStyle
 }
 
 export interface RunState {
-  version: 1
+  version: 2
   slug: string
   step: Step
   phase_index: number
@@ -53,16 +99,12 @@ export interface RunState {
   pending_artifact: string | null
   /** Role for pending dispatch */
   pending_role: Role | null
+  /** Delivery boundary crossed for the pending dispatch, if known. */
+  pending_delivery: PendingDelivery | null
   /** Herdr pane id for the in-flight dispatch */
   pending_pane_id: string | null
   /** Label of that pane (apnea:role:unique) */
   pending_pane_label: string | null
-  /**
-   * Relative path to the floating oneshot exit-status file (written when the
-   * popup worker process ends). Null for regular panes. Herdr popups have no
-   * pane id — this is how wait detects death without hanging until timeout.
-   */
-  pending_floating_exit: string | null
   /**
    * Epoch ms when the in-flight dispatch was launched. Null when idle.
    * Persisted so a chunked `workflow_wait` measures elapsed time from the
@@ -108,8 +150,19 @@ export interface RunState {
   current_phase_package: string | null
   /** Last code-review path for commit gate */
   current_code_review: string | null
-  /** The next phase-package dispatch must consume planner-owned rework. */
-  phase_package_rework: boolean
+  /** The exact dispatch that owns the next review round, if any. */
+  required_rework: RequiredReworkTarget | null
+  /**
+   * In-flight commit transaction, if any. Set after VCS preparation and
+   * cleared only after completion + bookmark succeed; a crash leaves it
+   * durable so the next `workflow_commit_phase` call resumes that
+   * transaction instead of re-running gates and verification.
+   */
+  pending_commit: PendingCommit | null
+  /** Never serialized. An old planning state needs an explicit assertion. */
+  [LEGACY_PLAN_REWORK]?: true
+  /** Never serialized. Ambiguous old coding state needs an explicit assertion. */
+  [LEGACY_CODE_REWORK]?: true
 }
 
 export interface FrontMatter {