@gobing-ai/knowledge-kit 0.0.13 → 0.0.14

package/plugins/sp/scripts/feature-dev-precheck.ts

@@ -0,0 +1,238 @@
+#!/usr/bin/env bun
+/**
+ * feature-dev-precheck — portable identity/roster gate behind the feature-dev pipeline
+ * precheck (task 0825, feature I21, governance §1.1 composition budgets).
+ *
+ * Ports the former `feature-dev.yaml` `precheck:onEnter:0` shell program one-for-one so the
+ * workflow stays inside the shell-program caps while writing the same `.spur/run` artifacts:
+ *   - `<runId>-feature-dev-feature.json`    merged `feature show` capture (stdout + stderr)
+ *   - `<runId>-feature-dev-roster.json`     merged `task list --feature` capture
+ *   - `<runId>-feature-dev-tasks.txt`       frozen sorted todo WBS list, comma-joined
+ *   - `<runId>-feature-dev-precheck.status` `PASS`/`FAIL`
+ *
+ * Failure ladder (first failing check wins, message to stderr, FAIL status):
+ *   1. identity/roster read failure — missing featureId/runId, unknown feature, or a
+ *      non-zero rc from any of the three reads (message carries the rc triple);
+ *   2. roster not a non-empty JSON array;
+ *   3. roster contract breach — empty/duplicate/non-string WBS identities or a status
+ *      outside todo/done/cancelled/backlog/wip/testing/blocked;
+ *   4. refinement-blocking statuses present (backlog/wip/testing/blocked).
+ *
+ * Environment: `featureId`, `__runId` (required), `spurBin` (split on whitespace into a
+ * command plus prefix args). Soft-fail contract: the process always exits 0; the verdict
+ * lives in the status file. Node-builtin imports only; pure helpers are exported for unit
+ * testing (ADR-065).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Statuses that must be refined/resumed through their own pipelines before batching. */
+export const BLOCKING_STATUSES = ['backlog', 'wip', 'testing', 'blocked'] as const;
+
+/** Every status a roster row may carry (anything else fails the structural contract). */
+export const KNOWN_STATUSES = ['todo', 'done', 'cancelled', ...BLOCKING_STATUSES] as const;
+
+export interface FeatureDevPrecheckEnv {
+    featureId?: string;
+    __runId?: string;
+    spurBin?: string;
+    [key: string]: string | undefined;
+}
+
+export interface FeatureDevPrecheckOptions {
+    /** Base directory for `.spur/run`; defaults to the process cwd (CLI behavior). */
+    cwd?: string;
+    /** Extra environment for the spawned CLI reads (merged over process.env). */
+    env?: Record<string, string>;
+}
+
+export interface FeatureDevPrecheckResult {
+    status: 'PASS' | 'FAIL';
+    featureFile: string;
+    rosterFile: string;
+    tasksFile: string;
+    statusFile: string;
+    /** Frozen todo list; empty string on FAIL. */
+    tasks: string;
+}
+
+export interface RosterRow {
+    wbs: unknown;
+    status: unknown;
+}
+
+/** Identity gate: rc 0 when featureId and __runId are both non-empty, else 1. */
+export function identityRc(featureId: string | undefined, runId: string | undefined): number {
+    return featureId && runId ? 0 : 1;
+}
+
+/**
+ * jq `type == "object" and .id == $id` port: parsed JSON must be a non-array object whose
+ * `.id` equals the supplied feature id.
+ */
+export function featureIdentityMatches(raw: string, featureId: string): boolean {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return false;
+    }
+    return (
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        !Array.isArray(parsed) &&
+        (parsed as { id?: unknown }).id === featureId
+    );
+}
+
+/** jq roster-shape port: parsed JSON must be a non-empty array. */
+export function rosterIsNonEmptyArray(raw: string): boolean {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch {
+        return false;
+    }
+    return Array.isArray(parsed) && parsed.length > 0;
+}
+
+/** jq WBS-identity/status contract port: non-empty string wbs, unique, known statuses. */
+export function rosterContractHolds(rows: RosterRow[]): boolean {
+    const seen = new Set<string>();
+    for (const row of rows) {
+        if (row === null || typeof row !== 'object') return false;
+        if (typeof row.wbs !== 'string' || row.wbs.length === 0) return false;
+        if (seen.has(row.wbs)) return false;
+        seen.add(row.wbs);
+        if (typeof row.status !== 'string' || !(KNOWN_STATUSES as readonly string[]).includes(row.status)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** jq blocking-status port: any backlog/wip/testing/blocked member. */
+export function hasBlockingStatus(rows: RosterRow[]): boolean {
+    return rows.some(
+        (row) => typeof row.status === 'string' && (BLOCKING_STATUSES as readonly string[]).includes(row.status),
+    );
+}
+
+/** jq `sort | join(",")` port over the todo subset: codepoint-sorted, comma-joined, no newline. */
+export function freezeTodoList(rows: RosterRow[]): string {
+    return rows
+        .filter((row) => row.status === 'todo' && typeof row.wbs === 'string')
+        .map((row) => row.wbs as string)
+        .sort()
+        .join(',');
+}
+
+/** `spurBin` splits on whitespace into a command plus prefix args (PATH-independent runs). */
+export function spurCommand(spurBin: string | undefined): { cmd: string; prefix: string[] } {
+    const parts = (spurBin ?? 'spur')
+        .trim()
+        .split(/\s+/)
+        .filter((p) => p.length > 0);
+    return { cmd: parts[0] ?? 'spur', prefix: parts.slice(1) };
+}
+
+function readFileSyncRaw(path: string): string {
+    try {
+        return readFileSync(path, 'utf8');
+    } catch {
+        return '';
+    }
+}
+
+export function runFeatureDevPrecheck(
+    env: FeatureDevPrecheckEnv,
+    options: FeatureDevPrecheckOptions = {},
+): FeatureDevPrecheckResult {
+    const cwd = options.cwd;
+    const runDir = join('.spur', 'run');
+    mkdirSync(cwd ? join(cwd, runDir) : runDir, { recursive: true });
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+    const featureFile = join(runDir, `${env.__runId ?? ''}-feature-dev-feature.json`);
+    const rosterFile = join(runDir, `${env.__runId ?? ''}-feature-dev-roster.json`);
+    const tasksFile = join(runDir, `${env.__runId ?? ''}-feature-dev-tasks.txt`);
+    const statusFile = join(runDir, `${env.__runId ?? ''}-feature-dev-precheck.status`);
+    const featureId = env.featureId ?? '';
+
+    rmSync(abs(statusFile), { force: true });
+
+    const { cmd, prefix } = spurCommand(env.spurBin);
+    /** Spawn one CLI read; merged output into the artifact, 127 on a spawn error (exec loss). */
+    const read = (args: string[], target: string): number => {
+        const result = spawnSync(cmd, [...prefix, ...args], {
+            cwd,
+            encoding: 'utf8',
+            ...(options.env ? { env: { ...process.env, ...options.env } } : {}),
+        });
+        if (result.error !== undefined) {
+            writeFileSync(abs(target), `spawn failed: ${result.error.message}\n`);
+            return 127;
+        }
+        writeFileSync(abs(target), `${result.stdout ?? ''}${result.stderr ?? ''}`);
+        return result.status ?? 1;
+    };
+
+    const idRc = identityRc(featureId, env.__runId);
+    const showRc = idRc === 0 ? read(['feature', 'show', featureId, '--json'], featureFile) : 1;
+    const listRc =
+        idRc === 0 && showRc === 0 && featureIdentityMatches(readFileSyncRaw(abs(featureFile)), featureId)
+            ? read(['task', 'list', '--feature', featureId, '--json'], rosterFile)
+            : 1;
+
+    const fail = (message: string): FeatureDevPrecheckResult => {
+        process.stderr.write(`${message}\n`);
+        writeFileSync(abs(statusFile), 'FAIL\n');
+        return { status: 'FAIL', featureFile, rosterFile, tasksFile, statusFile, tasks: '' };
+    };
+
+    if (idRc !== 0 || showRc !== 0 || listRc !== 0) {
+        return fail(
+            `feature-dev precheck: missing featureId/runId, unknown feature '${featureId}', or unreadable roster (rc ${idRc}/${showRc}/${listRc}) — supply an existing planned feature via /sp:dev-plan or /sp:dev-idea; nothing was auto-created or re-planned`,
+        );
+    }
+
+    const rosterRaw = readFileSyncRaw(abs(rosterFile));
+    if (!rosterIsNonEmptyArray(rosterRaw)) {
+        return fail(
+            `feature-dev precheck: roster at ${rosterFile} is malformed, not an array, or empty — plan the feature first via /sp:dev-plan; refusing to replan or run an empty batch`,
+        );
+    }
+    const rows = JSON.parse(rosterRaw) as RosterRow[];
+    if (!rosterContractHolds(rows)) {
+        return fail(
+            `feature-dev precheck: roster has empty/duplicate/mismatched WBS identities or unknown statuses at ${rosterFile} — repair the task corpus; refusing to batch a broken roster`,
+        );
+    }
+    if (hasBlockingStatus(rows)) {
+        return fail(
+            'feature-dev precheck: linked task(s) are backlog/wip/testing/blocked — refine or resume them through their own task pipelines before batching; refusing to launch overlapping work',
+        );
+    }
+
+    const tasks = freezeTodoList(rows);
+    writeFileSync(abs(tasksFile), tasks);
+    writeFileSync(abs(statusFile), 'PASS\n');
+    return { status: 'PASS', featureFile, rosterFile, tasksFile, statusFile, tasks };
+}
+
+export const FEATURE_DEV_PRECHECK_USAGE =
+    'usage: feature-dev-precheck.ts  (env: featureId, __runId, optional spurBin) — no subcommands';
+
+export function main(argv: string[], env: FeatureDevPrecheckEnv = process.env): number {
+    if (argv.length > 0) {
+        process.stderr.write(`${FEATURE_DEV_PRECHECK_USAGE}\n`);
+        return 2;
+    }
+    runFeatureDevPrecheck(env);
+    return 0;
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}

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

@@ -0,0 +1,285 @@
+#!/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 {
+    BOUNDED_SYNC_CLI_USAGE,
+    blockedStateFile,
+    classifySyncResult,
+    computeFingerprint,
+    decideBoundedSync,
+    defaultSpurBin,
+    parseBlockedState,
+    parseBoundedSyncCliArgs,
+    processSyncResult,
+    runBoundedCli,
+    serializeBlockedState,
+    shouldSuppressBlocked,
+};