@groundctl/cli 0.2.1 → 0.3.0

package/dist/index.js

@@ -274,7 +274,7 @@ function generateProjectState(db, projectName) {
     md += "\n";
   }
   if (decisions.length > 0) {
-    md += "## Decisions made\n";
+    md += "## Architecture log\n";
     for (const d of decisions) {
       md += `- ${d.session_id}: ${d.description}`;
       if (d.rationale) md += ` \u2014 ${d.rationale}`;
@@ -874,7 +874,7 @@ async function completeCommand(featureIdOrName) {
 import { writeFileSync as writeFileSync3 } from "fs";
 import { join as join4 } from "path";
 import chalk4 from "chalk";
-async function syncCommand() {
+async function syncCommand(opts) {
   const db = await openDb();
   const projectName = process.cwd().split("/").pop() ?? "unknown";
   const projectState = generateProjectState(db, projectName);
@@ -883,8 +883,10 @@ async function syncCommand() {
   const cwd = process.cwd();
   writeFileSync3(join4(cwd, "PROJECT_STATE.md"), projectState);
   writeFileSync3(join4(cwd, "AGENTS.md"), agentsMd);
-  console.log(chalk4.green("\n  \u2713 PROJECT_STATE.md regenerated"));
-  console.log(chalk4.green("  \u2713 AGENTS.md regenerated\n"));
+  if (!opts?.silent) {
+    console.log(chalk4.green("\n  \u2713 PROJECT_STATE.md regenerated"));
+    console.log(chalk4.green("  \u2713 AGENTS.md regenerated\n"));
+  }
 }
 
 // src/commands/next.ts
@@ -1278,19 +1280,23 @@ function buildSummary(sessionId, fileCount, commitCount, decisionCount, lastText
 }
 
 // src/commands/ingest.ts
+function claudeEncode(p) {
+  return p.replace(/[^a-zA-Z0-9]/g, "-");
+}
 function findLatestTranscript(projectPath) {
   const projectsDir = join5(homedir2(), ".claude", "projects");
   if (!existsSync4(projectsDir)) return null;
-  const projectKey = projectPath.replace(/\//g, "-");
   let transcriptDir = null;
+  const projectKey = claudeEncode(projectPath);
   const directMatch = join5(projectsDir, projectKey);
   if (existsSync4(directMatch)) {
     transcriptDir = directMatch;
   } else {
     const projectName = projectPath.split("/").pop() ?? "";
+    const encodedName = claudeEncode(projectName);
     const dirs = readdirSync(projectsDir);
     for (const d of dirs) {
-      if (d.endsWith(`-${projectName}`) || d.includes(projectName.replace(/\//g, "-"))) {
+      if (d.endsWith(`-${encodedName}`) || d.includes(encodedName)) {
         transcriptDir = join5(projectsDir, d);
         break;
       }
@@ -1444,7 +1450,7 @@ ${sessionRow.summary}
     md += "\n";
   }
   if (decisions.length > 0) {
-    md += "## Decisions\n";
+    md += "## Architecture log\n";
     for (const d of decisions) {
       md += `- ${d.description}`;
       if (d.rationale) md += ` \u2014 ${d.rationale}`;
@@ -1569,7 +1575,7 @@ async function reportCommand(options) {
   console.log(chalk9.green(`
   \u2713 SESSION_REPORT.md written (session ${session.id})
 `));
-  console.log(chalk9.gray(`  ${files.length} files \xB7 ${decisions.length} decisions \xB7 ${completedFeatures.length} features completed`));
+  console.log(chalk9.gray(`  ${files.length} files \xB7 ${decisions.length} arch log entries \xB7 ${completedFeatures.length} features completed`));
   console.log("");
 }
 
@@ -1640,7 +1646,7 @@ async function healthCommand() {
   const decMark = decisionCount > 0 ? "\u2705" : "\u26A0\uFE0F ";
   const decColor = decisionCount > 0 ? chalk10.green : chalk10.yellow;
   console.log(
-    `  ${decMark} Decisions   ${decColor(decisionCount + " documented")}` + chalk10.gray(`  +${decisionScore}pts`)
+    `  ${decMark} Arch log    ${decColor(decisionCount + " entries")}` + chalk10.gray(`  +${decisionScore}pts`)
   );
   const claimMark = staleClaims === 0 ? "\u2705" : "\u26A0\uFE0F ";
   const claimColor = staleClaims === 0 ? chalk10.green : chalk10.red;
@@ -1656,7 +1662,7 @@ async function healthCommand() {
   const recommendations = [];
   if (testFiles === 0) recommendations.push("Write tests before your next feature (0 test files found).");
   if (staleClaims > 0) recommendations.push(`Release ${staleClaims} stale claim(s) with groundctl complete <feature>.`);
-  if (decisionCount === 0) recommendations.push("Document decisions during sessions so agents have context.");
+  if (decisionCount === 0) recommendations.push("Log architecture decisions during sessions so agents understand the why.");
   if (featurePct < 0.5 && total > 0) recommendations.push(`${counts.pending} features pending \u2014 run groundctl next to pick one.`);
   if (recommendations.length > 0) {
     console.log(chalk10.bold("  Recommendations:"));
@@ -1795,7 +1801,7 @@ body{background:var(--bg);color:var(--tx);font-family:var(--mo);font-size:13px;l
   <div class="hi">
     <div><span class="${meta.done > 0 ? "ok" : "warn"}">${meta.done > 0 ? "\u2713" : "\u26A0"}</span><span>Features ${meta.done}/${meta.total}</span></div>
     <div><span class="${meta.testFiles > 0 ? "ok" : "bad"}">${meta.testFiles > 0 ? "\u2713" : "\u2717"}</span><span>Tests ${meta.testFiles} files</span></div>
-    <div><span class="${meta.decCount > 0 ? "ok" : "warn"}">${meta.decCount > 0 ? "\u2713" : "\u26A0"}</span><span>Decisions ${meta.decCount}</span></div>
+    <div><span class="${meta.decCount > 0 ? "ok" : "warn"}">${meta.decCount > 0 ? "\u2713" : "\u26A0"}</span><span>Architecture log ${meta.decCount} entries</span></div>
     <div><span class="${meta.stale === 0 ? "ok" : "bad"}">${meta.stale === 0 ? "\u2713" : "\u2717"}</span><span>Claims ${meta.stale > 0 ? meta.stale + " stale" : "healthy"}</span></div>
   </div></div>
   <div class="rn">auto-refresh 10s<br><span style="color:var(--br)">${esc(dbPath.split("/").slice(-3).join("/"))}</span></div>
@@ -1845,6 +1851,247 @@ async function dashboardCommand(options) {
   });
 }
 
+// src/commands/watch.ts
+import {
+  existsSync as existsSync6,
+  readdirSync as readdirSync2,
+  statSync,
+  writeFileSync as writeFileSync5,
+  readFileSync as readFileSync6,
+  mkdirSync as mkdirSync3,
+  watch as fsWatch
+} from "fs";
+import { join as join8, resolve as resolve2 } from "path";
+import { homedir as homedir3 } from "os";
+import { spawn } from "child_process";
+import chalk12 from "chalk";
+var DEBOUNCE_MS = 8e3;
+var DIR_POLL_MS = 5e3;
+function claudeEncode2(p) {
+  return p.replace(/[^a-zA-Z0-9]/g, "-");
+}
+function findTranscriptDir(projectPath) {
+  const projectsDir = join8(homedir3(), ".claude", "projects");
+  if (!existsSync6(projectsDir)) return null;
+  const projectKey = claudeEncode2(projectPath);
+  const direct = join8(projectsDir, projectKey);
+  if (existsSync6(direct)) return direct;
+  const projectName = projectPath.split("/").pop() ?? "";
+  const encodedName = claudeEncode2(projectName);
+  const dirs = readdirSync2(projectsDir);
+  for (const d of dirs) {
+    if (d.endsWith(`-${encodedName}`) || d.includes(encodedName)) {
+      return join8(projectsDir, d);
+    }
+  }
+  return null;
+}
+function fileSize(p) {
+  try {
+    return statSync(p).size;
+  } catch {
+    return 0;
+  }
+}
+function writePidFile(groundctlDir, pid) {
+  try {
+    mkdirSync3(groundctlDir, { recursive: true });
+    writeFileSync5(join8(groundctlDir, "watch.pid"), String(pid), "utf8");
+  } catch {
+  }
+}
+function readPidFile(groundctlDir) {
+  try {
+    const raw = readFileSync6(join8(groundctlDir, "watch.pid"), "utf8").trim();
+    return parseInt(raw) || null;
+  } catch {
+    return null;
+  }
+}
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function runIngest(transcriptPath, projectPath) {
+  const filename = transcriptPath.split("/").slice(-2).join("/");
+  console.log(
+    chalk12.gray(`
+  [${(/* @__PURE__ */ new Date()).toLocaleTimeString()}] `) + chalk12.cyan(`Transcript stable \u2192 ingesting ${filename}`)
+  );
+  try {
+    const parsed = parseTranscript(transcriptPath, "auto", projectPath);
+    const db = await openDb();
+    const sessionId = parsed.sessionId;
+    const exists = queryOne(db, "SELECT id FROM sessions WHERE id = ?", [sessionId]);
+    if (exists) {
+      db.run("UPDATE sessions SET ended_at = ?, summary = ? WHERE id = ?", [
+        parsed.endedAt,
+        parsed.summary,
+        sessionId
+      ]);
+    } else {
+      db.run(
+        "INSERT INTO sessions (id, agent, started_at, ended_at, summary) VALUES (?, ?, ?, ?, ?)",
+        [sessionId, "claude-code", parsed.startedAt, parsed.endedAt, parsed.summary]
+      );
+    }
+    let newFiles = 0;
+    for (const file of parsed.filesModified) {
+      const dup = queryOne(
+        db,
+        "SELECT id FROM files_modified WHERE session_id = ? AND path = ?",
+        [sessionId, file.path]
+      );
+      if (!dup) {
+        db.run(
+          "INSERT INTO files_modified (session_id, path, operation, lines_changed) VALUES (?, ?, ?, ?)",
+          [sessionId, file.path, file.operation, file.linesChanged]
+        );
+        newFiles++;
+      }
+    }
+    let newDecisions = 0;
+    for (const d of parsed.decisions) {
+      const dup = queryOne(
+        db,
+        "SELECT id FROM decisions WHERE session_id = ? AND description = ?",
+        [sessionId, d.description]
+      );
+      if (!dup) {
+        db.run(
+          "INSERT INTO decisions (session_id, description, rationale) VALUES (?, ?, ?)",
+          [sessionId, d.description, d.rationale ?? null]
+        );
+        newDecisions++;
+      }
+    }
+    saveDb();
+    closeDb();
+    const parts = [];
+    if (newFiles > 0) parts.push(`${newFiles} file${newFiles !== 1 ? "s" : ""}`);
+    if (parsed.commits.length > 0) parts.push(`${parsed.commits.length} commit${parsed.commits.length !== 1 ? "s" : ""}`);
+    if (newDecisions > 0) parts.push(`${newDecisions} decision${newDecisions !== 1 ? "s" : ""} captured`);
+    const summary = parts.length > 0 ? parts.join(", ") : "no new data";
+    console.log(chalk12.green(`  \u2713 Session ingested \u2014 ${summary}`));
+    await syncCommand({ silent: true });
+    console.log(chalk12.gray("  \u21B3 PROJECT_STATE.md + AGENTS.md updated"));
+  } catch (err) {
+    console.log(chalk12.red(`  \u2717 Ingest failed: ${err.message}`));
+  }
+}
+function startWatcher(transcriptDir, projectPath) {
+  const pending = /* @__PURE__ */ new Map();
+  const ingested = /* @__PURE__ */ new Set();
+  const fileWatchers = /* @__PURE__ */ new Map();
+  function schedule(filePath) {
+    if (ingested.has(filePath)) return;
+    const existing = pending.get(filePath);
+    if (existing) clearTimeout(existing);
+    const timer = setTimeout(async () => {
+      pending.delete(filePath);
+      if (ingested.has(filePath)) return;
+      if (fileSize(filePath) === 0) return;
+      ingested.add(filePath);
+      fileWatchers.get(filePath)?.close();
+      fileWatchers.delete(filePath);
+      await runIngest(filePath, projectPath);
+    }, DEBOUNCE_MS);
+    pending.set(filePath, timer);
+  }
+  function watchFile(filePath) {
+    if (fileWatchers.has(filePath) || ingested.has(filePath)) return;
+    try {
+      const w = fsWatch(filePath, () => {
+        schedule(filePath);
+      });
+      fileWatchers.set(filePath, w);
+    } catch {
+    }
+  }
+  if (existsSync6(transcriptDir)) {
+    for (const f of readdirSync2(transcriptDir)) {
+      if (f.endsWith(".jsonl")) {
+        ingested.add(join8(transcriptDir, f));
+      }
+    }
+  }
+  fsWatch(transcriptDir, (_event, filename) => {
+    if (!filename?.endsWith(".jsonl")) return;
+    const fp = join8(transcriptDir, filename);
+    if (!existsSync6(fp) || ingested.has(fp)) return;
+    if (!fileWatchers.has(fp)) {
+      watchFile(fp);
+      schedule(fp);
+    }
+  });
+  console.log(chalk12.bold("\n  groundctl watch") + chalk12.gray(" \u2014 auto-ingest on session end\n"));
+  console.log(
+    chalk12.gray("  Watching: ") + chalk12.blue(transcriptDir.replace(homedir3(), "~"))
+  );
+  console.log(chalk12.gray("  Stability threshold: ") + chalk12.white(`${DEBOUNCE_MS / 1e3}s`));
+  console.log(chalk12.gray("  Press Ctrl+C to stop.\n"));
+}
+async function watchCommand(options) {
+  const projectPath = options.projectPath ? resolve2(options.projectPath) : process.cwd();
+  if (options.daemon) {
+    const args = [process.argv[1], "watch", "--project-path", projectPath];
+    const child = spawn(process.execPath, args, {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.unref();
+    const groundctlDir2 = join8(projectPath, ".groundctl");
+    writePidFile(groundctlDir2, child.pid);
+    console.log(chalk12.green(`
+  \u2713 groundctl watch running in background (PID ${child.pid})`));
+    console.log(chalk12.gray(`  PID saved to .groundctl/watch.pid`));
+    console.log(chalk12.gray(`  To stop: kill ${child.pid}
+`));
+    process.exit(0);
+  }
+  const groundctlDir = join8(projectPath, ".groundctl");
+  const existingPid = readPidFile(groundctlDir);
+  if (existingPid && processAlive(existingPid)) {
+    console.log(chalk12.yellow(`
+  \u26A0  A watcher is already running (PID ${existingPid}).`));
+    console.log(chalk12.gray(`  To stop it: kill ${existingPid}
+`));
+    process.exit(1);
+  }
+  let transcriptDir = findTranscriptDir(projectPath);
+  if (!transcriptDir) {
+    console.log(chalk12.bold("\n  groundctl watch\n"));
+    console.log(
+      chalk12.yellow("  No Claude Code transcript directory found for this project yet.")
+    );
+    console.log(chalk12.gray("  Waiting for first session to start...\n"));
+    await new Promise((resolve3) => {
+      const interval = setInterval(() => {
+        const dir = findTranscriptDir(projectPath);
+        if (dir) {
+          clearInterval(interval);
+          transcriptDir = dir;
+          resolve3();
+        }
+      }, DIR_POLL_MS);
+    });
+  }
+  startWatcher(transcriptDir, projectPath);
+  await new Promise(() => {
+    process.on("SIGINT", () => {
+      console.log(chalk12.gray("\n  Watcher stopped.\n"));
+      process.exit(0);
+    });
+    process.on("SIGTERM", () => {
+      process.exit(0);
+    });
+  });
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
@@ -1870,4 +2117,10 @@ program.command("ingest").description("Parse a transcript and write session data
 program.command("report").description("Generate SESSION_REPORT.md from SQLite").option("-s, --session <id>", "Report for a specific session").option("--all", "Generate report for all sessions").action(reportCommand);
 program.command("health").description("Show product health score").action(healthCommand);
 program.command("dashboard").description("Start web dashboard on port 4242").option("-p, --port <port>", "Port number", "4242").action(dashboardCommand);
+program.command("watch").description("Watch for session end and auto-ingest transcripts").option("--daemon", "Run in background (detached process)").option("--project-path <path>", "Project path (defaults to cwd)").action(
+  (opts) => watchCommand({
+    daemon: opts.daemon,
+    projectPath: opts.projectPath
+  })
+);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundctl/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Product memory for AI agent builders",
   "license": "MIT",
   "bin": {