@naxodev/apnea 0.1.0

package/extension/schema/config.ts

@@ -0,0 +1,315 @@
+import { Result, Schema } from "effect"
+import { ConfigError } from "../errors.ts"
+import {
+  DEFAULT_TIMEOUTS,
+  ROLE_MODE,
+  type ApneaConfig,
+  type PaneStyle,
+  type Profile,
+  type Role,
+  type RoleMode,
+} from "../domain/types.ts"
+
+const StringArray = Schema.Array(Schema.String)
+
+const ProfileSchema = Schema.Struct({
+  cmd_oneshot: Schema.optional(StringArray),
+  cmd_interactive: Schema.optional(StringArray),
+})
+
+const RoleBindingSchema = Schema.Struct({
+  profile: Schema.String.check(Schema.isMinLength(1)),
+})
+
+export const PaneStyleSchema = Schema.Literals(["regular", "floating"] as const)
+
+/**
+ * Mirrors `schemas/config.schema.json` top-level keys.
+ *
+ * `review_round_cap` / `timeouts_ms` carry no range `check`: an out-of-range
+ * number must fall back to the default (see below), not fail the decode. A
+ * hard failure here bricks every tool until the file is hand-edited.
+ */
+export const GlobalConfigSchema = Schema.Struct({
+  profiles: Schema.optional(Schema.Record(Schema.String, ProfileSchema)),
+  roles: Schema.optional(Schema.Record(Schema.String, RoleBindingSchema)),
+  review_round_cap: Schema.optional(Schema.Number),
+  timeouts_ms: Schema.optional(Schema.Record(Schema.String, Schema.Number)),
+  pane_style: Schema.optional(PaneStyleSchema),
+})
+
+const PROJECT_KNOWN = new Set([
+  "roles",
+  "review_round_cap",
+  "timeouts_ms",
+  "isolation",
+  "pane_style",
+])
+
+const PROJECT_FORBIDDEN = new Set([
+  "cmd",
+  "cmd_oneshot",
+  "cmd_interactive",
+  "bin",
+  "profiles",
+])
+
+/**
+ * Project overlay — unknown keys and profile-owned keys fail decode.
+ * Range-tolerant for the same reason as `GlobalConfigSchema`.
+ */
+export const ProjectConfigSchema = Schema.Struct({
+  roles: Schema.optional(Schema.Record(Schema.String, RoleBindingSchema)),
+  review_round_cap: Schema.optional(Schema.Number),
+  timeouts_ms: Schema.optional(Schema.Record(Schema.String, Schema.Number)),
+  isolation: Schema.optional(Schema.Literal("shared_cwd")),
+  pane_style: Schema.optional(PaneStyleSchema),
+})
+
+function configFail(
+  message: string,
+  path?: string,
+): Result.Result<never, ConfigError> {
+  return Result.fail(
+    path !== undefined
+      ? new ConfigError({ message, path })
+      : new ConfigError({ message }),
+  )
+}
+
+function asObject(
+  v: unknown,
+  label: string,
+): Result.Result<Record<string, unknown>, ConfigError> {
+  if (!v || typeof v !== "object" || Array.isArray(v)) {
+    return configFail(`${label} must be a JSON object`)
+  }
+  return Result.succeed(v as Record<string, unknown>)
+}
+
+/** Decode + apply parseGlobal defaults into ApneaConfig. */
+export function decodeGlobalConfig(
+  raw: unknown,
+): Result.Result<ApneaConfig, ConfigError> {
+  const objR = asObject(raw, "global config")
+  if (Result.isFailure(objR)) return configFail(objR.failure.message)
+
+  const obj = objR.success
+
+  if (
+    "isolation" in obj &&
+    obj.isolation !== undefined &&
+    obj.isolation !== "shared_cwd"
+  ) {
+    return configFail(
+      `unimplemented config value isolation=${JSON.stringify(obj.isolation)} (v1 only supports shared_cwd or omit)`,
+    )
+  }
+
+  // Reject cmd-like keys nested under roles before struct decode.
+  if (obj.roles && typeof obj.roles === "object" && !Array.isArray(obj.roles)) {
+    for (const [k, v] of Object.entries(obj.roles as Record<string, unknown>)) {
+      if (!v || typeof v !== "object" || Array.isArray(v)) continue
+      const r = v as Record<string, unknown>
+      for (const bad of PROJECT_FORBIDDEN) {
+        if (bad !== "profiles" && bad in r) {
+          return configFail(`roles.${k} must not include ${bad}; use profiles`)
+        }
+      }
+    }
+  }
+
+  const decoded = Schema.decodeUnknownResult(GlobalConfigSchema)(obj)
+  if (Result.isFailure(decoded)) {
+    return configFail(decoded.failure.message)
+  }
+
+  const d = decoded.success
+  const profiles: Record<string, Profile> = {}
+  for (const [name, p] of Object.entries(d.profiles ?? {})) {
+    const out: Profile = {}
+    if (p.cmd_oneshot) out.cmd_oneshot = [...p.cmd_oneshot]
+    if (p.cmd_interactive) out.cmd_interactive = [...p.cmd_interactive]
+    if (!out.cmd_oneshot?.length && !out.cmd_interactive?.length) {
+      return configFail(
+        `profile ${name} needs cmd_oneshot and/or cmd_interactive`,
+      )
+    }
+    profiles[name] = out
+  }
+
+  const roles: Record<string, { profile: string }> = {}
+  for (const [k, v] of Object.entries(d.roles ?? {})) {
+    roles[k] = { profile: v.profile }
+  }
+
+  const timeouts = { ...DEFAULT_TIMEOUTS }
+  if (d.timeouts_ms) {
+    for (const [k, v] of Object.entries(d.timeouts_ms)) {
+      if (typeof v === "number" && v >= 1000) timeouts[k] = v
+    }
+  }
+
+  const pane_style: PaneStyle =
+    d.pane_style === "regular" || d.pane_style === "floating"
+      ? d.pane_style
+      : "regular"
+
+  return Result.succeed({
+    profiles,
+    roles,
+    review_round_cap:
+      typeof d.review_round_cap === "number" && d.review_round_cap >= 1
+        ? d.review_round_cap
+        : 3,
+    timeouts_ms: timeouts,
+    pane_style,
+  })
+}
+
+/** Validate project overlay (unknown keys fail). Does not merge. */
+export function decodeProjectConfig(
+  raw: unknown,
+): Result.Result<typeof ProjectConfigSchema.Type, ConfigError> {
+  if (raw == null) {
+    return Result.succeed({})
+  }
+  const objR = asObject(raw, "project config")
+  if (Result.isFailure(objR)) return configFail(objR.failure.message)
+
+  const obj = objR.success
+
+  for (const key of Object.keys(obj)) {
+    if (PROJECT_FORBIDDEN.has(key)) {
+      return configFail(
+        `project config must not set ${key} (binaries/profiles only allowed in global config)`,
+      )
+    }
+    if (!PROJECT_KNOWN.has(key)) {
+      return configFail(`unknown project config key: ${key}`)
+    }
+    if (
+      key === "isolation" &&
+      obj.isolation !== "shared_cwd" &&
+      obj.isolation !== undefined
+    ) {
+      return configFail(
+        `unimplemented isolation=${JSON.stringify(obj.isolation)}`,
+      )
+    }
+  }
+
+  // roles must not carry profile-owned keys
+  if (obj.roles && typeof obj.roles === "object" && !Array.isArray(obj.roles)) {
+    for (const [k, v] of Object.entries(obj.roles as Record<string, unknown>)) {
+      if (!v || typeof v !== "object" || Array.isArray(v)) {
+        return configFail(`project roles.${k} must be a JSON object`)
+      }
+      const r = v as Record<string, unknown>
+      for (const bad of ["cmd", "cmd_oneshot", "cmd_interactive", "bin"]) {
+        if (bad in r) {
+          return configFail(`project roles.${k} must not set ${bad}`)
+        }
+      }
+    }
+  }
+
+  const decoded = Schema.decodeUnknownResult(ProjectConfigSchema)(obj, {
+    onExcessProperty: "error",
+  })
+  if (Result.isFailure(decoded)) {
+    return configFail(decoded.failure.message)
+  }
+  return Result.succeed(decoded.success)
+}
+
+/**
+ * Merge a validated project overlay onto a base config.
+ * Profiles always stay from the base (global-only).
+ */
+export function applyProjectConfig(
+  cfg: ApneaConfig,
+  overlay: typeof ProjectConfigSchema.Type,
+): ApneaConfig {
+  const roles = { ...cfg.roles }
+  if (overlay.roles) {
+    for (const [k, v] of Object.entries(overlay.roles)) {
+      roles[k] = { profile: v.profile }
+    }
+  }
+  const timeouts = { ...cfg.timeouts_ms }
+  if (overlay.timeouts_ms) {
+    for (const [k, v] of Object.entries(overlay.timeouts_ms)) {
+      if (typeof v === "number" && v >= 1000) timeouts[k] = v
+    }
+  }
+  return {
+    profiles: cfg.profiles,
+    roles,
+    review_round_cap:
+      overlay.review_round_cap !== undefined && overlay.review_round_cap >= 1
+        ? overlay.review_round_cap
+        : cfg.review_round_cap,
+    timeouts_ms: timeouts,
+    pane_style:
+      overlay.pane_style !== undefined ? overlay.pane_style : cfg.pane_style,
+  }
+}
+
+/**
+ * Resolve role → profile → `cmd_<mode>`. Shared by `ConfigLive` and the test
+ * fake so tests exercise the real resolution instead of a copy of it.
+ *
+ * Deliberately distinct from `validateRoleBindings` below: this is the runtime
+ * lookup, that one is the setup-time audit and phrases the same failures as
+ * actionable config guidance.
+ */
+export function resolveRoleCmdResult(
+  cfg: ApneaConfig,
+  role: Role,
+  mode: RoleMode = ROLE_MODE[role],
+): Result.Result<string[], ConfigError> {
+  const binding = cfg.roles[role]
+  if (!binding) {
+    return configFail(`no role binding for ${role}`)
+  }
+  const profile = cfg.profiles[binding.profile]
+  if (!profile) {
+    return configFail(`unknown profile ${binding.profile}`)
+  }
+  const cmd = mode === "oneshot" ? profile.cmd_oneshot : profile.cmd_interactive
+  if (!cmd?.length) {
+    return configFail(`profile ${binding.profile} has no cmd_${mode}`)
+  }
+  return Result.succeed([...cmd])
+}
+
+/**
+ * Validate planner/reviewer/coder role→profile bindings and required cmds.
+ * Success returns cfg unchanged.
+ */
+export function validateRoleBindings(
+  cfg: ApneaConfig,
+): Result.Result<ApneaConfig, ConfigError> {
+  for (const role of ["planner", "reviewer", "coder"] as Role[]) {
+    const binding = cfg.roles[role]
+    if (!binding) {
+      return configFail(`config missing roles.${role}`)
+    }
+    const profile = cfg.profiles[binding.profile]
+    if (!profile) {
+      return configFail(
+        `roles.${role} profile "${binding.profile}" not defined in global profiles`,
+      )
+    }
+    const mode = ROLE_MODE[role]
+    const cmd =
+      mode === "oneshot" ? profile.cmd_oneshot : profile.cmd_interactive
+    if (!cmd?.length) {
+      return configFail(
+        `profile "${binding.profile}" missing cmd_${mode} required by role ${role}`,
+      )
+    }
+  }
+  return Result.succeed(cfg)
+}

package/extension/schema/frontmatter.ts

@@ -0,0 +1,34 @@
+import { Result, Schema } from "effect"
+import { ArtifactInvalid } from "../errors.ts"
+
+const VerdictSchema = Schema.Literals(["APPROVED", "CHANGES_REQUIRED"] as const)
+const ReworkTargetSchema = Schema.Literals(["code", "phase_package"] as const)
+
+/**
+ * Schema for the parsed front-matter result shape (after the line parser).
+ * Consumed by wait in Phase 4.
+ */
+export const FrontMatterResultSchema = Schema.Struct({
+  status: Schema.String,
+  verdict: Schema.optional(VerdictSchema),
+  nits: Schema.optional(Schema.String),
+  rework: Schema.optional(ReworkTargetSchema),
+})
+
+export type FrontMatterResult = typeof FrontMatterResultSchema.Type
+
+export function decodeFrontMatterResult(
+  raw: unknown,
+  artifact = "artifact",
+): Result.Result<FrontMatterResult, ArtifactInvalid> {
+  const decoded = Schema.decodeUnknownResult(FrontMatterResultSchema)(raw)
+  if (Result.isFailure(decoded)) {
+    return Result.fail(
+      new ArtifactInvalid({
+        artifact,
+        message: decoded.failure.message,
+      }),
+    )
+  }
+  return Result.succeed(decoded.success)
+}

package/extension/schema/state.ts

@@ -0,0 +1,119 @@
+import { Result, Schema } from "effect"
+import { StateCorrupt } from "../errors.ts"
+import type { RunState, Step } from "../domain/types.ts"
+
+export const StepSchema = Schema.Literals([
+  "planning",
+  "plan_review",
+  "phase_packaging",
+  "coding",
+  "code_review",
+  "committing",
+  "finishing",
+  "done",
+] as const)
+
+export const VcsBackendSchema = Schema.Literals(["jj", "git"] as const)
+
+export const RoleSchema = Schema.Literals([
+  "orchestrator",
+  "planner",
+  "reviewer",
+  "coder",
+] as const)
+
+const PaneRefSchema = Schema.Struct({
+  pane_id: Schema.String,
+  label: Schema.String,
+  profile_fingerprint: Schema.optionalKey(Schema.NullOr(Schema.String)),
+})
+
+/**
+ * Runtime codec for `state.json` (version 1).
+ * Missing pane-tracking fields are filled in `decodeRunState` (legacy files).
+ */
+export const RunStateSchema = Schema.Struct({
+  version: Schema.Literal(1),
+  slug: Schema.String.check(Schema.isMinLength(1)),
+  step: StepSchema,
+  phase_index: Schema.Number,
+  phase_count_hint: Schema.NullOr(Schema.Number),
+  rounds: Schema.Record(Schema.String, Schema.Number),
+  vcs: VcsBackendSchema,
+  allow_dirty: Schema.Boolean,
+  goal: Schema.String,
+  last_error: Schema.NullOr(Schema.String),
+  pending_artifact: Schema.NullOr(Schema.String),
+  pending_role: Schema.NullOr(RoleSchema),
+  // optional on Encoded so legacy fixtures without pane fields still decode
+  pending_pane_id: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  pending_pane_label: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  /** Mirrored in `schemas/state.schema.json`; drift is caught by schema.test.ts. */
+  pending_floating_exit: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  pending_started_at: Schema.optionalKey(Schema.NullOr(Schema.Number)),
+  pending_deadline_ms: Schema.optionalKey(Schema.NullOr(Schema.Number)),
+  pending_nudged_at: Schema.optionalKey(Schema.NullOr(Schema.Number)),
+  pending_final_grace: Schema.optionalKey(Schema.Boolean),
+  pending_extended: Schema.optionalKey(Schema.Boolean),
+  role_panes: Schema.optionalKey(Schema.Record(Schema.String, PaneRefSchema)),
+  package_root: Schema.String,
+  reviewer_tree_fingerprint: Schema.NullOr(Schema.String),
+  current_phase_package: Schema.NullOr(Schema.String),
+  current_code_review: Schema.NullOr(Schema.String),
+  phase_package_rework: Schema.optionalKey(Schema.Boolean),
+})
+
+export type DecodedRunState = typeof RunStateSchema.Type
+
+export function decodeRunState(
+  json: unknown,
+  path = "state.json",
+): Result.Result<RunState, StateCorrupt> {
+  const decoded = Schema.decodeUnknownResult(RunStateSchema)(json)
+  if (Result.isFailure(decoded)) {
+    return Result.fail(
+      new StateCorrupt({
+        path,
+        message: decoded.failure.message,
+      }),
+    )
+  }
+  const d = decoded.success
+  // Backward-compat defaults for state.json files predating pane tracking.
+  const state: RunState = {
+    version: 1,
+    slug: d.slug,
+    step: d.step as Step,
+    phase_index: d.phase_index,
+    phase_count_hint: d.phase_count_hint,
+    rounds: { ...d.rounds },
+    vcs: d.vcs,
+    allow_dirty: d.allow_dirty,
+    goal: d.goal,
+    last_error: d.last_error,
+    pending_artifact: d.pending_artifact,
+    pending_role: d.pending_role,
+    pending_pane_id: d.pending_pane_id ?? null,
+    pending_pane_label: d.pending_pane_label ?? null,
+    pending_floating_exit: d.pending_floating_exit ?? null,
+    pending_started_at: d.pending_started_at ?? null,
+    pending_deadline_ms: d.pending_deadline_ms ?? null,
+    pending_nudged_at: d.pending_nudged_at ?? null,
+    pending_final_grace: d.pending_final_grace ?? false,
+    pending_extended: d.pending_extended ?? false,
+    role_panes: Object.fromEntries(
+      Object.entries(d.role_panes ?? {}).map(([role, pane]) => [
+        role,
+        { ...pane, profile_fingerprint: pane.profile_fingerprint ?? null },
+      ]),
+    ),
+    package_root: d.package_root,
+    reviewer_tree_fingerprint: d.reviewer_tree_fingerprint,
+    current_phase_package: d.current_phase_package,
+    current_code_review: d.current_code_review,
+    phase_package_rework: d.phase_package_rework ?? false,
+  }
+  return Result.succeed(state)
+}
+
+export type { Step }

package/extension/services/app-live.ts

@@ -0,0 +1,24 @@
+import { Layer } from "effect"
+import { neutralHostAdapter, type ApneaHostAdapter } from "../host-adapter.ts"
+import { ConfigLive } from "./config.ts"
+import { FileSystemLive } from "./file-system.ts"
+import { makeHerdrLive } from "./herdr.ts"
+import { RunStoreLive } from "./run-store.ts"
+import { VcsLive } from "./vcs.ts"
+
+/**
+ * Blueprint layer for tool calls. Built freshly on every `Effect.provide`
+ * inside runTool — no module-level ManagedRuntime.
+ */
+export const makeAppLive = (hostAdapter: ApneaHostAdapter) =>
+  Layer.provideMerge(
+    Layer.mergeAll(
+      RunStoreLive,
+      ConfigLive,
+      VcsLive,
+      makeHerdrLive(hostAdapter),
+    ),
+    FileSystemLive,
+  )
+
+export const AppLive = makeAppLive(neutralHostAdapter)

package/extension/services/config.ts

@@ -0,0 +1,103 @@
+import { Context, Effect, Layer, Result } from "effect"
+import { globalConfigPath, projectConfigPath } from "../domain/paths.ts"
+import { ConfigError } from "../errors.ts"
+import {
+  ROLE_MODE,
+  type ApneaConfig,
+  type Role,
+  type RoleMode,
+} from "../domain/types.ts"
+import {
+  applyProjectConfig,
+  decodeGlobalConfig,
+  decodeProjectConfig,
+  resolveRoleCmdResult,
+  validateRoleBindings,
+} from "../schema/config.ts"
+import { FileSystem } from "./file-system.ts"
+
+export interface ConfigService {
+  readonly load: (root: string) => Effect.Effect<ApneaConfig, ConfigError>
+  readonly resolveRoleCmd: (
+    cfg: ApneaConfig,
+    role: Role,
+    mode?: RoleMode,
+  ) => Effect.Effect<string[], ConfigError>
+}
+
+export class Config extends Context.Service<Config, ConfigService>()(
+  "apnea/Config",
+) {}
+
+function parseJson(
+  text: string,
+  filePath: string,
+): Effect.Effect<unknown, ConfigError> {
+  return Effect.try({
+    try: () => JSON.parse(text) as unknown,
+    catch: (e) =>
+      new ConfigError({
+        message: `invalid JSON at ${filePath}: ${e instanceof Error ? e.message : String(e)}`,
+        path: filePath,
+      }),
+  })
+}
+
+export const ConfigLive = Layer.effect(
+  Config,
+  Effect.gen(function* () {
+    const fs = yield* FileSystem
+
+    const load = (root: string): Effect.Effect<ApneaConfig, ConfigError> =>
+      Effect.gen(function* () {
+        const gPath = globalConfigPath()
+        const gPresent = yield* fs.exists(gPath)
+        if (!gPresent) {
+          return yield* new ConfigError({
+            message: `missing global config at ${gPath}. Run apnea-setup / create profiles there.`,
+            path: gPath,
+          })
+        }
+        const gText = yield* fs.readFile(gPath)
+        const gRaw = yield* parseJson(gText, gPath)
+        const gDecoded = decodeGlobalConfig(gRaw)
+        if (Result.isFailure(gDecoded)) {
+          return yield* gDecoded.failure
+        }
+        let cfg = gDecoded.success
+
+        const pPath = projectConfigPath(root)
+        const pPresent = yield* fs.exists(pPath)
+        if (pPresent) {
+          const pText = yield* fs.readFile(pPath)
+          const pRaw = yield* parseJson(pText, pPath)
+          const pDecoded = decodeProjectConfig(pRaw)
+          if (Result.isFailure(pDecoded)) {
+            return yield* pDecoded.failure
+          }
+          cfg = applyProjectConfig(cfg, pDecoded.success)
+        }
+
+        const validated = validateRoleBindings(cfg)
+        if (Result.isFailure(validated)) {
+          return yield* validated.failure
+        }
+        return validated.success
+      })
+
+    const resolveRoleCmd = (
+      cfg: ApneaConfig,
+      role: Role,
+      mode: RoleMode = ROLE_MODE[role],
+    ): Effect.Effect<string[], ConfigError> =>
+      Effect.gen(function* () {
+        const resolved = resolveRoleCmdResult(cfg, role, mode)
+        if (Result.isFailure(resolved)) {
+          return yield* resolved.failure
+        }
+        return resolved.success
+      })
+
+    return Config.of({ load, resolveRoleCmd })
+  }),
+)