qualia-framework 6.5.0 → 6.6.0

package/bin/auto-report.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// ~/.claude/bin/auto-report.js — B1 auto-capture (framework side).
+//
+// Fires at SHIP TIME: when a Qualia project's tracking.json reaches
+// status `shipped`, POST a session report to the ERP tagged `source: "auto"`,
+// so the ERP reflects real shipped work without anyone running /qualia-report.
+//
+// Design (mirrors the constraints learned the hard way):
+//   • Ship-time, NOT per-turn. The Stop hook fires every turn; this guards on
+//     status===shipped + a per-shipped-unit dedupe marker, so it POSTs exactly
+//     ONCE per shipped (milestone, phase) — never a per-turn spam stream.
+//   • Fail-soft. Never throws, never blocks. On any upload failure it enqueues
+//     to the existing erp-retry queue (drained by session-start) and exits 0.
+//   • One ERP-upload seam. Reuses erp-retry's postOnce/enqueue/config/key
+//     readers and report-payload's buildPayload — no duplicated contract.
+//   • No double-posting. The dedupe marker means re-running on the same shipped
+//     unit is a no-op; the ERP also UPSERTs on (project_id, client_report_id).
+//
+// Invoked fire-and-forget (detached) by hooks/stop-session-log.js, or directly:
+//   node auto-report.js            # run the guarded auto-report for cwd
+//   SOURCE handled internally as "auto"; set DRY_RUN=1 to mark the report dry.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+const { spawnSync } = require("child_process");
+const { buildPayload } = require("./report-payload.js");
+const { enqueue, postOnce, readApiKey, readConfig } = require("./erp-retry.js");
+
+function qualiaHome(home = os.homedir()) {
+  if (process.env.QUALIA_HOME) return process.env.QUALIA_HOME;
+  const parent = path.basename(path.dirname(__dirname));
+  if (parent === ".codex" || parent === ".claude") return path.dirname(__dirname);
+  return path.join(home, ".claude");
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function markerFile(home, projectKey) {
+  const safe = String(projectKey || "project").replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 80);
+  return path.join(qualiaHome(home), `.qualia-auto-report-${safe}.json`);
+}
+
+function erpUrl(cfg) {
+  const base = (cfg && cfg.erp && cfg.erp.url) || "https://portal.qualiasolutions.net";
+  return base.replace(/\/+$/, "") + "/api/v1/reports";
+}
+
+function allocateReportId(cwd) {
+  // Sequential QS-REPORT-NN via state.js (the same allocator /qualia-report uses).
+  try {
+    const r = spawnSync("node", [path.join(__dirname, "state.js"), "next-report-id"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 4000,
+    });
+    if (r.status === 0 && r.stdout) {
+      const parsed = JSON.parse(r.stdout);
+      if (parsed && parsed.report_id) return parsed.report_id;
+    }
+  } catch {}
+  return "";
+}
+
+// The single decision + action. Returns a small status object; never throws.
+async function maybeAutoReport({ cwd = process.cwd(), home = os.homedir(), env = process.env } = {}) {
+  try {
+    // Guard 1 — ERP configured. No key / disabled → silent no-op.
+    const cfg = readConfig();
+    if (cfg && cfg.erp && cfg.erp.enabled === false) return { skipped: "erp-disabled" };
+    const apiKey = readApiKey();
+    if (!apiKey) return { skipped: "no-key" };
+
+    // Guard 2 — Qualia project at SHIP time only.
+    const tracking = readJson(path.join(cwd, ".planning", "tracking.json"));
+    if (!tracking) return { skipped: "no-project" };
+    if (String(tracking.status) !== "shipped") return { skipped: "not-shipped" };
+
+    // Guard 3 — dedupe: one report per shipped (milestone, phase).
+    const projectKey =
+      tracking.project_id ||
+      tracking.project ||
+      path.basename(cwd);
+    const unit = `${tracking.milestone || 1}:${tracking.phase || 0}:shipped`;
+    const mFile = markerFile(home, projectKey);
+    const marker = readJson(mFile) || {};
+    if (marker.last === unit) return { skipped: "already-reported", unit };
+
+    // Allocate a sequential client_report_id (the ERP dedupe key).
+    const clientReportId = allocateReportId(cwd);
+    const idempotencyKey = crypto.randomUUID();
+    const payload = buildPayload({
+      cwd,
+      home,
+      env: { ...env, SOURCE: "auto", CLIENT_REPORT_ID: clientReportId },
+    });
+    const body = JSON.stringify(payload);
+    const url = erpUrl(cfg);
+
+    const result = await postOnce(
+      { url, payload: body, idempotency_key: idempotencyKey },
+      apiKey,
+    );
+
+    const writeMarker = (extra) => {
+      try {
+        fs.writeFileSync(
+          mFile,
+          JSON.stringify({ last: unit, client_report_id: clientReportId, at: new Date().toISOString(), ...extra }, null, 2),
+          { mode: 0o600 },
+        );
+      } catch {}
+    };
+
+    if (result.code === "200") {
+      writeMarker({ posted: true });
+      return { posted: clientReportId, unit };
+    }
+
+    // Any non-200 → enqueue for the retry queue (session-start drains it).
+    // Mark the unit so we don't re-allocate a new id on the next turn; the
+    // queued item carries this client_report_id and the ERP dedupes on it.
+    try {
+      enqueue({
+        client_report_id: clientReportId,
+        idempotency_key: idempotencyKey,
+        url,
+        payload: body,
+        last_error: result.error ? `network: ${result.error}` : `HTTP ${result.code}`,
+      });
+    } catch {}
+    writeMarker({ queued: true, last_error: result.error || `HTTP ${result.code}` });
+    return { queued: clientReportId, unit, error: result.error || `HTTP ${result.code}` };
+  } catch (e) {
+    // Auto-capture must never break a session.
+    return { skipped: "error", error: e && e.message ? e.message : String(e) };
+  }
+}
+
+module.exports = { maybeAutoReport };
+
+if (require.main === module) {
+  maybeAutoReport()
+    .then((r) => {
+      if (process.env.QUALIA_DEBUG) process.stdout.write(JSON.stringify(r) + "\n");
+      process.exit(0);
+    })
+    .catch(() => process.exit(0));
+}

package/bin/erp-retry.js

@@ -274,8 +274,10 @@ function actionClear() {
   log(`queue cleared (backup at ${bak})`);
 }
 
-// ─── Export for in-process use (qualia-report skill enqueues directly) ──
-module.exports = { enqueue, readQueue, writeQueue };
+// ─── Export for in-process use (qualia-report skill enqueues directly;
+//     auto-report.js reuses the POST + config/key readers so there is ONE
+//     ERP-upload seam, not two). ──
+module.exports = { enqueue, readQueue, writeQueue, postOnce, readApiKey, readConfig };
 
 // ─── CLI entrypoint ─────────────────────────────────────
 if (require.main === module) {

package/bin/report-payload.js

@@ -136,6 +136,11 @@ function buildPayload(options = {}) {
     notes,
     submitted_by: env.SUBMITTED_BY || "unknown",
     submitted_at: submittedAt,
+    // B1 — provenance. 'auto' = captured automatically at ship-time (auto-report.js);
+    // 'manual' = a deliberate /qualia-report. Defaults to 'manual' so the manual
+    // flow is unchanged; auto-report passes SOURCE=auto.
+    source: env.SOURCE === "auto" ? "auto" : "manual",
+    ...(env.DRY_RUN === "1" ? { dry_run: true } : {}),
   };
 }
 

package/hooks/stop-session-log.js

@@ -85,6 +85,21 @@ function readJson(p) {
 }
 
 try {
+  // ── B1 auto-capture: fire-and-forget the ship-time auto-report ─────────
+  // Detached subprocess so this hook stays fast (no network here, per its
+  // design). auto-report.js guards on status===shipped + a per-shipped-unit
+  // dedupe marker, so it's a cheap no-op on every turn except the one right
+  // after a ship. Wrapped + unref'd so it never blocks or breaks the session.
+  try {
+    const { spawn } = require("child_process");
+    const child = spawn(
+      process.execPath,
+      [path.join(__dirname, "..", "bin", "auto-report.js")],
+      { cwd: process.cwd(), detached: true, stdio: "ignore" },
+    );
+    child.unref();
+  } catch {}
+
   // ── Skip if too soon since last write ────────────────────
   const now = Date.now();
   let lastWrite = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.5.0",
+  "version": "6.6.0",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/tests/auto-report.test.sh

@@ -0,0 +1,158 @@
+#!/bin/bash
+# tests/auto-report.test.sh — B1 framework auto-capture (bin/auto-report.js +
+# the source field on bin/report-payload.js). Verifies the ship-time trigger,
+# the guards, the source tag, dedupe, and fail-soft enqueue — with a stub ERP
+# server so nothing touches a real endpoint.
+
+FRAMEWORK_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+NODE="${NODE:-node}"
+
+echo "auto-report.test.sh — B1 framework auto-capture"
+
+"$NODE" - "$FRAMEWORK_DIR" <<'NODE'
+const path = require("path");
+const fs = require("fs");
+const os = require("os");
+const http = require("http");
+
+const FRAMEWORK_DIR = process.argv[2];
+let pass = 0, fail = 0;
+const ok = (m) => { console.log("  ✓ " + m); pass++; };
+const bad = (m) => { console.log("  ✗ " + m); fail++; };
+
+function mktemp(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+function setupProject(tmp, tracking) {
+  fs.mkdirSync(path.join(tmp, ".planning"), { recursive: true });
+  fs.writeFileSync(path.join(tmp, ".planning", "tracking.json"), JSON.stringify(tracking));
+}
+function setupHome(home, { key = true, erpUrl, enabled } = {}) {
+  fs.mkdirSync(home, { recursive: true });
+  if (key) fs.writeFileSync(path.join(home, ".erp-api-key"), "qlt_test_key");
+  const cfg = { erp: {} };
+  if (erpUrl) cfg.erp.url = erpUrl;
+  if (enabled === false) cfg.erp.enabled = false;
+  fs.writeFileSync(path.join(home, ".qualia-config.json"), JSON.stringify(cfg));
+}
+
+// Fresh module instances per case (QUALIA_HOME is read at module load).
+function loadAutoReport(home) {
+  process.env.QUALIA_HOME = home;
+  const p1 = require.resolve(path.join(FRAMEWORK_DIR, "bin", "auto-report.js"));
+  const p2 = require.resolve(path.join(FRAMEWORK_DIR, "bin", "erp-retry.js"));
+  delete require.cache[p1];
+  delete require.cache[p2];
+  return require(p1);
+}
+
+(async () => {
+  // ── 1. report-payload tags source correctly ───────────────────────────
+  {
+    const { buildPayload } = require(path.join(FRAMEWORK_DIR, "bin", "report-payload.js"));
+    const proj = mktemp("ar-payload-");
+    setupProject(proj, { status: "shipped", project_id: "p", phase: 1, total_phases: 1 });
+    const auto = buildPayload({ cwd: proj, env: { SOURCE: "auto" } });
+    const manual = buildPayload({ cwd: proj, env: {} });
+    auto.source === "auto" ? ok("buildPayload: SOURCE=auto -> source 'auto'") : bad(`auto source=${auto.source}`);
+    manual.source === "manual" ? ok("buildPayload: default -> source 'manual'") : bad(`default source=${manual.source}`);
+    const dry = buildPayload({ cwd: proj, env: { SOURCE: "auto", DRY_RUN: "1" } });
+    dry.dry_run === true ? ok("buildPayload: DRY_RUN=1 -> dry_run true") : bad("dry_run not set");
+  }
+
+  // ── 2. guard: no API key -> skip ───────────────────────────────────────
+  {
+    const home = mktemp("ar-nokey-home-");
+    setupHome(home, { key: false });
+    const proj = mktemp("ar-nokey-");
+    setupProject(proj, { status: "shipped", project_id: "p" });
+    const { maybeAutoReport } = loadAutoReport(home);
+    const r = await maybeAutoReport({ cwd: proj, home });
+    r.skipped === "no-key" ? ok("guard: no ERP key -> skipped no-key") : bad(`expected no-key, got ${JSON.stringify(r)}`);
+  }
+
+  // ── 3. guard: ERP disabled -> skip ─────────────────────────────────────
+  {
+    const home = mktemp("ar-disabled-home-");
+    setupHome(home, { key: true, enabled: false });
+    const proj = mktemp("ar-disabled-");
+    setupProject(proj, { status: "shipped", project_id: "p" });
+    const { maybeAutoReport } = loadAutoReport(home);
+    const r = await maybeAutoReport({ cwd: proj, home });
+    r.skipped === "erp-disabled" ? ok("guard: ERP disabled -> skipped") : bad(`expected erp-disabled, got ${JSON.stringify(r)}`);
+  }
+
+  // ── 4. guard: status != shipped -> skip ────────────────────────────────
+  {
+    const home = mktemp("ar-notship-home-");
+    setupHome(home, { key: true, erpUrl: "http://127.0.0.1:1" });
+    const proj = mktemp("ar-notship-");
+    setupProject(proj, { status: "built", project_id: "p" });
+    const { maybeAutoReport } = loadAutoReport(home);
+    const r = await maybeAutoReport({ cwd: proj, home });
+    r.skipped === "not-shipped" ? ok("guard: status=built -> skipped not-shipped") : bad(`expected not-shipped, got ${JSON.stringify(r)}`);
+  }
+
+  // ── 5. ship-time POST: source 'auto' reaches the endpoint + dedupe ─────
+  {
+    let received = null;
+    const server = http.createServer((req, res) => {
+      let b = "";
+      req.on("data", (c) => (b += c));
+      req.on("end", () => {
+        try { received = JSON.parse(b); } catch { received = { _raw: b }; }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true, report_id: "QS-REPORT-AUTO" }));
+      });
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const port = server.address().port;
+
+    const home = mktemp("ar-post-home-");
+    setupHome(home, { key: true, erpUrl: `http://127.0.0.1:${port}` });
+    const proj = mktemp("ar-post-");
+    setupProject(proj, { status: "shipped", project_id: "ship-proj", milestone: 1, phase: 3, total_phases: 4 });
+    const { maybeAutoReport } = loadAutoReport(home);
+
+    const r1 = await maybeAutoReport({ cwd: proj, home });
+    (r1.posted !== undefined) ? ok("ship: POST fired (status=shipped)") : bad(`expected posted, got ${JSON.stringify(r1)}`);
+    (received && received.source === "auto") ? ok("ship: endpoint received source 'auto'") : bad(`endpoint source=${received && received.source}`);
+
+    // marker written
+    const markerExists = fs.readdirSync(home).some((f) => f.startsWith(".qualia-auto-report-"));
+    markerExists ? ok("ship: dedupe marker written") : bad("no dedupe marker file");
+
+    // second call on the SAME shipped unit -> dedupe skip (no second POST)
+    received = null;
+    const r2 = await maybeAutoReport({ cwd: proj, home });
+    r2.skipped === "already-reported" ? ok("dedupe: 2nd call -> already-reported") : bad(`expected already-reported, got ${JSON.stringify(r2)}`);
+    received === null ? ok("dedupe: no 2nd POST sent") : bad("a duplicate POST was sent");
+
+    server.close();
+  }
+
+  // ── 6. fail-soft: server 500 -> enqueue, no throw ──────────────────────
+  {
+    const server = http.createServer((req, res) => {
+      let b = ""; req.on("data", (c) => (b += c)); req.on("end", () => { res.writeHead(500); res.end("nope"); });
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const port = server.address().port;
+    const home = mktemp("ar-fail-home-");
+    setupHome(home, { key: true, erpUrl: `http://127.0.0.1:${port}` });
+    const proj = mktemp("ar-fail-");
+    setupProject(proj, { status: "shipped", project_id: "fail-proj", milestone: 1, phase: 1 });
+    const { maybeAutoReport } = loadAutoReport(home);
+    let threw = false, r;
+    try { r = await maybeAutoReport({ cwd: proj, home }); } catch { threw = true; }
+    !threw ? ok("fail-soft: 500 did not throw") : bad("maybeAutoReport threw on 500");
+    (r && r.queued !== undefined) ? ok("fail-soft: failed POST enqueued for retry") : bad(`expected queued, got ${JSON.stringify(r)}`);
+    const queueFile = path.join(home, ".erp-retry-queue.json");
+    fs.existsSync(queueFile) ? ok("fail-soft: retry queue file created") : bad("no retry queue file");
+    server.close();
+  }
+
+  console.log(`\n=== Results: ${pass} passed, ${fail} failed ===`);
+  process.exit(fail === 0 ? 0 : 1);
+})();
+NODE

package/tests/run-all.sh

@@ -12,6 +12,7 @@ SUITES=(
   "state"
   "hooks"
   "bin"
+  "auto-report"
   "lib"
   "skills"
   "refs"