@0dai-dev/cli 4.2.0 → 4.3.5

package/lib/commands/gh.js

@@ -0,0 +1,506 @@
+"use strict";
+
+const shared = require("../shared");
+const { log, D, R, fs, path, spawnSync } = shared;
+
+const BRANCH_PROTECTION_RULES = {
+  required_status_checks: {
+    strict: true,
+    contexts: [],
+    checks: [
+      { context: "dirty-tree", app_id: -1 },
+      { context: "lint", app_id: -1 },
+      { context: "test", app_id: -1 },
+      { context: "file-size", app_id: -1 },
+    ],
+  },
+  enforce_admins: false,
+  required_pull_request_reviews: {
+    dismiss_stale_reviews: true,
+    require_code_owner_reviews: false,
+    required_approving_review_count: 1,
+    require_last_push_approval: true,
+  },
+  restrictions: {
+    users: [],
+    teams: [],
+    apps: [],
+  },
+  required_linear_history: true,
+  allow_force_pushes: false,
+  allow_deletions: false,
+  block_creations: false,
+  required_conversation_resolution: true,
+  lock_branch: false,
+  allow_fork_syncing: false,
+};
+
+const POLICY_FILES = [
+  {
+    rel: ".github/.0dai/branch-protection-rules.json",
+    content: () => JSON.stringify(BRANCH_PROTECTION_RULES, null, 2) + "\n",
+  },
+  {
+    rel: ".github/PULL_REQUEST_TEMPLATE.md",
+    content: () => [
+      "## What Changed",
+      "",
+      "- ",
+      "",
+      "## Linked Work",
+      "",
+      "- Closes #",
+      "",
+      "## Validation",
+      "",
+      "- [ ] Lint passed",
+      "- [ ] Tests passed",
+      "- [ ] Dirty-tree check passed",
+      "",
+      "## Release Impact",
+      "",
+      "- [ ] No release note needed",
+      "- [ ] Update `CHANGELOG.md`",
+      "- [ ] Add or update `release-notes/`",
+      "",
+      "## Rollback",
+      "",
+      "- Reversal: `git revert <merge-sha>`",
+      "- Data migration: none",
+      "",
+    ].join("\n"),
+  },
+  {
+    rel: ".github/workflows/ci.yml",
+    content: () => [
+      "name: CI",
+      "",
+      "on:",
+      "  pull_request:",
+      "    branches: [main]",
+      "  push:",
+      "    branches: [main]",
+      "",
+      "permissions:",
+      "  contents: read",
+      "",
+      "jobs:",
+      "  dirty-tree:",
+      "    runs-on: ubuntu-latest",
+      "    steps:",
+      "      - uses: actions/checkout@v4",
+      "      - name: Generated file guard",
+      "        run: git diff --exit-code",
+      "",
+      "  lint:",
+      "    runs-on: ubuntu-latest",
+      "    steps:",
+      "      - uses: actions/checkout@v4",
+      "      - uses: actions/setup-node@v4",
+      "        if: hashFiles('package.json') != ''",
+      "        with:",
+      "          node-version: '20'",
+      "      - uses: actions/setup-python@v5",
+      "        if: hashFiles('pyproject.toml', 'requirements.txt', '**/*.py') != ''",
+      "        with:",
+      "          python-version: '3.12'",
+      "      - name: Lint",
+      "        run: |",
+      "          if [ -f package.json ]; then npm run lint --if-present; fi",
+      "          if find . -path './.git' -prune -o -name '*.py' -print -quit | grep -q .; then",
+      "            python3 -m compileall -q .",
+      "          fi",
+      "",
+      "  test:",
+      "    runs-on: ubuntu-latest",
+      "    steps:",
+      "      - uses: actions/checkout@v4",
+      "      - uses: actions/setup-node@v4",
+      "        if: hashFiles('package.json') != ''",
+      "        with:",
+      "          node-version: '20'",
+      "      - uses: actions/setup-python@v5",
+      "        if: hashFiles('pyproject.toml', 'requirements.txt', 'tests/**/*.py') != ''",
+      "        with:",
+      "          python-version: '3.12'",
+      "      - name: Test",
+      "        run: |",
+      "          if [ -f package.json ]; then npm test --if-present; fi",
+      "          if [ -d tests ] && find tests -name '*.py' -print -quit | grep -q .; then",
+      "            python3 -m pytest",
+      "          fi",
+      "",
+      "  file-size:",
+      "    runs-on: ubuntu-latest",
+      "    steps:",
+      "      - uses: actions/checkout@v4",
+      "      - name: File size guard",
+      "        run: |",
+      "          if [ -x .githooks/check-file-size.sh ]; then",
+      "            bash .githooks/check-file-size.sh",
+      "          else",
+      "            echo \"No .githooks/check-file-size.sh present; skipping.\"",
+      "          fi",
+      "",
+    ].join("\n"),
+  },
+  {
+    rel: ".githooks/check-file-size.sh",
+    executable: true,
+    content: () => [
+      "#!/usr/bin/env bash",
+      "set -euo pipefail",
+      "",
+      "MAX_WARN=\"${MAX_WARN:-800}\"",
+      "MAX_FAIL=\"${MAX_FAIL:-2000}\"",
+      "WAIVER_TAG=\"# pragma: loc-waiver\"",
+      "mode=\"${1:-all}\"",
+      "",
+      "file_has_waiver() {",
+      "  local file=\"$1\"",
+      "  [ -f \"$file\" ] && head -n 32 \"$file\" 2>/dev/null | grep -qF \"$WAIVER_TAG\"",
+      "}",
+      "",
+      "if [ \"$mode\" = \"--staged\" ]; then",
+      "  files=\"$(git diff --cached --name-only --diff-filter=ACM 2>/dev/null | grep -E '\\.(py|js|ts|tsx|jsx|sh)$' || true)\"",
+      "else",
+      "  files=\"$(find . -path './.git' -prune -o -path './node_modules' -prune -o -type f \\( -name '*.py' -o -name '*.js' -o -name '*.ts' -o -name '*.tsx' -o -name '*.jsx' -o -name '*.sh' \\) -print 2>/dev/null || true)\"",
+      "fi",
+      "",
+      "[ -n \"$files\" ] || exit 0",
+      "",
+      "failed=0",
+      "while IFS= read -r file; do",
+      "  [ -n \"$file\" ] || continue",
+      "  [ -f \"$file\" ] || continue",
+      "  lines=\"$(wc -l < \"$file\")\"",
+      "  if [ \"$lines\" -ge \"$MAX_FAIL\" ] && ! file_has_waiver \"$file\"; then",
+      "    printf 'FAIL %s: %s LOC >= %s\\n' \"$file\" \"$lines\" \"$MAX_FAIL\"",
+      "    failed=$((failed + 1))",
+      "  fi",
+      "done <<< \"$files\"",
+      "",
+      "[ \"$failed\" -eq 0 ] || exit 1",
+      "",
+    ].join("\n"),
+  },
+  {
+    rel: ".githooks/pre-commit",
+    executable: true,
+    content: () => [
+      "#!/usr/bin/env bash",
+      "set -euo pipefail",
+      "",
+      "repo_root=\"$(git rev-parse --show-toplevel 2>/dev/null)\" || exit 0",
+      "git diff --cached --check",
+      "if [ -x \"$repo_root/.githooks/check-file-size.sh\" ]; then",
+      "  bash \"$repo_root/.githooks/check-file-size.sh\" --staged",
+      "fi",
+      "if [ -f \"$repo_root/scripts/scan_secrets.py\" ]; then",
+      "  python3 \"$repo_root/scripts/scan_secrets.py\" --target \"$repo_root\"",
+      "fi",
+      "",
+    ].join("\n"),
+  },
+  {
+    rel: "CHANGELOG.md",
+    content: () => [
+      "# Changelog",
+      "",
+      "All notable changes to this project are documented here.",
+      "",
+      "## Unreleased",
+      "",
+      "### Added",
+      "",
+      "- Initial 0dai project policy scaffold.",
+      "",
+    ].join("\n"),
+  },
+  {
+    rel: "CONTRIBUTING.md",
+    content: () => [
+      "# Contributing",
+      "",
+      "## Branch Flow",
+      "",
+      "1. Branch from `main`.",
+      "2. Keep changes focused and reviewable.",
+      "3. Open a pull request back to `main`.",
+      "4. Wait for required CI checks and review before merge.",
+      "",
+      "Use descriptive branch names such as `feat/<issue>-short-topic`,",
+      "`fix/<issue>-short-topic`, or `docs/<issue>-short-topic`.",
+      "",
+      "## Commits",
+      "",
+      "- Use an imperative summary under 72 characters.",
+      "- Reference the issue or task when one exists.",
+      "- Include the why in the body for non-trivial changes.",
+      "",
+      "## Local Checks",
+      "",
+      "Run the project lint and test commands from `ai/manifest/commands.yaml` when",
+      "they are present. The generated `.githooks/` path is activated by `0dai init`",
+      "with:",
+      "",
+      "```bash",
+      "git config core.hooksPath .githooks",
+      "```",
+      "",
+    ].join("\n"),
+  },
+  {
+    rel: "RELEASE_NOTES_TEMPLATE.md",
+    content: () => [
+      "# Release Notes: vX.Y.Z",
+      "",
+      "## Summary",
+      "",
+      "- ",
+      "",
+      "## Changes",
+      "",
+      "- ",
+      "",
+      "## Validation",
+      "",
+      "- ",
+      "",
+      "## Rollback",
+      "",
+      "- Revert the release commit or tag.",
+      "",
+    ].join("\n"),
+  },
+  { rel: "VERSION", content: () => "0.1.0\n" },
+  { rel: "release-notes/.gitkeep", content: () => "" },
+];
+
+function parseOptions(args) {
+  const opts = { branch: "main", rules: "", dryRun: false };
+  for (let i = 0; i < args.length; i++) {
+    const arg = String(args[i] || "");
+    if (arg === "--branch" && args[i + 1]) {
+      opts.branch = String(args[++i]);
+    } else if ((arg === "--rules" || arg === "--input") && args[i + 1]) {
+      opts.rules = String(args[++i]);
+    } else if (arg === "--dry-run") {
+      opts.dryRun = true;
+    }
+  }
+  return opts;
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function writeIfMissing(target, rel, content, executable) {
+  const dest = path.join(target, rel);
+  if (fs.existsSync(dest)) return false;
+  ensureDir(dest);
+  fs.writeFileSync(dest, content, "utf8");
+  if (executable) fs.chmodSync(dest, 0o755);
+  return true;
+}
+
+function scaffoldGithubFlowPolicy(target) {
+  let created = 0;
+  for (const file of POLICY_FILES) {
+    if (writeIfMissing(target, file.rel, file.content(), !!file.executable)) created += 1;
+  }
+  return created;
+}
+
+function isGitRepo(target) {
+  const result = spawnSync("git", ["-C", target, "rev-parse", "--is-inside-work-tree"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  return result.status === 0 && String(result.stdout || "").trim() === "true";
+}
+
+function hasGithubRemote(target) {
+  const result = spawnSync("git", ["-C", target, "remote", "get-url", "origin"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.status !== 0) return false;
+  return /github\.com[:/]/.test(String(result.stdout || ""));
+}
+
+function ensureHooksPath(target) {
+  if (!isGitRepo(target)) return false;
+  const result = spawnSync("git", ["-C", target, "config", "core.hooksPath", ".githooks"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return result.status === 0;
+}
+
+function getHooksPath(target) {
+  if (!isGitRepo(target)) return null;
+  const result = spawnSync("git", ["-C", target, "config", "--get", "core.hooksPath"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.status !== 0) return "";
+  return String(result.stdout || "").trim();
+}
+
+function warnHooksPathDrift(target) {
+  const hooksPath = getHooksPath(target);
+  if (hooksPath === null || hooksPath === ".githooks") return false;
+  const current = hooksPath || "not set";
+  log(`warning: core.hooksPath is ${current}; expected .githooks for 0dai git policy`);
+  console.log(`  ${D}Run: git config core.hooksPath .githooks${R}`);
+  return true;
+}
+
+function defaultRulesPath(target) {
+  return path.join(target, ".github", ".0dai", "branch-protection-rules.json");
+}
+
+function findInstallGitPolicyScript(target) {
+  const repoRoot = path.resolve(__dirname, "..", "..", "..", "..");
+  const candidates = [
+    path.join(target, "bootstrap", "install_git_policy.sh"),
+    path.join(process.cwd(), "bootstrap", "install_git_policy.sh"),
+    path.join(repoRoot, "bootstrap", "install_git_policy.sh"),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) || "";
+}
+
+function runBootstrapInstaller(target) {
+  if (process.env.ODAI_GIT_POLICY_JS_ONLY === "1") return false;
+  const script = findInstallGitPolicyScript(target);
+  if (!script) return false;
+  const result = spawnSync("bash", [script, "--target", target], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) {
+    const reason = String(result.stderr || result.stdout || "unknown error").trim().split("\n").pop();
+    log(`git policy installer skipped: ${reason}`);
+    return false;
+  }
+  return true;
+}
+
+function applyBranchProtection(target, options = {}) {
+  const branch = options.branch || "main";
+  const rules = options.rules || defaultRulesPath(target);
+  const failOnError = !!options.failOnError;
+  const dryRun = !!options.dryRun;
+  const inherit = !!options.inherit;
+
+  if (!fs.existsSync(rules)) {
+    const message = `branch protection rules not found: ${rules}`;
+    if (failOnError) throw new Error(message);
+    return { ok: false, skipped: true, reason: message };
+  }
+  if (!hasGithubRemote(target)) {
+    const message = "origin is not a GitHub remote";
+    if (failOnError) throw new Error(message);
+    return { ok: false, skipped: true, reason: message };
+  }
+  if (spawnSync("gh", ["--version"], { stdio: "ignore" }).status !== 0) {
+    const message = "gh CLI not found";
+    if (failOnError) throw new Error(message);
+    return { ok: false, skipped: true, reason: message };
+  }
+
+  const endpoint = `repos/:owner/:repo/branches/${branch}/protection`;
+  if (dryRun) {
+    console.log(`gh api ${endpoint} -X PUT --input ${rules}`);
+    return { ok: true, dryRun: true };
+  }
+
+  const result = spawnSync("gh", ["api", endpoint, "-X", "PUT", "--input", rules], {
+    cwd: target,
+    encoding: "utf8",
+    stdio: inherit ? "inherit" : ["ignore", "pipe", "pipe"],
+  });
+  if (result.status === 0) return { ok: true };
+
+  const message = String(result.stderr || result.stdout || "gh api failed").trim();
+  if (failOnError) throw new Error(message);
+  return { ok: false, skipped: false, reason: message };
+}
+
+function printBranchProtection(target, options = {}) {
+  const branch = options.branch || "main";
+  if (!hasGithubRemote(target)) throw new Error("origin is not a GitHub remote");
+  if (spawnSync("gh", ["--version"], { stdio: "ignore" }).status !== 0) throw new Error("gh CLI not found");
+  const result = spawnSync("gh", ["api", `repos/:owner/:repo/branches/${branch}/protection`, "-X", "GET"], {
+    cwd: target,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) throw new Error(String(result.stderr || result.stdout || "gh api failed").trim());
+  process.stdout.write(result.stdout);
+}
+
+function ensureGithubFlowPolicy(target, options = {}) {
+  if (process.env.ODAI_GIT_POLICY_SKIP === "1") return { installed: false, skipped: true };
+  if (runBootstrapInstaller(target)) return { installed: true, via: "bootstrap" };
+
+  const created = scaffoldGithubFlowPolicy(target);
+  ensureHooksPath(target);
+  let protection = null;
+  if (!options.skipApply) {
+    protection = applyBranchProtection(target, {
+      branch: options.branch || "main",
+      rules: options.rules || defaultRulesPath(target),
+      failOnError: false,
+    });
+  }
+  return { installed: true, via: "js", created, protection };
+}
+
+async function cmdGh(target, sub, args = []) {
+  if (sub !== "branch-protection") {
+    console.log("Usage: 0dai gh branch-protection [print|apply] [--branch main] [--rules FILE] [--dry-run]");
+    process.exitCode = 1;
+    return;
+  }
+
+  const rest = args.slice(2);
+  const action = rest[0] && !String(rest[0]).startsWith("-") ? String(rest[0]) : "print";
+  const options = parseOptions(rest);
+
+  try {
+    if (action === "apply") {
+      scaffoldGithubFlowPolicy(target);
+      ensureHooksPath(target);
+      applyBranchProtection(target, { ...options, failOnError: true, inherit: !options.dryRun });
+      if (!options.dryRun) log(`applied branch protection to ${options.branch || "main"}`);
+      return;
+    }
+    if (action === "print" || action === "show" || action === "current") {
+      printBranchProtection(target, options);
+      return;
+    }
+    if (action === "install") {
+      const result = ensureGithubFlowPolicy(target, { skipApply: true });
+      log(`installed git policy files${result.created ? ` (${result.created} created)` : ""}`);
+      return;
+    }
+    console.log("Usage: 0dai gh branch-protection [print|apply|install] [--branch main] [--rules FILE] [--dry-run]");
+    process.exitCode = 1;
+  } catch (err) {
+    log(`branch-protection ${action} failed: ${err.message || err}`);
+    console.log(`  ${D}Rules: ${options.rules || defaultRulesPath(target)}${R}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  BRANCH_PROTECTION_RULES,
+  cmdGh,
+  ensureGithubFlowPolicy,
+  scaffoldGithubFlowPolicy,
+  applyBranchProtection,
+  warnHooksPathDrift,
+};

package/lib/commands/graph.js

@@ -2,6 +2,63 @@
 const shared = require("../shared");
 const { log, T, R, D, fs, path, apiCall, AUTH_FILE, buildProjectIdentity, collectMetadata, recordExperienceEvent } = shared;
 
+function graphAuthToken(auth) {
+  return String((auth && (auth.api_key || auth.access_token || auth.token)) || "").trim();
+}
+
+function isPaidGraphPlan(auth) {
+  const plan = String((auth && auth.plan) || "free").toLowerCase();
+  return ["pro", "team", "enterprise"].includes(plan);
+}
+
+function graphPayloadForPush(localGraph, auth) {
+  const nodes = localGraph.nodes || {};
+  const localEdges = localGraph.edges || [];
+  const edges = isPaidGraphPlan(auth) ? localEdges : [];
+  return {
+    nodes,
+    edges,
+    localEdgeCount: localEdges.length,
+    edgesLocalOnly: localEdges.length - edges.length,
+  };
+}
+
+function readStructuralMemorySummary(target) {
+  const script = shared.findRepoScript(target, "structural_memory.py");
+  if (!script) return null;
+  const result = shared.spawnSync("python3", [script, "--target", target, "--json"], {
+    encoding: "utf8",
+    timeout: 10000,
+  });
+  if (result.status !== 0 || !result.stdout) return null;
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    return null;
+  }
+}
+
+function formatStructuralMemorySummary(summary) {
+  if (!summary || typeof summary !== "object") return [];
+  const surfaces = summary.surfaces || {};
+  const roles = summary.roles || {};
+  const parts = [
+    `records=${summary.total_records || 0}`,
+    `memory=${surfaces.memory || 0}`,
+    `graph=${surfaces.graph || 0}`,
+    `experience=${surfaces.experience || 0}`,
+  ];
+  const roleParts = Object.entries(roles)
+    .filter(([, count]) => Number(count) > 0)
+    .slice(0, 6)
+    .map(([role, count]) => `${role}:${count}`);
+  const lines = [`Structural memory: ${parts.join(", ")}`];
+  if (roleParts.length) lines.push(`  roles: ${roleParts.join(", ")}`);
+  const driftCount = Number(summary.drift_warning_count || 0);
+  if (driftCount > 0) lines.push(`  drift warnings: ${driftCount}`);
+  return lines;
+}
+
 async function cmdGraph(target, sub, args) {
   const graphFile = path.join(target, "ai", "manifest", "project_graph.json");
 
@@ -9,7 +66,7 @@ async function cmdGraph(target, sub, args) {
     // Check auth
     let auth;
     try { auth = JSON.parse(fs.readFileSync(AUTH_FILE, "utf8")); } catch {}
-    if (!auth || !auth.access_token) {
+    if (!graphAuthToken(auth)) {
       log("Graph push requires an account. Run: 0dai auth login");
       return;
     }
@@ -25,11 +82,11 @@ async function cmdGraph(target, sub, args) {
       return;
     }
 
-    const nodes = localGraph.nodes || {};
-    const edges = localGraph.edges || [];
+    const { nodes, edges, localEdgeCount, edgesLocalOnly } = graphPayloadForPush(localGraph, auth);
     const identity = buildProjectIdentity(target, collectMetadata(target));
 
-    log(`Pushing graph (${Object.keys(nodes).length} nodes, ${edges.length} edges)...`);
+    const edgeSuffix = edgesLocalOnly > 0 ? `, ${edgesLocalOnly} local-only edges held back` : "";
+    log(`Pushing graph (${Object.keys(nodes).length} nodes, ${edges.length} edges${edgeSuffix})...`);
     const result = await apiCall("/v1/graph/sync", {
       project_id: identity.project_id,
       nodes,
@@ -58,7 +115,7 @@ async function cmdGraph(target, sub, args) {
       model: "0dai-cli",
       effort: "medium",
       task: { goal: "push graph to server", task_type: "feat", result: "success", elapsed_seconds: 0, cost_usd: 0 },
-      context: { stack: "unknown", files_touched: 1, tests_passed: true, graph_nodes_used: Object.keys(nodes).length, graph_edges_used: edges.length },
+      context: { stack: "unknown", files_touched: 1, tests_passed: true, graph_nodes_used: Object.keys(nodes).length, graph_edges_used: edges.length, graph_edges_local_only: localEdgeCount - edges.length },
     });
     return;
   }
@@ -66,7 +123,7 @@ async function cmdGraph(target, sub, args) {
   if (sub === "pull") {
     let auth;
     try { auth = JSON.parse(fs.readFileSync(AUTH_FILE, "utf8")); } catch {}
-    if (!auth || !auth.access_token) {
+    if (!graphAuthToken(auth)) {
       log("Graph pull requires an account. Run: 0dai auth login");
       return;
     }
@@ -148,11 +205,15 @@ async function cmdGraph(target, sub, args) {
     }
 
     log(`Local graph: ${localNodes} nodes, ${localEdges} edges`);
+    const structuralSummary = readStructuralMemorySummary(target);
+    for (const line of formatStructuralMemorySummary(structuralSummary)) {
+      log(line);
+    }
 
     // Check plan for edge sync status
     let auth;
     try { auth = JSON.parse(fs.readFileSync(AUTH_FILE, "utf8")); } catch {}
-    if (auth && auth.access_token) {
+    if (graphAuthToken(auth)) {
       const plan = (auth.plan || "free").toLowerCase();
       const edgeStatus = plan === "free" ? `${D}nodes only (Pro for edges)${R}` : `${T}full sync${R}`;
       log(`Server sync: ${edgeStatus}`);
@@ -174,7 +235,7 @@ async function cmdGraph(target, sub, args) {
     const nodeIdx = args.indexOf("--node");
     const nodeId = nodeIdx >= 0 ? args[nodeIdx + 1] : null;
 
-    if (["pro", "team", "enterprise"].includes(plan) && auth.access_token) {
+    if (["pro", "team", "enterprise"].includes(plan) && graphAuthToken(auth)) {
       const identity = buildProjectIdentity(target, collectMetadata(target));
       const params = new URLSearchParams({
         project_id: identity.project_id,
@@ -236,7 +297,7 @@ async function cmdGraph(target, sub, args) {
       log(`${D}Outcomes require Pro plan. Upgrade: 0dai upgrade${R}`);
       return;
     }
-    if (!auth.access_token) {
+    if (!graphAuthToken(auth)) {
       log("Graph outcomes requires an account. Run: 0dai auth login");
       return;
     }
@@ -267,4 +328,11 @@ async function cmdGraph(target, sub, args) {
   console.log("  outcomes Show outcome analytics (Pro only)");
 }
 
-module.exports = { cmdGraph };
+module.exports = {
+  cmdGraph,
+  graphAuthToken,
+  graphPayloadForPush,
+  isPaidGraphPlan,
+  readStructuralMemorySummary,
+  formatStructuralMemorySummary,
+};

package/lib/commands/heatmap.js

@@ -0,0 +1,17 @@
+"use strict";
+const shared = require("../shared");
+const { log, spawnSync, findRepoScript } = shared;
+
+function cmdHeatmap(target, args) {
+  const script = findRepoScript(target, "heatmap.py");
+  if (!script) {
+    log("heatmap script unavailable in this environment");
+    return;
+  }
+
+  const forwarded = [script, "--target", target, ...(args || [])];
+  const result = spawnSync("python3", forwarded, { stdio: "inherit" });
+  if (typeof result.status === "number" && result.status !== 0) process.exit(result.status);
+}
+
+module.exports = { cmdHeatmap };