@wyattjoh/demur 0.4.2 → 0.6.0

package/extensions/demur/settings.ts

@@ -2,6 +2,21 @@ import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { getDemurConfigDirectory } from "./paths.ts";
+
+/**
+ * How the Pi extension applies demur to Bash calls.
+ */
+export type DemurMode = "enforce" | "passive" | "disabled";
+
+/**
+ * Modes accepted by the Pi extension command.
+ */
+export const DEMUR_MODES: readonly DemurMode[] = [
+  "enforce",
+  "passive",
+  "disabled",
+];
 
 /**
  * How the Pi extension handles guard failures that produce no trustworthy
@@ -23,9 +38,13 @@ export const FAILURE_POLICIES: readonly FailurePolicy[] = [
  */
 export type DemurSettings = {
   /**
-   * Whether Bash calls are routed through demur.
+   * Whether demur enforces, observes, or bypasses Bash calls.
+   */
+  mode: DemurMode;
+  /**
+   * Whether full command evaluations are appended to the training log.
    */
-  enabled: boolean;
+  training: boolean;
   /**
    * Host action to take when demur cannot obtain a trustworthy judgment.
    */
@@ -36,19 +55,20 @@ export type DemurSettings = {
  * Safe settings used when no persisted Pi configuration exists.
  */
 export const DEFAULT_DEMUR_SETTINGS: DemurSettings = {
-  enabled: true,
+  mode: "enforce",
+  training: false,
   failurePolicy: "block",
 };
 
 type DemurConfig = DemurSettings & {
-  version: 1;
+  version: 2;
 };
 
 /**
- * Resolve the global demur configuration file according to the XDG config
- * convention.
+ * Resolve the global demur configuration file using demur-specific and XDG
+ * directory conventions.
  *
- * @param environment - Process environment used to resolve `XDG_CONFIG_HOME`
+ * @param environment - Process environment used to resolve demur and XDG overrides
  * @param homeDirectory - Home directory used when the XDG override is absent
  * @returns Absolute path to demur's global configuration file
  */
@@ -56,16 +76,17 @@ export function getDemurConfigPath(
   environment: NodeJS.ProcessEnv = process.env,
   homeDirectory: string = homedir(),
 ): string {
-  const configDirectory =
-    environment.XDG_CONFIG_HOME || join(homeDirectory, ".config");
-  return join(configDirectory, "demur", "config.json");
+  return join(
+    getDemurConfigDirectory(environment, homeDirectory),
+    "config.json",
+  );
 }
 
 /**
  * Load the globally persisted Pi settings.
  *
- * A missing file uses the enabled, fail-closed defaults. Version 1 files from
- * before the enabled toggle omit that field and are treated as enabled.
+ * A missing file uses the enforcing, fail-closed defaults. Version 1 files are
+ * migrated from their former `enabled` boolean and start with training off.
  * Invalid or unreadable files are rejected so the extension can warn the user
  * while still falling back safely.
  *
@@ -88,18 +109,36 @@ export async function loadDemurSettings(
     throw new Error(`invalid demur config in ${configPath}: expected an object`);
   }
 
-  const { version, enabled, failurePolicy } = value as Record<string, unknown>;
+  const config = value as Record<string, unknown>;
+  if (config.version === 1) {
+    if (
+      (config.enabled !== undefined && typeof config.enabled !== "boolean") ||
+      !isFailurePolicy(config.failurePolicy)
+    ) {
+      throw new Error(`invalid demur config in ${configPath}: unsupported values`);
+    }
+
+    return {
+      mode: config.enabled === false ? "disabled" : "enforce",
+      training: false,
+      failurePolicy: config.failurePolicy,
+    };
+  }
+
   if (
-    version !== 1 ||
-    (enabled !== undefined && typeof enabled !== "boolean") ||
-    !isFailurePolicy(failurePolicy)
+    config.version !== 2 ||
+    !isDemurMode(config.mode) ||
+    typeof config.training !== "boolean" ||
+    (config.mode === "disabled" && config.training) ||
+    !isFailurePolicy(config.failurePolicy)
   ) {
     throw new Error(`invalid demur config in ${configPath}: unsupported values`);
   }
 
   return {
-    enabled: enabled ?? true,
-    failurePolicy,
+    mode: config.mode,
+    training: config.training,
+    failurePolicy: config.failurePolicy,
   };
 }
 
@@ -113,7 +152,11 @@ export async function saveDemurSettings(
   settings: DemurSettings,
   configPath: string = getDemurConfigPath(),
 ): Promise<void> {
-  const config: DemurConfig = { version: 1, ...settings };
+  if (settings.mode === "disabled" && settings.training) {
+    throw new Error("training cannot be enabled while demur is disabled");
+  }
+
+  const config: DemurConfig = { version: 2, ...settings };
   const temporaryPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
 
   await mkdir(dirname(configPath), { recursive: true, mode: 0o700 });
@@ -133,6 +176,17 @@ export async function saveDemurSettings(
   }
 }
 
+/**
+ * Parse a command argument as a Pi operating mode.
+ *
+ * @param value - Raw slash-command argument
+ * @returns Normalized mode, or `undefined` when the argument is invalid
+ */
+export function parseDemurMode(value: string): DemurMode | undefined {
+  const normalized = value.trim().toLowerCase();
+  return isDemurMode(normalized) ? normalized : undefined;
+}
+
 /**
  * Parse a command argument as a Pi failure policy.
  *
@@ -144,6 +198,10 @@ export function parseFailurePolicy(value: string): FailurePolicy | undefined {
   return isFailurePolicy(normalized) ? normalized : undefined;
 }
 
+function isDemurMode(value: unknown): value is DemurMode {
+  return DEMUR_MODES.some((mode) => mode === value);
+}
+
 function isFailurePolicy(value: unknown): value is FailurePolicy {
   return FAILURE_POLICIES.some((policy) => policy === value);
 }

package/extensions/demur/training-store.ts

@@ -0,0 +1,334 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, rmdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { Decision, Verdict } from "../../src/types.ts";
+import { getDemurStateDirectory } from "./paths.ts";
+
+const LOCK_RETRY_MS = 10;
+const LOCK_TIMEOUT_MS = 5_000;
+
+/**
+ * Guard modes that can emit training records.
+ */
+export type TrainingMode = "enforce" | "passive";
+
+/**
+ * Action the Pi host took after demur evaluated a command.
+ */
+export type TrainingHostAction = "allow" | "block";
+
+/**
+ * Complete evidence captured for one training-mode command evaluation.
+ */
+export type TrainingRecord = {
+  version: 1;
+  id: string;
+  recordedAt: string;
+  command: string;
+  cwd: string;
+  mode: TrainingMode;
+  verdict: Verdict;
+  hostAction: TrainingHostAction;
+};
+
+/**
+ * Human review of one captured training evaluation.
+ */
+export type TrainingReview = {
+  version: 1;
+  recordId: string;
+  reviewedAt: string;
+  originalDecision: Decision;
+  expectedDecision: Decision;
+  note: string | undefined;
+};
+
+/**
+ * Input required to append a human review.
+ */
+export type TrainingReviewInput = {
+  recordId: string;
+  originalDecision: Decision;
+  expectedDecision: Decision;
+  note: string | undefined;
+};
+
+/**
+ * Resolve the global training-record file according to demur and XDG overrides.
+ *
+ * @param environment - Process environment used to resolve demur and XDG overrides
+ * @param homeDirectory - Home directory used when the XDG override is absent
+ * @returns Absolute path to the append-only training JSONL file
+ */
+export function getTrainingLogPath(
+  environment: NodeJS.ProcessEnv = process.env,
+  homeDirectory: string = homedir(),
+): string {
+  return join(
+    getDemurStateDirectory(environment, homeDirectory),
+    "training.jsonl",
+  );
+}
+
+/**
+ * Resolve the global training-review file according to demur and XDG overrides.
+ *
+ * @param environment - Process environment used to resolve demur and XDG overrides
+ * @param homeDirectory - Home directory used when the XDG override is absent
+ * @returns Absolute path to the append-only review JSONL file
+ */
+export function getTrainingReviewPath(
+  environment: NodeJS.ProcessEnv = process.env,
+  homeDirectory: string = homedir(),
+): string {
+  return join(
+    getDemurStateDirectory(environment, homeDirectory),
+    "training-reviews.jsonl",
+  );
+}
+
+/**
+ * Append one complete command evaluation to the global training log.
+ *
+ * @param input - Evaluation evidence captured by the Pi extension
+ * @param logPath - Training file to append
+ * @returns The persisted record with generated identity and timestamp
+ */
+export async function recordTrainingEvaluation(
+  input: Omit<TrainingRecord, "version" | "id" | "recordedAt">,
+  logPath: string = getTrainingLogPath(),
+): Promise<TrainingRecord> {
+  const record: TrainingRecord = {
+    version: 1,
+    id: randomUUID(),
+    recordedAt: new Date().toISOString(),
+    ...input,
+  };
+  await appendJsonLine(logPath, record);
+  return record;
+}
+
+/**
+ * Load and validate all captured training evaluations.
+ *
+ * @param logPath - Training file to read
+ * @returns Valid training records in capture order
+ */
+export async function loadTrainingRecords(
+  logPath: string = getTrainingLogPath(),
+): Promise<ReadonlyArray<TrainingRecord>> {
+  return readJsonLines(logPath, parseTrainingRecord);
+}
+
+/**
+ * Append a human decision review to the global review log.
+ *
+ * @param input - Reviewed record identity, expected decision, and optional note
+ * @param reviewPath - Review file to append
+ * @returns The persisted review with its generated timestamp
+ */
+export async function recordTrainingReview(
+  input: TrainingReviewInput,
+  reviewPath: string = getTrainingReviewPath(),
+): Promise<TrainingReview> {
+  const review: TrainingReview = {
+    version: 1,
+    reviewedAt: new Date().toISOString(),
+    ...input,
+  };
+  await appendJsonLine(reviewPath, review);
+  return review;
+}
+
+/**
+ * Load and validate all human training reviews.
+ *
+ * @param reviewPath - Review file to read
+ * @returns Valid reviews in capture order
+ */
+export async function loadTrainingReviews(
+  reviewPath: string = getTrainingReviewPath(),
+): Promise<ReadonlyArray<TrainingReview>> {
+  return readJsonLines(reviewPath, parseTrainingReview);
+}
+
+async function appendJsonLine(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const release = await acquireLock(`${path}.lock`);
+
+  try {
+    const line = JSON.stringify(
+      value,
+      (_key, nestedValue: unknown) =>
+        nestedValue === undefined ? null : nestedValue,
+    );
+    await appendFile(path, `${line}\n`, {
+      encoding: "utf8",
+      flag: "a",
+      mode: 0o600,
+    });
+  } finally {
+    await release();
+  }
+}
+
+async function readJsonLines<T>(
+  path: string,
+  parse: (value: unknown, path: string, line: number) => T,
+): Promise<ReadonlyArray<T>> {
+  let content: string;
+  try {
+    content = await readFile(path, "utf8");
+  } catch (error: unknown) {
+    if (isErrorCode(error, "ENOENT")) return [];
+    throw error;
+  }
+
+  return content
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "")
+    .map((line, index) => {
+      let value: unknown;
+      try {
+        value = JSON.parse(line);
+      } catch (error: unknown) {
+        throw new Error(
+          `invalid JSONL in ${path} at line ${index + 1}: ${errorDetail(error)}`,
+        );
+      }
+      return parse(value, path, index + 1);
+    });
+}
+
+function parseTrainingRecord(
+  value: unknown,
+  path: string,
+  line: number,
+): TrainingRecord {
+  if (value === null || typeof value !== "object") {
+    throw invalidRecord(path, line);
+  }
+
+  const record = value as Record<string, unknown>;
+  if (
+    record.version !== 1 ||
+    typeof record.id !== "string" ||
+    typeof record.recordedAt !== "string" ||
+    typeof record.command !== "string" ||
+    typeof record.cwd !== "string" ||
+    (record.mode !== "enforce" && record.mode !== "passive") ||
+    (record.hostAction !== "allow" && record.hostAction !== "block") ||
+    !isVerdict(record.verdict)
+  ) {
+    throw invalidRecord(path, line);
+  }
+
+  const verdict = record.verdict as Record<string, unknown>;
+  return {
+    version: 1,
+    id: record.id,
+    recordedAt: record.recordedAt,
+    command: record.command,
+    cwd: record.cwd,
+    mode: record.mode,
+    verdict: {
+      decision: verdict.decision as Decision,
+      reason: verdict.reason as string,
+      judgments: verdict.judgments === null
+        ? undefined
+        : verdict.judgments as Verdict["judgments"],
+      failure: verdict.failure === null
+        ? undefined
+        : verdict.failure as Verdict["failure"],
+      latencyMs: verdict.latencyMs as number,
+      usage: verdict.usage === null
+        ? undefined
+        : verdict.usage as Verdict["usage"],
+    },
+    hostAction: record.hostAction,
+  };
+}
+
+function parseTrainingReview(
+  value: unknown,
+  path: string,
+  line: number,
+): TrainingReview {
+  if (value === null || typeof value !== "object") {
+    throw invalidRecord(path, line);
+  }
+
+  const review = value as Record<string, unknown>;
+  if (
+    review.version !== 1 ||
+    typeof review.recordId !== "string" ||
+    typeof review.reviewedAt !== "string" ||
+    !isDecision(review.originalDecision) ||
+    !isDecision(review.expectedDecision) ||
+    (review.note !== undefined &&
+      review.note !== null &&
+      typeof review.note !== "string")
+  ) {
+    throw invalidRecord(path, line);
+  }
+
+  return {
+    version: 1,
+    recordId: review.recordId,
+    reviewedAt: review.reviewedAt,
+    originalDecision: review.originalDecision,
+    expectedDecision: review.expectedDecision,
+    note: review.note === null ? undefined : review.note,
+  };
+}
+
+function isVerdict(value: unknown): value is Verdict {
+  if (value === null || typeof value !== "object") return false;
+  const verdict = value as Record<string, unknown>;
+  return isDecision(verdict.decision) &&
+    typeof verdict.reason === "string" &&
+    typeof verdict.latencyMs === "number";
+}
+
+function isDecision(value: unknown): value is Decision {
+  return value === "allow" || value === "ask" || value === "deny";
+}
+
+function invalidRecord(path: string, line: number): Error {
+  return new Error(`invalid training record in ${path} at line ${line}`);
+}
+
+async function acquireLock(lockPath: string): Promise<() => Promise<void>> {
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      await mkdir(lockPath, { mode: 0o700 });
+      return async () => {
+        await rmdir(lockPath);
+      };
+    } catch (error: unknown) {
+      if (!isErrorCode(error, "EEXIST")) throw error;
+      if (Date.now() - startedAt >= LOCK_TIMEOUT_MS) {
+        throw new Error(`timed out waiting for training state lock: ${lockPath}`);
+      }
+      await delay(LOCK_RETRY_MS);
+    }
+  }
+}
+
+function isErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === code;
+}
+
+function errorDetail(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyattjoh/demur",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "type": "module",
   "description": "A proof-of-concept destructive-command guard for coding agents.",
   "license": "MIT",
@@ -23,7 +23,9 @@
   ],
   "files": [
     "extensions/demur/cost-tracker.ts",
+    "extensions/demur/paths.ts",
     "extensions/demur/settings.ts",
+    "extensions/demur/training-store.ts",
     "extensions/demur/index.ts",
     "src/adapters/claude-code.ts",
     "src/adapters/pi-worker.ts",
@@ -36,6 +38,9 @@
     "src/policy.ts",
     "src/questions.ts",
     "src/state.ts",
+    "src/settings-model.ts",
+    "src/training-review-model.ts",
+    "src/training-review-tui.tsx",
     "src/types.ts"
   ],
   "publishConfig": {
@@ -47,7 +52,7 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "vitest run && bun test ./src/training-review-tui.bun.tsx",
     "build:pi": "bun build extensions/demur/index.ts --target=node --outfile=dist/demur-guard.js --format=esm --external @earendil-works/pi-coding-agent && bun build src/adapters/pi-worker.ts --target=bun --outfile=dist/demur-pi-worker.js --format=esm",
     "build:claude": "bun build src/adapters/claude-code.ts --target=bun --outfile=dist/demur-hook.js --format=esm",
     "build": "bun run build:pi && bun run build:claude",
@@ -63,12 +68,16 @@
   },
   "dependencies": {
     "@effect/ai-typesafe": "4.0.0-rc.116",
-    "effect": "4.0.0-rc.116"
+    "@opentui/core": "^0.5.11",
+    "@opentui/react": "^0.5.11",
+    "effect": "4.0.0-rc.116",
+    "react": "^19.3.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.85.1",
     "@effect/vitest": "4.0.0-rc.116",
     "@types/bun": "1.4.2",
+    "@types/react": "^19.3.0",
     "typescript": "7.0.2",
     "vitest": "5.0.1"
   },