@basou/core 0.28.0 → 0.30.0

package/dist/index.js

@@ -1,5 +1,14 @@
-// src/adapters/claude-code/claude-code-adapter.ts
+// src/adapters/command-lookup.ts
 import { spawn } from "child_process";
+async function isOnPath(command) {
+  return new Promise((resolve3) => {
+    const child = spawn("which", [command], { stdio: "ignore" });
+    child.on("error", () => resolve3(false));
+    child.on("exit", (code) => resolve3(code === 0));
+  });
+}
+
+// src/adapters/claude-code/claude-code-adapter.ts
 var claudeCodeAdapterMetadata = {
   kind: "claude-code-adapter",
   version: "0.1.0"
@@ -10,17 +19,123 @@ async function resolveClaudeCodeCommand(lookup = isOnPath) {
   }
   throw new Error("Claude Code CLI not found in PATH. Install claude-code (or claude) first.");
 }
-async function isOnPath(command) {
-  return new Promise((resolve3) => {
-    const child = spawn("which", [command], { stdio: "ignore" });
-    child.on("error", () => resolve3(false));
-    child.on("exit", (code) => resolve3(code === 0));
-  });
-}
 function summarizeAdapterOutput(_stream, _raw) {
   throw new Error("adapter_output summary is not implemented in this release");
 }
 
+// src/adapters/claude-code/settings-hook.ts
+var STOP_HOOK_TIMEOUT_SECONDS = 20;
+var BASOU_STOP_HOOK = /(?:\bbasou|(?:@basou|packages)\/cli\/dist\/index\.js['"]?)\s+hook\s+stop\b/;
+function isBasouStopHookCommand(command) {
+  return BASOU_STOP_HOOK.test(command);
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function buildStopHookCommand(options) {
+  const flags = [];
+  if (options.block === true) flags.push("--block");
+  if (options.requireReview === true) flags.push("--require-review");
+  if (options.minEdits !== void 0) flags.push(`--min-edits ${options.minEdits}`);
+  const suffix = flags.length > 0 ? ` ${flags.join(" ")}` : "";
+  return `node ${shellQuote(options.cliEntry)} hook stop${suffix} 2>/dev/null || true`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function cloneSettings(settings) {
+  if (settings === void 0 || settings === null) return {};
+  if (!isRecord(settings)) {
+    throw new Error("Claude settings is not a JSON object.");
+  }
+  return structuredClone(settings);
+}
+function upsertStopHook(settings, command) {
+  const root = cloneSettings(settings);
+  if (root.hooks === void 0) {
+    root.hooks = {};
+  } else if (!isRecord(root.hooks)) {
+    throw new Error("The 'hooks' key in Claude settings is not an object.");
+  }
+  const hooks = root.hooks;
+  if (hooks.Stop === void 0) {
+    hooks.Stop = [];
+  } else if (!Array.isArray(hooks.Stop)) {
+    throw new Error("The 'hooks.Stop' key in Claude settings is not an array.");
+  }
+  const stop = hooks.Stop;
+  for (const group of stop) {
+    if (!isRecord(group) || !Array.isArray(group.hooks)) continue;
+    for (const entry of group.hooks) {
+      if (!isRecord(entry)) continue;
+      if (typeof entry.command === "string" && isBasouStopHookCommand(entry.command)) {
+        const unchanged = entry.type === "command" && entry.command === command && entry.timeout === STOP_HOOK_TIMEOUT_SECONDS;
+        entry.type = "command";
+        entry.command = command;
+        entry.timeout = STOP_HOOK_TIMEOUT_SECONDS;
+        return { settings: root, action: unchanged ? "unchanged" : "updated" };
+      }
+    }
+  }
+  stop.push({ hooks: [{ type: "command", command, timeout: STOP_HOOK_TIMEOUT_SECONDS }] });
+  return { settings: root, action: "installed" };
+}
+function removeStopHook(settings) {
+  const root = cloneSettings(settings);
+  if (!isRecord(root.hooks) || !Array.isArray(root.hooks.Stop)) {
+    return { settings: root, action: "absent" };
+  }
+  const hooks = root.hooks;
+  const stop = hooks.Stop;
+  let removed = false;
+  const newStop = [];
+  for (const group of stop) {
+    if (!isRecord(group) || !Array.isArray(group.hooks)) {
+      newStop.push(group);
+      continue;
+    }
+    const keptHooks = group.hooks.filter((entry) => {
+      if (isRecord(entry) && typeof entry.command === "string" && isBasouStopHookCommand(entry.command)) {
+        removed = true;
+        return false;
+      }
+      return true;
+    });
+    if (keptHooks.length === group.hooks.length) {
+      newStop.push(group);
+    } else if (keptHooks.length > 0) {
+      group.hooks = keptHooks;
+      newStop.push(group);
+    }
+  }
+  if (!removed) {
+    return { settings: root, action: "absent" };
+  }
+  if (newStop.length === 0) {
+    delete hooks.Stop;
+  } else {
+    hooks.Stop = newStop;
+  }
+  if (Object.keys(hooks).length === 0) {
+    delete root.hooks;
+  }
+  return { settings: root, action: "removed" };
+}
+function findBasouStopHookCommand(settings) {
+  if (!isRecord(settings) || !isRecord(settings.hooks) || !Array.isArray(settings.hooks.Stop)) {
+    return null;
+  }
+  for (const group of settings.hooks.Stop) {
+    if (!isRecord(group) || !Array.isArray(group.hooks)) continue;
+    for (const entry of group.hooks) {
+      if (isRecord(entry) && typeof entry.command === "string" && isBasouStopHookCommand(entry.command)) {
+        return entry.command;
+      }
+    }
+  }
+  return null;
+}
+
 // src/adapters/claude-code/ask-user-question.ts
 function readString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
@@ -106,6 +221,14 @@ var CAPTURE_VERB = /(?:decision\s+(?:capture|record)|note)\b/;
 var CAPTURE_COMMAND_PATTERN = new RegExp(
   `(?:^|[\\n;&|(])\\s*${CAPTURE_INVOCATION.source}\\s+${CAPTURE_VERB.source}`
 );
+var SHIP_ACT_PATTERN = /(?:^|[\n;&|(])\s*(?:git\s+push|git\s+merge|gh\s+pr\s+(?:create|merge))(?![-\w])/;
+var DRY_RUN_PUSH_PATTERN = /(?:^|[\n;&|(])\s*git\s+push\b[^\n;&|()]*?\s-(?:-dry-run|n)\b/;
+function isShipAct(command) {
+  return SHIP_ACT_PATTERN.test(command) && !DRY_RUN_PUSH_PATTERN.test(command);
+}
+var REVIEW_RECORD_PATTERN = new RegExp(
+  `(?:^|[\\n;&|(])\\s*${CAPTURE_INVOCATION.source}\\s+review\\s+record\\b`
+);
 var FILE_EDIT_TOOLS = /* @__PURE__ */ new Set(["Edit", "Write", "NotebookEdit"]);
 function evaluateStopHook(input) {
   const minEdits = input.minEdits ?? DEFAULT_STOP_HOOK_MIN_EDITS;
@@ -113,6 +236,7 @@ function evaluateStopHook(input) {
     return {
       kind: "silent",
       reason: "stop_hook_active",
+      review: { fires: false, reason: "stop_hook_active" },
       commandCount: 0,
       fileCount: 0,
       decisionPointCount: 0
@@ -121,6 +245,8 @@ function evaluateStopHook(input) {
   let commandCount = 0;
   let fileCount = 0;
   let captured = false;
+  let shipped = false;
+  let reviewed = false;
   for (const record of input.records) {
     if (readString2(record.type) !== "assistant") continue;
     for (const tool of toolUsesOf2(record)) {
@@ -130,7 +256,11 @@ function evaluateStopHook(input) {
         commandCount += 1;
         const toolInput = isObject2(tool.input) ? tool.input : void 0;
         const command = toolInput !== void 0 ? readString2(toolInput.command) : void 0;
-        if (command !== void 0 && CAPTURE_COMMAND_PATTERN.test(command)) captured = true;
+        if (command !== void 0) {
+          if (CAPTURE_COMMAND_PATTERN.test(command)) captured = true;
+          if (isShipAct(command)) shipped = true;
+          if (REVIEW_RECORD_PATTERN.test(command)) reviewed = true;
+        }
       } else if (FILE_EDIT_TOOLS.has(name)) {
         fileCount += 1;
       }
@@ -138,14 +268,21 @@ function evaluateStopHook(input) {
   }
   const decisionPointCount = countUncapturedDecisionPoints(input.records);
   const counts = { commandCount, fileCount, decisionPointCount };
+  const review = evaluateReviewGate({ shipped, reviewed, fileCount, minEdits });
   if (captured) {
-    return { kind: "silent", reason: "already_captured", ...counts };
+    return { kind: "silent", reason: "already_captured", review, ...counts };
   }
   const substantive = fileCount >= minEdits || decisionPointCount > 0;
   if (!substantive) {
-    return { kind: "silent", reason: "not_substantive", ...counts };
+    return { kind: "silent", reason: "not_substantive", review, ...counts };
   }
-  return { kind: "nudge", additionalContext: renderNudge(counts), ...counts };
+  return { kind: "nudge", additionalContext: renderNudge(counts), review, ...counts };
+}
+function evaluateReviewGate(input) {
+  if (!input.shipped) return { fires: false, reason: "no_ship_act" };
+  if (input.fileCount < input.minEdits) return { fires: false, reason: "not_substantive_code" };
+  if (input.reviewed) return { fires: false, reason: "already_reviewed" };
+  return { fires: true, additionalContext: renderReviewNudge() };
 }
 function renderNudge(counts) {
   const did = [];
@@ -168,6 +305,14 @@ function renderNudge(counts) {
     "If nothing is worth capturing, just stop \u2014 do not invent decisions."
   ].join("\n");
 }
+function renderReviewNudge() {
+  return [
+    "This session shipped code (a push / PR / merge) after substantive edits but recorded no review.",
+    "An adversarial / second-opinion review before shipping is the discipline here. If a review ran, record it now so it lands on the durable trail:",
+    '  - run `basou review record` and pipe a JSON object: { "reviewer": "...", "target": "...", with optional "verdict" / "findings" / "blocked" } (an explicit "blocked": [] records that you blocked nothing).',
+    "If no review ran, that is the gap this is meant to catch \u2014 review before relying on this. If a review genuinely was not warranted, just stop \u2014 do not fabricate a review record."
+  ].join("\n");
+}
 function readString2(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
@@ -494,6 +639,16 @@ function toolUses(record) {
   return result;
 }
 
+// src/adapters/codex/codex-adapter.ts
+var codexAdapterMetadata = {
+  kind: "codex-adapter",
+  version: "0.1.0"
+};
+async function resolveCodexCommand(lookup = isOnPath) {
+  if (await lookup("codex")) return { command: "codex" };
+  throw new Error("Codex CLI not found in PATH. Install codex first.");
+}
+
 // src/adapters/codex/rollout-importer.ts
 var CODEX_IMPORT_SOURCE = "codex-import";
 function codexRolloutToImportPayload(records, options) {
@@ -1084,6 +1239,25 @@ var NoteAddedEventSchema = BaseEventSchema.extend({
   // surface. Optional so pre-existing note_added events remain valid.
   kind: z3.enum(["note", "next_step"]).optional()
 });
+var ReviewFindingSchema = z3.object({
+  title: z3.string().min(1),
+  severity: z3.enum(["high", "medium", "low"]).optional(),
+  location: z3.string().min(1).optional(),
+  summary: z3.string().min(1).optional()
+});
+var ReviewBlockedSchema = z3.object({
+  title: z3.string().min(1),
+  reason: z3.enum(["spec-deviation", "design-reversal"]),
+  why: z3.string().min(1).optional()
+});
+var ReviewRecordedEventSchema = BaseEventSchema.extend({
+  type: z3.literal("review_recorded"),
+  reviewer: z3.string().min(1),
+  target: z3.string().min(1),
+  verdict: z3.enum(["pass", "needs-attention", "fail"]).optional(),
+  findings: z3.array(ReviewFindingSchema).optional(),
+  blocked: z3.array(ReviewBlockedSchema).optional()
+});
 var AdapterOutputEventSchema = BaseEventSchema.extend({
   type: z3.literal("adapter_output"),
   stream: z3.enum(["stdout", "stderr"]),
@@ -1111,6 +1285,7 @@ var EventSchema = z3.discriminatedUnion("type", [
   TaskDeletedEventSchema,
   TaskArchivedEventSchema,
   NoteAddedEventSchema,
+  ReviewRecordedEventSchema,
   AdapterOutputEventSchema
 ]);
 
@@ -1409,6 +1584,7 @@ var SessionStatusSchema = z4.enum([
 var SessionSourceKindSchema = z4.enum([
   "claude-code-adapter",
   "claude-code-import",
+  "codex-adapter",
   "codex-import",
   "human",
   "import",
@@ -6755,6 +6931,159 @@ async function findReviewGaps(input) {
   };
 }
 
+// src/review/review-record.ts
+var VALID_VERDICTS = /* @__PURE__ */ new Set(["pass", "needs-attention", "fail"]);
+var VALID_SEVERITIES = /* @__PURE__ */ new Set(["high", "medium", "low"]);
+var VALID_BLOCK_REASONS = /* @__PURE__ */ new Set(["spec-deviation", "design-reversal"]);
+var ALLOWED_KEYS = /* @__PURE__ */ new Set([
+  "reviewer",
+  "target",
+  "verdict",
+  "findings",
+  "blocked"
+]);
+var ALLOWED_FINDING_KEYS = /* @__PURE__ */ new Set([
+  "title",
+  "severity",
+  "location",
+  "summary"
+]);
+var ALLOWED_BLOCKED_KEYS = /* @__PURE__ */ new Set(["title", "reason", "why"]);
+var REVIEW_RECORD_NO_INPUT_HINT = "No input: pipe a JSON object describing the review to stdin or pass --file <path>.";
+function parseReviewRecordInput(raw) {
+  if (raw.trim().length === 0) {
+    throw new Error(REVIEW_RECORD_NO_INPUT_HINT);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Input is not valid JSON: ${detail}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("Input must be a single JSON object describing one review.");
+  }
+  const obj = parsed;
+  for (const key of Object.keys(obj)) {
+    if (!ALLOWED_KEYS.has(key)) {
+      throw new Error(
+        `Unknown field '${key}'. Allowed: reviewer, target, verdict, findings, blocked.`
+      );
+    }
+  }
+  const reviewer = requireNonEmptyString(obj.reviewer, "reviewer");
+  const target = requireNonEmptyString(obj.target, "target");
+  const out = { reviewer, target };
+  if (obj.verdict !== void 0) {
+    if (typeof obj.verdict !== "string" || !VALID_VERDICTS.has(obj.verdict)) {
+      throw new Error(`verdict must be one of pass, needs-attention, fail, got '${obj.verdict}'.`);
+    }
+    out.verdict = obj.verdict;
+  }
+  if (obj.findings !== void 0) {
+    out.findings = parseFindings(obj.findings);
+  }
+  if (obj.blocked !== void 0) {
+    out.blocked = parseBlocked(obj.blocked);
+  }
+  return out;
+}
+function parseFindings(value) {
+  if (!Array.isArray(value)) {
+    throw new Error("findings must be an array of objects.");
+  }
+  return value.map((item, i) => {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+      throw new Error(`findings[${i}] must be a JSON object.`);
+    }
+    const obj = item;
+    for (const key of Object.keys(obj)) {
+      if (!ALLOWED_FINDING_KEYS.has(key)) {
+        throw new Error(
+          `findings[${i}]: unknown field '${key}'. Allowed: title, severity, location, summary.`
+        );
+      }
+    }
+    const finding = {
+      title: requireNonEmptyString(obj.title, `findings[${i}].title`)
+    };
+    if (obj.severity !== void 0) {
+      if (typeof obj.severity !== "string" || !VALID_SEVERITIES.has(obj.severity)) {
+        throw new Error(
+          `findings[${i}].severity must be one of high, medium, low, got '${obj.severity}'.`
+        );
+      }
+      finding.severity = obj.severity;
+    }
+    if (obj.location !== void 0) {
+      finding.location = requireNonEmptyString(obj.location, `findings[${i}].location`);
+    }
+    if (obj.summary !== void 0) {
+      finding.summary = requireNonEmptyString(obj.summary, `findings[${i}].summary`);
+    }
+    return finding;
+  });
+}
+function parseBlocked(value) {
+  if (!Array.isArray(value)) {
+    throw new Error("blocked must be an array of objects.");
+  }
+  return value.map((item, i) => {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+      throw new Error(`blocked[${i}] must be a JSON object.`);
+    }
+    const obj = item;
+    for (const key of Object.keys(obj)) {
+      if (!ALLOWED_BLOCKED_KEYS.has(key)) {
+        throw new Error(`blocked[${i}]: unknown field '${key}'. Allowed: title, reason, why.`);
+      }
+    }
+    if (typeof obj.reason !== "string" || !VALID_BLOCK_REASONS.has(obj.reason)) {
+      throw new Error(
+        `blocked[${i}].reason must be one of spec-deviation, design-reversal, got '${obj.reason}'.`
+      );
+    }
+    const blocked = {
+      title: requireNonEmptyString(obj.title, `blocked[${i}].title`),
+      reason: obj.reason
+    };
+    if (obj.why !== void 0) {
+      blocked.why = requireNonEmptyString(obj.why, `blocked[${i}].why`);
+    }
+    return blocked;
+  });
+}
+function requireNonEmptyString(value, field) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${field} must be a non-empty string.`);
+  }
+  return value;
+}
+function buildReviewRecordedEvent(input) {
+  const { review } = input;
+  return {
+    schema_version: "0.1.0",
+    id: input.eventId,
+    session_id: input.sessionId,
+    occurred_at: input.occurredAt,
+    source: "local-cli",
+    type: "review_recorded",
+    reviewer: review.reviewer,
+    target: review.target,
+    ...review.verdict !== void 0 ? { verdict: review.verdict } : {},
+    ...review.findings !== void 0 ? { findings: review.findings } : {},
+    ...review.blocked !== void 0 ? { blocked: review.blocked } : {}
+  };
+}
+var LABEL_FRAGMENT_MAX = 40;
+function buildReviewRecordLabel(review) {
+  return `Ad-hoc review: ${truncate(review.reviewer)} -> ${truncate(review.target)}`;
+}
+function truncate(value) {
+  return value.length > LABEL_FRAGMENT_MAX ? `${value.slice(0, LABEL_FRAGMENT_MAX - 3)}...` : value;
+}
+
 // src/runtime/child-process-runner.ts
 import { spawn as spawn2 } from "child_process";
 var DEFAULT_KILL_GRACE_MS = 5e3;
@@ -7137,6 +7466,8 @@ var GENERATED_START = "<!-- BASOU:GENERATED:START -->";
 var GENERATED_END = "<!-- BASOU:GENERATED:END -->";
 var PROTOCOL_START = "<!-- BASOU:PROTOCOLS:START -->";
 var PROTOCOL_END = "<!-- BASOU:PROTOCOLS:END -->";
+var ORIENTATION_START = "<!-- BASOU:ORIENTATION:START -->";
+var ORIENTATION_END = "<!-- BASOU:ORIENTATION:END -->";
 var DEFAULT_MARKERS = { start: GENERATED_START, end: GENERATED_END };
 async function readMarkdownFile(filePath) {
   try {
@@ -7661,9 +7992,13 @@ export {
   IsoTimestampSchema,
   JSON_SCHEMA_VERSION,
   ManifestSchema,
+  ORIENTATION_END,
+  ORIENTATION_START,
   PROTOCOL_END,
   PROTOCOL_START,
+  REVIEW_RECORD_NO_INPUT_HINT,
   RiskLevelSchema,
+  STOP_HOOK_TIMEOUT_SECONDS,
   STUCK_THRESHOLD_MS,
   SchemaVersionSchema,
   SessionIdSchema,
@@ -7690,7 +8025,10 @@ export {
   assertBasouRootSafe,
   basouPaths,
   buildJsonSchemas,
+  buildReviewRecordLabel,
+  buildReviewRecordedEvent,
   buildStatusSnapshot,
+  buildStopHookCommand,
   chainEvents,
   chainRawJsonLines,
   classifyFilesBySourceRoot,
@@ -7698,6 +8036,7 @@ export {
   classifySuspect,
   claudeCodeAdapterMetadata,
   claudeTranscriptToImportPayload,
+  codexAdapterMetadata,
   codexRolloutToImportPayload,
   computeWorkStats,
   createAdHocSessionWithEvent,
@@ -7712,6 +8051,7 @@ export {
   enumerateTaskIds,
   evaluateStopHook,
   finalizeSessionYaml,
+  findBasouStopHookCommand,
   findErrorCode,
   findReviewGaps,
   formatDurationMs,
@@ -7721,6 +8061,7 @@ export {
   importSessionFromJson,
   inspectChainTail,
   instructionMode,
+  isBasouStopHookCommand,
   isGitNotFound,
   isImportDerivedSource,
   isLazyExpired,
@@ -7737,6 +8078,7 @@ export {
   overwriteYamlFile,
   parseDuration,
   parseMarkers,
+  parseReviewRecordInput,
   pathBasename,
   planArchive,
   planGitignore,
@@ -7759,6 +8101,7 @@ export {
   refreshTaskLinkedSessions,
   reimportPreservingId,
   removeMarkerSection,
+  removeStopHook,
   renderDecisions,
   renderHandoff,
   renderOrientation,
@@ -7768,6 +8111,7 @@ export {
   replayEvents,
   resolveBasouRepositoryRoot,
   resolveClaudeCodeCommand,
+  resolveCodexCommand,
   resolveRepositoryRoot,
   resolveSessionId,
   resolveTaskId,
@@ -7788,6 +8132,7 @@ export {
   ulid,
   unknownManifestKeys,
   updateTaskStatusWithEvent,
+  upsertStopHook,
   verifyEventsChain,
   writeEventsBulk,
   writeManifest,