ikanban 0.5.0 → 0.5.1

package/README.md

@@ -31,7 +31,8 @@ exits 1 when the Roadmap differs. With no file it syncs every tracked plan file.
 
 `ikanban hooks install` adds a git `pre-push` hook (any git host, never blocks a push) and an
 agent hook for Claude Code, Gemini CLI and Copilot CLI (`.iKanban/hooks/roadmap-sync.js`).
-No CI is needed.
+No CI is needed. `--trace` also wires the kit's trace hook (`.iKanban/hooks/trace.js`) for the
+same agents; tracing stays off until `node .iKanban/hooks/trace.js --on`.
 
 ## Infrastructure scans
 

package/hooks/roadmap-sync.js

@@ -3,7 +3,8 @@
 // after each file write (Claude Code PostToolUse, Gemini CLI AfterTool, Copilot
 // CLI postToolUse; `npx ikanban hooks install` wires them). It reads the hook's
 // JSON on stdin, and only when the written file is a plan file (a JSON file with
-// a top-level "roadmap" block) it runs `ikanban roadmap sync <file>`.
+// a top-level "roadmap" block) it runs `ikanban roadmap sync <file>`. A written
+// <plan>.graph.json (the plan's diagram) syncs <plan>.json beside it.
 // It never blocks the agent: it always exits 0 and prints "{}" (the hook answer
 // every agent accepts); messages go to stderr.
 const fs = require("node:fs");
@@ -71,7 +72,9 @@ function main(input) {
   const root = repoRoot(cwd);
   if (!root) return;
   const args = event.tool_input || event.toolArgs || event.tool_args || {};
-  const plans = [...new Set(filePaths(args).map((p) => path.resolve(cwd, p)))].filter((f) => isPlan(f, root));
+  // IKA-2870 (plan 45 P7): a written <plan>.graph.json syncs <plan>.json beside it, which sends it.
+  const written = filePaths(args).map((p) => path.resolve(cwd, p).replace(/\.graph\.json$/, ".json"));
+  const plans = [...new Set(written)].filter((f) => isPlan(f, root));
   const [cmd, pre] = cliCommand();
   for (const plan of plans) {
     // An argument array and no shell: nothing from the hook input or the plan is

package/hooks/trace.js

@@ -294,6 +294,23 @@ async function record(cfg, cwd, session, e) {
 const MAX_PLAN = 256 * 1024;
 const planState = (key) => path.join(os.homedir(), ".ikanban", "plans", `${key}.sha256`);
 
+/** IKA-2854 (plan 45): the plan's diagram at docs/plans/<KEY>.graph.json, sent with the plan. Only a
+ *  regular file inside the repository, at most 256 KB, holding a JSON object; anything else is no
+ *  diagram (the server and the browser check it again). Returns [text, object] or []. */
+function readGraph(root, key) {
+  const file = path.join(root, "docs", "plans", `${key}.graph.json`);
+  try {
+    const st = fs.lstatSync(file);
+    if (!st.isFile() || st.size > MAX_PLAN) return [];
+    if (!fs.realpathSync(file).startsWith(fs.realpathSync(root) + path.sep)) return [];
+    const text = fs.readFileSync(file, "utf8");
+    const doc = JSON.parse(text);
+    return doc && typeof doc === "object" && !Array.isArray(doc) ? [text, doc] : [];
+  } catch {
+    return [];
+  }
+}
+
 /** IKA-2741 (plan 7 P6-T6): the task's plan, checked with the kit's own checker, goes to the Plan
  *  stage in Pipelines ("checked on laptop"). Only a regular file at docs/plans/<KEY>.json, and only
  *  when it changed since the last send. It is never a merge verdict: only the runner gives one. */
@@ -310,7 +327,9 @@ async function sendPlan(cfg, cwd, team, agent) {
   }
   if (!st.isFile() || st.size > MAX_PLAN) return;
   const text = fs.readFileSync(file, "utf8");
-  const sha = require("node:crypto").createHash("sha256").update(text).digest("hex");
+  const [graphText = "", graph] = readGraph(root, key);
+  // The diagram is in the checksum, so a changed diagram alone is sent too.
+  const sha = require("node:crypto").createHash("sha256").update(text).update("\0").update(graphText).digest("hex");
   try {
     if (fs.readFileSync(planState(key), "utf8") === sha) return;
   } catch {
@@ -327,7 +346,7 @@ async function sendPlan(cfg, cwd, team, agent) {
   const first = errors[0];
   const detail = first ? `${first.where}: ${first.problem}`.replace(/\s+/g, " ").slice(0, 300) : undefined;
   await api(cfg, `/api/teams/${team}/laptop-plans`, { task: key, agent, status: errors.length ? "failed" : "passed", detail, plan: plan.phases,
-    decisions: Array.isArray(plan.decisions) ? plan.decisions : undefined });
+    decisions: Array.isArray(plan.decisions) ? plan.decisions : undefined, graph });
   fs.mkdirSync(path.dirname(planState(key)), { recursive: true, mode: 0o700 });
   fs.writeFileSync(planState(key), sha, { mode: 0o600 });
 }

package/lib/plancheck.js

@@ -155,12 +155,22 @@ async function serverGaps(file, plan, opts, stages = ["before_done"]) {
   const { connection } = require("./roadmap.js");
   const { ikanbanFetch } = safe();
   const c = connection({ token: opts.token, "base-url": opts["base-url"] }, file);
-  const team = opts.team || c.team || (plan.roadmap && plan.roadmap.team) || "";
+  // IKA-2839: --team, then the plan's own team, then the settings team (another team's plan
+  // was read from the settings team and refused with a 404).
+  let team = String(opts.team || (plan.roadmap && plan.roadmap.team) || c.team || "");
   const task = String(opts.task);
   if (!c.token) return [{ where: task, problem: "no API key to read its critic gaps", fix: "set VIBE_API_TOKEN, pass --token, or set api_key in .iKanban/settings-local.json" }];
-  if (!/^[0-9a-f-]{36}$/i.test(team)) return [{ where: task, problem: `team "${team}" is not a team id`, fix: "pass --team <team id> or set team in .iKanban/settings-local.json" }];
   let res;
   try {
+    // The route takes only a team id: an identifier such as "TUT" is looked up among the key's teams.
+    if (team && !/^[0-9a-f-]{36}$/i.test(team)) {
+      const t = await ikanbanFetch("/api/teams", { base: c.base, token: c.token });
+      const body = await t.json().catch(() => ({}));
+      const hit = t.ok && Array.isArray(body.data) && body.data.find((x) => String(x.identifier || "").toLowerCase() === team.toLowerCase());
+      if (!hit) return [{ where: task, problem: `team "${team}" not found among your teams${t.ok ? "" : ` (HTTP ${t.status})`}`, fix: "set roadmap.team to a team identifier or id the key's account is in, or pass --team <team id>" }];
+      team = hit.id;
+    }
+    if (!/^[0-9a-f-]{36}$/i.test(team)) return [{ where: task, problem: `team "${team}" is not a team id`, fix: "pass --team <team id> or set team in .iKanban/settings-local.json" }];
     res = await ikanbanFetch(`/api/teams/${team}/tasks/${encodeURIComponent(task)}/critic-reviews`, { base: c.base, token: c.token });
   } catch (e) {
     return [{ where: task, problem: `critic gaps not read: ${e.message}`, fix: "check the network and the API address, then run the check again" }];

package/lib/roadmap.js

@@ -74,6 +74,17 @@ function toDocument(plan) {
   };
 }
 
+/** IKA-2870 (plan 45 P7): <name>.graph.json beside the plan, one view per phase. Only a regular file
+ *  of at most 256 KB holding a JSON object; else no diagram, never a failed sync (the server checks). */
+function readGraph(file) {
+  const g = file.replace(/\.json$/i, "") + ".graph.json";
+  try {
+    const st = fs.lstatSync(g);
+    const doc = st.isFile() && st.size <= 256 * 1024 ? JSON.parse(fs.readFileSync(g, "utf8")) : null;
+    return doc && typeof doc === "object" && !Array.isArray(doc) ? doc : undefined;
+  } catch { return undefined; }
+}
+
 /** .iKanban/settings-local.json (or the older .i-kanban/) nearest to `dir`. */
 function localSettings(dir) {
   for (let d = path.resolve(dir); ; d = path.dirname(d)) {
@@ -125,6 +136,7 @@ async function syncFile(file, opts) {
   const doc = toDocument(plan);
   doc.project = doc.project || c.project;
   doc.dry_run = Boolean(opts.check || opts["dry-run"]);
+  doc.graph = readGraph(file) ?? null; // null clears a diagram the file no longer has
   // Deleting an empty phase the sync created needs an explicit flag; MCP never deletes.
   if (opts["allow-delete"]) doc.allow_delete = true;
   let res;
@@ -199,6 +211,49 @@ function addHook(settings, event, entry, script = "roadmap-sync.js") {
   return settings;
 }
 
+// Plan 43 P4-T2: `--trace` also wires the trace hook, exactly as .iKanban/README.md shows it.
+// Wiring only: the hook does nothing until `node .iKanban/hooks/trace.js --on`.
+const TRACE = "node .iKanban/hooks/trace.js";
+const CLAUDE_TRACE = 'node "$CLAUDE_PROJECT_DIR/.iKanban/hooks/trace.js"';
+const TRACE_AGENTS = {
+  claude: (root) => {
+    mergeJson(path.join(root, ".claude", "settings.json"), (s) => {
+      addHook(s, "PostToolUse", { hooks: [{ type: "command", command: CLAUDE_TRACE, async: true }] }, "trace.js");
+      addHook(s, "PostToolUseFailure", { hooks: [{ type: "command", command: CLAUDE_TRACE, async: true }] }, "trace.js");
+      // Stop in the foreground: a background Stop hook is stopped when Claude Code exits (README).
+      return addHook(s, "Stop", { hooks: [{ type: "command", command: CLAUDE_TRACE }] }, "trace.js");
+    });
+    return ".claude/settings.json trace (PostToolUse, PostToolUseFailure, Stop)";
+  },
+  gemini: (root) => {
+    mergeJson(path.join(root, ".gemini", "settings.json"), (s) => {
+      addHook(s, "AfterTool", { matcher: "*", hooks: [{ name: "ikanban-trace", type: "command", command: TRACE, timeout: 10000 }] }, "trace.js");
+      return addHook(s, "AfterAgent", { hooks: [{ name: "ikanban-trace", type: "command", command: TRACE, timeout: 10000 }] }, "trace.js");
+    });
+    return ".gemini/settings.json trace (AfterTool, AfterAgent)";
+  },
+  copilot: (root) => {
+    mergeJson(path.join(root, ".github", "hooks", "ikanban-trace.json"), (s) => {
+      s.version = 1;
+      for (const event of ["postToolUse", "postToolUseFailure", "agentStop"]) {
+        addHook(s, event, { type: "command", bash: `${TRACE} copilot:${event}`, cwd: ".", timeoutSec: 10 }, "trace.js");
+      }
+      return s;
+    });
+    return ".github/hooks/ikanban-trace.json (postToolUse, postToolUseFailure, agentStop)";
+  },
+  agy: (root) => {
+    mergeJson(path.join(root, ".agents", "hooks.json"), (s) => {
+      s["ikanban-trace"] = {
+        PostToolUse: [{ matcher: ".*", hooks: [{ type: "command", command: "node ../.iKanban/hooks/trace.js agy:PostToolUse", timeout: 10 }] }],
+        Stop: [{ type: "command", command: "node ../.iKanban/hooks/trace.js agy:Stop", timeout: 10 }],
+      };
+      return s;
+    });
+    return ".agents/hooks.json trace (PostToolUse, Stop)";
+  },
+};
+
 const AGENTS = {
   claude: (root) => {
     mergeJson(path.join(root, ".claude", "settings.json"), (s) => {
@@ -251,7 +306,7 @@ function installHooks(opts) {
   const script = path.join(root, ".iKanban", "hooks", "roadmap-sync.js");
   fs.mkdirSync(path.dirname(script), { recursive: true });
   // The hook runs its commands through ikanban-safe.js, so both files go together.
-  for (const name of ["roadmap-sync.js", "deploy-check.js", "ikanban-safe.js", "plan-gate.js"]) {
+  for (const name of ["roadmap-sync.js", "deploy-check.js", "ikanban-safe.js", "plan-gate.js", ...(opts.trace ? ["trace.js"] : [])]) {
     fs.copyFileSync(path.join(__dirname, "..", "hooks", name), path.join(path.dirname(script), name));
     done.push(`.iKanban/hooks/${name}`);
   }
@@ -276,11 +331,14 @@ function installHooks(opts) {
   for (const a of wanted) {
     if (!AGENTS[a]) throw new Error(`unknown agent "${a}" (claude, gemini, copilot, agy)`);
     done.push(AGENTS[a](root));
+    if (opts.trace) done.push(TRACE_AGENTS[a](root));
   }
   for (const d of done) console.log(`  installed: ${d}`);
   console.log("Plan files (JSON with a top-level \"roadmap\" block) now reach the Roadmap on every agent write and every git push.");
   console.log("Before an edit or a writing shell command, the plan gate needs the task's plan, docs/plans/<TASK-KEY>.json (the key from the branch name), to pass: node .iKanban/hooks/plan-gate.js check docs/plans/<TASK-KEY>.json. How to write one: .iKanban/prompts/feature-plan.md.");
   console.log("After a deploy, the deploy check reads your site's build marker; name your deploy commands in .iKanban/settings-local.json \"deploy_check\" (README).");
+  if (opts.trace && wanted.length) console.log("The trace hook is wired but still off. Turn it on in this repository with: node .iKanban/hooks/trace.js --on");
+  else if (opts.trace) console.log("Trace hook not wired: no agent folder found (looked for .claude, .gemini, .github, .agents). Create the agent's folder, or name it: ikanban hooks install --trace --agent claude");
   // IKA-2244: the sync's default server is prod; say which one this repository will use.
   const base = connection({}, path.join(root, "plan.json")).base;
   console.log(`  server: ${base} (set api_url in .iKanban/settings-local.json, or IKANBAN_BASE_URL, to use another)`);
@@ -292,9 +350,11 @@ const HELP = `Usage:
       Make each plan's Roadmap match the file. No file: every tracked JSON file
       with a top-level "roadmap" block. --check: change nothing, exit 1 on drift.
       --allow-delete: also delete an emptied phase the sync created (else it stays).
-  ikanban hooks install [--agent claude,gemini,copilot]
+  ikanban hooks install [--agent claude,gemini,copilot,agy] [--trace]
       Keep the Roadmap in step without CI: a git pre-push hook (any git host) and
-      a hook for each agent whose folder exists (.claude, .gemini, .github).
+      a hook for each agent whose folder exists (.claude, .gemini, .github, .agents).
+      --trace: also wire .iKanban/hooks/trace.js for those agents. Tracing stays
+      off until: node .iKanban/hooks/trace.js --on
 
 Key: VIBE_API_TOKEN, --token, or api_key in .iKanban/settings-local.json.
 Server: IKANBAN_BASE_URL, --base-url, or api_url there (default https://api.i-kanban.com).`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ikanban",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "iKanban CLI: AI and security scans of your own repo; findings filed into iKanban, reports kept encrypted on your machine",
   "bin": { "ikanban": "bin/ikanban.js" },
   "files": ["bin", "lib", "hooks", "scanners", "README.md", "LICENSE.md"],