codeharness 0.20.0 → 0.21.0

package/dist/modules/observability/index.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Types for the observability analyzer module.
+ *
+ * These interfaces are tool-agnostic: any static analysis tool
+ * (Semgrep, ESLint, custom) can produce conforming output.
+ * See architecture Decision 1 for rationale.
+ */
+/** Severity levels for observability gaps */
+type GapSeverity = 'error' | 'warning' | 'info';
+/**
+ * A single observability gap found by static analysis.
+ *
+ * Maps 1:1 from analyzer output. The `type` field carries the
+ * rule ID from the analyzer (e.g., "catch-without-logging"),
+ * NOT a Semgrep-specific identifier.
+ */
+interface ObservabilityGap {
+    /** File path where the gap was found */
+    readonly file: string;
+    /** Line number in the file */
+    readonly line: number;
+    /** Rule identifier from the analyzer */
+    readonly type: string;
+    /** Human-readable description of the gap */
+    readonly description: string;
+    /** Severity of the gap */
+    readonly severity: GapSeverity;
+}
+/**
+ * Summary statistics from an analysis run.
+ */
+interface AnalyzerSummary {
+    /** Total number of functions scanned */
+    readonly totalFunctions: number;
+    /** Number of functions that have log statements */
+    readonly functionsWithLogs: number;
+    /** Number of error handlers without logging */
+    readonly errorHandlersWithoutLogs: number;
+    /** Coverage percentage: functionsWithLogs / totalFunctions * 100 */
+    readonly coveragePercent: number;
+    /** Distribution of log levels found (e.g., { debug: 5, error: 3 }) */
+    readonly levelDistribution: Record<string, number>;
+}
+/**
+ * Configuration for the analyzer module.
+ *
+ * Allows callers to specify which tool to use and where rules live.
+ * Defaults are applied when not provided.
+ */
+interface AnalyzerConfig {
+    /** The analysis tool to use. Default: 'semgrep' */
+    readonly tool?: string;
+    /** Directory containing analysis rules, relative to project root. Default: 'patches/observability/' */
+    readonly rulesDir?: string;
+    /** Timeout for the analysis subprocess in milliseconds. Default: 60000 */
+    readonly timeout?: number;
+    /**
+     * Total number of functions in the project (from an external count or AST scan).
+     * When provided, enables accurate coverage computation:
+     * coveragePercent = (totalFunctions - functionsWithoutLogs) / totalFunctions * 100.
+     * When omitted, totalFunctions defaults to the count of function-no-debug-log matches
+     * (functions lacking logs), producing 0% coverage as the best conservative estimate.
+     */
+    readonly totalFunctions?: number;
+}
+/**
+ * The result of an analysis run, independent of the underlying tool.
+ *
+ * Any static analysis tool that produces this shape can be used as
+ * a drop-in replacement for Semgrep.
+ */
+interface AnalyzerResult {
+    /** The tool that produced this result (e.g., 'semgrep', 'eslint', 'custom') */
+    readonly tool: string;
+    /** Observability gaps found */
+    readonly gaps: ObservabilityGap[];
+    /** Summary statistics */
+    readonly summary: AnalyzerSummary;
+    /** Whether the analysis was skipped (e.g., tool not installed) */
+    readonly skipped?: boolean;
+    /** Reason the analysis was skipped, if applicable */
+    readonly skipReason?: string;
+}
+/** A single coverage history entry with timestamp */
+interface CoverageHistoryEntry {
+    /** Coverage percentage at this point in time */
+    readonly coveragePercent: number;
+    /** ISO 8601 timestamp when this measurement was taken */
+    readonly timestamp: string;
+}
+/** Static analysis coverage state persisted in sprint-state.json */
+interface StaticCoverageState {
+    /** Current coverage percentage */
+    readonly coveragePercent: number;
+    /** ISO 8601 timestamp of last scan */
+    readonly lastScanTimestamp: string;
+    /** Historical coverage entries */
+    readonly history: readonly CoverageHistoryEntry[];
+}
+/** Coverage targets configuration */
+interface CoverageTargets {
+    /** Target coverage percentage for static analysis (default 80) */
+    readonly staticTarget: number;
+    /** Target coverage percentage for runtime observability (default 60) */
+    readonly runtimeTarget?: number;
+}
+/**
+ * Top-level observability coverage state in sprint-state.json.
+ *
+ * Contains `static` (Story 1.3) and optional `runtime` (Story 2.1) sections.
+ * Follows architecture Decision 2 (Separate Metrics).
+ */
+interface ObservabilityCoverageState {
+    /** Static analysis coverage metrics */
+    readonly static: StaticCoverageState;
+    /** Coverage targets */
+    readonly targets: CoverageTargets;
+    /** Runtime observability coverage metrics (Story 2.1) */
+    readonly runtime?: RuntimeCoverageState;
+}
+/** A single AC's runtime coverage entry from verification */
+interface RuntimeCoverageEntry {
+    /** Acceptance criterion identifier */
+    readonly acId: string;
+    /** Whether log events were detected for this AC */
+    readonly logEventsDetected: boolean;
+    /** Number of log events detected */
+    readonly logEventCount: number;
+    /** Gap note if no log events detected */
+    readonly gapNote?: string;
+}
+/** Result of computing runtime coverage from parsed observability gaps */
+interface RuntimeCoverageResult {
+    /** Per-AC runtime coverage entries */
+    readonly entries: readonly RuntimeCoverageEntry[];
+    /** Total number of ACs evaluated */
+    readonly totalACs: number;
+    /** Number of ACs that produced log events */
+    readonly acsWithLogs: number;
+    /** Runtime coverage percentage: acsWithLogs / totalACs * 100 */
+    readonly coveragePercent: number;
+}
+/** Runtime coverage state persisted in sprint-state.json */
+interface RuntimeCoverageState {
+    /** Runtime coverage percentage */
+    readonly coveragePercent: number;
+    /** ISO 8601 timestamp of last validation */
+    readonly lastValidationTimestamp: string;
+    /** Number of modules with telemetry */
+    readonly modulesWithTelemetry: number;
+    /** Total number of modules */
+    readonly totalModules: number;
+    /** Whether telemetry was detected at all */
+    readonly telemetryDetected: boolean;
+}
+/** Trend comparison between latest and previous coverage entries */
+interface CoverageTrend {
+    /** Latest coverage percentage */
+    readonly current: number;
+    /** Previous coverage percentage, or null if only one entry */
+    readonly previous: number | null;
+    /** Delta: current - previous, or null if only one entry */
+    readonly delta: number | null;
+    /** Timestamp of latest measurement */
+    readonly currentTimestamp: string;
+    /** Timestamp of previous measurement, or null */
+    readonly previousTimestamp: string | null;
+}
+/** Result of checking coverage against a target */
+interface CoverageTargetResult {
+    /** Whether coverage meets or exceeds the target */
+    readonly met: boolean;
+    /** Current coverage percentage */
+    readonly current: number;
+    /** Target coverage percentage */
+    readonly target: number;
+    /** Gap: target - current (0 if met) */
+    readonly gap: number;
+}
+
+/**
+ * Discriminated union Result type for consistent error handling.
+ * All module functions return Result<T> instead of throwing exceptions.
+ */
+/** Successful result carrying data of type T */
+interface Ok<T> {
+    readonly success: true;
+    readonly data: T;
+}
+/** Failed result carrying an error message and optional context */
+interface Fail {
+    readonly success: false;
+    readonly error: string;
+    readonly context?: Record<string, unknown>;
+}
+/** Discriminated union: success field is the discriminant */
+type Result<T> = Ok<T> | Fail;
+
+/**
+ * Observability analyzer module — runs static analysis and produces
+ * a standardized gap report.
+ *
+ * Currently implements Semgrep integration but the AnalyzerResult
+ * interface is tool-agnostic: any tool producing the same shape
+ * can be used as a drop-in replacement.
+ */
+
+/**
+ * Run observability analysis on a project directory.
+ *
+ * @param projectDir - Absolute path to the project root
+ * @param config - Optional configuration overriding defaults
+ * @returns Result containing the analysis report, or a skip result if the tool is not installed
+ */
+declare function analyze(projectDir: string, config?: AnalyzerConfig): Result<AnalyzerResult>;
+
+/**
+ * Coverage state persistence — tracks observability coverage in sprint-state.json.
+ *
+ * Implements Story 1.3: read/write/trend/target comparison for static analysis coverage.
+ * Only the `static` section is managed here; `runtime` is deferred to Epic 2.
+ */
+
+/**
+ * Save coverage result from an analysis run into sprint-state.json.
+ *
+ * Updates `observability.static.coveragePercent`, `observability.static.lastScanTimestamp`,
+ * and appends to `observability.static.history`. Preserves all other state fields.
+ */
+declare function saveCoverageResult(projectDir: string, result: AnalyzerResult): Result<void>;
+/**
+ * Read the observability coverage state from sprint-state.json.
+ *
+ * Returns the typed `ObservabilityCoverageState` from the `observability` key.
+ * If no observability section exists, returns default state.
+ */
+declare function readCoverageState(projectDir: string): Result<ObservabilityCoverageState>;
+/**
+ * Get coverage trend by comparing latest vs previous history entries.
+ */
+declare function getCoverageTrend(projectDir: string): Result<CoverageTrend>;
+/**
+ * Check current coverage against a target threshold.
+ *
+ * @param projectDir - Project root directory
+ * @param target - Target percentage (default 80%)
+ * @returns Structured result indicating whether coverage meets the target
+ */
+declare function checkCoverageTarget(projectDir: string, target?: number): Result<CoverageTargetResult>;
+
+/** Per-AC observability gap presence */
+interface ObservabilityGapEntry {
+    /** Acceptance criterion identifier */
+    readonly acId: string;
+    /** Whether an observability gap was detected */
+    readonly hasGap: boolean;
+    /** The gap note text, if present */
+    readonly gapNote?: string;
+}
+/** Result of parsing observability gaps from proof content */
+interface ObservabilityGapResult {
+    /** Per-AC gap presence */
+    readonly entries: readonly ObservabilityGapEntry[];
+    /** Total number of ACs found in proof */
+    readonly totalACs: number;
+    /** Number of ACs with observability gaps */
+    readonly gapCount: number;
+    /** Number of ACs without gaps (produced log events) */
+    readonly coveredCount: number;
+}
+
+/**
+ * Runtime coverage computation — tracks observability coverage from verification proofs.
+ *
+ * Implements Story 2.1: computes runtime coverage from parsed observability gaps
+ * and persists results to sprint-state.json under `observability.runtime`.
+ * Separate from `coverage.ts` (static coverage) per architecture Decision 2.
+ */
+
+/**
+ * Compute runtime coverage from parsed observability gap results.
+ *
+ * Coverage = acsWithLogs / totalACs * 100.
+ * Returns 0% coverage when totalACs is 0 (avoids division by zero).
+ */
+declare function computeRuntimeCoverage(gapResults: ObservabilityGapResult): RuntimeCoverageResult;
+/**
+ * Persist runtime coverage results to sprint-state.json under `observability.runtime`.
+ *
+ * Uses atomic write (write to temp, then rename) to prevent corruption.
+ * Preserves all existing state fields including static coverage data.
+ */
+declare function saveRuntimeCoverage(projectDir: string, result: RuntimeCoverageResult): Result<void>;
+
+export { type AnalyzerConfig, type AnalyzerResult, type AnalyzerSummary, type CoverageHistoryEntry, type CoverageTargetResult, type CoverageTargets, type CoverageTrend, type GapSeverity, type ObservabilityCoverageState, type ObservabilityGap, type RuntimeCoverageEntry, type RuntimeCoverageResult, type RuntimeCoverageState, type StaticCoverageState, analyze, checkCoverageTarget, computeRuntimeCoverage, getCoverageTrend, readCoverageState, saveCoverageResult, saveRuntimeCoverage };

package/dist/modules/observability/index.js

@@ -0,0 +1,366 @@
+// src/modules/observability/analyzer.ts
+import { execFileSync } from "child_process";
+import { join } from "path";
+
+// src/types/result.ts
+function ok(data) {
+  return { success: true, data };
+}
+function fail(error, context) {
+  if (context !== void 0) {
+    return { success: false, error, context };
+  }
+  return { success: false, error };
+}
+
+// src/modules/observability/analyzer.ts
+var DEFAULT_RULES_DIR = "patches/observability/";
+var DEFAULT_TIMEOUT = 6e4;
+var FUNCTION_NO_LOG_RULE = "function-no-debug-log";
+var CATCH_WITHOUT_LOGGING_RULE = "catch-without-logging";
+var ERROR_PATH_NO_LOG_RULE = "error-path-no-log";
+function matchesRule(gapType, ruleName) {
+  return gapType === ruleName || gapType.endsWith(`.${ruleName}`);
+}
+function analyze(projectDir, config) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail("projectDir is required and must be a non-empty string");
+  }
+  const tool = config?.tool ?? "semgrep";
+  if (tool !== "semgrep") {
+    return fail(`Unsupported analyzer tool: ${tool}`);
+  }
+  if (!checkSemgrepInstalled()) {
+    return ok({
+      tool: "semgrep",
+      gaps: [],
+      summary: {
+        totalFunctions: 0,
+        functionsWithLogs: 0,
+        errorHandlersWithoutLogs: 0,
+        coveragePercent: 0,
+        levelDistribution: {}
+      },
+      skipped: true,
+      skipReason: "static analysis skipped -- install semgrep"
+    });
+  }
+  const rulesDir = config?.rulesDir ?? DEFAULT_RULES_DIR;
+  const timeout = config?.timeout ?? DEFAULT_TIMEOUT;
+  const fullRulesDir = join(projectDir, rulesDir);
+  const rawResult = runSemgrep(projectDir, fullRulesDir, timeout);
+  if (!rawResult.success) {
+    return fail(rawResult.error);
+  }
+  const gaps = parseSemgrepOutput(rawResult.data);
+  const summaryOpts = config?.totalFunctions != null ? { totalFunctions: config.totalFunctions } : void 0;
+  const summary = computeSummary(gaps, summaryOpts);
+  return ok({
+    tool: "semgrep",
+    gaps,
+    summary
+  });
+}
+function checkSemgrepInstalled() {
+  try {
+    execFileSync("semgrep", ["--version"], {
+      encoding: "utf-8",
+      timeout: 5e3,
+      stdio: "pipe"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function runSemgrep(projectDir, rulesDir, timeout = DEFAULT_TIMEOUT) {
+  try {
+    const stdout = execFileSync(
+      "semgrep",
+      ["scan", "--config", rulesDir, "--json", projectDir],
+      { encoding: "utf-8", timeout, stdio: ["pipe", "pipe", "pipe"] }
+    );
+    const parsed = JSON.parse(stdout);
+    if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.results)) {
+      return fail("Semgrep scan returned invalid JSON: missing results array");
+    }
+    return ok(parsed);
+  } catch (error) {
+    return fail(`Semgrep scan failed: ${String(error)}`);
+  }
+}
+function parseSemgrepOutput(raw) {
+  if (!raw.results || !Array.isArray(raw.results)) {
+    return [];
+  }
+  return raw.results.map((r) => ({
+    file: r.path,
+    line: r.start.line,
+    type: r.check_id,
+    description: r.extra.message,
+    severity: normalizeSeverity(r.extra.severity)
+  }));
+}
+function computeSummary(gaps, opts) {
+  const functionsWithoutLogs = gaps.filter(
+    (g) => matchesRule(g.type, FUNCTION_NO_LOG_RULE)
+  ).length;
+  const errorHandlersWithoutLogs = gaps.filter(
+    (g) => matchesRule(g.type, CATCH_WITHOUT_LOGGING_RULE) || matchesRule(g.type, ERROR_PATH_NO_LOG_RULE)
+  ).length;
+  const totalFunctions = opts?.totalFunctions ?? functionsWithoutLogs;
+  const functionsWithLogs = totalFunctions - functionsWithoutLogs;
+  const coveragePercent = totalFunctions === 0 ? 100 : Math.round(functionsWithLogs / totalFunctions * 100 * 100) / 100;
+  const levelDistribution = {};
+  for (const gap of gaps) {
+    levelDistribution[gap.severity] = (levelDistribution[gap.severity] ?? 0) + 1;
+  }
+  return {
+    totalFunctions,
+    functionsWithLogs,
+    errorHandlersWithoutLogs,
+    coveragePercent,
+    levelDistribution
+  };
+}
+function normalizeSeverity(severity) {
+  const lower = severity.toLowerCase();
+  if (lower === "error") return "error";
+  if (lower === "warning") return "warning";
+  return "info";
+}
+
+// src/modules/observability/coverage.ts
+import { readFileSync, writeFileSync, renameSync, existsSync } from "fs";
+import { join as join2 } from "path";
+var STATE_FILE = "sprint-state.json";
+var TMP_FILE = ".sprint-state.json.tmp";
+var DEFAULT_STATIC_TARGET = 80;
+var MAX_HISTORY_ENTRIES = 100;
+function defaultCoverageState() {
+  return {
+    static: {
+      coveragePercent: 0,
+      lastScanTimestamp: "",
+      history: []
+    },
+    targets: {
+      staticTarget: DEFAULT_STATIC_TARGET
+    }
+  };
+}
+function readStateFile(projectDir) {
+  const fp = join2(projectDir, STATE_FILE);
+  if (!existsSync(fp)) {
+    return ok({});
+  }
+  try {
+    const raw = readFileSync(fp, "utf-8");
+    const parsed = JSON.parse(raw);
+    return ok(parsed);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail(`Failed to read ${STATE_FILE}: ${msg}`);
+  }
+}
+function writeStateAtomic(projectDir, state) {
+  try {
+    const data = JSON.stringify(state, null, 2) + "\n";
+    const tmp = join2(projectDir, TMP_FILE);
+    const final = join2(projectDir, STATE_FILE);
+    writeFileSync(tmp, data, "utf-8");
+    renameSync(tmp, final);
+    return ok(void 0);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail(`Failed to write ${STATE_FILE}: ${msg}`);
+  }
+}
+function saveCoverageResult(projectDir, result) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail("projectDir is required and must be a non-empty string");
+  }
+  const stateResult = readStateFile(projectDir);
+  if (!stateResult.success) {
+    return fail(stateResult.error);
+  }
+  const state = stateResult.data;
+  const existing = extractCoverageState(state);
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const fullHistory = [
+    ...existing.static.history,
+    { coveragePercent: result.summary.coveragePercent, timestamp }
+  ];
+  const trimmedHistory = fullHistory.length > MAX_HISTORY_ENTRIES ? fullHistory.slice(fullHistory.length - MAX_HISTORY_ENTRIES) : fullHistory;
+  const updatedStatic = {
+    coveragePercent: result.summary.coveragePercent,
+    lastScanTimestamp: timestamp,
+    history: trimmedHistory
+  };
+  const updatedObservability = {
+    static: updatedStatic,
+    targets: existing.targets
+  };
+  const updatedState = {
+    ...state,
+    observability: updatedObservability
+  };
+  return writeStateAtomic(projectDir, updatedState);
+}
+function readCoverageState(projectDir) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail("projectDir is required and must be a non-empty string");
+  }
+  const stateResult = readStateFile(projectDir);
+  if (!stateResult.success) {
+    return fail(stateResult.error);
+  }
+  return ok(extractCoverageState(stateResult.data));
+}
+function getCoverageTrend(projectDir) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail("projectDir is required and must be a non-empty string");
+  }
+  const stateResult = readCoverageState(projectDir);
+  if (!stateResult.success) {
+    return fail(stateResult.error);
+  }
+  const { history } = stateResult.data.static;
+  if (history.length === 0) {
+    return ok({
+      current: 0,
+      previous: null,
+      delta: null,
+      currentTimestamp: "",
+      previousTimestamp: null
+    });
+  }
+  const latest = history[history.length - 1];
+  if (history.length === 1) {
+    return ok({
+      current: latest.coveragePercent,
+      previous: null,
+      delta: null,
+      currentTimestamp: latest.timestamp,
+      previousTimestamp: null
+    });
+  }
+  const prev = history[history.length - 2];
+  return ok({
+    current: latest.coveragePercent,
+    previous: prev.coveragePercent,
+    delta: latest.coveragePercent - prev.coveragePercent,
+    currentTimestamp: latest.timestamp,
+    previousTimestamp: prev.timestamp
+  });
+}
+function checkCoverageTarget(projectDir, target) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail("projectDir is required and must be a non-empty string");
+  }
+  const stateResult = readCoverageState(projectDir);
+  if (!stateResult.success) {
+    return fail(stateResult.error);
+  }
+  const effectiveTarget = target ?? stateResult.data.targets.staticTarget;
+  const current = stateResult.data.static.coveragePercent;
+  const met = current >= effectiveTarget;
+  const gap = met ? 0 : effectiveTarget - current;
+  return ok({ met, current, target: effectiveTarget, gap });
+}
+function extractCoverageState(state) {
+  const obs = state.observability;
+  if (!obs) {
+    return defaultCoverageState();
+  }
+  const staticSection = obs.static;
+  const targets = obs.targets;
+  return {
+    static: {
+      coveragePercent: typeof staticSection?.coveragePercent === "number" ? staticSection.coveragePercent : 0,
+      lastScanTimestamp: typeof staticSection?.lastScanTimestamp === "string" ? staticSection.lastScanTimestamp : "",
+      history: Array.isArray(staticSection?.history) ? staticSection.history.filter(
+        (entry) => typeof entry === "object" && entry !== null && typeof entry.coveragePercent === "number" && typeof entry.timestamp === "string"
+      ) : []
+    },
+    targets: {
+      staticTarget: typeof targets?.staticTarget === "number" ? targets.staticTarget : DEFAULT_STATIC_TARGET
+    }
+  };
+}
+
+// src/modules/observability/runtime-coverage.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, renameSync as renameSync2, existsSync as existsSync2 } from "fs";
+import { join as join3 } from "path";
+var STATE_FILE2 = "sprint-state.json";
+var TMP_FILE2 = ".sprint-state.json.tmp";
+function computeRuntimeCoverage(gapResults) {
+  const entries = gapResults.entries.map((entry) => ({
+    acId: entry.acId,
+    logEventsDetected: !entry.hasGap,
+    logEventCount: entry.hasGap ? 0 : 1,
+    // Binary: gap means 0, no gap means at least 1
+    gapNote: entry.gapNote
+  }));
+  const totalACs = gapResults.totalACs;
+  const acsWithLogs = gapResults.coveredCount;
+  const coveragePercent = totalACs === 0 ? 0 : acsWithLogs / totalACs * 100;
+  return { entries, totalACs, acsWithLogs, coveragePercent };
+}
+function saveRuntimeCoverage(projectDir, result) {
+  if (!projectDir || typeof projectDir !== "string") {
+    return fail("projectDir is required and must be a non-empty string");
+  }
+  const fp = join3(projectDir, STATE_FILE2);
+  let state = {};
+  if (existsSync2(fp)) {
+    try {
+      const raw = readFileSync2(fp, "utf-8");
+      state = JSON.parse(raw);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return fail(`Failed to read ${STATE_FILE2}: ${msg}`);
+    }
+  }
+  const existingObs = state.observability ?? {};
+  const runtimeState = {
+    coveragePercent: result.coveragePercent,
+    lastValidationTimestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    modulesWithTelemetry: result.acsWithLogs,
+    totalModules: result.totalACs,
+    telemetryDetected: result.acsWithLogs > 0
+  };
+  const existingTargets = existingObs.targets ?? {};
+  const targets = {
+    ...existingTargets,
+    runtimeTarget: typeof existingTargets.runtimeTarget === "number" ? existingTargets.runtimeTarget : 60
+  };
+  const updatedState = {
+    ...state,
+    observability: {
+      ...existingObs,
+      runtime: runtimeState,
+      targets
+    }
+  };
+  try {
+    const data = JSON.stringify(updatedState, null, 2) + "\n";
+    const tmp = join3(projectDir, TMP_FILE2);
+    const finalPath = join3(projectDir, STATE_FILE2);
+    writeFileSync2(tmp, data, "utf-8");
+    renameSync2(tmp, finalPath);
+    return ok(void 0);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return fail(`Failed to write ${STATE_FILE2}: ${msg}`);
+  }
+}
+export {
+  analyze,
+  checkCoverageTarget,
+  computeRuntimeCoverage,
+  getCoverageTrend,
+  readCoverageState,
+  saveCoverageResult,
+  saveRuntimeCoverage
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeharness",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "description": "CLI for codeharness — makes autonomous coding agents produce software that actually works",
   "bin": {
@@ -29,7 +29,10 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@inkjs/ui": "^2.0.0",
     "commander": "^14.0.3",
+    "ink": "^6.8.0",
+    "react": "^19.2.4",
     "yaml": "^2.8.2"
   },
   "devDependencies": {
@@ -38,7 +41,9 @@
     "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
     "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
     "@vitest/coverage-v8": "^4.1.0",
+    "ink-testing-library": "^4.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"