opencode-turnstile 0.0.0-stage → 0.1.1

package/src/config.ts

@@ -0,0 +1,272 @@
+/**
+ * @fileoverview Config boundary: layered configuration for the plugin.
+ * Precedence: code defaults ⊕ JSON config file ⊕ environment variables ⊕
+ * injected overrides (tests). Config is read once at setup; restart
+ * sessions to apply. Invalid keys are ignored and journaled to the
+ * env-resolved metrics directory (the journaler does not exist until
+ * config resolves): config errors never crash the host, per the fail-open
+ * contract.
+ */
+
+import * as fs from "node:fs"
+import * as os from "node:os"
+import * as path from "node:path"
+
+import { appendLine, defaultMetricsDir } from "./journal.ts"
+import { GATE_RE, VERDICT_RE } from "./markers.ts"
+import type { TurnstileConfig } from "./types.ts"
+
+/** Default config file location. */
+export const CONFIG_PATH: string = path.join(os.homedir(), ".config", "opencode", "turnstile.json")
+
+/** Environment variable names honored by the env layer. */
+export const ENV_KEYS = {
+  trace: "TURNSTILE_TRACE",
+  metricsDir: "TURNSTILE_METRICS_DIR",
+  config: "TURNSTILE_CONFIG",
+} as const
+
+/**
+ * Builds the code defaults for every config key.
+ * @param env Environment consulted for XDG_DATA_HOME only.
+ * @returns The default TurnstileConfig (byte-equivalent to the historical
+ *     hardcoded constants).
+ */
+export function defaultConfig(
+  env: Record<string, string | undefined> = process.env,
+): TurnstileConfig {
+  return {
+    metricsDir: defaultMetricsDir(env),
+    journalMaxBytes: 5 * 1024 * 1024,
+    journalMaxGenerations: 5,
+    maxReviewerRounds: 2,
+    maxSessions: 64,
+    readWarn: 8,
+    readBlock: 15,
+    waiverMarker: "USER WAIVER:",
+    plansDir: path.join(".opencode", "plans"),
+    trace: true,
+    agents: {
+      reviewer: "reviewer",
+      planReviewer: "plan-reviewer",
+      executor: "executor",
+      testRunner: "test-runner",
+      debugger: "debugger",
+      bareOutput: ["test-runner", "reviewer", "plan-reviewer"],
+    },
+    gateMarker: GATE_RE.source,
+    verdictMarker: VERDICT_RE.source,
+  }
+}
+
+/**
+ * Validates a patch value for a scalar key.
+ * @param key Config key being set.
+ * @param value Candidate value.
+ * @returns true when the value has the right type for the key.
+ */
+function isValidScalar(key: keyof TurnstileConfig, value: unknown): boolean {
+  if (key === "trace") return typeof value === "boolean"
+  if (key === "metricsDir" || key === "waiverMarker" || key === "plansDir") {
+    return typeof value === "string" && value.trim().length > 0
+  }
+  if (key === "gateMarker" || key === "verdictMarker") return typeof value === "string"
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+}
+
+/** Scalar config keys whose valid values are finite positive numbers. */
+type NumericConfigKey = Extract<
+  keyof TurnstileConfig,
+  | "journalMaxBytes"
+  | "journalMaxGenerations"
+  | "maxReviewerRounds"
+  | "maxSessions"
+  | "readWarn"
+  | "readBlock"
+>
+
+/**
+ * Assigns a validated scalar into the config without erasing the key→type
+ * correlation the validator just established.
+ * @param config The config to mutate.
+ * @param key The validated config key.
+ * @param value The validated value.
+ */
+function assignScalar(config: TurnstileConfig, key: keyof TurnstileConfig, value: unknown): void {
+  if (key === "trace") config.trace = value as boolean
+  else if (key === "metricsDir") config.metricsDir = value as string
+  else if (key === "waiverMarker") config.waiverMarker = value as string
+  else if (key === "plansDir") config.plansDir = value as string
+  else if (key === "gateMarker") config.gateMarker = value as string
+  else if (key === "verdictMarker") config.verdictMarker = value as string
+  else config[key as NumericConfigKey] = value as number
+}
+
+/**
+ * Merges a patch into a base config with per-key validation. Unknown keys
+ * and wrongly-typed values are skipped and reported as warnings; the
+ * `agents` sub-object merges one level deep.
+ * @param base The config to merge into.
+ * @param patch Candidate overrides (typically parsed JSON or injected opts).
+ * @returns The merged config plus one warning string per skipped key.
+ */
+export function mergeConfig(
+  base: TurnstileConfig,
+  patch: unknown,
+): { config: TurnstileConfig; warnings: string[] } {
+  const warnings: string[] = []
+  const config: TurnstileConfig = { ...base, agents: { ...base.agents } }
+  if (patch === null || typeof patch !== "object" || Array.isArray(patch)) {
+    if (patch !== undefined) {
+      warnings.push(
+        `config: expected an object, got ${Array.isArray(patch) ? "array" : typeof patch}`,
+      )
+    }
+    return { config, warnings }
+  }
+  for (const [key, value] of Object.entries(patch as Record<string, unknown>)) {
+    if (key === "agents") {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        warnings.push(`config: agents must be an object; keeping defaults`)
+        continue
+      }
+      for (const [agentKey, agentValue] of Object.entries(value as Record<string, unknown>)) {
+        if (agentKey === "bareOutput") {
+          if (
+            Array.isArray(agentValue) &&
+            agentValue.every((v) => typeof v === "string" && v.trim().length > 0)
+          ) {
+            // Copy: a mutated injected options object must not retro-mutate
+            // the live config.
+            config.agents.bareOutput = [...(agentValue as string[])]
+          } else {
+            warnings.push(
+              `config: agents.bareOutput must be an array of non-empty strings; keeping default`,
+            )
+          }
+          continue
+        }
+        if (!(agentKey in config.agents)) {
+          warnings.push(`config: unknown agents key "${agentKey}" ignored`)
+          continue
+        }
+        if (typeof agentValue === "string" && agentValue.trim().length > 0) {
+          const name = agentKey as
+            "reviewer" | "planReviewer" | "executor" | "testRunner" | "debugger"
+          config.agents[name] = agentValue
+        } else {
+          warnings.push(`config: agents.${agentKey} must be a non-empty string; keeping default`)
+        }
+      }
+      continue
+    }
+    if (!(key in config)) {
+      warnings.push(`config: unknown key "${key}" ignored`)
+      continue
+    }
+    if (isValidScalar(key as keyof TurnstileConfig, value)) {
+      assignScalar(config, key as keyof TurnstileConfig, value)
+    } else {
+      warnings.push(`config: invalid value for "${key}"; keeping default`)
+    }
+  }
+  return { config, warnings }
+}
+
+/**
+ * Journals a config warning to the env-resolved metrics directory. Used
+ * only for problems detected before the real journaler exists, so the
+ * sink honors the caller's injected env (tests stay off the user journal).
+ * @param error The warning/error text.
+ * @param env Environment providing TURNSTILE_METRICS_DIR / XDG_DATA_HOME.
+ */
+function journalConfigError(error: string, env: Record<string, string | undefined>): void {
+  const metricsDir =
+    env[ENV_KEYS.metricsDir] ??
+    process.env[ENV_KEYS.metricsDir] ??
+    defaultMetricsDir({ ...process.env, ...env })
+  appendLine(
+    path.join(metricsDir, "turnstile.jsonl"),
+    JSON.stringify({ ts: new Date().toISOString(), type: "error", error }),
+  )
+}
+
+/**
+ * Reads and parses the JSON config file, returning a patch object.
+ * @param env Environment providing the config path override.
+ * @returns The parsed patch (or undefined) plus any warning.
+ */
+function readFileLayer(env: Record<string, string | undefined>): {
+  patch: unknown
+  warnings: string[]
+} {
+  const configPath = env[ENV_KEYS.config] ?? CONFIG_PATH
+  try {
+    return { patch: JSON.parse(fs.readFileSync(configPath, "utf8")), warnings: [] }
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code
+    if (code === "ENOENT") return { patch: undefined, warnings: [] }
+    const warning =
+      code === "EISDIR"
+        ? `config file ${configPath} is a directory; ignored`
+        : `config file ${configPath} unreadable/malformed: ${e}`
+    journalConfigError(warning, env)
+    return { patch: undefined, warnings: [warning] }
+  }
+}
+
+/**
+ * Applies the env layer on top of a merged config.
+ * @param config The config to mutate.
+ * @param env The environment to read.
+ * @returns One warning string per invalid env value.
+ */
+function applyEnvLayer(config: TurnstileConfig, env: Record<string, string | undefined>): string[] {
+  const warnings: string[] = []
+  const trace = env[ENV_KEYS.trace]
+  if (trace !== undefined) {
+    if (trace === "0" || trace === "false") config.trace = false
+    else if (trace === "1" || trace === "true") config.trace = true
+    else
+      warnings.push(
+        `env ${ENV_KEYS.trace}=${trace} invalid (use 0/1/true/false); keeping current value`,
+      )
+  }
+  const metricsDir = env[ENV_KEYS.metricsDir]
+  if (metricsDir !== undefined) {
+    if (metricsDir.trim().length > 0) config.metricsDir = metricsDir
+    else warnings.push(`env ${ENV_KEYS.metricsDir} empty; keeping current value`)
+  }
+  return warnings
+}
+
+/**
+ * Resolves the full layered configuration: defaults ⊕ config file ⊕ env ⊕
+ * injected overrides. Config-file and validation problems are journaled to
+ * the default metrics directory and returned as warnings, never thrown.
+ * @param env Environment providing XDG_DATA_HOME, TURNSTILE_* variables.
+ * @param overrides Final-layer overrides (injected options; tests).
+ * @returns The resolved config plus one warning string per skipped/invalid
+ *     key or file problem.
+ */
+export function loadConfig(
+  env: Record<string, string | undefined> = process.env,
+  overrides?: Partial<TurnstileConfig>,
+): { config: TurnstileConfig; warnings: string[] } {
+  const warnings: string[] = []
+  const fileLayer = readFileLayer(env)
+  const fileMerge = mergeConfig(defaultConfig(env), fileLayer.patch)
+  const config = fileMerge.config
+  warnings.push(...fileLayer.warnings, ...fileMerge.warnings)
+  warnings.push(...applyEnvLayer(config, env))
+  let resolved = config
+  if (overrides !== undefined) {
+    const merged = mergeConfig(config, overrides)
+    resolved = merged.config
+    warnings.push(...merged.warnings)
+  }
+  for (const warning of warnings) {
+    if (!warning.startsWith("config file")) journalConfigError(warning, env)
+  }
+  return { config: resolved, warnings }
+}

package/src/gates.ts

@@ -0,0 +1,295 @@
+/**
+ * @fileoverview Policy boundary: enforcement decisions: the reviewer
+ * dispatch gate, the plan-approval gate, the whole-file read horizon, and
+ * the decomposition gate.
+ * Functions here either return normally or throw a deliberate BLOCKED
+ * error; every other failure fails open upstream (hooks guard and journal).
+ * All tunables (thresholds, marker, agent names) come from the injected
+ * config; persistence goes through the injected Journaler.
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import type { Journaler } from "./journal.ts"
+import type { GateLedger } from "./state.ts"
+import type { TurnstileConfig } from "./types.ts"
+
+/**
+ * The only error type turnstile deliberately throws at the host: an
+ * enforcement block. Hook guards rethrow `BlockError` instances and
+ * journal everything else (fail-open contract).
+ */
+export class BlockError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "BlockError"
+  }
+}
+
+/** Enforcement functions bound to one resolved config + journaler. */
+export interface Gates {
+  /**
+   * Enforces the reviewer dispatch gate for a pending `task` dispatch:
+   * records a waiver when the prompt carries the waiver marker (per
+   * dispatch, not sticky), then blocks when the dispatch cap is exhausted
+   * or the test gate has not gone green.
+   * @param sessionID The parent session ID.
+   * @param prompt The dispatch prompt text.
+   * @param ledger The gate ledger to read and mutate state from.
+   * @throws Error with a `BLOCKED by turnstile:` prefix when the dispatch
+   *     must not proceed.
+   */
+  guardReviewerDispatch(sessionID: string, prompt: string, ledger: GateLedger): void
+  /**
+   * Enforces the whole-file read horizon for a session.
+   * @param sessionID The parent session ID.
+   * @param ledger The gate ledger to read state from.
+   * @throws Error with a `BLOCKED by turnstile:` prefix once the read
+   *     count has reached the configured block threshold.
+   */
+  guardReadLimit(sessionID: string, ledger: GateLedger): void
+  /**
+   * Enforces the decomposition gate: when any plan file in the configured
+   * plans directory carries a `## Decomposition` block, executor
+   * dispatches must cite the chunk-N / AC-n they implement. Unreadable
+   * plans dirs fail open.
+   * @param sessionID The parent session ID (used in journal entries).
+   * @param prompt The dispatch prompt text to check for chunk citations.
+   * @param projectDir The current project directory.
+   * @throws Error with a `BLOCKED by turnstile:` prefix when a decomposed
+   *     plan exists and the prompt cites no chunk.
+   */
+  enforceDecomposition(sessionID: string, prompt: string, projectDir: string): void
+  /**
+   * Enforces the plan-approval gate: when any plan file exists in the
+   * configured plans directory, executor dispatches require a current
+   * plan-reviewer `VERDICT: APPROVE` for the session (or a waiver).
+   * Approval is invalidated when plan files change, forcing re-review
+   * after a re-plan.
+   * @param sessionID The parent session ID.
+   * @param prompt The dispatch prompt text (checked for the waiver marker).
+   * @param projectDir The current project directory.
+   * @param ledger The gate ledger to read and mutate plan state from.
+   * @throws Error with a `BLOCKED by turnstile:` prefix when no plan file
+   *     exists yet is approved for this task.
+   */
+  enforcePlanApproval(
+    sessionID: string,
+    prompt: string,
+    projectDir: string,
+    ledger: GateLedger,
+  ): void
+}
+
+/**
+ * Binds enforcement functions to a resolved config and journaler.
+ * @param config The resolved plugin configuration.
+ * @param journaler The telemetry writer for gate and blocked entries.
+ * @returns The three enforcement functions.
+ */
+export function createGates(config: TurnstileConfig, journaler: Journaler): Gates {
+  /**
+   * Enforces the reviewer dispatch gate for a pending `task` dispatch.
+   * Records a waiver (with journal + trace) when the prompt carries the
+   * waiver marker, then blocks the dispatch when the dispatch cap is
+   * exhausted or the test gate has not gone green. The cap counts reviewer
+   * dispatches themselves (per the documented "max 2 reviewer dispatches
+   * per task" contract), not BLOCK verdicts. A waiver applies to the
+   * dispatch carrying it only; every dispatch prompt must contain the
+   * literal marker to be exempt.
+   * @param sessionID The parent session ID.
+   * @param prompt The dispatch prompt text.
+   * @param ledger The gate ledger to read and mutate state from.
+   * @throws Error with a `BLOCKED by turnstile:` prefix when the dispatch
+   *     must not proceed.
+   */
+  function guardReviewerDispatch(sessionID: string, prompt: string, ledger: GateLedger): void {
+    const s = ledger.state(sessionID)
+    const at = prompt.indexOf(config.waiverMarker)
+    const waived = at !== -1
+    if (waived) {
+      journaler.journal({
+        type: "gate",
+        sessionID,
+        result: "WAIVED",
+        // Waiver quotes carry raw prompt context; journal them only when
+        // the trace is enabled (SECURITY.md redaction contract).
+        waiver: config.trace ? prompt.slice(at, at + 200) : "<present>",
+      })
+      journaler.traceEvent("user", "waiver", prompt.slice(at, at + 120))
+    }
+    if (s.reviewRounds >= config.maxReviewerRounds && !waived) {
+      journaler.journal({
+        type: "blocked",
+        sessionID,
+        agent: config.agents.reviewer,
+        reason: "round-limit",
+      })
+      throw new BlockError(
+        `BLOCKED by turnstile: reviewer round limit (${config.maxReviewerRounds}) reached. Escalate the open findings to the user, or start a new task (a new user prompt resets the cap).`,
+      )
+    }
+    if (!s.hasGatePass && !waived) {
+      journaler.journal({
+        type: "blocked",
+        sessionID,
+        agent: config.agents.reviewer,
+        reason: "no-gate-pass",
+      })
+      throw new BlockError(
+        "BLOCKED by turnstile: no reviewer dispatch before the test gate is green. " +
+          "Run the test-runner subagent first; dispatch reviewer only after its first line is " +
+          "`GATE: PASS tests=<n> passed=<n> failed=<n>`, or obtain an explicit user waiver " +
+          "(the dispatch prompt must contain the literal marker 'USER WAIVER:' followed by the user's words).",
+      )
+    }
+    // Check-then-increment: the Nth dispatch is allowed and the (N+1)th is
+    // blocked, so exactly `maxReviewerRounds` dispatches succeed per task.
+    s.reviewRounds++
+  }
+
+  /**
+   * Enforces the whole-file read horizon for a session.
+   * @param sessionID The parent session ID.
+   * @param ledger The gate ledger to read state from.
+   * @throws Error with a `BLOCKED by turnstile:` prefix once the read
+   *     count has reached the configured block threshold.
+   */
+  function guardReadLimit(sessionID: string, ledger: GateLedger): void {
+    if (ledger.state(sessionID).reads >= config.readBlock) {
+      journaler.journal({ type: "blocked", sessionID, tool: "read", reason: "read-limit" })
+      throw new BlockError(
+        `BLOCKED by turnstile: ${config.readBlock} whole-file reads this session. Switch to grep/glob for targeted retrieval, or report being stuck and escalate to the user.`,
+      )
+    }
+  }
+
+  /**
+   * Enforces the decomposition gate: when any plan file in the configured
+   * plans directory carries a `## Decomposition` block, executor
+   * dispatches must cite the chunk-N / AC-n they implement.
+   * @param sessionID The parent session ID (used in journal entries).
+   * @param prompt The dispatch prompt text to check for chunk citations.
+   * @param projectDir The current project directory.
+   * @throws Error with a `BLOCKED by turnstile:` prefix when a decomposed
+   *     plan exists and the prompt cites no chunk.
+   */
+  // Cached plans-dir verdict keyed by the directory's content signature
+  // (dir mtime + sorted plan names + per-file mtimes). Saves the
+  // per-dispatch rescan; any fs error throws to the caller's fail-open.
+  let plansCache: { key: string; scan: PlansScan } | null = null
+
+  /** What one plans-dir scan establishes for both plan gates. */
+  interface PlansScan {
+    /** Sorted plan file names (empty when the dir holds no plans). */
+    names: string[]
+    /** First (sorted) plan carrying a `## Decomposition` block, or null. */
+    decompFile: string | null
+  }
+
+  /**
+   * Scans the plans directory, returning the scan and whether it differs
+   * from the previously cached scan (used to invalidate plan approval).
+   * @param dir Absolute plans directory path.
+   * @returns The scan plus a `changed` flag (false on the host's first
+   *     scan so a journal-replayed approval survives a restart).
+   */
+  function scanPlans(dir: string): { scan: PlansScan; changed: boolean } {
+    const names = fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith(".md"))
+      .sort()
+    const files = names.map((n) => `${n}:${fs.statSync(path.join(dir, n)).mtimeMs}`)
+    const key = `${dir}|${fs.statSync(dir).mtimeMs}|${files.join(",")}`
+    if (plansCache !== null && plansCache.key === key) {
+      return { scan: plansCache.scan, changed: false }
+    }
+    const decompFile =
+      names.find((n) => fs.readFileSync(path.join(dir, n), "utf8").includes("## Decomposition")) ??
+      null
+    const scan: PlansScan = { names, decompFile }
+    const changed = plansCache !== null
+    plansCache = { key, scan }
+    return { scan, changed }
+  }
+
+  function enforceDecomposition(sessionID: string, prompt: string, projectDir: string): void {
+    if (/\b(?:chunk-\d+|AC-\d+)\b/.test(prompt)) return
+    const plansDir = path.join(projectDir, config.plansDir)
+    try {
+      if (!fs.existsSync(plansDir)) return
+      const { scan } = scanPlans(plansDir)
+      if (scan.decompFile !== null) {
+        journaler.journal({
+          type: "blocked",
+          sessionID,
+          agent: config.agents.executor,
+          reason: "missing-chunk-ref",
+          plan: scan.decompFile,
+        })
+        throw new BlockError(
+          `BLOCKED by turnstile: plan "${scan.decompFile}" has a ## Decomposition block — executor dispatches must cite the chunk-N / AC-n they implement.`,
+        )
+      }
+    } catch (e) {
+      if (e instanceof BlockError) throw e
+      // unreadable plans dir: fail-open
+    }
+  }
+
+  function enforcePlanApproval(
+    sessionID: string,
+    prompt: string,
+    projectDir: string,
+    ledger: GateLedger,
+  ): void {
+    const at = prompt.indexOf(config.waiverMarker)
+    if (at !== -1) {
+      journaler.journal({
+        type: "plan",
+        sessionID,
+        result: "WAIVED",
+        // Waiver quotes carry raw prompt context; journal them only when
+        // the trace is enabled (SECURITY.md redaction contract).
+        waiver: config.trace ? prompt.slice(at, at + 200) : "<present>",
+      })
+      journaler.traceEvent("user", "plan-waiver", prompt.slice(at, at + 120))
+      return
+    }
+    const plansDir = path.join(projectDir, config.plansDir)
+    try {
+      if (!fs.existsSync(plansDir)) return
+      const { scan, changed } = scanPlans(plansDir)
+      if (scan.names.length === 0) return
+      const s = ledger.state(sessionID)
+      if (changed) {
+        // Plan files changed since the last scan → any prior approval is
+        // stale and re-review is required. The host's very first scan does
+        // not clear (changed=false there) so a journal-replayed approval
+        // survives a restart.
+        s.hasPlanVerdict = false
+      }
+      if (!s.hasPlanVerdict) {
+        const plan = scan.names[0]
+        journaler.journal({
+          type: "blocked",
+          sessionID,
+          agent: config.agents.executor,
+          reason: "no-plan-verdict",
+          plan,
+        })
+        throw new BlockError(
+          `BLOCKED by turnstile: no plan approval for "${plan}". Dispatch the plan-reviewer subagent first; proceed with executor only after the plan-reviewer's first line is ` +
+            "`VERDICT: APPROVE crit=<n> high=<n> med=<n> low=<n>`, or obtain an explicit user waiver " +
+            "(the dispatch prompt must contain the literal marker 'USER WAIVER:' followed by the user's words).",
+        )
+      }
+    } catch (e) {
+      if (e instanceof BlockError) throw e
+      // unreadable plans dir: fail-open
+    }
+  }
+
+  return { guardReviewerDispatch, guardReadLimit, enforceDecomposition, enforcePlanApproval }
+}