@basou/cli 0.19.0 → 0.20.0

package/dist/index.js

@@ -2033,9 +2033,135 @@ async function assertWorkspaceInitialized4(basouRoot) {
   }
 }
 
+// src/commands/hook.ts
+import { open, readFile as readFile2, stat as stat2 } from "fs/promises";
+import {
+  DEFAULT_STOP_HOOK_MIN_ACTIONS,
+  evaluateStopHook
+} from "@basou/core";
+var MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
+function registerHookCommand(program2) {
+  const hook = program2.command("hook").description(
+    "Claude Code hook handlers (read a hook payload on stdin, emit hook JSON on stdout)"
+  );
+  hook.command("stop").description(
+    "Stop-hook: when a substantive session recorded no decisions or next step, emit a non-blocking nudge to capture them. Reads the Stop hook JSON payload on stdin; never blocks and never fails the session."
+  ).option(
+    "--min-actions <n>",
+    `Minimum commands+edits before nudging (default ${DEFAULT_STOP_HOOK_MIN_ACTIONS})`
+  ).addHelpText("after", HOOK_STOP_HELP).action(async (options) => {
+    const minActions = parseMinActions(options.minActions);
+    await runHookStop(minActions !== void 0 ? { minActions } : {});
+  });
+}
+var HOOK_STOP_HELP = `
+Install as a Claude Code Stop hook in ~/.claude/settings.json:
+  {
+    "hooks": {
+      "Stop": [
+        { "hooks": [ { "type": "command", "command": "basou hook stop" } ] }
+      ]
+    }
+  }
+
+On every turn end basou inspects the session transcript. If the session did
+substantive work (>= ${DEFAULT_STOP_HOOK_MIN_ACTIONS} commands + file edits by default) but ran no capture
+verb ('basou decision capture' / 'decision record' / 'note'), it emits a
+non-blocking reminder so the agent can record the why / next step. The reminder
+continues the conversation (Claude may act on it or stop); it never forces.
+The 'stop_hook_active' flag is honored so the nudge cannot loop.
+`;
+async function runHookStop(options, ctx = {}) {
+  try {
+    await doRunHookStop(options, ctx);
+  } catch {
+  }
+}
+async function doRunHookStop(options, ctx) {
+  const readStdin = ctx.readStdin ?? defaultReadStdin;
+  const readTranscript = ctx.readTranscript ?? readTranscriptBounded;
+  const write = ctx.write ?? ((text) => void process.stdout.write(text));
+  const raw = await readStdin();
+  if (raw.trim().length === 0) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (typeof payload !== "object" || payload === null) return;
+  const fields = payload;
+  if (fields.stop_hook_active === true) return;
+  const transcriptPath = typeof fields.transcript_path === "string" ? fields.transcript_path : "";
+  if (transcriptPath.length === 0) return;
+  let transcript;
+  try {
+    transcript = await readTranscript(transcriptPath);
+  } catch {
+    return;
+  }
+  const records = parseTranscript(transcript);
+  const evaluation = evaluateStopHook({
+    records,
+    // stop_hook_active was already handled by the early return above.
+    stopHookActive: false,
+    ...options.minActions !== void 0 ? { minActions: options.minActions } : {}
+  });
+  if (evaluation.kind !== "nudge") return;
+  write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "Stop",
+        additionalContext: evaluation.additionalContext
+      }
+    })}
+`
+  );
+}
+function parseTranscript(transcript) {
+  const records = [];
+  for (const line of transcript.split(/\r?\n/)) {
+    if (line.trim().length === 0) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        records.push(parsed);
+      }
+    } catch {
+    }
+  }
+  return records;
+}
+async function defaultReadStdin() {
+  if (process.stdin.isTTY === true) return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function readTranscriptBounded(path, maxBytes = MAX_TRANSCRIPT_BYTES) {
+  const { size } = await stat2(path);
+  if (size <= maxBytes) return readFile2(path, "utf8");
+  const handle = await open(path, "r");
+  try {
+    const buffer = Buffer.alloc(maxBytes);
+    const { bytesRead } = await handle.read(buffer, 0, maxBytes, size - maxBytes);
+    const text = buffer.subarray(0, bytesRead).toString("utf8");
+    const firstNewline = text.indexOf("\n");
+    return firstNewline >= 0 ? text.slice(firstNewline + 1) : text;
+  } finally {
+    await handle.close();
+  }
+}
+function parseMinActions(raw) {
+  if (raw === void 0 || !/^\d+$/.test(raw)) return void 0;
+  return Number(raw);
+}
+
 // src/commands/import.ts
 import { createReadStream } from "fs";
-import { readdir, readFile as readFile2, rm, stat as stat2 } from "fs/promises";
+import { readdir, readFile as readFile3, rm, stat as stat3 } from "fs/promises";
 import { homedir as homedir4 } from "os";
 import { basename as basename2, dirname, join as join5, resolve as resolve4 } from "path";
 import { createInterface } from "readline";
@@ -2433,7 +2559,7 @@ async function selectTranscriptFiles(projectsRoot, projectPaths, options) {
 }
 async function pathExists(file) {
   try {
-    await stat2(file);
+    await stat3(file);
     return true;
   } catch (error) {
     if (findErrorCode5(error, "ENOENT")) return false;
@@ -2442,7 +2568,7 @@ async function pathExists(file) {
 }
 async function statSize(file) {
   try {
-    return (await stat2(file)).size;
+    return (await stat3(file)).size;
   } catch (error) {
     if (findErrorCode5(error, "ENOENT")) return void 0;
     throw error;
@@ -2528,7 +2654,7 @@ async function readFirstLine(file) {
 async function readJsonlRecords(file) {
   let buffer;
   try {
-    buffer = await readFile2(file);
+    buffer = await readFile3(file);
   } catch (error) {
     if (findErrorCode5(error, "ENOENT")) {
       throw new Error("Source log not found", { cause: error });
@@ -4887,7 +5013,7 @@ function renderProjectRename(result) {
 }
 
 // src/commands/protocol.ts
-import { readFile as readFile3 } from "fs/promises";
+import { readFile as readFile4 } from "fs/promises";
 import {
   PROTOCOL_END,
   PROTOCOL_START,
@@ -4898,7 +5024,7 @@ import {
 
 // src/lib/durable-write.ts
 import { randomUUID } from "crypto";
-import { lstat, open, rename, stat as stat3, unlink as unlink2 } from "fs/promises";
+import { lstat, open as open2, rename, stat as stat4, unlink as unlink2 } from "fs/promises";
 import { basename as basename5, dirname as dirname3, join as join8 } from "path";
 async function assertNotSymlink(targetPath) {
   try {
@@ -4918,7 +5044,7 @@ async function writeFileDurable(targetPath, content) {
   const tmpPath = join8(dir, `.${basename5(targetPath)}.tmp.${randomUUID()}`);
   let mode = 420;
   try {
-    mode = (await stat3(targetPath)).mode & 511;
+    mode = (await stat4(targetPath)).mode & 511;
   } catch (error) {
     if (!(error instanceof Error && error.code === "ENOENT")) {
       throw error;
@@ -4926,7 +5052,7 @@ async function writeFileDurable(targetPath, content) {
   }
   let handle;
   try {
-    handle = await open(tmpPath, "wx", mode);
+    handle = await open2(tmpPath, "wx", mode);
     await handle.writeFile(content, "utf8");
     await handle.chmod(mode);
     await handle.sync();
@@ -4939,7 +5065,7 @@ async function writeFileDurable(targetPath, content) {
     throw error;
   }
   try {
-    const dirHandle = await open(dir, "r");
+    const dirHandle = await open2(dir, "r");
     try {
       await dirHandle.sync();
     } finally {
@@ -5070,7 +5196,7 @@ async function readProtocolSources(entries) {
   for (const entry of entries) {
     let content;
     try {
-      content = await readFile3(entry.source, "utf8");
+      content = await readFile4(entry.source, "utf8");
     } catch (error) {
       if (error instanceof Error && error.code === "ENOENT") {
         throw new Error(
@@ -5210,7 +5336,7 @@ import { assertBasouRootSafe as assertBasouRootSafe9, basouPaths as basouPaths11
 import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
 
 // src/commands/refresh-watch.ts
-import { readdir as readdir2, stat as stat4 } from "fs/promises";
+import { readdir as readdir2, stat as stat5 } from "fs/promises";
 import { homedir as homedir7 } from "os";
 import { join as join10 } from "path";
 import { findErrorCode as findErrorCode8 } from "@basou/core";
@@ -5239,7 +5365,7 @@ async function scanSourceLogs(roots) {
         await walk(full);
       } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
         try {
-          const info = await stat4(full);
+          const info = await stat5(full);
           out.set(full, { mtimeMs: info.mtimeMs, size: info.size });
         } catch (error) {
           if (findErrorCode8(error, "ENOENT")) continue;
@@ -6157,7 +6283,7 @@ async function resolveRepositoryRootForRun(cwd) {
 }
 
 // src/commands/session.ts
-import { readFile as readFile4 } from "fs/promises";
+import { readFile as readFile5 } from "fs/promises";
 import { basename as basename6, isAbsolute as isAbsolute6, join as join12, relative as relative3 } from "path";
 import {
   acquireLock as acquireLock6,
@@ -6602,7 +6728,7 @@ async function doRunSessionImport(options, ctx) {
 }
 async function readInputFile(path) {
   try {
-    return await readFile4(path, "utf8");
+    return await readFile5(path, "utf8");
   } catch (error) {
     if (findErrorCode11(error, "ENOENT")) {
       throw new Error("Import source not found", { cause: error });
@@ -6719,7 +6845,7 @@ async function doRunSessionNote(sessionIdInput, options, ctx) {
 }
 async function readNoteFile(path) {
   try {
-    return await readFile4(path, "utf8");
+    return await readFile5(path, "utf8");
   } catch (error) {
     if (findErrorCode11(error, "ENOENT")) {
       throw new Error("Note source not found", { cause: error });
@@ -7026,7 +7152,7 @@ async function resolveRepositoryRootForStatus(cwd) {
 }
 
 // src/commands/task.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 import { join as join13 } from "path";
 import {
   archiveTask,
@@ -8042,7 +8168,7 @@ function parsePositiveInt2(raw) {
 }
 async function readDescriptionFile(path) {
   try {
-    return await readFile5(path, "utf8");
+    return await readFile6(path, "utf8");
   } catch (error) {
     if (findErrorCode14(error, "ENOENT")) {
       throw new Error("Description source not found", { cause: error });
@@ -9728,6 +9854,7 @@ function buildProgram() {
   registerReviewGapsCommand(program2);
   registerProjectCommand(program2);
   registerProtocolCommand(program2);
+  registerHookCommand(program2);
   return program2;
 }