@basou/cli 0.19.0 → 0.21.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 });
@@ -2759,6 +2885,19 @@ import {
   resolveSessionId as resolveSessionId2
 } from "@basou/core";
 import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+var NOTE_SUBCOMMAND_LOOKALIKES = /* @__PURE__ */ new Set([
+  "list",
+  "ls",
+  "show",
+  "get",
+  "add",
+  "new",
+  "edit",
+  "rm",
+  "remove",
+  "delete",
+  "help"
+]);
 var LABEL_BODY_MAX = 80;
 var LABEL_TRUNCATE_HEAD2 = LABEL_BODY_MAX - 3;
 function registerNoteCommand(program2) {
@@ -2784,6 +2923,12 @@ async function doRunNote(body, options, ctx) {
   if (body.trim().length === 0) {
     throw new Error("Note body must not be empty");
   }
+  const reserved = body.trim().toLowerCase();
+  if (NOTE_SUBCOMMAND_LOOKALIKES.has(reserved)) {
+    throw new Error(
+      `'basou note' records a free-text note and has no '${body.trim()}' subcommand. To record a note, pass its full text (e.g. \`basou note "<your note>"\`).`
+    );
+  }
   const cwd = ctx.cwd ?? process.cwd();
   const repositoryRoot = await resolveBasouRootForCommand(cwd, "note");
   const paths = basouPaths8(repositoryRoot);
@@ -4887,7 +5032,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 +5043,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 +5063,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 +5071,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 +5084,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 +5215,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 +5355,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 +5384,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 +6302,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 +6747,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 +6864,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 +7171,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,
@@ -7047,7 +7192,6 @@ import {
   reconcileTask,
   refreshTaskLinkedSessions,
   replayEvents as replayEvents3,
-  resolveRepositoryRoot as resolveRepositoryRoot12,
   resolveSessionId as resolveSessionId4,
   resolveTaskId as resolveTaskId2,
   TaskStatusSchema,
@@ -8042,7 +8186,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 });
@@ -8054,17 +8198,7 @@ async function readDescriptionFile(path) {
   }
 }
 async function resolveRepositoryRootForTask(cwd, subcmd) {
-  try {
-    return await resolveRepositoryRoot12(cwd);
-  } catch (error) {
-    if (error instanceof Error && error.message === "Not a git repository") {
-      throw new Error(
-        `Not a git repository. Run 'git init' first, then re-run 'basou task ${subcmd}'.`,
-        { cause: error }
-      );
-    }
-    throw error;
-  }
+  return resolveBasouRootForCommand(cwd, `task ${subcmd}`);
 }
 async function assertWorkspaceInitialized12(basouRoot) {
   try {
@@ -8162,7 +8296,7 @@ import {
   basouPaths as basouPaths19,
   enumerateSessionDirs as enumerateSessionDirs3,
   findErrorCode as findErrorCode15,
-  resolveRepositoryRoot as resolveRepositoryRoot13,
+  resolveRepositoryRoot as resolveRepositoryRoot12,
   resolveSessionId as resolveSessionId5,
   verifyEventsChain
 } from "@basou/core";
@@ -8233,7 +8367,7 @@ function renderVerdict(row) {
 }
 async function resolveRepositoryRootForVerify(cwd) {
   try {
-    return await resolveRepositoryRoot13(cwd);
+    return await resolveRepositoryRoot12(cwd);
   } catch (error) {
     if (error instanceof Error && error.message === "Not a git repository") {
       throw new Error("Not a git repository. Run 'git init' first, then re-run 'basou verify'.", {
@@ -8263,7 +8397,7 @@ import {
   basouPaths as basouPaths20,
   findErrorCode as findErrorCode17,
   readManifest as readManifest13,
-  resolveRepositoryRoot as resolveRepositoryRoot14
+  resolveRepositoryRoot as resolveRepositoryRoot13
 } from "@basou/core";
 import { InvalidArgumentError as InvalidArgumentError7 } from "commander";
 
@@ -9679,7 +9813,7 @@ function waitForShutdown(signal) {
 }
 async function resolveRepositoryRootForView(cwd) {
   try {
-    return await resolveRepositoryRoot14(cwd);
+    return await resolveRepositoryRoot13(cwd);
   } catch (error) {
     if (error instanceof Error && error.message === "Not a git repository") {
       throw new Error("Not a git repository. Run 'git init' first, then re-run 'basou view'.", {
@@ -9728,6 +9862,7 @@ function buildProgram() {
   registerReviewGapsCommand(program2);
   registerProjectCommand(program2);
   registerProtocolCommand(program2);
+  registerHookCommand(program2);
   return program2;
 }