@gobing-ai/spur 0.3.99 → 0.4.1

package/plugins/sp/scripts/batch-plan.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+/**
+ * batch-plan — letters-first batch plan surface (task 1104, feature I13).
+ *
+ * The projection logic lives in packages/app/src/workflow/plan-projection.ts (unit-tested
+ * there); this script is ADR-130 glue — argv/IO only — over the bundled core in
+ * ../lib/plan-projection.generated.* (regenerate: `bun run build:plugin-lib && bun run build:scripts`).
+ *
+ * Modes:
+ *   waves --tasks <file>  file: JSON array of {wbs, name}; prints `{ waves: [...] }` — waves
+ *                         of 24 tasks as A Prepare batch + A1..A4 + B..Y task rows + Z Batch report.
+ *   task-children --letter <A-Z> --plan <file>
+ *                         file: a `workflow show --format todo --json` payload (or a bare plan
+ *                         array); prints the task's phase digits as a JSON array.
+ * Exit 0 on success, 1 on unreadable/invalid input, 2 on usage error. Runs under bare
+ * `node batch-plan.mjs` (committed twin) — keep the twin in lockstep.
+ */
+import { readFileSync } from 'node:fs';
+import type { BatchTask, PhasedPlanItem } from '../lib/plan-projection.generated.mjs';
+import { buildBatchPlan, taskPhaseChildren } from '../lib/plan-projection.generated.mjs';
+
+export * from '../lib/plan-projection.generated.mjs';
+
+export const BATCH_PLAN_USAGE =
+    'usage: batch-plan.ts waves --tasks <tasks.json> | task-children --letter <A-Z> --plan <plan.json>';
+
+function readJsonFile(path: string): unknown {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function isBatchTask(value: unknown): value is BatchTask {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        typeof (value as BatchTask).wbs === 'string' &&
+        typeof (value as BatchTask).name === 'string'
+    );
+}
+
+export function main(argv: string[]): number {
+    const mode = argv[0];
+    if (mode === 'waves') {
+        if (argv[1] !== '--tasks' || argv[2] === undefined) {
+            process.stderr.write(`${BATCH_PLAN_USAGE}\n`);
+            return 2;
+        }
+        let tasks: unknown;
+        try {
+            tasks = readJsonFile(argv[2]);
+        } catch (error) {
+            process.stderr.write(
+                `batch-plan: cannot read ${argv[2]} — ${error instanceof Error ? error.message : String(error)}\n`,
+            );
+            return 1;
+        }
+        if (!Array.isArray(tasks) || !tasks.every(isBatchTask)) {
+            process.stderr.write('batch-plan: --tasks file must be a JSON array of {wbs, name}\n');
+            return 1;
+        }
+        process.stdout.write(`${JSON.stringify({ waves: buildBatchPlan(tasks) })}\n`);
+        return 0;
+    }
+    if (mode === 'task-children') {
+        let letter = '';
+        let planPath = '';
+        for (let i = 1; i + 1 < argv.length; i += 2) {
+            if (argv[i] === '--letter') letter = argv[i + 1] ?? '';
+            else if (argv[i] === '--plan') planPath = argv[i + 1] ?? '';
+        }
+        if (!/^[A-Z]$/.test(letter) || planPath === '') {
+            process.stderr.write(`${BATCH_PLAN_USAGE}\n`);
+            return 2;
+        }
+        let payload: unknown;
+        try {
+            payload = readJsonFile(planPath);
+        } catch (error) {
+            process.stderr.write(
+                `batch-plan: cannot read ${planPath} — ${error instanceof Error ? error.message : String(error)}\n`,
+            );
+            return 1;
+        }
+        // Accept a bare plan array or a full `workflow show --format todo --json` payload.
+        const plan = Array.isArray(payload) ? payload : (payload as { plan?: PhasedPlanItem[] }).plan;
+        if (!Array.isArray(plan)) {
+            process.stderr.write(
+                'batch-plan: --plan file must be a plan array or a todo --json payload with a `plan` field\n',
+            );
+            return 1;
+        }
+        process.stdout.write(`${JSON.stringify(taskPhaseChildren(letter, plan as PhasedPlanItem[]))}\n`);
+        return 0;
+    }
+    process.stderr.write(`${BATCH_PLAN_USAGE}\n`);
+    return 2;
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}

package/plugins/sp/scripts/batch-preflight.mjs

@@ -3,6 +3,30 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // plugins/sp/scripts/batch-preflight.ts
+var NON_ABORTING_PREFLIGHT_CODES = new Set([
+  "L4.scenario-unverified",
+  "L4.verifying-incomplete-tasks"
+]);
+function classifyFeaturePreflightFindings(findings) {
+  const aborting = [];
+  const nonAborting = [];
+  for (const f of findings) {
+    if (f.severity === "error") {
+      if (NON_ABORTING_PREFLIGHT_CODES.has(f.code)) {
+        nonAborting.push(f);
+      } else {
+        aborting.push(f);
+      }
+    } else {
+      nonAborting.push(f);
+    }
+  }
+  return {
+    aborting,
+    nonAborting,
+    shouldAbort: aborting.length > 0
+  };
+}
 function quickReadiness(input) {
   const status = (input.status ?? "").toLowerCase();
   const operation = input.operation;
@@ -190,6 +214,7 @@ function parsePreflightCliArgs(argv) {
   let filteredCount = null;
   let requiredSections = [];
   let presentSections = [];
+  let classifyFeature = null;
   for (let i = 0;i < argv.length; i++) {
     const a = argv[i];
     if (a === "--help" || a === "-h")
@@ -214,7 +239,9 @@ function parsePreflightCliArgs(argv) {
       presentSections = raw.length === 0 ? [] : raw.split(",").map((s) => s.trim()).filter(Boolean);
     } else if (a === "--wbs")
       wbs = argv[++i] ?? wbs;
-    else if (a === "--status")
+    else if (a === "--classify-feature") {
+      classifyFeature = argv[++i] ?? "[]";
+    } else if (a === "--status")
       status = argv[++i] ?? null;
     else if (a === "--deps") {
       const raw = argv[++i] ?? "";
@@ -240,7 +267,8 @@ function parsePreflightCliArgs(argv) {
     force,
     filteredCount,
     requiredSections,
-    presentSections
+    presentSections,
+    classifyFeature
   };
 }
 var PREFLIGHT_CLI_USAGE = `Usage:
@@ -253,6 +281,24 @@ function runPreflightCli(argv) {
   const args = parsePreflightCliArgs(argv);
   if (args.help)
     return { exitCode: 0, stdout: "", stderr: PREFLIGHT_CLI_USAGE };
+  if (args.classifyFeature !== null) {
+    try {
+      const findings = JSON.parse(args.classifyFeature);
+      const res = classifyFeaturePreflightFindings(Array.isArray(findings) ? findings : []);
+      return {
+        exitCode: res.shouldAbort ? 1 : 0,
+        stdout: `${JSON.stringify(res, null, 2)}
+`,
+        stderr: ""
+      };
+    } catch (e) {
+      return {
+        exitCode: 1,
+        stdout: "",
+        stderr: `Invalid JSON for --classify-feature: ${String(e)}`
+      };
+    }
+  }
   if (!args.status)
     return { exitCode: 1, stdout: "", stderr: PREFLIGHT_CLI_USAGE };
   if (args.recovery) {
@@ -327,5 +373,7 @@ export {
   quickReadiness,
   preflightTask,
   parsePreflightCliArgs,
-  PREFLIGHT_CLI_USAGE
+  classifyFeaturePreflightFindings,
+  PREFLIGHT_CLI_USAGE,
+  NON_ABORTING_PREFLIGHT_CODES
 };

package/plugins/sp/scripts/batch-preflight.ts

@@ -25,6 +25,51 @@ export type PreflightResult =
     | { action: 'run'; code?: string; reason?: string }
     | { action: 'skip'; code: string; reason: string; unmetDeps?: string[] };
 
+// ── Feature preflight classification (1132 R4) ──────────────────────────────
+/**
+ * 1132 R4: Codes that are expected pre-run states under `feature check --strict`
+ * and must not abort the batch. Structured classification in code (replaces prose-only).
+ */
+export const NON_ABORTING_PREFLIGHT_CODES = new Set<string>([
+    'L4.scenario-unverified',
+    'L4.verifying-incomplete-tasks',
+]);
+
+export interface FeaturePreflightFinding {
+    layer: string;
+    code: string;
+    severity: string;
+    message: string;
+    section?: string;
+}
+
+export interface FeaturePreflightClassification {
+    aborting: FeaturePreflightFinding[];
+    nonAborting: FeaturePreflightFinding[];
+    shouldAbort: boolean;
+}
+
+export function classifyFeaturePreflightFindings(findings: FeaturePreflightFinding[]): FeaturePreflightClassification {
+    const aborting: FeaturePreflightFinding[] = [];
+    const nonAborting: FeaturePreflightFinding[] = [];
+    for (const f of findings) {
+        if (f.severity === 'error') {
+            if (NON_ABORTING_PREFLIGHT_CODES.has(f.code)) {
+                nonAborting.push(f);
+            } else {
+                aborting.push(f);
+            }
+        } else {
+            nonAborting.push(f);
+        }
+    }
+    return {
+        aborting,
+        nonAborting,
+        shouldAbort: aborting.length > 0,
+    };
+}
+
 // ── Command-aware quick readiness (task 0814 R2) ──────────────────────────────
 // Read-only admission decision for the requested dev operation. Distinguishes
 // runnable / needs-refinement / blocked / skipped / invalid outcomes without
@@ -299,6 +344,8 @@ export interface PreflightCliArgs {
     requiredSections: string[];
     /** Sections actually present in the task. */
     presentSections: string[];
+    /** Feature findings to classify (1132 R4). */
+    classifyFeature: string | null;
 }
 
 export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
@@ -314,6 +361,7 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
     let filteredCount: number | null = null;
     let requiredSections: string[] = [];
     let presentSections: string[] = [];
+    let classifyFeature: string | null = null;
 
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -346,7 +394,9 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
                           .map((s) => s.trim())
                           .filter(Boolean);
         } else if (a === '--wbs') wbs = argv[++i] ?? wbs;
-        else if (a === '--status') status = argv[++i] ?? null;
+        else if (a === '--classify-feature') {
+            classifyFeature = argv[++i] ?? '[]';
+        } else if (a === '--status') status = argv[++i] ?? null;
         else if (a === '--deps') {
             const raw = argv[++i] ?? '';
             deps =
@@ -378,6 +428,7 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
         filteredCount,
         requiredSections,
         presentSections,
+        classifyFeature,
     };
 }
 
@@ -392,6 +443,26 @@ Exit: 0 = run (or recovery hint printed); 2 = skip; 1 = usage.`;
 export function runPreflightCli(argv: string[]): { exitCode: number; stdout: string; stderr: string } {
     const args = parsePreflightCliArgs(argv);
     if (args.help) return { exitCode: 0, stdout: '', stderr: PREFLIGHT_CLI_USAGE };
+
+    // Feature findings classification (1132 R4)
+    if (args.classifyFeature !== null) {
+        try {
+            const findings = JSON.parse(args.classifyFeature);
+            const res = classifyFeaturePreflightFindings(Array.isArray(findings) ? findings : []);
+            return {
+                exitCode: res.shouldAbort ? 1 : 0,
+                stdout: `${JSON.stringify(res, null, 2)}\n`,
+                stderr: '',
+            };
+        } catch (e) {
+            return {
+                exitCode: 1,
+                stdout: '',
+                stderr: `Invalid JSON for --classify-feature: ${String(e)}`,
+            };
+        }
+    }
+
     if (!args.status) return { exitCode: 1, stdout: '', stderr: PREFLIGHT_CLI_USAGE };
 
     if (args.recovery) {

package/plugins/sp/scripts/commit-guard.mjs

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/commit-guard.ts
+import { spawnSync } from "child_process";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { join } from "path";
+var COMMIT_GUARD_USAGE = "usage: commit-guard start --run <id> | stage --run <id> [--base <sha>] -- <paths\u2026> | check --run <id>";
+function isBookkeeping(path) {
+  return path === ".spur" || path.startsWith(".spur/");
+}
+function at(options, rel) {
+  return options.cwd ? join(options.cwd, rel) : rel;
+}
+function artifactPath(run) {
+  return join(".spur", "run", `${run}-tree-start.json`);
+}
+function gitOf(options) {
+  if (options.git)
+    return options.git;
+  return (args) => {
+    const run = spawnSync("git", args, { cwd: options.cwd, encoding: "utf8" });
+    return { status: run.status ?? 1, stdout: run.stdout ?? "" };
+  };
+}
+function hashPath(path, git) {
+  const run = git(["hash-object", "--", path]);
+  return run.status === 0 ? run.stdout.trim() : null;
+}
+function parsePorcelainZ(stdout) {
+  const tokens = stdout.split("\x00");
+  const paths = [];
+  for (let i = 0;i < tokens.length; i++) {
+    const entry = tokens[i] ?? "";
+    if (entry.length < 4)
+      continue;
+    const path = entry.slice(3);
+    if (!isBookkeeping(path))
+      paths.push(path);
+    if (/[RC]/.test(entry.slice(0, 2)))
+      i++;
+  }
+  return paths;
+}
+function conflictMarkerLine(content) {
+  let opener = false;
+  for (const line of content.split(`
+`)) {
+    if (/^<{7}( |$)/.test(line))
+      opener = true;
+    else if (/^={7}(\s|$)/.test(line) && opener)
+      return true;
+    else if (/^>{7}( |$)/.test(line))
+      return true;
+  }
+  return opener;
+}
+function changedSinceBase(base, git) {
+  const tracked = git(["diff", "--name-only", base]);
+  const others = git(["ls-files", "--others", "--exclude-standard", "-z"]);
+  if (tracked.status !== 0 || others.status !== 0)
+    return new Set;
+  const clean = (out, sep) => out.split(sep).map((p) => p.trim()).filter((p) => p.length > 0 && !isBookkeeping(p));
+  return new Set([...clean(tracked.stdout, `
+`), ...clean(others.stdout, "\x00")]);
+}
+function readTreeStart(run, options) {
+  try {
+    const parsed = JSON.parse(readFileSync(at(options, artifactPath(run)), "utf8"));
+    if (typeof parsed.head === "string" && Array.isArray(parsed.dirty))
+      return parsed;
+  } catch {}
+  return null;
+}
+function runContext(run, options) {
+  const git = gitOf(options);
+  const start = readTreeStart(run, options);
+  if (!start)
+    return null;
+  let base = options.base ?? "";
+  if (!base) {
+    try {
+      const anchored = readFileSync(at(options, join(".spur", "run", `${run}-base.sha`)), "utf8").trim();
+      if (/^[0-9a-f]{7,40}$/i.test(anchored))
+        base = anchored;
+    } catch {}
+  }
+  if (!base)
+    base = start.head.length > 0 ? start.head : "HEAD";
+  const written = changedSinceBase(base, git);
+  for (const entry of start.dirty)
+    if (hashPath(entry.path, git) === entry.sha)
+      written.delete(entry.path);
+  return { git, base, start, written };
+}
+function missingStart(run) {
+  process.stderr.write(`commit-guard: no ${artifactPath(run)} \u2014 run \`commit-guard start --run ${run}\` first
+`);
+  return 1;
+}
+function runStart(run, options = {}) {
+  const git = gitOf(options);
+  const head = git(["rev-parse", "HEAD"]);
+  const status = git(["status", "--porcelain=v1", "-z"]);
+  if (head.status !== 0 || status.status !== 0) {
+    process.stderr.write(`commit-guard: git probe failed (rev-parse HEAD / status) \u2014 is this a work tree?
+`);
+    return 1;
+  }
+  const snapshot = {
+    head: head.stdout.trim(),
+    dirty: parsePorcelainZ(status.stdout).map((path) => ({ path, sha: hashPath(path, git) }))
+  };
+  const abs = at(options, artifactPath(run));
+  mkdirSync(join(abs, ".."), { recursive: true });
+  writeFileSync(`${abs}.tmp`, `${JSON.stringify(snapshot, null, 2)}
+`);
+  renameSync(`${abs}.tmp`, abs);
+  return 0;
+}
+function conflictingTarget(paths, options, git) {
+  const unmerged = new Set(git(["diff", "--name-only", "--diff-filter=U"]).stdout.split(`
+`).map((p) => p.trim()));
+  for (const path of paths) {
+    if (unmerged.has(path))
+      return `${path} (unmerged)`;
+    try {
+      if (conflictMarkerLine(readFileSync(at(options, path), "utf8")))
+        return `${path} (conflict markers)`;
+    } catch {}
+  }
+  return null;
+}
+function runStage(run, paths, options = {}) {
+  if (paths.length === 0) {
+    process.stderr.write(`${COMMIT_GUARD_USAGE}
+`);
+    return { staged: [], foreign: [], exitCode: 1 };
+  }
+  const context = runContext(run, options);
+  if (!context)
+    return { staged: [], foreign: [], exitCode: missingStart(run) };
+  const conflict = conflictingTarget(paths, options, context.git);
+  if (conflict) {
+    process.stderr.write(`commit-guard: refusing to stage ${conflict}; nothing staged
+`);
+    return { staged: [], foreign: [], exitCode: 3 };
+  }
+  const dirtyAtStart = new Set(context.start.dirty.map((entry) => entry.path));
+  const staged = paths.filter((path) => context.written.has(path));
+  const refused = paths.filter((path) => !context.written.has(path));
+  for (const path of refused) {
+    const why = dirtyAtStart.has(path) ? "foreign \u2014 dirty at start, untouched by this run" : "unchanged since base";
+    process.stderr.write(`commit-guard: refused ${path} (${why})
+`);
+  }
+  if (staged.length > 0 && context.git(["add", "--", ...staged]).status !== 0) {
+    process.stderr.write(`commit-guard: git add failed \u2014 nothing staged
+`);
+    return { staged: [], foreign: [], exitCode: 1 };
+  }
+  const foreign = refused.filter((path) => dirtyAtStart.has(path));
+  process.stdout.write(`${JSON.stringify({ staged, foreign })}
+`);
+  return { staged, foreign, exitCode: refused.length > 0 ? 2 : 0 };
+}
+function runCheck(run, options = {}) {
+  const context = runContext(run, options);
+  if (!context)
+    return missingStart(run);
+  const foreign = [...changedSinceBase(context.base, context.git)].filter((path) => !context.written.has(path)).sort();
+  process.stdout.write(`${JSON.stringify({ foreign })}
+`);
+  return 0;
+}
+function takeFlag(args, name) {
+  const index = args.indexOf(name);
+  const value = index === -1 ? undefined : args[index + 1];
+  const missing = value === undefined || value.startsWith("--");
+  if (index !== -1)
+    args.splice(index, missing ? 1 : 2);
+  return missing ? undefined : value;
+}
+function main(argv, options = {}) {
+  const args = [...argv];
+  takeFlag(args, "--spur-bin");
+  const sub = args.shift();
+  const run = takeFlag(args, "--run");
+  const base = takeFlag(args, "--base");
+  const usage = () => {
+    process.stderr.write(`${COMMIT_GUARD_USAGE}
+`);
+    return 1;
+  };
+  if (!run)
+    return usage();
+  if (sub === "start")
+    return args.length === 0 ? runStart(run, options) : usage();
+  if (sub === "check")
+    return args.length === 0 ? runCheck(run, { ...options, base }) : usage();
+  if (sub === "stage")
+    return runStage(run, args.filter((arg) => arg !== "--"), { ...options, base }).exitCode;
+  return usage();
+}
+{
+  process.exit(main(process.argv.slice(2)));
+}
+export {
+  runStart,
+  runStage,
+  runCheck,
+  parsePorcelainZ,
+  main,
+  conflictMarkerLine,
+  COMMIT_GUARD_USAGE
+};