@basou/cli 0.18.0 → 0.20.0

package/dist/program.js

@@ -838,6 +838,9 @@ function registerDecisionCommand(program) {
     "Related file path (repeatable). Path is opaque; existence is verified at render time.",
     collectLinkedFile,
     []
+  ).option(
+    "--track",
+    "Record as a strategic track (an unfinished direction + why). orientation/handoff keep resurfacing open tracks until you close one with 'basou decision void'."
   ).option(
     "--session <session_id>",
     "Attach to an existing session; otherwise an ad-hoc session is created"
@@ -870,13 +873,22 @@ Input format (a JSON array; one object per decision):
       "alternatives": ["npm workspaces", "yarn"],
       "rejected_reason": "npm hoisting caused phantom-dependency bugs",
       "linked_files": ["pnpm-workspace.yaml"]
+    },
+    {
+      "title": "Form-based admin editing is the next track (only 6/19 sections done)",
+      "rationale": "Raw-JSON editing is a stopgap, not the final shape; cover the rest.",
+      "kind": "track"
     }
   ]
 
-Only "title" is required; every other field is optional. All decisions are
-written into one ad-hoc session timestamped now, so orientation surfaces them
-as the latest decisions. Run from a workspace-view directory and it resolves to
-the planning repo, like 'basou orient' / 'basou refresh' / 'basou note'.
+Only "title" is required; every other field is optional. Set "kind": "track" to
+record a strategic, UNFINISHED direction (+ why): orientation/handoff resurface
+open tracks every session until you close one with 'basou decision void <id>'.
+Absent / "decision" is a point-in-time decision (surfaced only as the latest).
+All decisions are written into one ad-hoc session timestamped now, so
+orientation surfaces them as the latest decisions. Run from a workspace-view
+directory and it resolves to the planning repo, like 'basou orient' /
+'basou refresh' / 'basou note'.
 
 Example (heredoc on stdin):
   basou decision capture <<'JSON'
@@ -973,7 +985,7 @@ async function doRunDecisionRecord(options, ctx) {
     workingDirectory: repositoryRoot,
     invocation: {
       command: "basou decision record",
-      args: ["--title", options.title]
+      args: options.track === true ? ["--title", options.title, "--track"] : ["--title", options.title]
     },
     targetEventBuilders: [
       (sessionId, eventId) => buildDecisionEvent({
@@ -1254,7 +1266,8 @@ var CAPTURE_ALLOWED_KEYS = /* @__PURE__ */ new Set([
   "rejected_reason",
   "alternatives",
   "linked_events",
-  "linked_files"
+  "linked_files",
+  "kind"
 ]);
 function parseCaptureInput(raw) {
   if (raw.trim().length === 0) {
@@ -1283,7 +1296,7 @@ function validateCaptureItem(item, index) {
   for (const key of Object.keys(obj)) {
     if (!CAPTURE_ALLOWED_KEYS.has(key)) {
       throw new Error(
-        `decision[${index}]: unknown field '${key}'. Allowed: title, rationale, rejected_reason, alternatives, linked_events, linked_files.`
+        `decision[${index}]: unknown field '${key}'. Allowed: title, rationale, rejected_reason, alternatives, linked_events, linked_files, kind.`
       );
     }
   }
@@ -1291,6 +1304,12 @@ function validateCaptureItem(item, index) {
     throw new Error(`decision[${index}].title must be a non-empty string.`);
   }
   const out = { title: obj.title };
+  if (obj.kind !== void 0) {
+    if (obj.kind !== "decision" && obj.kind !== "track") {
+      throw new Error(`decision[${index}].kind must be "decision" or "track", got '${obj.kind}'.`);
+    }
+    if (obj.kind === "track") out.kind = "track";
+  }
   if (obj.rationale !== void 0) {
     out.rationale = requireNonEmptyString(obj.rationale, index, "rationale");
   }
@@ -1358,6 +1377,7 @@ function toRichFields(decision) {
   if (decision.alternatives !== void 0) out.alternatives = [...decision.alternatives];
   if (decision.linked_events !== void 0) out.linked_events = [...decision.linked_events];
   if (decision.linked_files !== void 0) out.linked_files = [...decision.linked_files];
+  if (decision.kind !== void 0) out.kind = decision.kind;
   return out;
 }
 function buildCaptureLabel(count) {
@@ -1375,6 +1395,7 @@ function captureItemToPayload(item) {
     payload.rejected_reason = item.input.rejected_reason;
   if (item.input.linked_events !== void 0) payload.linked_events = item.input.linked_events;
   if (item.input.linked_files !== void 0) payload.linked_files = item.input.linked_files;
+  if (item.input.kind !== void 0) payload.kind = item.input.kind;
   return payload;
 }
 function printCapturePreview(options, decisions) {
@@ -1386,7 +1407,7 @@ function printCapturePreview(options, decisions) {
     `Would capture ${decisions.length} decision${decisions.length === 1 ? "" : "s"} (dry run; nothing written):`
   );
   for (const decision of decisions) {
-    console.log(`- ${decision.title}`);
+    console.log(`- ${decision.title}${decision.kind === "track" ? " [TRACK]" : ""}`);
   }
 }
 function printCaptureResult(options, result) {
@@ -1407,7 +1428,9 @@ function printCaptureResult(options, result) {
     `Captured ${result.items.length} decision${result.items.length === 1 ? "" : "s"} in ad-hoc session ${sid}:`
   );
   for (const item of result.items) {
-    console.log(`- ${item.decisionId}: ${item.input.title}`);
+    console.log(
+      `- ${item.decisionId}: ${item.input.title}${item.input.kind === "track" ? " [TRACK]" : ""}`
+    );
   }
 }
 function pickRichFields(options) {
@@ -1423,6 +1446,7 @@ function pickRichFields(options) {
   if (options.linkedFile !== void 0 && options.linkedFile.length > 0) {
     out.linked_files = [...options.linkedFile];
   }
+  if (options.track === true) out.kind = "track";
   return out;
 }
 function buildDecisionEvent(input) {
@@ -1439,7 +1463,8 @@ function buildDecisionEvent(input) {
     ...input.rich.alternatives !== void 0 ? { alternatives: input.rich.alternatives } : {},
     ...input.rich.rejected_reason !== void 0 ? { rejected_reason: input.rich.rejected_reason } : {},
     ...input.rich.linked_events !== void 0 ? { linked_events: input.rich.linked_events } : {},
-    ...input.rich.linked_files !== void 0 ? { linked_files: input.rich.linked_files } : {}
+    ...input.rich.linked_files !== void 0 ? { linked_files: input.rich.linked_files } : {},
+    ...input.rich.kind !== void 0 ? { kind: input.rich.kind } : {}
   };
 }
 function buildAdHocLabel(title) {
@@ -1506,15 +1531,19 @@ function printDecisionResult(options, result) {
     }
     if (result.rich.linked_events !== void 0) payload.linked_events = result.rich.linked_events;
     if (result.rich.linked_files !== void 0) payload.linked_files = result.rich.linked_files;
+    if (result.rich.kind !== void 0) payload.kind = result.rich.kind;
     console.log(JSON.stringify(payload));
     return;
   }
+  const trackPrefix = result.rich.kind === "track" ? "track " : "";
   const rationaleSuffix = result.rich.rationale !== void 0 ? ` (rationale: ${result.rich.rationale})` : "";
   if (result.mode === "ad-hoc") {
-    console.log(`Recorded ${result.decisionId} in ad-hoc session ${sid}${rationaleSuffix}`);
+    console.log(
+      `Recorded ${trackPrefix}${result.decisionId} in ad-hoc session ${sid}${rationaleSuffix}`
+    );
   } else {
     console.log(
-      `Recorded ${result.decisionId} in session ${sid} (${result.sessionStatus})${rationaleSuffix}`
+      `Recorded ${trackPrefix}${result.decisionId} in session ${sid} (${result.sessionStatus})${rationaleSuffix}`
     );
   }
 }
@@ -2004,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(program) {
+  const hook = program.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";
@@ -2404,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;
@@ -2413,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;
@@ -2499,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 });
@@ -4858,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,
@@ -4869,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 {
@@ -4889,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;
@@ -4897,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();
@@ -4910,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 {
@@ -5041,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(
@@ -5181,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";
@@ -5210,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;
@@ -6128,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,
@@ -6573,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 });
@@ -6690,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 });
@@ -6997,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,
@@ -8013,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 });
@@ -9699,6 +9854,7 @@ function buildProgram() {
   registerReviewGapsCommand(program);
   registerProjectCommand(program);
   registerProtocolCommand(program);
+  registerHookCommand(program);
   return program;
 }
 export {