@cubedot/cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,1171 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import { fileURLToPath as fileURLToPath4 } from "url";
+import { dirname as dirname4, join as join9 } from "path";
+import { readFileSync as readFileSync9 } from "fs";
+
+// src/commands/init.ts
+import pc from "picocolors";
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join3 } from "path";
+
+// src/mcp.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+var REQUIRED_TOOLS = [
+  "orient",
+  "get",
+  "tree",
+  "recall",
+  "fetch",
+  "get_document",
+  "list_work"
+];
+function buildConnectUrl(mcpUrl, projectId) {
+  const u = new URL(mcpUrl);
+  const pathname = u.pathname.replace(/\/+$/, "");
+  return `${u.origin}${pathname}?project=${encodeURIComponent(projectId)}`;
+}
+function categorizeError(err) {
+  if (err === null || err === void 0) return "Unknown error";
+  const e = err;
+  const status = e["response"]?.status ?? e["status"] ?? e["statusCode"];
+  const code = e["code"] ?? e["cause"]?.["code"];
+  const name = err.name;
+  if (status === 400) return "Bad request (400): invalid project ID or API key format.";
+  if (status === 401) return "Authentication failed (401): check your API key.";
+  if (status === 404)
+    return "Project not found (404): check your project ID and MCP URL.";
+  if (code === "ECONNREFUSED" || code === "ENOTFOUND")
+    return `Connection refused: check the MCP URL (${err.message ?? ""}).`;
+  if (name === "TimeoutError" || name === "AbortError")
+    return "Connection timed out: check the URL and network.";
+  return `Connection failed: ${err.message ?? String(err)}`;
+}
+async function createMcpClient(connectUrl, key, timeoutMs = 3e4) {
+  const client = new Client({ name: "cubedot-cli", version: "0.1.0" });
+  const signal = AbortSignal.timeout(timeoutMs);
+  const transport = new StreamableHTTPClientTransport(new URL(connectUrl), {
+    requestInit: {
+      headers: { "x-api-key": key },
+      signal
+    }
+  });
+  await client.connect(transport);
+  return client;
+}
+async function validateTools(client) {
+  const result = await client.listTools();
+  if (!Array.isArray(result.tools)) {
+    throw new Error(
+      "Invalid response from MCP server: tools list is not an array."
+    );
+  }
+  const names = result.tools.map((t) => t.name);
+  const missing = REQUIRED_TOOLS.filter((n) => !names.includes(n));
+  if (missing.length > 0) {
+    throw new Error(
+      `MCP server is missing required tools: ${missing.join(", ")}`
+    );
+  }
+  return names;
+}
+async function callTool(client, name, args = {}) {
+  const result = await client.callTool({ name, arguments: args });
+  if (!result?.content || !Array.isArray(result.content)) return "";
+  return result.content.filter((c) => c.type === "text").map((c) => String(c.text ?? "")).join("\n");
+}
+
+// src/scaffold.ts
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function getAssetPath(name) {
+  return fileURLToPath(new URL(`../cli-assets/${name}`, import.meta.url));
+}
+function writeMcpJson(cwd, mcpUrl, projectId, key) {
+  const path = join(cwd, ".mcp.json");
+  let existing = {};
+  if (existsSync(path)) {
+    try {
+      existing = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+    }
+  }
+  const config = {
+    ...existing,
+    mcpServers: {
+      ...existing.mcpServers ?? {},
+      cubedot: {
+        type: "http",
+        url: `${mcpUrl}?project=${encodeURIComponent(projectId)}`,
+        headers: { "x-api-key": key }
+      }
+    }
+  };
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+function readCubedotConfig(cwd) {
+  const path = join(cwd, ".cubedot", "config.json");
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeCubedotConfig(cwd, config) {
+  const dir = join(cwd, ".cubedot");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, "config.json"),
+    JSON.stringify(config, null, 2) + "\n",
+    "utf8"
+  );
+}
+function installAgentAssets(cwd) {
+  const agentsDir = join(cwd, ".claude", "agents");
+  if (!existsSync(agentsDir)) mkdirSync(agentsDir, { recursive: true });
+  copyFileSync(
+    getAssetPath("CubedotVerifier.md"),
+    join(agentsDir, "CubedotVerifier.md")
+  );
+  const cubedotDir = join(cwd, ".cubedot");
+  if (!existsSync(cubedotDir)) mkdirSync(cubedotDir, { recursive: true });
+  copyFileSync(
+    getAssetPath("fia-operating-manual.md"),
+    join(cubedotDir, "fia-operating-manual.md")
+  );
+}
+function scaffoldCubedotDirs(cwd) {
+  const progress = join(cwd, ".cubedot", "progress");
+  const reports = join(cwd, ".cubedot", "reports");
+  const docs = join(cwd, ".cubedot", "docs");
+  const sync = join(cwd, ".cubedot", "sync");
+  for (const dir of [progress, reports, docs, sync]) {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  }
+  const fieldNotes = join(cwd, ".cubedot", "field-notes.md");
+  if (!existsSync(fieldNotes)) {
+    writeFileSync(
+      fieldNotes,
+      "# Field Notes\n\nAppend-only log of spec gaps, inferred assumptions, and approved overrides.\n",
+      "utf8"
+    );
+  }
+  const linksJson = join(cwd, ".cubedot", "links.json");
+  if (!existsSync(linksJson)) {
+    writeFileSync(linksJson, "{}\n", "utf8");
+  }
+}
+var GITIGNORE_ENTRIES = [
+  ".mcp.json",
+  ".cubedot/config.json",
+  ".cubedot/docs/",
+  ".cubedot/sync/"
+];
+function updateGitignore(cwd) {
+  const path = join(cwd, ".gitignore");
+  let content = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const lines = content.split("\n");
+  let changed = false;
+  for (const entry of GITIGNORE_ENTRIES) {
+    if (!lines.some((l) => l.trim() === entry)) {
+      content = content.endsWith("\n") ? content + entry + "\n" : content + "\n" + entry + "\n";
+      changed = true;
+    }
+  }
+  if (changed) {
+    writeFileSync(path, content, "utf8");
+  }
+}
+function readHashes(cwd) {
+  const path = join(cwd, ".cubedot", "sync", "hashes.json");
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeHashes(cwd, hashes) {
+  const dir = join(cwd, ".cubedot", "sync");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "hashes.json"), JSON.stringify(hashes, null, 2) + "\n", "utf8");
+}
+function readLinks(cwd) {
+  const path = join(cwd, ".cubedot", "links.json");
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+// src/hotmemory.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2 } from "path";
+var START = (name) => `<!-- CUBEDOT:START:${name} -->`;
+var END = (name) => `<!-- CUBEDOT:END:${name} -->`;
+function hasAllMarkers(content) {
+  for (const name of ["IDENTITY", "CONVENTIONS", "REGISTRY"]) {
+    const s = content.indexOf(START(name));
+    const e = content.indexOf(END(name));
+    if (s === -1 || e === -1 || e <= s) return false;
+  }
+  return true;
+}
+function replaceBlock(text, name, newContent) {
+  const s = START(name);
+  const e = END(name);
+  const si = text.indexOf(s);
+  const ei = text.indexOf(e);
+  if (si === -1 || ei === -1 || ei <= si) return text;
+  return text.slice(0, si + s.length) + "\n" + newContent.trimEnd() + "\n" + text.slice(ei);
+}
+function updateMarkers(content, identity, conventions, registry) {
+  let out = content;
+  out = replaceBlock(out, "IDENTITY", identity);
+  out = replaceBlock(out, "CONVENTIONS", conventions);
+  out = replaceBlock(out, "REGISTRY", registry);
+  return out;
+}
+function parseIdentity(orientText) {
+  const lines = orientText.split("\n").filter((l) => l.trim() !== "");
+  if (lines.length === 0) return "Project: (unknown \u2014 run `orient` to populate)";
+  const head = lines[0].replace(/^#+\s*/, "");
+  const rest = lines.slice(1, 8);
+  return [head, ...rest].join("\n");
+}
+function parseRegistry(treeText) {
+  if (!treeText.trim() || treeText.startsWith("No features")) {
+    return "No features with codes yet \u2014 commit M02, then `cubedot sync` to populate the registry.";
+  }
+  const lines = treeText.split("\n");
+  const kept = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const indent = line.length - line.trimStart().length;
+    if (indent === 0 || indent === 2) {
+      kept.push(line);
+    }
+  }
+  return kept.length > 0 ? kept.join("\n") : "No features with codes yet \u2014 commit M02, then `cubedot sync` to populate the registry.";
+}
+function extractFnCodes(treeText) {
+  const codes = /* @__PURE__ */ new Set();
+  const fnPattern = /^\s{2}(FN-\d+-\d+)/;
+  for (const line of treeText.split("\n")) {
+    const m = fnPattern.exec(line);
+    if (m) codes.add(m[1]);
+  }
+  return codes;
+}
+function parseRegistryBlock(content) {
+  const map = /* @__PURE__ */ new Map();
+  const s = START("REGISTRY");
+  const e = END("REGISTRY");
+  const si = content.indexOf(s);
+  const ei = content.indexOf(e);
+  if (si === -1 || ei === -1) return map;
+  const block = content.slice(si + s.length, ei);
+  const fnLine = /^\s{2}(FN-\d+-\d+):\s*(.+)$/;
+  for (const line of block.split("\n")) {
+    const m = fnLine.exec(line);
+    if (m) map.set(m[1], m[2].trim());
+  }
+  return map;
+}
+function parseConventions(techStackText) {
+  if (!techStackText || !techStackText.trim()) {
+    return "Tech stack not yet defined. Run `cubedot sync` after populating tech-stack in CubeDot.";
+  }
+  const stripped = techStackText.replace(/^#\s+Tech Stack\s*\n?/, "").trim();
+  if (!stripped) return "Tech stack defined but empty \u2014 check CubeDot.";
+  return stripped;
+}
+function generateMemoryFiles(cwd, identity, conventions, registry) {
+  const templatePath = getAssetPath("CLAUDE.md");
+  const template = readFileSync2(templatePath, "utf8");
+  const filled = updateMarkers(template, identity, conventions, registry);
+  writeFileSync2(join2(cwd, "AGENTS.md"), filled, "utf8");
+  const claudePath = join2(cwd, "CLAUDE.md");
+  if (!existsSync2(claudePath)) {
+    writeFileSync2(claudePath, filled, "utf8");
+  } else {
+    const existing = readFileSync2(claudePath, "utf8");
+    if (hasAllMarkers(existing)) {
+      writeFileSync2(
+        claudePath,
+        updateMarkers(existing, identity, conventions, registry),
+        "utf8"
+      );
+    } else {
+      console.warn(
+        "[cubedot] CLAUDE.md exists but has no CUBEDOT markers \u2014 inserting generated blocks."
+      );
+      const h1Match = /^(#\s+[^\n]+\n)/m.exec(existing);
+      const insertAfter = h1Match ? h1Match.index + h1Match[0].length : 0;
+      const markerBlocks = extractMarkerBlocks(filled);
+      const updated = existing.slice(0, insertAfter) + "\n" + markerBlocks + "\n" + existing.slice(insertAfter);
+      writeFileSync2(claudePath, updated, "utf8");
+    }
+  }
+}
+function extractMarkerBlocks(filled) {
+  const blocks = [];
+  for (const name of ["IDENTITY", "CONVENTIONS", "REGISTRY"]) {
+    const s = filled.indexOf(START(name));
+    const e = filled.indexOf(END(name));
+    if (s !== -1 && e !== -1 && e > s) {
+      blocks.push(filled.slice(s, e + END(name).length));
+    }
+  }
+  return blocks.join("\n\n");
+}
+
+// src/commands/init.ts
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname as dirname2 } from "path";
+var __filename = fileURLToPath2(import.meta.url);
+var __dirname2 = dirname2(__filename);
+var pkg = JSON.parse(
+  readFileSync3(join3(__dirname2, "../package.json"), "utf8")
+);
+function decodeToken(token) {
+  let json;
+  try {
+    const b64 = token.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+    json = Buffer.from(padded, "base64").toString("utf8");
+  } catch {
+    throw new Error("Invalid connect token: cannot decode base64url.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw new Error("Invalid connect token: decoded value is not valid JSON.");
+  }
+  const t = parsed;
+  if (t["v"] !== 1) {
+    throw new Error(
+      `Unsupported connect token version: ${t["v"]}. Expected v:1. The web page that generated this token must emit {v:1, projectId, key, mcpUrl}.`
+    );
+  }
+  if (!t["projectId"] || !t["key"] || !t["mcpUrl"]) {
+    throw new Error(
+      "Invalid connect token: missing required fields (projectId, key, mcpUrl)."
+    );
+  }
+  return {
+    v: 1,
+    projectId: String(t["projectId"]),
+    key: String(t["key"]),
+    mcpUrl: String(t["mcpUrl"])
+  };
+}
+async function initCommand(opts) {
+  const cwd = process.cwd();
+  let projectId;
+  let key;
+  let mcpUrl;
+  if (opts.token) {
+    const t = decodeToken(opts.token);
+    projectId = t.projectId;
+    key = t.key;
+    mcpUrl = t.mcpUrl;
+  } else if (opts.project && opts.key && opts.url) {
+    projectId = opts.project;
+    key = opts.key;
+    mcpUrl = opts.url;
+  } else if (opts.project || opts.key || opts.url) {
+    console.error(
+      pc.red(
+        "Error: --project, --key, and --url must all be provided together."
+      )
+    );
+    process.exit(1);
+  } else {
+    if (!process.stdin.isTTY) {
+      console.error(
+        pc.red(
+          "Non-interactive shell: pass --token or --project/--key/--url."
+        )
+      );
+      process.exit(1);
+    }
+    console.log(
+      pc.yellow(
+        "\u26A0  The connect token contains your API key \u2014 treat it like a password."
+      )
+    );
+    const { default: input } = await import("@inquirer/input");
+    const raw = await input({
+      message: "Paste your connect token (from the CubeDot web UI):"
+    });
+    const t = decodeToken(raw.trim());
+    projectId = t.projectId;
+    key = t.key;
+    mcpUrl = t.mcpUrl;
+  }
+  if (opts.token || !opts.project) {
+    if (!process.stdin.isTTY && opts.token) {
+      console.warn(
+        pc.yellow(
+          "\u26A0  --token contains your API key \u2014 store it in a secret, not in shell history."
+        )
+      );
+    }
+  }
+  const connectUrl = buildConnectUrl(mcpUrl, projectId);
+  console.log(pc.dim(`Connecting to ${connectUrl} \u2026`));
+  let client;
+  try {
+    client = await createMcpClient(connectUrl, key);
+  } catch (err) {
+    console.error(pc.red(`Error: ${categorizeError(err)}`));
+    process.exit(1);
+  }
+  try {
+    await validateTools(client);
+  } catch (err) {
+    await client.close();
+    console.error(pc.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+  let orientText = "";
+  let treeText = "";
+  let techStackText = null;
+  try {
+    orientText = await callTool(client, "orient");
+    treeText = await callTool(client, "tree");
+    try {
+      techStackText = await callTool(client, "get_document", {
+        name: "tech-stack"
+      });
+    } catch {
+    }
+  } catch (err) {
+    await client.close();
+    console.error(
+      pc.red(`Error fetching project data: ${err.message}`)
+    );
+    process.exit(1);
+  } finally {
+    await client.close();
+  }
+  writeMcpJson(cwd, mcpUrl, projectId, key);
+  writeCubedotConfig(cwd, {
+    projectId,
+    mcpUrl,
+    lastSynced: (/* @__PURE__ */ new Date()).toISOString(),
+    cliVersion: pkg.version
+  });
+  const identity = parseIdentity(orientText);
+  const conventions = parseConventions(techStackText);
+  const registry = parseRegistry(treeText);
+  generateMemoryFiles(cwd, identity, conventions, registry);
+  installAgentAssets(cwd);
+  scaffoldCubedotDirs(cwd);
+  updateGitignore(cwd);
+  const projectName = orientText.split("\n").find((l) => l.trim())?.replace(/^#+\s*/, "") ?? projectId;
+  console.log("\n" + pc.green("\u2713") + " Cubedot connected: " + pc.bold(projectName));
+  console.log(pc.dim(`  Project ID : ${projectId}`));
+  console.log(pc.dim(`  MCP URL    : ${mcpUrl}`));
+  console.log(
+    pc.dim(`  Tools      : ${REQUIRED_TOOLS.join(", ")}`)
+  );
+  console.log("\nFiles written:");
+  const written = [
+    ".mcp.json (gitignored \u2014 holds your key)",
+    ".cubedot/config.json (gitignored)",
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".claude/agents/CubedotVerifier.md",
+    ".cubedot/fia-operating-manual.md",
+    ".cubedot/progress/  (empty, commit-tracked)",
+    ".cubedot/reports/   (commit-tracked)",
+    ".cubedot/field-notes.md (commit-tracked)",
+    ".gitignore (updated)"
+  ];
+  for (const f of written) console.log("  " + pc.dim(f));
+  console.log("\nOpen Claude Code in this directory to start building. \u2728");
+}
+
+// src/commands/sync.ts
+import pc2 from "picocolors";
+import { createHash } from "crypto";
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
+import { join as join5 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import { dirname as dirname3 } from "path";
+
+// src/ledger.ts
+import {
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync4,
+  readdirSync,
+  renameSync,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { join as join4 } from "path";
+import { randomUUID } from "crypto";
+var FN_CODE_REGEX = /^FN-\d{3}-\d{2,}$/;
+function validateFnCode(code) {
+  if (!FN_CODE_REGEX.test(code)) {
+    throw new Error(
+      `Invalid FN code: "${code}". Expected format: FN-NNN-NN (e.g. FN-001-02).`
+    );
+  }
+}
+function getLedgerPath(cwd, code) {
+  return join4(cwd, ".cubedot", "progress", `${code}.json`);
+}
+function readLedger(cwd, code) {
+  const path = getLedgerPath(cwd, code);
+  if (!existsSync4(path)) return null;
+  try {
+    return JSON.parse(readFileSync4(path, "utf8"));
+  } catch {
+    throw new Error(
+      `Failed to read ledger for ${code}: file exists but contains malformed JSON.`
+    );
+  }
+}
+function readAllLedgers(cwd) {
+  const dir = join4(cwd, ".cubedot", "progress");
+  if (!existsSync4(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => {
+    try {
+      return JSON.parse(readFileSync4(join4(dir, f), "utf8"));
+    } catch {
+      return null;
+    }
+  }).filter((r) => r !== null);
+}
+function writeLedger(cwd, record) {
+  const path = getLedgerPath(cwd, record.code);
+  const dir = join4(cwd, ".cubedot", "progress");
+  if (!existsSync4(dir)) mkdirSync2(dir, { recursive: true });
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  writeFileSync3(tmp, JSON.stringify(record, null, 2) + "\n", "utf8");
+  renameSync(tmp, path);
+}
+function writeLedgerFlags(cwd, code, flags) {
+  const record = readLedger(cwd, code);
+  if (!record) return;
+  writeLedger(cwd, { ...record, flags, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+}
+function startFn(cwd, code, actor = "agent") {
+  validateFnCode(code);
+  const existing = readLedger(cwd, code);
+  if (existing) {
+    throw new Error(
+      `Cannot start ${code}: already in state "${existing.state}". Use 'cubedot complete ${code}' or 'cubedot done ${code}' to advance.`
+    );
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const record = {
+    code,
+    state: "in_progress",
+    flags: [],
+    actor,
+    history: [{ state: "in_progress", actor, at: now }],
+    overrides: [],
+    discrepancies: [],
+    reportPath: `.cubedot/reports/${code}.md`,
+    updatedAt: now
+  };
+  writeLedger(cwd, record);
+  return record;
+}
+function completeFn(cwd, code, actor = "agent") {
+  validateFnCode(code);
+  const existing = readLedger(cwd, code);
+  if (!existing) {
+    throw new Error(
+      `Cannot complete ${code}: no ledger entry found. Run 'cubedot start ${code}' first.`
+    );
+  }
+  if (existing.state !== "in_progress") {
+    throw new Error(
+      `Cannot complete ${code}: current state is "${existing.state}", expected "in_progress".`
+    );
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const record = {
+    ...existing,
+    state: "code-complete",
+    actor,
+    history: [...existing.history, { state: "code-complete", actor, at: now }],
+    updatedAt: now
+  };
+  writeLedger(cwd, record);
+  return record;
+}
+function doneFn(cwd, code, actor = "human", force = false, discrepancies = []) {
+  validateFnCode(code);
+  const existing = readLedger(cwd, code);
+  if (!existing) {
+    throw new Error(`Cannot mark ${code} done: no ledger entry found.`);
+  }
+  if (existing.state === "done") {
+    throw new Error(`${code} is already done.`);
+  }
+  if (existing.state === "in_progress" && !force) {
+    throw new Error(
+      `Cannot mark ${code} done: current state is "in_progress", not "code-complete". Use --force to override (a discrepancy will be recorded).`
+    );
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const forcedOverride = force && existing.state === "in_progress" ? [
+    ...existing.overrides,
+    { condition: "done from in_progress", approvedBy: actor, at: now }
+  ] : existing.overrides;
+  const record = {
+    ...existing,
+    state: "done",
+    actor,
+    history: [...existing.history, { state: "done", actor, at: now }],
+    overrides: forcedOverride,
+    discrepancies: [...existing.discrepancies, ...discrepancies],
+    updatedAt: now
+  };
+  writeLedger(cwd, record);
+  return record;
+}
+
+// src/commands/sync.ts
+var __filename2 = fileURLToPath3(import.meta.url);
+var __dirname3 = dirname3(__filename2);
+var pkg2 = JSON.parse(
+  readFileSync5(join5(__dirname3, "../package.json"), "utf8")
+);
+function fileHash(filePath) {
+  if (!existsSync5(filePath)) return "";
+  try {
+    return createHash("sha256").update(readFileSync5(filePath)).digest("hex");
+  } catch {
+    return "";
+  }
+}
+async function syncCommand() {
+  const cwd = process.cwd();
+  const config = readCubedotConfig(cwd);
+  if (!config) {
+    console.error(
+      pc2.red(
+        "Error: .cubedot/config.json not found. Run `cubedot init` first."
+      )
+    );
+    process.exit(1);
+  }
+  const STALE_DAYS = 3;
+  if (config.lastSynced) {
+    const ageDays = (Date.now() - new Date(config.lastSynced).getTime()) / 864e5;
+    if (ageDays >= STALE_DAYS) {
+      console.log(
+        pc2.yellow(
+          `\u26A0  Last synced ${Math.floor(ageDays)} day(s) ago \u2014 refreshing now.`
+        )
+      );
+    }
+  }
+  const connectUrl = buildConnectUrl(config.mcpUrl, config.projectId);
+  console.log(pc2.dim(`Connecting to ${connectUrl} \u2026`));
+  let client;
+  try {
+    client = await createMcpClient(connectUrl, await readKeyFromMcpJson(cwd));
+  } catch (err) {
+    console.error(pc2.red(`Error: ${categorizeError(err)}`));
+    process.exit(1);
+  }
+  try {
+    await validateTools(client);
+  } catch (err) {
+    await client.close();
+    console.error(pc2.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+  let orientText = "";
+  let treeText = "";
+  let techStackText = null;
+  try {
+    orientText = await callTool(client, "orient");
+    treeText = await callTool(client, "tree");
+    try {
+      techStackText = await callTool(client, "get_document", {
+        name: "tech-stack"
+      });
+    } catch {
+    }
+  } catch (err) {
+    await client.close();
+    console.error(
+      pc2.red(`Error fetching project data: ${err.message}`)
+    );
+    process.exit(1);
+  } finally {
+    await client.close();
+  }
+  generateMemoryFiles(
+    cwd,
+    parseIdentity(orientText),
+    parseConventions(techStackText),
+    parseRegistry(treeText)
+  );
+  writeCubedotConfig(cwd, {
+    ...config,
+    lastSynced: (/* @__PURE__ */ new Date()).toISOString(),
+    cliVersion: pkg2.version
+  });
+  const specFnCodes = extractFnCodes(treeText);
+  const ledgers = readAllLedgers(cwd);
+  const prevHashes = readHashes(cwd);
+  const nextHashes = { ...prevHashes };
+  const links = readLinks(cwd);
+  const orphaned = [];
+  const needsReverification = [];
+  const skipOrphanDetection = specFnCodes.size === 0 && ledgers.length > 0;
+  if (skipOrphanDetection) {
+    console.log(
+      pc2.yellow(
+        "\u26A0  Spec tree returned no functionalities \u2014 skipping orphan detection this sync."
+      )
+    );
+  }
+  for (const record of ledgers) {
+    if (record.flags.includes("orphaned")) continue;
+    if (!skipOrphanDetection && !specFnCodes.has(record.code)) {
+      const newFlags = [.../* @__PURE__ */ new Set([...record.flags, "orphaned"])];
+      writeLedgerFlags(cwd, record.code, newFlags);
+      orphaned.push(record.code);
+      continue;
+    }
+    if (record.state === "done") {
+      const files = links[record.code] ?? [];
+      for (const filePath of files) {
+        const absPath = join5(cwd, filePath);
+        const newHash = fileHash(absPath);
+        const oldHash = prevHashes[filePath] ?? "";
+        nextHashes[filePath] = newHash;
+        if (oldHash && newHash !== oldHash) {
+          if (!record.flags.includes("needs-re-verification")) {
+            const newFlags = [
+              .../* @__PURE__ */ new Set([...record.flags, "needs-re-verification"])
+            ];
+            writeLedgerFlags(cwd, record.code, newFlags);
+            needsReverification.push(record.code);
+          }
+        }
+      }
+    }
+  }
+  for (const [code, files] of Object.entries(links)) {
+    for (const filePath of files) {
+      const absPath = join5(cwd, filePath);
+      nextHashes[filePath] = fileHash(absPath);
+    }
+  }
+  writeHashes(cwd, nextHashes);
+  console.log(pc2.green("\u2713") + " Sync complete.");
+  if (orphaned.length > 0) {
+    console.log(
+      pc2.yellow(`  Orphaned (removed from spec): ${orphaned.join(", ")}`)
+    );
+  }
+  if (needsReverification.length > 0) {
+    console.log(
+      pc2.yellow(
+        `  Needs re-verification (spec changed after done): ${needsReverification.join(", ")}`
+      )
+    );
+  }
+  if (orphaned.length === 0 && needsReverification.length === 0) {
+    console.log(pc2.dim("  No drift detected."));
+  }
+  console.log(pc2.dim("  AGENTS.md and CLAUDE.md updated."));
+}
+async function readKeyFromMcpJson(cwd) {
+  const mcpPath = join5(cwd, ".mcp.json");
+  if (!existsSync5(mcpPath)) {
+    throw new Error(".mcp.json not found. Run `cubedot init` first.");
+  }
+  const mcp = JSON.parse(readFileSync5(mcpPath, "utf8"));
+  const key = mcp.mcpServers?.["cubedot"]?.headers?.["x-api-key"];
+  if (!key) {
+    throw new Error(
+      ".mcp.json is missing the cubedot x-api-key. Re-run `cubedot init`."
+    );
+  }
+  return key;
+}
+
+// src/commands/status.ts
+import pc3 from "picocolors";
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
+import { join as join6 } from "path";
+async function statusCommand() {
+  const cwd = process.cwd();
+  let ok = true;
+  const config = readCubedotConfig(cwd);
+  if (!config) {
+    console.log(pc3.red("\u2717") + " .cubedot/config.json \u2014 missing (run `cubedot init`)");
+    ok = false;
+  } else {
+    console.log(pc3.green("\u2713") + " .cubedot/config.json");
+    console.log(pc3.dim(`    projectId: ${config.projectId}`));
+    if (config.lastSynced) {
+      const ageDays = (Date.now() - new Date(config.lastSynced).getTime()) / 864e5;
+      const ageStr = ageDays < 1 ? "today" : `${Math.floor(ageDays)} day(s) ago`;
+      const stale = ageDays >= 3;
+      console.log(
+        (stale ? pc3.yellow("\u26A0 ") : pc3.dim("   ")) + `  Last synced: ${ageStr}${stale ? " \u2014 consider running `cubedot sync`" : ""}`
+      );
+    }
+  }
+  const mcpPath = join6(cwd, ".mcp.json");
+  if (!existsSync6(mcpPath)) {
+    console.log(pc3.red("\u2717") + " .mcp.json \u2014 missing");
+    ok = false;
+  } else {
+    try {
+      const mcp = JSON.parse(readFileSync6(mcpPath, "utf8"));
+      const keyRaw = mcp.mcpServers?.["cubedot"]?.headers?.["x-api-key"] ?? "";
+      const keyTail = keyRaw ? keyRaw.slice(-8) : "(empty)";
+      console.log(pc3.green("\u2713") + ` .mcp.json \u2014 key tail: \u2026${keyTail}`);
+    } catch {
+      console.log(pc3.red("\u2717") + " .mcp.json \u2014 malformed JSON");
+      ok = false;
+    }
+  }
+  for (const file of ["AGENTS.md", "CLAUDE.md"]) {
+    const path = join6(cwd, file);
+    if (!existsSync6(path)) {
+      console.log(pc3.red("\u2717") + ` ${file} \u2014 missing`);
+      ok = false;
+    } else {
+      const content = readFileSync6(path, "utf8");
+      const markers = hasAllMarkers(content);
+      console.log(
+        (markers ? pc3.green("\u2713") : pc3.yellow("\u26A0")) + ` ${file}${markers ? "" : " \u2014 markers missing or malformed (run `cubedot sync`)"}`
+      );
+    }
+  }
+  const verifier = join6(cwd, ".claude", "agents", "CubedotVerifier.md");
+  const manual = join6(cwd, ".cubedot", "fia-operating-manual.md");
+  console.log(
+    (existsSync6(verifier) ? pc3.green("\u2713") : pc3.red("\u2717")) + " .claude/agents/CubedotVerifier.md"
+  );
+  console.log(
+    (existsSync6(manual) ? pc3.green("\u2713") : pc3.red("\u2717")) + " .cubedot/fia-operating-manual.md"
+  );
+  const ledgers = readAllLedgers(cwd);
+  if (ledgers.length === 0) {
+    console.log(pc3.dim("  Ledger: no entries yet"));
+  } else {
+    const counts = {};
+    for (const l of ledgers) counts[l.state] = (counts[l.state] ?? 0) + 1;
+    const summary = Object.entries(counts).map(([s, n]) => `${n} ${s}`).join(", ");
+    console.log(pc3.dim(`  Ledger: ${ledgers.length} entries (${summary})`));
+  }
+  if (config) {
+    console.log(pc3.dim("\nChecking MCP connectivity \u2026"));
+    try {
+      const key = await readKeyFromMcpJson(cwd);
+      const connectUrl = buildConnectUrl(config.mcpUrl, config.projectId);
+      const client = await createMcpClient(connectUrl, key);
+      try {
+        await validateTools(client);
+        console.log(pc3.green("\u2713") + " MCP server reachable \u2014 all 7 tools present");
+      } finally {
+        await client.close();
+      }
+    } catch (err) {
+      console.log(
+        pc3.red("\u2717") + " MCP server: " + categorizeError(err)
+      );
+      ok = false;
+    }
+  }
+  process.exit(ok ? 0 : 1);
+}
+
+// src/commands/check.ts
+import pc4 from "picocolors";
+import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
+import { join as join7 } from "path";
+async function checkCommand() {
+  const cwd = process.cwd();
+  const issues = [];
+  const config = readCubedotConfig(cwd);
+  if (!config) {
+    issues.push(".cubedot/config.json missing \u2014 run `cubedot init`");
+  }
+  const mcpPath = join7(cwd, ".mcp.json");
+  if (!existsSync7(mcpPath)) {
+    issues.push(".mcp.json missing \u2014 run `cubedot init`");
+  } else {
+    try {
+      const mcp = JSON.parse(readFileSync7(mcpPath, "utf8"));
+      if (!mcp.mcpServers?.["cubedot"]) {
+        issues.push(
+          ".mcp.json missing mcpServers.cubedot \u2014 run `cubedot init`"
+        );
+      }
+    } catch {
+      issues.push(".mcp.json contains malformed JSON");
+    }
+  }
+  const agentsPath = join7(cwd, "AGENTS.md");
+  if (!existsSync7(agentsPath)) {
+    issues.push("AGENTS.md missing \u2014 run `cubedot init`");
+  } else {
+    const content = readFileSync7(agentsPath, "utf8");
+    if (!hasAllMarkers(content)) {
+      issues.push(
+        "AGENTS.md is missing or has malformed CUBEDOT markers \u2014 run `cubedot sync`"
+      );
+    }
+  }
+  const claudePath = join7(cwd, "CLAUDE.md");
+  if (!existsSync7(claudePath)) {
+    issues.push("CLAUDE.md missing \u2014 run `cubedot init`");
+  } else {
+    const content = readFileSync7(claudePath, "utf8");
+    if (!hasAllMarkers(content)) {
+      issues.push(
+        "CLAUDE.md is missing or has malformed CUBEDOT markers \u2014 run `cubedot sync`"
+      );
+    }
+  }
+  const verifier = join7(cwd, ".claude", "agents", "CubedotVerifier.md");
+  if (!existsSync7(verifier)) {
+    issues.push(
+      ".claude/agents/CubedotVerifier.md missing \u2014 run `cubedot init`"
+    );
+  }
+  const manual = join7(cwd, ".cubedot", "fia-operating-manual.md");
+  if (!existsSync7(manual)) {
+    issues.push(
+      ".cubedot/fia-operating-manual.md missing \u2014 run `cubedot init`"
+    );
+  }
+  for (const dir of [".cubedot/progress", ".cubedot/reports"]) {
+    if (!existsSync7(join7(cwd, dir))) {
+      issues.push(`${dir}/ missing \u2014 run 'cubedot init'`);
+    }
+  }
+  if (existsSync7(claudePath)) {
+    const content = readFileSync7(claudePath, "utf8");
+    if (content.includes("fia-operating-manual") && !existsSync7(join7(cwd, ".cubedot", "fia-operating-manual.md"))) {
+      issues.push(
+        "CLAUDE.md references .cubedot/fia-operating-manual.md but it is missing"
+      );
+    }
+  }
+  if (issues.length === 0) {
+    console.log(pc4.green("\u2713") + " All checks passed.");
+    process.exit(0);
+  } else {
+    console.log(pc4.red(`\u2717 ${issues.length} issue(s) found:
+`));
+    for (const issue of issues) {
+      console.log("  " + pc4.red("\u2022") + " " + issue);
+    }
+    process.exit(1);
+  }
+}
+
+// src/commands/start.ts
+import pc5 from "picocolors";
+function startCommand(fn, opts) {
+  const cwd = process.cwd();
+  const actor = opts.actor === "human" ? "human" : "agent";
+  try {
+    const record = startFn(cwd, fn, actor);
+    console.log(
+      pc5.green("\u2713") + ` ${fn} \u2192 in_progress (actor: ${record.actor}, at: ${record.updatedAt})`
+    );
+    console.log(pc5.dim(`  Ledger: .cubedot/progress/${fn}.json`));
+  } catch (err) {
+    console.error(pc5.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+// src/commands/complete.ts
+import pc6 from "picocolors";
+function completeCommand(fn, opts) {
+  const cwd = process.cwd();
+  const actor = opts.actor === "human" ? "human" : "agent";
+  try {
+    const record = completeFn(cwd, fn, actor);
+    console.log(
+      pc6.green("\u2713") + ` ${fn} \u2192 code-complete (actor: ${record.actor}, at: ${record.updatedAt})`
+    );
+    console.log(
+      pc6.dim(
+        `  Next: spawn CubedotVerifier, then ask the developer to run \`cubedot done ${fn}\`.`
+      )
+    );
+  } catch (err) {
+    console.error(pc6.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+// src/commands/done.ts
+import pc7 from "picocolors";
+function doneCommand(fn, opts) {
+  const cwd = process.cwd();
+  const actor = opts.actor === "agent" ? "agent" : "human";
+  const force = opts.force === true;
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const discrepancies = (opts.discrepancy ?? []).map(
+    (criterion) => ({ criterion, at: now })
+  );
+  try {
+    const record = doneFn(cwd, fn, actor, force, discrepancies);
+    console.log(
+      pc7.green("\u2713") + ` ${fn} \u2192 done (actor: ${record.actor}, at: ${record.updatedAt})`
+    );
+    if (record.overrides.length > 0) {
+      console.log(
+        pc7.yellow(
+          `  \u26A0  Override recorded: ${record.overrides[record.overrides.length - 1].condition}`
+        )
+      );
+    }
+    if (discrepancies.length > 0) {
+      console.log(
+        pc7.yellow(
+          `  \u26A0  ${discrepancies.length} discrepancy(ies) recorded (criteria accepted unmet):`
+        )
+      );
+      for (const d of discrepancies) {
+        console.log(pc7.yellow(`     - ${d.criterion}`));
+      }
+    }
+  } catch (err) {
+    console.error(pc7.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+}
+
+// src/commands/progress.ts
+import pc8 from "picocolors";
+import { existsSync as existsSync8, readFileSync as readFileSync8 } from "fs";
+import { join as join8 } from "path";
+function progressCommand() {
+  const cwd = process.cwd();
+  const ledgers = readAllLedgers(cwd);
+  let fnNames = /* @__PURE__ */ new Map();
+  for (const file of ["AGENTS.md", "CLAUDE.md"]) {
+    const path = join8(cwd, file);
+    if (existsSync8(path)) {
+      fnNames = parseRegistryBlock(readFileSync8(path, "utf8"));
+      if (fnNames.size > 0) break;
+    }
+  }
+  const byState = {
+    done: [],
+    "code-complete": [],
+    in_progress: []
+  };
+  const flagged = [];
+  for (const l of ledgers) {
+    (byState[l.state] ?? []).push(l);
+    if (l.flags.length > 0) flagged.push(l);
+  }
+  const total = fnNames.size || ledgers.length;
+  const doneCount = byState["done"].length;
+  const ccCount = byState["code-complete"].length;
+  const ipCount = byState["in_progress"].length;
+  const todoCount = Math.max(0, total - doneCount - ccCount - ipCount);
+  console.log("\n" + pc8.bold("Progress Summary"));
+  console.log("\u2501".repeat(40));
+  console.log(`  Done:           ${pc8.green(String(doneCount))}/${total}`);
+  if (ccCount > 0)
+    console.log(`  Code-complete:  ${pc8.cyan(String(ccCount))}/${total}`);
+  if (ipCount > 0)
+    console.log(`  In progress:    ${pc8.yellow(String(ipCount))}/${total}`);
+  if (todoCount > 0)
+    console.log(`  Todo:           ${pc8.dim(String(todoCount))}/${total}`);
+  const active = [
+    ...byState["in_progress"],
+    ...byState["code-complete"]
+  ];
+  if (active.length > 0) {
+    console.log("\n" + pc8.bold("Active:"));
+    for (const l of active) {
+      const name = fnNames.get(l.code) ? ` \u2014 ${fnNames.get(l.code)}` : "";
+      const stateLabel = l.state === "in_progress" ? pc8.yellow("in_progress") : pc8.cyan("code-complete");
+      console.log(`  ${l.code}${name}  [${stateLabel}]`);
+    }
+  }
+  if (fnNames.size > 0) {
+    const ledgerCodes = new Set(ledgers.map((l) => l.code));
+    const registryOrder = Array.from(fnNames.keys());
+    const nextCode = registryOrder.find((code) => !ledgerCodes.has(code));
+    if (nextCode) {
+      console.log("\n" + pc8.bold("Next unblocked:"));
+      console.log(`  ${nextCode} \u2014 ${fnNames.get(nextCode) ?? ""}`);
+    }
+  }
+  if (flagged.length > 0) {
+    console.log("\n" + pc8.bold(pc8.yellow("Flagged:")));
+    for (const l of flagged) {
+      console.log(`  ${l.code}  [${l.flags.join(", ")}]`);
+    }
+  }
+  if (byState["done"].length > 0) {
+    console.log("\n" + pc8.bold("Done:"));
+    for (const l of byState["done"]) {
+      const name = fnNames.get(l.code) ? ` \u2014 ${fnNames.get(l.code)}` : "";
+      console.log(`  ${pc8.green("\u2713")} ${l.code}${name}`);
+    }
+  }
+  console.log("");
+}
+
+// src/cli.ts
+var __filename3 = fileURLToPath4(import.meta.url);
+var __dirname4 = dirname4(__filename3);
+var pkg3 = JSON.parse(
+  readFileSync9(join9(__dirname4, "../package.json"), "utf8")
+);
+var program = new Command();
+var collect = (value, prev) => [...prev, value];
+program.name("cubedot").description(
+  "Connect your repo to the Cubedot MCP and drive the spec-first build loop."
+).version(pkg3.version);
+program.command("init").description("Connect and scaffold the repo (validates MCP, writes config + hot-memory files).").option("--token <token>", "Base64url connect token {v:1, projectId, key, mcpUrl}").option("--project <projectId>", "Project ID (alternative to --token)").option("--key <key>", "MCP API key (alternative to --token)").option("--url <url>", "MCP URL (alternative to --token)").action(initCommand);
+program.command("sync").description("Refresh local projection (AGENTS.md/CLAUDE.md markers) and detect drift.").action(syncCommand);
+program.command("status").description("Connectivity ping + file-health check (read-only).").action(statusCommand);
+program.command("check").description("Validate markers, config, and server name (read-only; CI-friendly).").action(checkCommand);
+program.command("start <fn>").description("Set a functionality to in_progress.").option("--actor <actor>", "Actor performing the action", "agent").action(startCommand);
+program.command("complete <fn>").description("Set a functionality to code-complete (requires in_progress state).").option("--actor <actor>", "Actor performing the action", "agent").action(completeCommand);
+program.command("done <fn>").description("Mark a functionality done (human gate; requires code-complete state).").option("--actor <actor>", "Actor performing the action", "human").option("--force", "Override the code-complete gate (records a discrepancy).").option(
+  "--discrepancy <text>",
+  "Record an acceptance criterion accepted as unmet at done (repeatable).",
+  collect,
+  []
+).action(doneCommand);
+program.command("progress").description("Print completion summary across all tracked functionalities (read-only).").action(progressCommand);
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});