@gobing-ai/spur 0.3.53 → 0.3.55

package/plugins/sp/scripts/feature-sync-bounded.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// plugins/sp/scripts/feature-sync-bounded.ts
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+function classifySyncResult(result) {
+  if (result.proposal.gateBlocked === true)
+    return "blocked";
+  if (result.applied === true)
+    return "applied";
+  if (result.proposal.from !== result.proposal.to)
+    return "blocked";
+  return "no-op";
+}
+function computeFingerprint(input) {
+  const material = [
+    input.featureContentHash,
+    ...[...input.taskStatusVector].sort(),
+    ...[...input.verdictMtimeVector].sort()
+  ].join(`
+`);
+  return createHash("sha256").update(material).digest("hex").slice(0, 32);
+}
+var blockedStateFile = (featureId, runDir) => `${runDir.replace(/\/$/, "")}/feature-sync-blocked-${featureId}.json`;
+function serializeBlockedState(state) {
+  return `${JSON.stringify(state)}
+`;
+}
+function parseBlockedState(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0)
+    return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed.featureId !== "string" || typeof parsed.inputFingerprint !== "string" || typeof parsed.proposal !== "object" || parsed.proposal === null) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function shouldSuppressBlocked(prior, currentFingerprint) {
+  if (!prior)
+    return { suppress: false };
+  if (prior.inputFingerprint === currentFingerprint) {
+    return { suppress: true, replay: prior.result };
+  }
+  return { suppress: false };
+}
+function decideBoundedSync(prior, currentFingerprint) {
+  const decision = shouldSuppressBlocked(prior, currentFingerprint);
+  if (decision.suppress && decision.replay) {
+    return { kind: "suppress", replay: decision.replay };
+  }
+  return { kind: "invoke" };
+}
+function processSyncResult(result, currentFingerprint, persistedAt, wasSuppressed) {
+  const classification = classifySyncResult(result);
+  if (classification === "blocked") {
+    return {
+      classification,
+      emit: result,
+      persist: {
+        featureId: result.proposal.featureId,
+        inputFingerprint: currentFingerprint,
+        proposal: result.proposal,
+        classification,
+        result,
+        persistedAt
+      },
+      annotation: wasSuppressed ? `feature-sync-bounded: suppressed duplicate blocked sync for ${result.proposal.featureId} (inputs unchanged)` : `feature-sync-bounded: blocked proposal for ${result.proposal.featureId} — ${result.proposal.reason}`
+    };
+  }
+  return {
+    classification,
+    emit: result,
+    annotation: ""
+  };
+}
+var BOUNDED_SYNC_CLI_USAGE = `Usage:
+  bun plugins/sp/scripts/feature-sync-bounded.ts <feature-id> \\
+    --spur-bin <spur|bun apps/cli/src/index.ts> \\
+    [--run-dir .spur/run] [--json]
+
+Wraps 'spur feature sync <id> --json' with bounded retry-suppression: an identical
+blocked proposal is reported once and suppressed until feature file content, linked
+task statuses, or verdict artifact mtimes change. Applied and no-op results pass
+through unchanged.
+
+Exit: 0 = sync handled (applied / no-op / suppressed-blocked / live-blocked).`;
+function defaultSpurBin() {
+  if (process.env.SPUR_BIN)
+    return process.env.SPUR_BIN;
+  const local = fileURLToPath(new URL("../../../apps/cli/src/index.ts", import.meta.url));
+  if (existsSync(local))
+    return `bun ${local}`;
+  return "spur";
+}
+function parseBoundedSyncCliArgs(argv) {
+  let featureId = "";
+  let spurBin = defaultSpurBin();
+  let runDir = ".spur/run";
+  let json = false;
+  let help = false;
+  for (let i = 0;i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h")
+      help = true;
+    else if (a === "--json")
+      json = true;
+    else if (a === "--spur-bin")
+      spurBin = argv[++i] ?? spurBin;
+    else if (a === "--run-dir")
+      runDir = argv[++i] ?? runDir;
+    else if (!a.startsWith("--") && featureId === "")
+      featureId = a;
+  }
+  return { featureId, spurBin, runDir, json, help };
+}
+function runSpurJson(spurBin, args) {
+  const binParts = spurBin.split(/\s+/).filter(Boolean);
+  const cmd = binParts[0] ?? "spur";
+  const cmdArgs = [...binParts.slice(1), ...args];
+  const r = spawnSync(cmd, cmdArgs, { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+  const decode = (b) => typeof b === "string" ? b : Buffer.from(b ?? []).toString("utf8");
+  return {
+    stdout: typeof r.stdout === "string" ? r.stdout : decode(r.stdout),
+    stderr: typeof r.stderr === "string" ? r.stderr : decode(r.stderr),
+    exitCode: r.status ?? (r.error ? 1 : 0),
+    ok: (r.status ?? (r.error ? 1 : 0)) === 0
+  };
+}
+function readFeatureContentHash(spurBin, featureId) {
+  const r = runSpurJson(spurBin, ["feature", "show", featureId, "--json"]);
+  if (!r.ok)
+    return null;
+  try {
+    const parsed = JSON.parse(r.stdout);
+    if (typeof parsed.content !== "string")
+      return null;
+    return createHash("sha256").update(parsed.content).digest("hex");
+  } catch {
+    return null;
+  }
+}
+function readTaskStatusVector(spurBin, featureId) {
+  const r = runSpurJson(spurBin, ["task", "list", "--feature", featureId, "--json"]);
+  if (!r.ok)
+    return null;
+  try {
+    const parsed = JSON.parse(r.stdout);
+    return parsed.filter((t) => typeof t.wbs === "string" && typeof t.status === "string").map((t) => `${t.wbs}:${t.status}`).sort();
+  } catch {
+    return null;
+  }
+}
+function readVerdictMtimeVector(runDir) {
+  const dir = runDir.replace(/\/$/, "");
+  let entries;
+  try {
+    entries = readdirSync(dir).filter((f) => f.endsWith("-verdict.json"));
+  } catch {
+    return [];
+  }
+  const vector = [];
+  for (const entry of entries) {
+    try {
+      const mtime = statSync(`${dir}/${entry}`).mtimeMs;
+      vector.push(`${entry.replace("-verdict.json", "")}:${mtime}`);
+    } catch {}
+  }
+  return vector.sort();
+}
+function writeBlockedState(state, path) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serializeBlockedState(state));
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`feature-sync-bounded: could not persist blocked state to ${path} — ${reason}
+`);
+  }
+}
+function readBlockedState(path) {
+  try {
+    if (!existsSync(path))
+      return null;
+    const text = readFileSync(path, "utf8");
+    return parseBlockedState(text);
+  } catch {
+    return null;
+  }
+}
+function runBoundedCli(argv) {
+  const args = parseBoundedSyncCliArgs(argv);
+  if (args.help)
+    return { exitCode: 0, stdout: "", stderr: BOUNDED_SYNC_CLI_USAGE };
+  if (!args.featureId)
+    return { exitCode: 1, stdout: "", stderr: BOUNDED_SYNC_CLI_USAGE };
+  const statePath = blockedStateFile(args.featureId, args.runDir);
+  const prior = readBlockedState(statePath);
+  const featureContentHash = readFeatureContentHash(args.spurBin, args.featureId);
+  const taskStatusVector = readTaskStatusVector(args.spurBin, args.featureId);
+  if (featureContentHash === null || taskStatusVector === null) {
+    return invokeLiveSync(args, statePath);
+  }
+  const verdictMtimeVector = readVerdictMtimeVector(args.runDir);
+  const currentFingerprint = computeFingerprint({
+    featureContentHash,
+    taskStatusVector,
+    verdictMtimeVector
+  });
+  const decision = decideBoundedSync(prior, currentFingerprint);
+  if (decision.kind === "suppress") {
+    const processed = processSyncResult(decision.replay, currentFingerprint, new Date().toISOString(), true);
+    emitResult(processed.emit, processed.annotation, args.json);
+    return { exitCode: 0, stdout: "", stderr: "" };
+  }
+  return invokeLiveSync(args, statePath, currentFingerprint);
+}
+function invokeLiveSync(args, statePath, fingerprint) {
+  const r = runSpurJson(args.spurBin, ["feature", "sync", args.featureId, "--json"]);
+  if (!r.ok) {
+    return { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr };
+  }
+  let result;
+  try {
+    result = JSON.parse(r.stdout);
+  } catch {
+    return { exitCode: r.exitCode, stdout: r.stdout, stderr: "" };
+  }
+  if (!result || typeof result !== "object" || !result.proposal) {
+    return {
+      exitCode: r.exitCode,
+      stdout: r.stdout,
+      stderr: "unrecognized feature sync envelope: missing proposal"
+    };
+  }
+  const currentFingerprint = fingerprint ?? computeFingerprint({
+    featureContentHash: readFeatureContentHash(args.spurBin, args.featureId) ?? "",
+    taskStatusVector: readTaskStatusVector(args.spurBin, args.featureId) ?? [],
+    verdictMtimeVector: readVerdictMtimeVector(args.runDir)
+  });
+  const processed = processSyncResult(result, currentFingerprint, new Date().toISOString(), false);
+  if (processed.persist)
+    writeBlockedState(processed.persist, statePath);
+  emitResult(processed.emit, processed.annotation, args.json);
+  return { exitCode: 0, stdout: "", stderr: "" };
+}
+function emitResult(result, annotation, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(result)}
+`);
+  } else {
+    process.stdout.write(`${result.proposal.featureId}: ${result.proposal.from} → ${result.proposal.to} (applied=${result.applied})
+`);
+  }
+  if (annotation.length > 0)
+    process.stderr.write(`${annotation}
+`);
+}
+{
+  const { exitCode, stdout, stderr } = runBoundedCli(process.argv.slice(2));
+  if (stdout)
+    process.stdout.write(stdout);
+  if (stderr)
+    process.stderr.write(`${stderr}
+`);
+  process.exit(exitCode);
+}
+export {
+  shouldSuppressBlocked,
+  serializeBlockedState,
+  runBoundedCli,
+  processSyncResult,
+  parseBoundedSyncCliArgs,
+  parseBlockedState,
+  defaultSpurBin,
+  decideBoundedSync,
+  computeFingerprint,
+  classifySyncResult,
+  blockedStateFile,
+  BOUNDED_SYNC_CLI_USAGE
+};

package/plugins/sp/scripts/feature-sync-bounded.ts

@@ -19,6 +19,7 @@
  * to avoid importing service packages into the plugin tree.
  */
 
+import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
@@ -280,14 +281,14 @@ function runSpurJson(spurBin: string, args: string[]): SpawnResult {
     const binParts = spurBin.split(/\s+/).filter(Boolean);
     const cmd = binParts[0] ?? 'spur';
     const cmdArgs = [...binParts.slice(1), ...args];
-    const r = Bun.spawnSync({ cmd: [cmd, ...cmdArgs], stdio: ['ignore', 'pipe', 'pipe'] });
+    const r = spawnSync(cmd, cmdArgs, { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf8' });
     const decode = (b: unknown): string =>
         typeof b === 'string' ? b : Buffer.from((b as Uint8Array) ?? []).toString('utf8');
     return {
-        stdout: decode(r.stdout),
-        stderr: decode(r.stderr),
-        exitCode: r.exitCode ?? 0,
-        ok: (r.exitCode ?? 0) === 0,
+        stdout: typeof r.stdout === 'string' ? r.stdout : decode(r.stdout),
+        stderr: typeof r.stderr === 'string' ? r.stderr : decode(r.stderr),
+        exitCode: r.status ?? (r.error ? 1 : 0),
+        ok: (r.status ?? (r.error ? 1 : 0)) === 0,
     };
 }
 
@@ -361,8 +362,8 @@ function writeBlockedState(state: BlockedState, path: string): void {
 
 function readBlockedState(path: string): BlockedState | null {
     try {
-        const f = Bun.file(path);
-        const text = f.size > 0 ? readFileSync(path, 'utf8') : '';
+        if (!existsSync(path)) return null;
+        const text = readFileSync(path, 'utf8');
         return parseBlockedState(text);
     } catch {
         return null;
@@ -470,7 +471,7 @@ function emitResult(result: FeatureSyncResult, annotation: string, json: boolean
 }
 
 if (import.meta.main) {
-    const { exitCode, stdout, stderr } = runBoundedCli(Bun.argv.slice(2));
+    const { exitCode, stdout, stderr } = runBoundedCli(process.argv.slice(2));
     if (stdout) process.stdout.write(stdout);
     if (stderr) process.stderr.write(`${stderr}\n`);
     process.exit(exitCode);

package/plugins/sp/scripts/history-load.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/history-load.ts
+import { spawnSync } from "child_process";
+import { existsSync, realpathSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+var VALUE_FLAGS = {
+  "--source": true,
+  "--session": true,
+  "--task": true,
+  "--since": true,
+  "--until": true
+};
+var BOOL_FLAGS = {
+  "--report": true,
+  "--dry-run": true,
+  "--json": true
+};
+var ALL_FLAGS = { ...VALUE_FLAGS, ...BOOL_FLAGS };
+function usage() {
+  console.error("Usage: history-load.ts [--source <name>] [--session <id>] [--task <wbs>] " + "[--since <iso>] [--until <iso>] [--report] [--dry-run] [--json]");
+  process.exit(2);
+}
+var FLAG_KEY = {
+  "--source": "source",
+  "--session": "session",
+  "--task": "task",
+  "--since": "since",
+  "--until": "until",
+  "--report": "report",
+  "--dry-run": "dryRun",
+  "--json": "json"
+};
+function parseArgs(argv) {
+  const out = { report: false, dryRun: false, json: false };
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--") || ALL_FLAGS[arg] !== true)
+      usage();
+    if (BOOL_FLAGS[arg] === true) {
+      out[FLAG_KEY[arg]] = true;
+      continue;
+    }
+    const value = argv[++i];
+    if (value === undefined || value.startsWith("--"))
+      usage();
+    out[FLAG_KEY[arg]] = value;
+  }
+  return out;
+}
+function defaultSpurBin() {
+  if (process.env.SPUR_BIN)
+    return process.env.SPUR_BIN;
+  const local = fileURLToPath(new URL("../../../apps/cli/src/index.ts", import.meta.url));
+  if (existsSync(local))
+    return `bun ${local}`;
+  return "spur";
+}
+function runSpur(spurBin, args) {
+  const [file = "spur", ...lead] = spurBin.split(/\s+/).filter(Boolean);
+  const result = spawnSync(file, [...lead, ...args], { encoding: "utf-8" });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? ""
+  };
+}
+function latestArtifactPath(cwd) {
+  const pointer = join(cwd, ".spur", "reports", "history", "latest.json");
+  if (!existsSync(pointer))
+    return null;
+  try {
+    return realpathSync(pointer);
+  } catch {
+    return null;
+  }
+}
+function parseImportJson(stdout) {
+  try {
+    const parsed = JSON.parse(stdout);
+    return parsed && Array.isArray(parsed.entries) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function buildAnalyzeArgs(args) {
+  const out = ["history", "analyze", "--json"];
+  if (args.source)
+    out.push("--source", args.source);
+  if (args.session)
+    out.push("--session", args.session);
+  if (args.task)
+    out.push("--task", args.task);
+  if (args.since)
+    out.push("--since", args.since);
+  if (args.until)
+    out.push("--until", args.until);
+  return out;
+}
+function emitJson(obj) {
+  process.stdout.write(`${JSON.stringify(obj)}
+`);
+}
+function buildDegradedWarnings(imp) {
+  const detailFor = (source) => imp?.warnings?.find((w) => w.source === source)?.detail ?? "no warning detail reported by import";
+  return (imp?.entries ?? []).filter((e) => e.status === "degraded" || e.status === "failed").map((e) => ({
+    source: e.source,
+    status: e.status,
+    parseErrors: typeof e.parseErrors === "number" ? e.parseErrors : 0,
+    validationErrors: typeof e.validationErrors === "number" ? e.validationErrors : 0,
+    detail: detailFor(e.source)
+  }));
+}
+function withWarnings(payload, degraded) {
+  return degraded.length > 0 ? { ...payload, warnings: degraded } : payload;
+}
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const spurBin = defaultSpurBin();
+  const cwd = process.cwd();
+  const importArgs = ["history", "import", "--json"];
+  if (args.source)
+    importArgs.push("--source", args.source);
+  if (args.dryRun)
+    importArgs.push("--dry-run");
+  const importResult = runSpur(spurBin, importArgs);
+  const imp = parseImportJson(importResult.stdout);
+  if (importResult.status !== 0 && importResult.status !== 2) {
+    const failed = (imp?.entries ?? []).filter((e) => e.status !== "ok" && e.status !== "empty").map((e) => e.source);
+    const warning = imp?.warnings?.find((w) => w.code === "source-failed" || w.code === "source-degraded");
+    const detail = warning?.detail || importResult.stderr.trim() || "import exited non-zero";
+    const message = failed.length > 0 ? `import failed for source(s): ${failed.join(", ")} \u2014 ${detail}` : detail;
+    if (args.json) {
+      emitJson({
+        import: imp ?? { entries: [], exitCode: importResult.status },
+        artifact: null,
+        reported: false,
+        status: "error",
+        message
+      });
+    } else {
+      console.error(message);
+    }
+    process.exit(importResult.status);
+  }
+  const degraded = importResult.status === 2 ? buildDegradedWarnings(imp) : [];
+  if (degraded.length > 0 && !args.json) {
+    console.error("WARNING: import fan-out degraded \u2014 proceeding with the healthy sources:");
+    for (const w of degraded) {
+      console.error(`  ${w.source}: status=${w.status} parseErrors=${w.parseErrors} ` + `validationErrors=${w.validationErrors} \u2014 ${w.detail}`);
+    }
+  }
+  if (args.dryRun) {
+    const analyzeArgs = buildAnalyzeArgs(args);
+    const sequence = [`spur history import --json${args.source ? ` --source ${args.source}` : ""} --dry-run`];
+    sequence.push(`spur ${analyzeArgs.join(" ")}`);
+    if (args.report)
+      sequence.push("spur history report --mode forensics <artifact-path>");
+    if (args.json) {
+      emitJson(withWarnings({
+        import: imp ?? { entries: [], exitCode: importResult.status },
+        artifact: null,
+        reported: false,
+        status: "dry-run",
+        wouldRun: sequence
+      }, degraded));
+    } else {
+      console.log("[dry-run] would run:");
+      for (const line of sequence)
+        console.log(`  ${line}`);
+    }
+    process.exit(0);
+  }
+  const analyzeResult = runSpur(spurBin, buildAnalyzeArgs(args));
+  if (analyzeResult.status !== 0) {
+    const message = analyzeResult.stderr.trim() || `history analyze exited non-zero (${analyzeResult.status})`;
+    if (args.json) {
+      emitJson({
+        import: imp ?? { entries: [], exitCode: 0 },
+        artifact: null,
+        reported: false,
+        status: "error",
+        message
+      });
+    } else {
+      console.error(message);
+    }
+    process.exit(analyzeResult.status);
+  }
+  let artifact = null;
+  try {
+    artifact = JSON.parse(analyzeResult.stdout);
+  } catch {}
+  const artifactPath = latestArtifactPath(cwd);
+  const messages = artifact?.totals?.messages;
+  if (typeof messages === "number" && messages === 0) {
+    const message = "history analyze: window matched zero messages \u2014 nothing to report";
+    if (args.json) {
+      emitJson({
+        import: imp ?? { entries: [], exitCode: 0 },
+        artifact: artifactPath,
+        reported: false,
+        status: "empty-window",
+        message
+      });
+    } else {
+      console.error(message);
+    }
+    process.exit(1);
+  }
+  if (artifactPath === null) {
+    const message = "history analyze completed but no artifact pointer (.spur/reports/history/latest.json) was found";
+    if (args.json) {
+      emitJson({
+        import: imp ?? { entries: [], exitCode: 0 },
+        artifact: null,
+        reported: false,
+        status: "error",
+        message
+      });
+    } else {
+      console.error(message);
+    }
+    process.exit(1);
+  }
+  let reported = false;
+  let reportText = "";
+  if (args.report) {
+    const reportResult = runSpur(spurBin, ["history", "report", "--mode", "forensics", artifactPath]);
+    reported = reportResult.status === 0;
+    reportText = reportResult.stdout;
+    if (reportResult.status !== 0) {
+      const message = reportResult.stderr.trim() || `history report exited non-zero (${reportResult.status})`;
+      if (args.json) {
+        emitJson({
+          import: imp ?? { entries: [], exitCode: 0 },
+          artifact: artifactPath,
+          reported: false,
+          status: "error",
+          message
+        });
+      } else {
+        console.error(message);
+      }
+      process.exit(reportResult.status);
+    }
+  }
+  const count = (imp?.entries ?? []).reduce((sum, e) => sum + (typeof e.messages === "number" ? e.messages : 0), 0);
+  if (args.json) {
+    const payload = withWarnings({
+      import: imp ?? { entries: [], exitCode: 0 },
+      artifact: artifactPath,
+      reported,
+      status: "ok"
+    }, degraded);
+    if (args.report)
+      payload.report = reportText;
+    emitJson(payload);
+  } else {
+    console.log(`history import: ${count} records`);
+    console.log(`artifact: ${artifactPath}`);
+    if (args.report)
+      process.stdout.write(reportText);
+  }
+}
+main();