@0dai-dev/cli 4.3.5 → 4.3.7

package/lib/commands/experience.js

@@ -1,12 +1,43 @@
 "use strict";
+const fs = require("fs");
+const path = require("path");
 const shared = require("../shared");
 const { log, D, R, spawnSync, findRepoScript } = shared;
 
+// npm-installed users have no repo checkout. Fall back to the self-contained
+// python experience closure bundled into the package at lib/python/ by
+// scripts/build-python-bundle.js (#4360).
+function resolveBundledScript(name) {
+  const bundled = path.join(__dirname, "..", "python", name);
+  return fs.existsSync(bundled) ? bundled : null;
+}
+
+function resolvePythonScript(target, name) {
+  return findRepoScript(target, name) || resolveBundledScript(name);
+}
+
+function printExperienceHelp() {
+  console.log("Usage: 0dai experience [list|stats|record-json|sync|warnings|dismiss]");
+  console.log("");
+  console.log("Commands:");
+  console.log("  list         Show recent local experience events");
+  console.log("  stats        Summarize local experience events");
+  console.log("  record-json  Record one JSON payload through the repo experience helper");
+  console.log("  sync         Sync eligible events when the repo helper permits it");
+  console.log("  warnings     Show anti-pattern warnings");
+  console.log("  dismiss      Dismiss an anti-pattern warning");
+}
+
 function cmdExperience(target, sub, args) {
-  const experienceScript = findRepoScript(target, "experience_pipeline.py");
+  if (sub === "--help" || sub === "-h" || args.includes("--help") || args.includes("-h")) {
+    printExperienceHelp();
+    process.exit(0);
+  }
+
+  const experienceScript = resolvePythonScript(target, "experience_pipeline.py");
   if (!experienceScript) {
     log("experience pipeline unavailable in this environment");
-    console.log(`  ${D}Expected scripts/experience_pipeline.py in repo checkout${R}`);
+    console.log(`  ${D}Needs scripts/experience_pipeline.py (repo) or the bundled lib/python copy; requires python3${R}`);
     process.exit(1);
   }
 
@@ -34,8 +65,12 @@ function cmdExperience(target, sub, args) {
     if (args.includes("--json")) forwarded.push("--json");
     const limitIdx = args.indexOf("--limit");
     if (limitIdx >= 0 && args[limitIdx + 1]) forwarded.push("--limit", args[limitIdx + 1]);
+  } else if (command === "record-json") {
+    if (args.includes("--json")) forwarded.push("--json");
+    const payloadIdx = args.indexOf("--payload");
+    if (payloadIdx >= 0 && args[payloadIdx + 1]) forwarded.push("--payload", args[payloadIdx + 1]);
   } else if (command === "warnings") {
-    const detectorScript = findRepoScript(target, "anti_pattern_detector.py");
+    const detectorScript = resolvePythonScript(target, "anti_pattern_detector.py");
     if (!detectorScript) { log("anti-pattern detector unavailable"); process.exit(1); }
     const fwd = [detectorScript, "warnings", "--target", target];
     if (args.includes("--json")) fwd.push("--json");
@@ -47,7 +82,7 @@ function cmdExperience(target, sub, args) {
     if (typeof wr.status === "number") process.exit(wr.status);
     process.exit(1);
   } else if (command === "dismiss") {
-    const detectorScript = findRepoScript(target, "anti_pattern_detector.py");
+    const detectorScript = resolvePythonScript(target, "anti_pattern_detector.py");
     if (!detectorScript) { log("anti-pattern detector unavailable"); process.exit(1); }
     const patternId = args.find(a => a && !a.startsWith("-")) || "";
     if (!patternId) { console.log("Usage: 0dai experience dismiss <pattern_id>"); process.exit(1); }
@@ -57,7 +92,7 @@ function cmdExperience(target, sub, args) {
     if (typeof dr.status === "number") process.exit(dr.status);
     process.exit(1);
   } else {
-    console.log("Usage: 0dai experience [list|stats|sync|warnings|dismiss]");
+    printExperienceHelp();
     process.exit(1);
   }
 

package/lib/commands/export.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 0dai.dev
+//
+// F14 G4 Phase 2 — `0dai export --all` CLI command.
+//
+// Bundles user-owned tenant data into a tarball per the contract
+// at docs/governance/data-export-contract.md (F14 G4 Phase 1 /
+// PR #3569). Phase 2 ships personas + path-protect.yaml as real
+// data, plus usage-ledger.jsonl when present; the other 6 surfaces emit placeholder JSON
+// ({"_status": "not-implemented", "since": "F14 G4 Phase 2"}).
+//
+// Cosign signing is deferred to Phase 3 (stubs .sig + .crt as
+// empty files alongside the tarball so the layout contract holds).
+//
+// Usage:
+//   0dai export --all [--output PATH] [--target DIR]
+
+"use strict";
+
+const shared = require("../shared");
+const { T, R, D, log } = shared;
+const { buildExportTarball } = require("../utils/export-bundler");
+
+function parseExportArgs(args) {
+  const out = { all: false, output: null, target: process.cwd() };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--all") out.all = true;
+    else if (a === "--output" && args[i + 1]) { out.output = args[i + 1]; i++; }
+    else if (a === "--target" && args[i + 1]) { out.target = args[i + 1]; i++; }
+  }
+  return out;
+}
+
+function defaultOutputName() {
+  const now = new Date().toISOString().replace(/[:.]/g, "-").replace(/Z$/, "Z");
+  return `0dai-export-${now}.tar.gz`;
+}
+
+async function cmdExport(target, args) {
+  const opts = parseExportArgs(args);
+  if (!opts.all) {
+    console.error(`${T}[0dai-export]${R} --all is required (partial export is a Phase 2 follow-up)`);
+    process.exit(2);
+  }
+  const sourceRoot = opts.target || target || process.cwd();
+  const outputPath = opts.output || defaultOutputName();
+
+  log(`tenant data source: ${sourceRoot}`);
+  log(`output:             ${outputPath}`);
+
+  let result;
+  try {
+    result = await buildExportTarball({ sourceRoot, outputPath });
+  } catch (err) {
+    console.error(`${T}[0dai-export]${R} bundle failed: ${err.message}`);
+    process.exit(3);
+  }
+
+  log(`personas:       ${result.counts.personas} bundled`);
+  log(`path-protect:   ${result.counts.pathProtect} file(s)`);
+  log(`usage-ledger:   ${result.counts.usageLedger} file(s)`);
+  log(`placeholders:   ${result.counts.placeholders} surfaces (Phase 2 not-implemented)`);
+  log(`tarball:        ${result.tarballPath}`);
+  log(`sha256:         ${result.sha256}`);
+  if (result.signed) {
+    log(`signature:      cosign keyless signed (${result.sigPath})`);
+  } else {
+    log(`${D}signature:      ${result.signSkipReason} — stub .sig + .crt written${R}`);
+  }
+}
+
+module.exports = { cmdExport };

package/lib/commands/feedback.js

@@ -11,7 +11,9 @@ function writeFeedbackOutbox(target, report, result) {
     queued_at: new Date().toISOString(),
     project: path.basename(target),
     report,
+    error_type: "feedback_endpoint_error",
     error: result && result.error ? result.error : "feedback endpoint did not acknowledge receipt",
+    retry_command: "0dai feedback retry",
     response: result || null,
   }, null, 2) + "\n", { mode: 0o600 });
   return outboxPath;
@@ -33,36 +35,147 @@ function feedbackAccepted(result) {
   return Boolean(result && (result.received || result.ok));
 }
 
-async function cmdFeedbackPush(target) {
+function hasHelp(args = []) {
+  return args.includes("--help") || args.includes("-h");
+}
+
+function printFeedbackHelp() {
+  console.log("Usage: 0dai feedback [push|submit|retry|log|list] [--target PATH] [options]");
+  console.log("");
+  console.log("Commands:");
+  console.log("  push   Send local feedback reports and operational log entries");
+  console.log("  push   Send accepted feedback reports from ai/feedback/");
+  console.log("  retry  Retry queued feedback from a failed push");
+  console.log("  log    Append one feedback item to ai/feedback/operational.jsonl");
+  console.log("  list   List local feedback report files");
+}
+
+function printFeedbackPushHelp() {
+  console.log("Usage: 0dai feedback push --target PATH");
+  console.log("");
+  console.log("Sends accepted feedback reports from ai/feedback/ and operational.jsonl entries.");
+  console.log("Accepted reports: ai/feedback/*-report.json and ai/feedback/YYYYMMDD*.json.");
+  console.log("Accepted log: ai/feedback/operational.jsonl.");
+}
+
+function printFeedbackSubmitHelp() {
+  console.log("Usage: 0dai feedback push --target PATH");
+  console.log("");
+  console.log("Sends one accepted feedback report file. Use feedback push to send every accepted local report.");
+}
+
+function printFeedbackRetryHelp() {
+  console.log("Usage: 0dai feedback retry [--json]");
+  console.log("");
+  console.log("Retries queued feedback submissions from ~/.0dai/feedback-outbox/.");
+}
+
+function printFeedbackLogHelp() {
+  console.log("Usage: 0dai feedback log --type bug|suggestion|friction|positive --detail '...'");
+  console.log("");
+  console.log("Records one local feedback entry without sending it.");
+}
+
+function printFeedbackListHelp() {
+  console.log("Usage: 0dai feedback list");
+  console.log("");
+  console.log("Lists local *-report.json feedback files.");
+}
+
+function resolveFeedbackSubmitFile(target, fileArg) {
+  if (!fileArg) return { error: "missing --file" };
+  const fbDir = path.resolve(target, "ai", "feedback");
+  const fullPath = path.resolve(target, fileArg);
+  if (fullPath !== fbDir && !fullPath.startsWith(`${fbDir}${path.sep}`)) {
+    return { error: "file must be under ai/feedback/" };
+  }
+  if (!fs.existsSync(fullPath)) return { error: `file not found: ${fileArg}` };
+  return { fullPath };
+}
+
+async function cmdFeedbackPush(target, options = {}) {
   const fbDir = path.join(target, "ai", "feedback");
+  const onlyFile = options.onlyFile ? path.resolve(options.onlyFile) : "";
   const items = [];
+  const ignored = [];
+  let feedbackDirExists = false;
+  let jsonlStatus = "missing";
+  let includedOperationalLog = false;
+  const acceptedFormats = [
+    "ai/feedback/*-report.json",
+    "ai/feedback/YYYYMMDD*.json",
+    "ai/feedback/operational.jsonl",
+  ];
 
   // Collect from report JSON files
   try {
+    feedbackDirExists = fs.existsSync(fbDir) && fs.statSync(fbDir).isDirectory();
     for (const f of fs.readdirSync(fbDir)) {
-      if (f.endsWith("-report.json") || (f.endsWith(".json") && f.match(/^\d{8}/))) {
-        try {
-          const d = JSON.parse(fs.readFileSync(path.join(fbDir, f), "utf8"));
-          if (d.project || d.verdict) items.push({ type: "report", data: d, file: f });
-        } catch {}
+      const fullPath = path.join(fbDir, f);
+      if (onlyFile && path.resolve(fullPath) !== onlyFile) continue;
+      let stat = null;
+      try { stat = fs.statSync(fullPath); } catch {}
+      if (!stat || !stat.isFile()) {
+        ignored.push({ file: f, reason: "not a regular file" });
+        continue;
+      }
+      if (f === "operational.jsonl") continue;
+      if (!(f.endsWith("-report.json") || (f.endsWith(".json") && f.match(/^\d{8}/)))) {
+        ignored.push({ file: f, reason: "unsupported report name" });
+        continue;
+      }
+      try {
+        const d = JSON.parse(fs.readFileSync(fullPath, "utf8"));
+        if (d.project || d.verdict) items.push({ type: "report", data: d, file: f });
+        else ignored.push({ file: f, reason: "missing project or verdict" });
+      } catch (err) {
+        ignored.push({ file: f, reason: `invalid JSON: ${err.message || err}` });
       }
     }
-  } catch {}
+  } catch (err) {
+    if (!feedbackDirExists) ignored.push({ file: "ai/feedback/", reason: "directory does not exist" });
+    else ignored.push({ file: "ai/feedback/", reason: `could not scan directory: ${err.message || err}` });
+  }
 
   // Collect from operational.jsonl (feedback log entries)
   const jsonlPath = path.join(fbDir, "operational.jsonl");
   try {
-    if (fs.existsSync(jsonlPath)) {
-      const lines = fs.readFileSync(jsonlPath, "utf8").trim().split("\n").filter(Boolean);
-      for (const line of lines) {
-        try { items.push({ type: "log", data: JSON.parse(line) }); } catch {}
+    if (fs.existsSync(jsonlPath) && (!onlyFile || path.resolve(jsonlPath) === onlyFile)) {
+      const raw = fs.readFileSync(jsonlPath, "utf8");
+      const lines = raw.trim().split("\n").filter(Boolean);
+      jsonlStatus = lines.length ? `${lines.length} line(s)` : "empty";
+      if (!lines.length) ignored.push({ file: "operational.jsonl", reason: "empty log" });
+      for (const [idx, line] of lines.entries()) {
+        try {
+          items.push({ type: "log", data: JSON.parse(line) });
+          includedOperationalLog = true;
+        }
+        catch (err) {
+          ignored.push({ file: `operational.jsonl:${idx + 1}`, reason: `invalid JSON: ${err.message || err}` });
+        }
       }
     }
-  } catch {}
+  } catch (err) {
+    jsonlStatus = `unreadable: ${err.message || err}`;
+    ignored.push({ file: "operational.jsonl", reason: jsonlStatus });
+  }
 
   if (!items.length) {
     log("no feedback found");
+    console.log(`  ${D}scanned: ${fbDir}${R}`);
+    console.log(`  ${D}accepted inputs: ${acceptedFormats.join(", ")}${R}`);
+    console.log(`  ${D}operational log: ${jsonlStatus}${R}`);
+    const shownIgnored = ignored.slice(0, 8);
+    for (const item of shownIgnored) {
+      console.log(`  ${D}ignored ${item.file}: ${item.reason}${R}`);
+    }
+    if (ignored.length > shownIgnored.length) {
+      console.log(`  ${D}ignored ${ignored.length - shownIgnored.length} more item(s)${R}`);
+    }
     console.log(`  ${D}Log feedback first: 0dai feedback log --type suggestion --detail '...'${R}`);
+    console.log(`  ${D}Report files must include project or verdict before push.${R}`);
+    console.log(`  ${D}Use 0dai feedback push --target . to send accepted reports from ai/feedback/.${R}`);
+    if (onlyFile) process.exitCode = 1;
     return;
   }
 
@@ -81,14 +194,17 @@ async function cmdFeedbackPush(target) {
     if (result.warning) console.log(`  ${D}${result.warning}${R}`);
     if (result.issue_error) console.log(`  ${D}issue warning: ${result.issue_error}${R}`);
     // Archive pushed entries
-    if (fs.existsSync(jsonlPath)) {
+    if (includedOperationalLog && fs.existsSync(jsonlPath)) {
       const archivePath = path.join(fbDir, `pushed-${Date.now()}.jsonl`);
       fs.renameSync(jsonlPath, archivePath);
     }
   } else {
     const outboxPath = writeFeedbackOutbox(target, report, result);
     log(`error: ${(result && result.error) || "unknown"}`);
+    console.log(`  ${D}type: feedback_endpoint_error${R}`);
+    console.log(`  ${D}endpoint: /v1/feedback${R}`);
     console.log(`  ${D}queued for retry: ${outboxPath}${R}`);
+    console.log(`  ${D}retry: 0dai feedback retry${R}`);
     console.log(`  ${D}source feedback was left in place${R}`);
     process.exitCode = 1;
   }
@@ -144,9 +260,35 @@ async function cmdFeedbackRetry(args = []) {
 async function cmdFeedback(target, sub, args) {
   const fbDir = path.join(target, "ai", "feedback");
 
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+    printFeedbackHelp();
+    return;
+  }
+
+  if (hasHelp(args)) {
+    if (sub === "push") printFeedbackPushHelp();
+    else if (sub === "submit") printFeedbackSubmitHelp();
+    else if (sub === "retry") printFeedbackRetryHelp();
+    else if (sub === "log") printFeedbackLogHelp();
+    else if (sub === "list") printFeedbackListHelp();
+    else printFeedbackHelp();
+    return;
+  }
+
   if (sub === "push") {
     return cmdFeedbackPush(target);
   }
+  if (sub === "submit") {
+    const fileArg = args.find((_, i) => args[i - 1] === "--file") || "";
+    const resolved = resolveFeedbackSubmitFile(target, fileArg);
+    if (resolved.error) {
+      log(`feedback submit error: ${resolved.error}`);
+      printFeedbackSubmitHelp();
+      process.exitCode = 1;
+      return;
+    }
+    return cmdFeedbackPush(target, { onlyFile: resolved.fullPath });
+  }
   if (sub === "retry") {
     return cmdFeedbackRetry(args);
   }
@@ -173,7 +315,7 @@ async function cmdFeedback(target, sub, args) {
     } catch { log("no feedback directory"); }
     return;
   }
-  console.log("Usage: 0dai feedback [push|retry|log|list] [--type ...] [--detail '...']");
+  printFeedbackHelp();
 }
 
-module.exports = { cmdFeedbackPush, cmdFeedbackRetry, cmdFeedback, writeFeedbackOutbox, listFeedbackOutbox, feedbackAccepted };
+module.exports = { cmdFeedbackPush, cmdFeedbackRetry, cmdFeedback, writeFeedbackOutbox, listFeedbackOutbox, feedbackAccepted, resolveFeedbackSubmitFile };

package/lib/commands/gh.js

@@ -330,12 +330,38 @@ function hasGithubRemote(target) {
   return /github\.com[:/]/.test(String(result.stdout || ""));
 }
 
+// An existing hook setup that pointing core.hooksPath at .githooks would
+// silently bypass (Husky, or non-sample committed .git/hooks).
+function existingHookSetup(target) {
+  try {
+    if (fs.existsSync(path.join(target, ".husky"))) return ".husky";
+    const hooksDir = path.join(target, ".git", "hooks");
+    if (fs.existsSync(hooksDir)) {
+      const real = fs.readdirSync(hooksDir).filter((f) => !f.endsWith(".sample"));
+      if (real.length) return ".git/hooks";
+    }
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
 function ensureHooksPath(target) {
   if (!isGitRepo(target)) return false;
+  const current = getHooksPath(target);
+  if (current === ".githooks") return true; // already ours — nothing to do
+  // Warn (don't silently clobber) when the user already has hooks we'd bypass.
+  const conflict = current && current !== ".githooks" ? `core.hooksPath=${current}` : existingHookSetup(target);
   const result = spawnSync("git", ["-C", target, "config", "core.hooksPath", ".githooks"], {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
   });
+  if (conflict && result.status === 0) {
+    log(`warning: redirected git hooks to .githooks — your existing hooks (${conflict}) are now bypassed`);
+    console.log(
+      `  ${D}Keep yours: git config core.hooksPath ${current || "<your-path>"} (or chain them from .githooks). Skip 0dai's policy: ODAI_GIT_POLICY_SKIP=1${R}`,
+    );
+  }
   return result.status === 0;
 }
 

package/lib/commands/graph.js

@@ -23,8 +23,12 @@ function graphPayloadForPush(localGraph, auth) {
   };
 }
 
+function missingGraphHint() {
+  return "No local graph found. Create ai/manifest/project_graph.json, or from a repo checkout run: python3 scripts/generate_project_graph.py --target .";
+}
+
 function readStructuralMemorySummary(target) {
-  const script = shared.findRepoScript(target, "structural_memory.py");
+  const script = shared.resolvePythonScript(target, "structural_memory.py");
   if (!script) return null;
   const result = shared.spawnSync("python3", [script, "--target", target, "--json"], {
     encoding: "utf8",
@@ -72,7 +76,7 @@ async function cmdGraph(target, sub, args) {
     }
 
     if (!fs.existsSync(graphFile)) {
-      log("No local graph found. Run: 0dai graph init or create ai/manifest/project_graph.json");
+      log(missingGraphHint());
       return;
     }
 
@@ -264,10 +268,10 @@ async function cmdGraph(target, sub, args) {
 
   if (sub === "context") {
     if (!fs.existsSync(graphFile)) {
-      log("No local graph found. Run: 0dai graph init or create ai/manifest/project_graph.json");
+      log(missingGraphHint());
       return;
     }
-    const slicerScript = shared.findRepoScript(target, "graph_slicer_cli.py");
+    const slicerScript = shared.resolvePythonScript(target, "graph_slicer_cli.py");
     if (!slicerScript) {
       log("graph slicer unavailable in this environment");
       console.log(`  ${D}Expected scripts/graph_slicer_cli.py in repo checkout${R}`);
@@ -333,6 +337,7 @@ module.exports = {
   graphAuthToken,
   graphPayloadForPush,
   isPaidGraphPlan,
+  missingGraphHint,
   readStructuralMemorySummary,
   formatStructuralMemorySummary,
 };

package/lib/commands/heatmap.js

@@ -3,7 +3,7 @@ const shared = require("../shared");
 const { log, spawnSync, findRepoScript } = shared;
 
 function cmdHeatmap(target, args) {
-  const script = findRepoScript(target, "heatmap.py");
+  const script = shared.resolvePythonScript(target, "heatmap.py");
   if (!script) {
     log("heatmap script unavailable in this environment");
     return;