@gobing-ai/knowledge-kit 0.0.12 → 0.0.14

package/plugins/sp/scripts/idea-handoff.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/idea-handoff.ts
+var libUrl = new URL('../lib/idea-handoff.generated.mjs', import.meta.url).href;
+async function loadHandoffLib() {
+    return await import(libUrl);
+}
+var IDEA_HANDOFF_USAGE = 'usage: idea-handoff.ts  (env: __runId, featureId, optional spurBin) \u2014 no subcommands';
+async function main(argv, env = process.env) {
+    if (argv.length > 0) {
+        process.stderr.write(`${IDEA_HANDOFF_USAGE}
+`);
+        return 2;
+    }
+    const { runIdeaHandoffCli } = await loadHandoffLib();
+    const outcome = await runIdeaHandoffCli(env);
+    return outcome.exitCode;
+}
+process.exit(await main(process.argv.slice(2)));
+
+export { IDEA_HANDOFF_USAGE, loadHandoffLib, main };

package/plugins/sp/scripts/idea-handoff.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+/**
+ * idea-handoff — portable entrypoint for the idea-pipeline finalization (task 0824, feature I21).
+ *
+ * ADR-065 standard plugin script: the workflow wrapper prefers the monorepo writer
+ * (`bun packages/app/src/workflow/idea-handoff-cli.ts`) and falls back to this script's
+ * registered `.mjs` twin under bare `node`, so a seeded project with no monorepo checkout
+ * still finalizes the handoff (run-scoped report + task-deps ordering + roster refresh) and
+ * fails closed (exit 1) when neither writer resolves.
+ *
+ * The behavior lives in the generated bundle `../lib/idea-handoff.generated.mjs`, produced by
+ * `bun run build:plugin-lib` from `packages/app/src/workflow/idea-handoff-cli.ts` — the same
+ * source the monorepo branch executes, so both branches share one contract (0604/0824).
+ * Declarations: `../lib/idea-handoff.generated.d.mts`. The bundle is imported by computed URL
+ * on purpose: `superskill script convert` must NOT inline it (its tree carries one
+ * `Bun.spawn` site in a ts-runtime streaming path this workflow never exercises), so the
+ * twin stays a thin node-runnable loader over the committed runtime asset.
+ *
+ * Environment: `__runId`, `featureId`, optional `spurBin`. Missing required vars exit 1
+ * (mis-invocation is failed-closed, never a silent skip).
+ */
+
+const libUrl = new URL('../lib/idea-handoff.generated.mjs', import.meta.url).href;
+
+export async function loadHandoffLib(): Promise<typeof import('../lib/idea-handoff.generated.mjs')> {
+    return (await import(libUrl)) as typeof import('../lib/idea-handoff.generated.mjs');
+}
+
+export const IDEA_HANDOFF_USAGE =
+    'usage: idea-handoff.ts  (env: __runId, featureId, optional spurBin) — no subcommands';
+
+export async function main(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
+    if (argv.length > 0) {
+        process.stderr.write(`${IDEA_HANDOFF_USAGE}\n`);
+        return 2;
+    }
+    const { runIdeaHandoffCli } = await loadHandoffLib();
+    const outcome = await runIdeaHandoffCli(env as { __runId?: string; featureId?: string; spurBin?: string });
+    return outcome.exitCode;
+}
+
+if (import.meta.main) {
+    process.exit(await main(process.argv.slice(2)));
+}

package/plugins/sp/scripts/inline-pipeline-parity-check.ts

@@ -0,0 +1,185 @@
+#!/usr/bin/env bun
+/**
+ * inline-pipeline-parity-check — two-sided gate between the inline pipeline
+ * driver's documented action/guard set and the resolved action/guard sets in
+ * `.spur/workflows/task-pipeline.yaml` and `.spur/workflows/idea-pipeline.yaml`
+ * (task 0755 R2/R3).
+ *
+ * The driver reference at `plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md`
+ * documents the set of action and guard kinds it implements. The two runtime
+ * pipelines are the only consumers the driver needs to keep in step with. The
+ * check is a symmetric set diff: an element present in one and absent in the
+ * other fails the check and names the element.
+ *
+ * The set is defined in {@link DOCUMENTED} below; the driver's markdown list is
+ * the human mirror. Update both when the driver adds or drops a kind.
+ *
+ * Usage:
+ *   bun plugins/sp/scripts/inline-pipeline-parity-check.ts
+ *     [--root <path>]               default: repo root
+ *
+ * Exit code: 0 when the sets agree; 1 on any divergence. Violations are printed
+ * to stderr; a summary to stdout.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+/** Documented action and guard set. Must stay in lockstep with the
+ *  "Supported action and guard set (0755 R2 parity contract)" section in
+ *  `plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md`. The
+ *  driver supports a kind if ANY workflow in `.spur/workflows/*.yaml` uses
+ *  it (the driver applies to any selected pipeline per its reference doc). */
+const DOCUMENTED = {
+    actions: new Set([
+        'shell',
+        'note',
+        'doctor.probe',
+        'file.read.into-var',
+        'hitl.confirm',
+        'agent.run',
+        'proof.fingerprint',
+        'run.artifact',
+        'command.gate',
+    ]),
+    guards: new Set(['always', 'shell']),
+} as const;
+
+/** Directory of workflow definitions the driver is responsible for. */
+const WORKFLOW_DIR = join('config', 'workflows');
+
+/** Walk a state list and yield every `kind:` value found in `onEnter` action
+ *  lists. Skips the top-level workflow `kind:` (e.g. `state-machine`). */
+function collectActionKinds(states: unknown): Set<string> {
+    const out = new Set<string>();
+    if (!Array.isArray(states)) return out;
+    for (const state of states) {
+        if (typeof state !== 'object' || state === null) continue;
+        const onEnter = (state as { onEnter?: unknown }).onEnter;
+        if (!Array.isArray(onEnter)) continue;
+        for (const action of onEnter) {
+            if (typeof action !== 'object' || action === null) continue;
+            const kind = (action as { kind?: unknown }).kind;
+            if (typeof kind === 'string') out.add(kind);
+        }
+    }
+    return out;
+}
+
+/** Walk a transition list and yield every `guard.kind` value. */
+function collectGuardKinds(transitions: unknown): Set<string> {
+    const out = new Set<string>();
+    if (!Array.isArray(transitions)) return out;
+    for (const transition of transitions) {
+        if (typeof transition !== 'object' || transition === null) continue;
+        const guard = (transition as { guard?: { kind?: unknown } }).guard;
+        const kind = guard?.kind;
+        if (typeof kind === 'string') out.add(kind);
+    }
+    return out;
+}
+
+/** Symmetric set diff. Returns elements in `a` but not in `b`, and vice versa. */
+function diff<T>(a: Set<T>, b: Set<T>): { onlyInA: T[]; onlyInB: T[] } {
+    const onlyInA: T[] = [];
+    const onlyInB: T[] = [];
+    for (const x of a) if (!b.has(x)) onlyInA.push(x);
+    for (const x of b) if (!a.has(x)) onlyInB.push(x);
+    return { onlyInA, onlyInB };
+}
+
+function parseArgs(argv: string[]): { root: string } {
+    let root = resolve('.');
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--root' && i + 1 < argv.length) {
+            root = resolve(argv[++i] ?? '.');
+        } else if (arg === '--help' || arg === '-h') {
+            process.stdout.write('Usage: bun inline-pipeline-parity-check.ts [--root <path>]\n');
+            process.exit(0);
+        }
+    }
+    return { root };
+}
+
+function listWorkflowFiles(dir: string): string[] {
+    let entries: string[];
+    try {
+        entries = readdirSync(dir);
+    } catch {
+        return [];
+    }
+    return entries.filter((e) => e.endsWith('.yaml')).map((e) => join(dir, e));
+}
+
+async function main(): Promise<number> {
+    const { root } = parseArgs(process.argv.slice(2));
+    const errors: string[] = [];
+
+    const workflowDir = join(root, WORKFLOW_DIR);
+    if (!statSync(workflowDir, { throwIfNoEntry: false })) {
+        process.stderr.write(`inline-pipeline-parity-check: workflow directory not found: ${workflowDir}\n`);
+        return 1;
+    }
+
+    const files = listWorkflowFiles(workflowDir);
+    if (files.length === 0) {
+        process.stderr.write(`inline-pipeline-parity-check: no .yaml workflows found in ${workflowDir}\n`);
+        return 1;
+    }
+
+    const unionActions = new Set<string>();
+    const unionGuards = new Set<string>();
+    const perFileKinds: { path: string; actions: Set<string>; guards: Set<string> }[] = [];
+
+    for (const path of files) {
+        let parsed: unknown;
+        try {
+            parsed = parseYaml(readFileSync(path, 'utf8'));
+        } catch (err) {
+            errors.push(`${path}: failed to parse (${err instanceof Error ? err.message : String(err)})`);
+            continue;
+        }
+        if (typeof parsed !== 'object' || parsed === null) {
+            continue;
+        }
+        const def = parsed as { states?: unknown; transitions?: unknown };
+        const actions = collectActionKinds(def.states);
+        const guards = collectGuardKinds(def.transitions);
+        perFileKinds.push({ path, actions, guards });
+        for (const a of actions) unionActions.add(a);
+        for (const g of guards) unionGuards.add(g);
+    }
+
+    const actionDiff = diff(unionActions, DOCUMENTED.actions);
+    const guardDiff = diff(unionGuards, DOCUMENTED.guards);
+
+    for (const x of actionDiff.onlyInA) {
+        const usedIn = perFileKinds.filter((f) => f.actions.has(x)).map((f) => f.path);
+        errors.push(`action kind "${x}" used in YAML (${usedIn.join(', ')}) but absent from inline-pipeline-driver.md`);
+    }
+    for (const x of actionDiff.onlyInB) {
+        errors.push(`action kind "${x}" documented in inline-pipeline-driver.md but never used in any workflow`);
+    }
+    for (const x of guardDiff.onlyInA) {
+        const usedIn = perFileKinds.filter((f) => f.guards.has(x)).map((f) => f.path);
+        errors.push(`guard kind "${x}" used in YAML (${usedIn.join(', ')}) but absent from inline-pipeline-driver.md`);
+    }
+    for (const x of guardDiff.onlyInB) {
+        errors.push(`guard kind "${x}" documented in inline-pipeline-driver.md but never used in any workflow`);
+    }
+
+    if (errors.length > 0) {
+        process.stderr.write(`inline-pipeline-parity-check: ${errors.length} divergence(s)\n`);
+        for (const e of errors) process.stderr.write(`  - ${e}\n`);
+        return 1;
+    }
+
+    process.stdout.write(
+        `inline-pipeline-parity-check: ok (${unionActions.size} actions, ${unionGuards.size} guards agree across ${files.length} workflows)\n`,
+    );
+    return 0;
+}
+
+process.exit(await main());

package/plugins/sp/scripts/inline-run-setup.ts

@@ -0,0 +1,198 @@
+#!/usr/bin/env bun
+/**
+ * inline-run-setup — authoritative inline full-pipeline run identity (task 0804 R1).
+ *
+ * Unlike the subprocess path (`spur workflow run`), the interactive inline driver
+ * allocated a run id but never persisted an authoritative `runs` row, so bound
+ * `run.artifact` registration (0785 R3) correctly refused every inline record. This
+ * script is the thin delegate the driver now runs at Run setup: it resolves the spur
+ * repo checkout from the SPUR_BIN chain, imports the real app service
+ * (`createOrAttachInlineRun` / `openInlineRunProjectDb` from packages/app), and lets it
+ * resolve the SAME project-or-bundled definition the engine would launch, compute the
+ * canonical definition digest with the exported hash machinery, and create-or-attach the
+ * run row through the existing engine persistence adapter.
+ *
+ * The script itself contains NO direct SQL, NO second hasher and NO persistence policy —
+ * every rule lives in packages/app (0804 D1). On a bundle-only install there is no repo
+ * checkout to import the app service from, so the setup fails closed with actionable
+ * remediation guidance (point SPUR_BIN at a repo checkout); it never falls back to an
+ * unbound run (0804 R1 failure policy).
+ *
+ * Outcome JSON is written to `.spur/run/<run-id>-inline-setup.json` so the driver can
+ * seed the inline var overlay (`__runId`, `__definitionDigest`) that proof capture and
+ * bound registration verify against. Exit 0 = authoritative identity ready (created or
+ * idempotently attached); exit 1 = fail closed, the driver must stop.
+ *
+ * Repo-only script (ADR-065): it imports the app workspace source, so it runs under bun
+ * against a monorepo checkout only — the same posture as task-size-precheck.ts and
+ * task-evidence-precheck.ts.
+ *
+ * Usage:
+ *   bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]
+ *
+ * Env: SPUR_BIN
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Outcome document written to `.spur/run/<run-id>-inline-setup.json`. */
+interface SetupOutcome {
+    readonly ok: boolean;
+    readonly runId: string;
+    readonly attached?: boolean;
+    readonly definitionDigest?: string;
+    readonly workflowName?: string;
+    readonly workflowVersion?: string | null;
+    readonly resolvedPath?: string;
+    readonly layer?: string;
+    readonly workdir?: string;
+    readonly status?: string;
+    readonly error?: string;
+}
+
+function usage(): never {
+    console.error(
+        'Usage: bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]',
+    );
+    process.exit(1);
+}
+
+/**
+ * The run id becomes a filename under `.spur/run/` (`<run-id>-inline-setup.json`), so it must be a
+ * single safe filename component before anything is written — the same guard class the
+ * task-pipeline.yaml route-reason action applies to `$__runId` (task 0804 R8). The allowlist
+ * refuses path separators, dot traversal (leading `.`), unresolved interpolation (`$`/`{`/`}`) and
+ * every other shell/unspecified metachar; valid UUID/timestamp-slug ids pass.
+ */
+const SAFE_RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function refuseUnsafeRunId(runId: string): never {
+    // Refuse BEFORE any outcome write: an unsafe id must never reach
+    // `.spur/run/<run-id>-inline-setup.json` (no traversal, no unintended file).
+    console.error(`inline-run-setup: refusing unsafe run id: ${runId}`);
+    console.error(
+        '  The run id must be a single safe filename component (alphanumeric/._-, no leading dot, ' +
+            'no path separators, interpolation or traversal; same class as the task-pipeline ' +
+            'route-reason guard, task 0804 R8). Allocate a fresh run id (uuid or timestamp slug) and retry.',
+    );
+    process.exit(1);
+}
+
+/**
+ * Resolve the spur repo checkout the same way the other prechecks resolve the CLI
+ * (--spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`), then derive the repo
+ * root from the resolved main module. `bun <repo>/apps/cli/src/index.ts` → repo root is
+ * three levels up. A bundle-only install (`spur` on PATH, a bundled `spur.js`, or a spur
+ * binary without the app workspace) has no app entry to import — the caller fails that
+ * closed with remediation guidance.
+ */
+function resolveAppEntry(
+    spurBin: string,
+): { entry: string; repoRoot: string } | { entry: null; repoRoot: null; chain: string } {
+    let candidates: string[] = [];
+    if (spurBin !== '') {
+        candidates = [spurBin];
+    } else {
+        // scripts/ -> plugins/sp/ -> <repo>/apps/cli/src/index.ts (fileURLToPath — raw
+        // pathname breaks on %-encoded paths, e.g. spaces in the checkout directory).
+        candidates = [fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url))];
+    }
+    for (const candidate of candidates) {
+        const tokens = candidate.split(/\s+/).filter(Boolean);
+        // The main module is the last path-like token (tolerates `bun <path>` /
+        // `bun run <path>` lead tokens). Only a TypeScript source entry proves a repo
+        // checkout; a bundled `spur.js` or a bare `spur` binary does not.
+        const mainModule = [...tokens].reverse().find((t) => t.endsWith('.ts'));
+        if (mainModule === undefined || !existsSync(mainModule)) continue;
+        // <repo>/apps/cli/src/index.ts → repo root; then require the app package source.
+        const srcDir = dirname(mainModule);
+        const repoRoot = resolve(srcDir, '..', '..', '..');
+        const appEntry = join(repoRoot, 'packages', 'app', 'src', 'index.ts');
+        if (existsSync(appEntry)) return { entry: appEntry, repoRoot };
+        return { entry: null, repoRoot: null, chain: `${candidate} (no ${appEntry})` };
+    }
+    return { entry: null, repoRoot: null, chain: spurBin === '' ? 'PATH spur (bundle-only install)' : spurBin };
+}
+
+function writeOutcome(runId: string, outcome: SetupOutcome): void {
+    const runDir = join(process.cwd(), '.spur', 'run');
+    if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
+    writeFileSync(join(runDir, `${runId}-inline-setup.json`), `${JSON.stringify(outcome, null, 4)}\n`);
+}
+
+async function main(): Promise<void> {
+    let runId = '';
+    let file = '';
+    let spurBin = process.env.SPUR_BIN ?? '';
+    const argv = process.argv.slice(2);
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--run-id') runId = argv[++i] ?? '';
+        else if (argv[i] === '--file') file = argv[++i] ?? '';
+        else if (argv[i] === '--spur-bin') spurBin = argv[++i] ?? spurBin;
+    }
+    if (runId.trim() === '' || file.trim() === '') usage();
+    if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
+
+    const { entry, repoRoot, chain } = resolveAppEntry(spurBin);
+    if (entry === null || repoRoot === null) {
+        const outcome: SetupOutcome = {
+            ok: false,
+            runId,
+            error:
+                `inline run setup failed closed: no monorepo checkout of spur is reachable via ${chain}. ` +
+                'The authoritative run identity must be persisted by the app service ' +
+                '(packages/app/src/services/inline-run-setup.ts); a bundle-only install cannot do this. ' +
+                'Remediation: point SPUR_BIN at a repo checkout, e.g. ' +
+                'SPUR_BIN="bun /path/to/spur/apps/cli/src/index.ts". The pipeline must not run unbound.',
+        };
+        writeOutcome(runId, outcome);
+        console.error(`inline-run-setup: FAIL for run ${runId}`);
+        console.error(`  ${outcome.error}`);
+        process.exit(1);
+    }
+
+    // Dynamic import by absolute path: the app source graph resolves its own workspace
+    // dependencies from the repo checkout, never from this plugin script's location.
+    const app = (await import(entry)) as {
+        createOrAttachInlineRun: (input: {
+            workdir: string;
+            getDb: () => Promise<unknown>;
+            file: string;
+            runId: string;
+        }) => Promise<SetupOutcome & { ok: boolean }>;
+        openInlineRunProjectDb: (workdir: string) => Promise<{ adapter: unknown; close: () => void }>;
+    };
+
+    const workdir = process.cwd();
+    const projectDb = await app.openInlineRunProjectDb(workdir);
+    let exitCode = 0;
+    try {
+        const result = await app.createOrAttachInlineRun({
+            workdir,
+            getDb: async () => projectDb.adapter,
+            file,
+            runId,
+        });
+        writeOutcome(runId, result);
+        if (!result.ok) {
+            console.error(`inline-run-setup: FAIL for run ${runId}`);
+            console.error(`  ${result.error}`);
+            exitCode = 1;
+        } else {
+            console.error(
+                `inline-run-setup: ${result.attached ? 'attached' : 'created'} run ${runId} ` +
+                    `(${result.workflowName}, layer ${result.layer}, digest ${result.definitionDigest}, status ${result.status})`,
+            );
+        }
+    } finally {
+        projectDb.close();
+    }
+    process.exit(exitCode);
+}
+
+main().catch((e: unknown) => {
+    console.error(`inline-run-setup: FAIL — ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+});