@naxodev/apnea 0.1.0

package/extension/workflows/reset.ts

@@ -0,0 +1,26 @@
+import { Effect } from "effect"
+import { getRound, setRound } from "../domain/rounds.ts"
+import type { AppError } from "../errors.ts"
+import { ok, type ToolResult } from "../result.ts"
+import { RunStore } from "../services/run-store.ts"
+
+/**
+ * Human-only: reset rework counter for a gate key.
+ * Missing/corrupt state → NoRunState / StateCorrupt.
+ */
+export const resetRoundsWorkflow = (
+  params: { gate: string },
+  root: string,
+): Effect.Effect<ToolResult, AppError, RunStore> =>
+  Effect.gen(function* () {
+    const store = yield* RunStore
+    const state = yield* store.require(root)
+    const key = params.gate
+    const prev = getRound(state, key)
+    setRound(state, key, 1)
+    state.last_error = null
+    yield* store.save(state, root)
+    return ok(`reset rounds for ${key}: ${prev} → 1`, {
+      note: "human-only tool; orchestrator must not call this",
+    })
+  })

package/extension/workflows/setup.ts

@@ -0,0 +1,301 @@
+import * as path from "node:path"
+import { Effect, Result } from "effect"
+import { supportsFloating } from "../domain/herdr.ts"
+import {
+  globalConfigPath,
+  packageRoot,
+  projectConfigPath,
+} from "../domain/paths.ts"
+import {
+  buildGlobalConfig,
+  detectionNotes,
+  pickRoles,
+  type Detected,
+} from "../domain/setup.ts"
+import { ConfigError, type AppError } from "../errors.ts"
+import { ok, type ToolResult } from "../result.ts"
+import { decodeGlobalConfig } from "../schema/config.ts"
+import { FileSystem } from "../services/file-system.ts"
+import { Herdr } from "../services/herdr.ts"
+
+export type SetupParams = {
+  /** Write .apnea/config.json role bindings in cwd */
+  project?: boolean
+  /** Overwrite existing global profiles (default: merge, keep existing profile keys) */
+  force?: boolean
+  /**
+   * Write (or refresh) a loop primer at `<root>/AGENTS.md` for harnesses
+   * that read that file but have no Apnea Pi plugin. Merge is marker-guarded
+   * — see `AGENTS_SECTION` — so a re-run never clobbers the rest of the file.
+   */
+  agents_md?: boolean
+}
+
+const AGENTS_MD_BEGIN = "<!-- apnea:begin -->"
+const AGENTS_MD_END = "<!-- apnea:end -->"
+
+/**
+ * Names real `apnea` CLI verbs, never Pi tool names — a harness with no
+ * Apnea plugin can only run shell commands, so a primer naming `dispatch_role`
+ * would be useless to it.
+ */
+const AGENTS_SECTION = `${AGENTS_MD_BEGIN}
+## Apnea runs
+
+Drive a run with the \`apnea\` CLI. Each result prints \`next:\` — follow it.
+
+\`\`\`
+apnea start "<goal>"     # writes state only; does NOT launch a role
+apnea dispatch plan      # then follow next: on every result
+apnea wait               # exit 3 = still waiting, call again; exit 0 = ready
+apnea commit --done      # after an APPROVED code review
+\`\`\`
+
+Never edit \`.apnea/state.json\` by hand. \`apnea reset-rounds\` is human-only.
+${AGENTS_MD_END}
+`
+
+const AGENTS_BLOCK_RE = /<!-- apnea:begin -->[\s\S]*?<!-- apnea:end -->\n?/
+
+/**
+ * Replace the marker-bounded block in place when present, otherwise append.
+ * Internal to `setupWorkflow`; `setup.test.ts` exercises merge behavior
+ * black-box, through the written `AGENTS.md` file, not by importing this.
+ */
+function mergeAgentsMd(existing: string | null): string {
+  if (existing == null || existing.length === 0) return AGENTS_SECTION
+  if (AGENTS_BLOCK_RE.test(existing)) {
+    return existing.replace(AGENTS_BLOCK_RE, AGENTS_SECTION)
+  }
+  const sep = existing.endsWith("\n") ? "\n" : "\n\n"
+  return `${existing}${sep}${AGENTS_SECTION}`
+}
+
+export type SetupDeps = {
+  /** Detect an executable on PATH (production: `which`). */
+  onPath: (bin: string) => boolean
+  /** Prepare host-specific role resources, or return null when none are needed. */
+  materializeRoleAgentDir: () => string | null
+}
+
+export type ProvisionResult = {
+  copied: string | null // dest dir, or null when skipped
+  linked: boolean // true only when we ran `herdr plugin link` OK
+  already_linked: boolean
+  notes: string[]
+}
+
+/**
+ * Copy the package's herdr-plugin into a stable config-local path and, when
+ * herdr is new enough and the plugin isn't already linked, run
+ * `herdr plugin link`. Never fails — every branch is a note.
+ */
+export const provisionHerdrPlugin = (opts: {
+  srcDir: string // packageRoot()/herdr-plugin
+  destDir: string // dirname(globalConfigPath())/herdr-plugin
+  version: [number, number, number] | null // herdr.version
+}): Effect.Effect<ProvisionResult, never, FileSystem | Herdr> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem
+    const herdr = yield* Herdr
+    const notes: string[] = []
+
+    const srcExists = yield* fs.exists(opts.srcDir)
+    if (!srcExists) {
+      notes.push("herdr-plugin missing from package — reinstall @naxodev/apnea")
+      return { copied: null, linked: false, already_linked: false, notes }
+    }
+
+    yield* fs.copyDir(opts.srcDir, opts.destDir)
+    const runTask = path.join(opts.destDir, "scripts", "run-task.sh")
+    if (yield* fs.exists(runTask)) {
+      yield* fs.chmod(runTask, 0o755)
+    }
+
+    if (!supportsFloating(opts.version)) {
+      const ver =
+        opts.version == null
+          ? "unknown"
+          : `${opts.version[0]}.${opts.version[1]}.${opts.version[2]}`
+      notes.push(
+        `herdr ${ver} < 0.7.4 — floating panes unavailable; run \`herdr update\`, then re-run /apnea setup`,
+      )
+      return {
+        copied: opts.destDir,
+        linked: false,
+        already_linked: false,
+        notes,
+      }
+    }
+
+    if (yield* herdr.hasApneaPlugin) {
+      return {
+        copied: opts.destDir,
+        linked: false,
+        already_linked: true,
+        notes,
+      }
+    }
+
+    const linkResult = yield* herdr.linkPlugin(opts.destDir)
+    if (!linkResult.ok) {
+      notes.push(
+        `herdr plugin link failed: ${linkResult.raw.trim() || "(no output)"}`,
+      )
+      return {
+        copied: opts.destDir,
+        linked: false,
+        already_linked: false,
+        notes,
+      }
+    }
+
+    return { copied: opts.destDir, linked: true, already_linked: false, notes }
+  })
+
+/**
+ * Deterministic Apnea setup: detect binaries, write global profiles
+ * (and optional project role bindings). Never writes cmd into project config.
+ */
+export const setupWorkflow = (
+  params: SetupParams,
+  root: string,
+  deps: SetupDeps,
+): Effect.Effect<ToolResult, AppError, FileSystem | Herdr> =>
+  Effect.gen(function* () {
+    const fs = yield* FileSystem
+    const herdr = yield* Herdr
+
+    const readJsonSafe = (
+      filePath: string,
+    ): Effect.Effect<Record<string, unknown>> =>
+      Effect.gen(function* () {
+        const present = yield* fs.exists(filePath)
+        if (!present) return {}
+        const text = yield* fs.readFile(filePath)
+        try {
+          const v = JSON.parse(text)
+          if (v && typeof v === "object" && !Array.isArray(v)) {
+            return v as Record<string, unknown>
+          }
+          return {}
+        } catch {
+          return {}
+        }
+      })
+
+    const has: Detected = {
+      pi: deps.onPath("pi"),
+      claude: deps.onPath("claude"),
+      codex: deps.onPath("codex"),
+      herdr: deps.onPath("herdr"),
+      jj: deps.onPath("jj"),
+      git: deps.onPath("git"),
+    }
+
+    if (!has.pi && !has.claude && !has.codex) {
+      return yield* new ConfigError({
+        message:
+          "no supported agent CLI on PATH — install pi, claude, or codex before apnea setup",
+      })
+    }
+
+    const gPath = globalConfigPath()
+    yield* fs.mkdir(path.dirname(gPath), { recursive: true })
+
+    const prev = yield* readJsonSafe(gPath)
+    const force = params.force === true
+    const globalConfig = buildGlobalConfig({ has, prev, force })
+
+    const serialized = `${JSON.stringify(globalConfig, null, 2)}\n`
+    yield* fs.writeFile(gPath, serialized)
+
+    let projectPath: string | null = null
+    if (params.project) {
+      const pPath = projectConfigPath(root)
+      // project: roles only — never cmd
+      const projectCfg = { roles: pickRoles(has) }
+      yield* fs.writeProjectFile(
+        root,
+        pPath,
+        `${JSON.stringify(projectCfg, null, 2)}\n`,
+      )
+      projectPath = pPath
+    }
+
+    const missing = detectionNotes(has)
+
+    // Host adapters may pre-build launch resources so first dispatch is fast.
+    let roleAgentDir: string | null = null
+    const materialized = yield* Effect.result(
+      Effect.try({ try: deps.materializeRoleAgentDir, catch: (e) => e }),
+    )
+    if (Result.isSuccess(materialized)) {
+      if (materialized.success !== null) {
+        roleAgentDir = materialized.success
+      }
+    } else {
+      const e = materialized.failure
+      missing.push(
+        `role agent dir failed: ${e instanceof Error ? e.message : String(e)}`,
+      )
+    }
+
+    let herdrPlugin: ProvisionResult | null = null
+    let herdrVer: string | null = null
+    if (has.herdr) {
+      const version = yield* herdr.version
+      herdrVer =
+        version == null ? null : `${version[0]}.${version[1]}.${version[2]}`
+      herdrPlugin = yield* provisionHerdrPlugin({
+        srcDir: path.join(packageRoot(), "herdr-plugin"),
+        destDir: path.join(path.dirname(globalConfigPath()), "herdr-plugin"),
+        version,
+      })
+      missing.push(...herdrPlugin.notes)
+    }
+
+    let agentsMdPath: string | null = null
+    if (params.agents_md) {
+      const target = path.join(root, "AGENTS.md")
+      const present = yield* fs.exists(target)
+      const existing = present ? yield* fs.readFile(target) : null
+      yield* fs.writeFile(target, mergeAgentsMd(existing))
+      agentsMdPath = target
+    }
+
+    // A failed decode after writing is a note, not a failure — a user with a
+    // malformed pre-existing config must still get a written config and an
+    // actionable note, never a hard refusal where today there is none.
+    const decoded = decodeGlobalConfig(globalConfig)
+    if (Result.isFailure(decoded)) {
+      missing.push(
+        `global config written but does not validate: ${decoded.failure.message}`,
+      )
+    }
+
+    const data: Record<string, unknown> = {
+      global: gPath,
+      project: projectPath,
+      detected: has,
+      roles: globalConfig.roles,
+      notes: missing,
+      role_agent_dir: roleAgentDir,
+      next: "edit ~/.config/apnea/config.json if model ids differ, then /apnea start <goal> inside Herdr",
+    }
+    if (params.agents_md) {
+      data.agents_md = agentsMdPath
+    }
+    if (has.herdr) {
+      data.herdr_version = herdrVer
+      data.herdr_plugin = herdrPlugin
+        ? {
+            copied: herdrPlugin.copied,
+            linked: herdrPlugin.linked,
+            already_linked: herdrPlugin.already_linked,
+          }
+        : null
+    }
+
+    return ok(`wrote global config ${gPath}`, data)
+  })

package/extension/workflows/start.ts

@@ -0,0 +1,149 @@
+import { Effect } from "effect"
+import { packageRoot } from "../domain/paths.ts"
+import { resetRecoveryLadder } from "../domain/recovery.ts"
+import { slugify } from "../domain/slug.ts"
+import { nextAfter } from "../domain/state-machine.ts"
+import { GateRefused, NoRunState, VcsError, type AppError } from "../errors.ts"
+import type { RunState } from "../domain/types.ts"
+import { ok, type ToolResult } from "../result.ts"
+import { Config } from "../services/config.ts"
+import { FileSystem } from "../services/file-system.ts"
+import { RunStore } from "../services/run-store.ts"
+import { Vcs } from "../services/vcs.ts"
+
+export type StartParams = {
+  goal: string
+  slug?: string
+  allow_dirty?: boolean
+  action?: "start" | "resume" | "abandon"
+}
+
+/**
+ * Start / resume / abandon an Apnea run.
+ * Refusals are tagged failures only — never ok:false ToolResults.
+ */
+export const startWorkflow = (
+  params: StartParams,
+  root: string,
+): Effect.Effect<ToolResult, AppError, FileSystem | RunStore | Config | Vcs> =>
+  Effect.gen(function* () {
+    const store = yield* RunStore
+    const fs = yield* FileSystem
+    const config = yield* Config
+    const vcsSvc = yield* Vcs
+    const action = params.action ?? "start"
+
+    if (action === "abandon") {
+      const bak = yield* store.abandon(root)
+      return ok(`abandoned run; state moved to ${bak}`, { backup: bak })
+    }
+
+    const existing = yield* store.load(root)
+
+    if (action === "resume") {
+      if (!existing) return yield* new NoRunState({})
+      // Never auto-dispatch; report reconcile info
+      const pending = existing.pending_artifact
+      let pendingStatus: string = "none"
+      if (pending) {
+        const absPath = pending.startsWith("/") ? pending : `${root}/${pending}`
+        const present = yield* fs.exists(absPath)
+        pendingStatus = present ? "artifact_exists" : "artifact_missing"
+      }
+      return ok(
+        "resume: re-resolve panes by label; do not auto-dispatch",
+        {
+          state: existing,
+          pending_status: pendingStatus,
+          hint:
+            pendingStatus === "artifact_exists"
+              ? "call workflow_wait to ingest pending artifact"
+              : pendingStatus === "artifact_missing"
+                ? "offer re-dispatch same round via dispatch_role"
+                : "inspect workflow_status and continue legal next step",
+        },
+        nextAfter(existing.step),
+      )
+    }
+
+    // start
+    if (existing) {
+      return yield* new GateRefused({
+        gate: "start",
+        message: `state.json already exists (step=${existing.step}). Use action=resume or action=abandon.`,
+        details: { step: existing.step, slug: existing.slug },
+      })
+    }
+
+    const cfg = yield* config.load(root)
+
+    const vcs = yield* vcsSvc.detect(root)
+    if (!vcs) {
+      return yield* new VcsError({
+        message: "no .jj or .git — refuse auto-commit setup (init vcs first)",
+      })
+    }
+
+    const allowDirty = params.allow_dirty === true
+    if (!allowDirty && (yield* vcsSvc.isDirty(root, vcs))) {
+      return yield* new GateRefused({
+        gate: "clean_tree",
+        message:
+          "working tree is dirty (file content). Commit/clean first, or pass allow_dirty=true",
+      })
+    }
+
+    const slug = params.slug?.trim() || slugify(params.goal)
+
+    if (vcs === "git") {
+      yield* vcsSvc.ensureGitBranch(root, slug)
+    }
+
+    const state: RunState = {
+      version: 1,
+      slug,
+      step: "planning",
+      phase_index: 1,
+      phase_count_hint: null,
+      rounds: {},
+      vcs,
+      allow_dirty: allowDirty,
+      goal: params.goal,
+      last_error: null,
+      pending_artifact: null,
+      pending_role: null,
+      pending_pane_id: null,
+      pending_pane_label: null,
+      pending_floating_exit: null,
+      pending_started_at: null,
+      pending_deadline_ms: null,
+      pending_nudged_at: null,
+      pending_final_grace: false,
+      pending_extended: false,
+      role_panes: {},
+      package_root: packageRoot(),
+      reviewer_tree_fingerprint: null,
+      current_phase_package: null,
+      current_code_review: null,
+      phase_package_rework: false,
+    }
+    // The literal above assigns the ladder's fields; this re-asserts them
+    // through the shared helper so a rung added there cannot be missed here.
+    // The type checker only catches a missing REQUIRED field — a flag added
+    // with a schema default would leave a fresh run carrying a stale rung.
+    resetRecoveryLadder(state)
+    yield* store.save(state, root)
+
+    return ok(
+      `started run slug=${slug} vcs=${vcs} step=planning. NEXT: dispatch_role kind=plan, then workflow_wait.`,
+      {
+        state,
+        profiles: Object.keys(cfg.profiles),
+        roles: cfg.roles,
+        next: "dispatch_role",
+        next_args: { kind: "plan" },
+        note: "start only writes state — it does not launch roles. Orchestrator must dispatch plan immediately.",
+      },
+      nextAfter(state.step),
+    )
+  })

package/extension/workflows/status.ts

@@ -0,0 +1,45 @@
+import { Effect, Result } from "effect"
+import { LEGAL_TOOLS, nextAfter } from "../domain/state-machine.ts"
+import type { StateCorrupt } from "../errors.ts"
+import { ok, type ToolResult } from "../result.ts"
+import { Config } from "../services/config.ts"
+import { RunStore } from "../services/run-store.ts"
+import { Vcs } from "../services/vcs.ts"
+
+/**
+ * Read-only snapshot. Missing state is a success (`has_state: false`),
+ * not NoRunState. Corrupt state may fail as StateCorrupt.
+ */
+export const statusWorkflow = (
+  root: string,
+): Effect.Effect<ToolResult, StateCorrupt, RunStore | Config | Vcs> =>
+  Effect.gen(function* () {
+    const store = yield* RunStore
+    const config = yield* Config
+    const vcsSvc = yield* Vcs
+    const state = yield* store.load(root)
+    if (!state) {
+      return ok("no active run", { has_state: false }, ["workflow_start"])
+    }
+
+    // Config summary never fails the tool
+    const cfgR = yield* Effect.result(config.load(root))
+    const cfgSummary: Record<string, unknown> = Result.isSuccess(cfgR)
+      ? {
+          roles: cfgR.success.roles,
+          review_round_cap: cfgR.success.review_round_cap,
+        }
+      : { config_error: cfgR.failure.message }
+
+    const vcs = yield* vcsSvc.detect(root)
+    return ok(
+      `step=${state.step} phase=${state.phase_index}`,
+      {
+        state,
+        legal_tools: LEGAL_TOOLS[state.step],
+        config: cfgSummary,
+        dirty: vcs ? yield* vcsSvc.isDirty(root, vcs) : null,
+      },
+      nextAfter(state.step),
+    )
+  })