@deftai/directive 0.55.0

package/dist/scm-parity.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * Golden-output parity harness (#1724): runs BOTH the Python oracle
+ * (`scripts/scm.py`) and the ported TS SCM CLI with identical argv, then
+ * diffs exit codes and normalised stdout/stderr. Exit 0 only on identical
+ * results.
+ *
+ * Exit codes: 0 parity / 1 divergence / 2 harness setup error.
+ */
+import { execFileSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Validation-only scenarios (no live gh network). */
+export const PARITY_SCENARIOS = [
+    { name: "usage-too-short", argv: [] },
+    { name: "unknown-namespace", argv: ["isue", "list"] },
+    { name: "unknown-issue-verb", argv: ["issue", "merge"] },
+    {
+        name: "rest-rejected-close",
+        argv: ["issue", "close", "--rest", "1", "--repo", "deftai/directive"],
+    },
+    {
+        name: "rest-rejected-edit",
+        argv: ["issue", "edit", "--rest", "1", "--repo", "deftai/directive"],
+    },
+    { name: "rest-view-missing-repo", argv: ["issue", "view", "--rest", "1"] },
+    {
+        name: "rest-view-missing-positional",
+        argv: ["issue", "view", "--rest", "--repo", "deftai/directive"],
+    },
+    {
+        name: "rest-view-non-integer",
+        argv: ["issue", "view", "--rest", "abc", "--repo", "deftai/directive"],
+    },
+    {
+        name: "rest-view-unknown-flag",
+        argv: ["issue", "view", "--rest", "1", "--repo", "deftai/directive", "--state", "closed"],
+    },
+    { name: "rest-list-missing-repo", argv: ["issue", "list", "--rest"] },
+    {
+        name: "rest-list-unknown-flag",
+        argv: ["issue", "list", "--rest", "--repo", "deftai/directive", "--unknown-flag", "x"],
+    },
+    {
+        name: "rest-list-leftover-positional",
+        argv: ["issue", "list", "--rest", "123", "--repo", "deftai/directive"],
+    },
+    {
+        name: "rest-list-non-integer-limit",
+        argv: ["issue", "list", "--rest", "--repo", "deftai/directive", "--limit", "many"],
+    },
+    {
+        name: "rest-view-invalid-repo",
+        argv: ["issue", "view", "--rest", "1", "--repo", "directive"],
+    },
+    {
+        name: "rest-list-invalid-repo",
+        argv: ["issue", "list", "--rest", "--repo", "directive"],
+    },
+];
+function runCapture(cmd, args, cwd) {
+    try {
+        const stdout = execFileSync(cmd, args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { status: 0, stdout, stderr: "" };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            status: typeof e.status === "number" ? e.status : 2,
+            stdout: typeof e.stdout === "string" ? e.stdout : "",
+            stderr: typeof e.stderr === "string" ? e.stderr : "",
+        };
+    }
+}
+/** Normalise gate output for comparison. */
+export function normaliseMessage(stdout, stderr, exitCode) {
+    const raw = exitCode === 0 ? stdout : stderr;
+    return raw
+        .split("\n")
+        .filter((line) => !line.startsWith("Using CPython") &&
+        !line.startsWith("Creating virtual environment") &&
+        !line.startsWith("Installed "))
+        .join("\n")
+        .trim()
+        .replace(/\s+/g, " ");
+}
+function resolveDeftRoot() {
+    if (process.env.DEFT_ROOT !== undefined && process.env.DEFT_ROOT.length > 0) {
+        return resolve(process.env.DEFT_ROOT);
+    }
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+}
+function runScenario(deftRoot, scenario) {
+    const pyArgs = ["run", "python", join(deftRoot, "scripts", "scm.py"), ...scenario.argv];
+    const tsArgs = [join(deftRoot, "packages", "core", "dist", "scm", "cli.js"), ...scenario.argv];
+    const py = runCapture("uv", pyArgs, deftRoot);
+    const ts = runCapture("node", tsArgs, deftRoot);
+    return {
+        python: {
+            name: scenario.name,
+            exitCode: py.status,
+            stdout: py.stdout,
+            stderr: py.stderr,
+        },
+        ts: {
+            name: scenario.name,
+            exitCode: ts.status,
+            stdout: ts.stdout,
+            stderr: ts.stderr,
+        },
+    };
+}
+/** Diff python vs TS outputs for one scenario. */
+export function diffParity(python, ts) {
+    const pythonMessage = normaliseMessage(python.stdout, python.stderr, python.exitCode);
+    const tsMessage = normaliseMessage(ts.stdout, ts.stderr, ts.exitCode);
+    return {
+        exitMismatch: python.exitCode !== ts.exitCode,
+        messageMismatch: pythonMessage !== tsMessage,
+        pythonMessage,
+        tsMessage,
+    };
+}
+/** Run all parity scenarios and return a structured result. */
+export function runParity() {
+    const deftRoot = resolveDeftRoot();
+    const scenarios = [];
+    for (const scenario of PARITY_SCENARIOS) {
+        const ran = runScenario(deftRoot, scenario);
+        const diff = diffParity(ran.python, ran.ts);
+        scenarios.push({
+            name: scenario.name,
+            pythonExit: ran.python.exitCode,
+            tsExit: ran.ts.exitCode,
+            ...diff,
+        });
+    }
+    const ok = scenarios.every((s) => !s.exitMismatch && !s.messageMismatch);
+    return { ok, scenarios };
+}
+/** Render a human-readable parity report. */
+export function renderReport(result) {
+    if (result.ok) {
+        return `scm parity: CLEAN -- Python and TS agree on ${result.scenarios.length} scenario(s).`;
+    }
+    const lines = ["scm parity: DIVERGENCE"];
+    for (const s of result.scenarios) {
+        if (s.exitMismatch || s.messageMismatch) {
+            lines.push(`  scenario: ${s.name}`);
+            if (s.exitMismatch) {
+                lines.push(`    exit mismatch: python=${s.pythonExit} ts=${s.tsExit}`);
+            }
+            if (s.messageMismatch) {
+                lines.push(`    python: ${s.pythonMessage}`);
+                lines.push(`    ts:     ${s.tsMessage}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    try {
+        const result = runParity();
+        if (result.ok) {
+            process.stdout.write(`${renderReport(result)}\n`);
+            process.exit(0);
+        }
+        process.stderr.write(`${renderReport(result)}\n`);
+        process.exit(1);
+    }
+    catch (err) {
+        const msg = String(err).replace(/\r?\n/g, " ");
+        process.stderr.write(`scm parity: harness error -- ${msg}\n`);
+        process.exit(2);
+    }
+}
+//# sourceMappingURL=scm-parity.js.map

package/dist/scope-lifecycle-parity.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+export interface CommandCapture {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ParityCase {
+    readonly name: string;
+    readonly argv: readonly string[];
+    readonly fileRel?: string;
+}
+export interface ParityDiff {
+    readonly caseName: string;
+    readonly exitMismatch: boolean;
+    readonly stdoutMismatch: boolean;
+    readonly stderrMismatch: boolean;
+    readonly pythonExit: number;
+    readonly tsExit: number;
+    readonly pythonStdout: string;
+    readonly pythonStderr: string;
+    readonly tsStdout: string;
+    readonly tsStderr: string;
+}
+export interface ParityResult {
+    readonly ok: boolean;
+    readonly diffs: ParityDiff[];
+}
+export declare function normalizeOutput(text: string): string;
+export declare const PARITY_CASES: readonly ParityCase[];
+export declare function buildArgv(repo: string, testCase: ParityCase): string[];
+export declare function diffCase(python: CommandCapture, ts: CommandCapture, caseName: string): ParityDiff;
+export declare function runParity(): ParityResult;
+export declare function renderReport(result: ParityResult): string;
+export declare function runParityCli(): number;
+//# sourceMappingURL=scope-lifecycle-parity.d.ts.map

package/dist/scope-lifecycle-parity.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * Golden-output parity harness (#1726): runs BOTH the Python oracle
+ * (`scripts/scope_lifecycle.py`) and the ported TS scope lifecycle CLI,
+ * then diffs exit codes and normalised stdout/stderr.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const FIXTURE_NAME = "2026-04-12-add-oauth.vbrief.json";
+export function normalizeOutput(text) {
+    return text
+        .replace(/--project-root [^\s]+/g, "--project-root <ROOT>")
+        .trim()
+        .replace(/\s+/g, " ");
+}
+function runCapture(cmd, args, cwd) {
+    const result = spawnSync(cmd, args, {
+        cwd,
+        encoding: "utf8",
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        exitCode: result.status ?? 2,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+    };
+}
+function resolveDeftRoot() {
+    if (process.env.DEFT_ROOT !== undefined && process.env.DEFT_ROOT.length > 0) {
+        return resolve(process.env.DEFT_ROOT);
+    }
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+}
+function writeFixture(repo, folder, status) {
+    const full = join(repo, "vbrief", folder, FIXTURE_NAME);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, `${JSON.stringify({
+        vBRIEFInfo: { version: "0.5" },
+        plan: { title: "Add OAuth support", status, items: [] },
+    }, null, 2)}\n`, "utf8");
+    return full;
+}
+export const PARITY_CASES = [
+    { name: "usage-no-args", argv: [] },
+    {
+        name: "invalid-transition-promote-active",
+        argv: ["promote", "<FILE>"],
+        fileRel: `vbrief/active/${FIXTURE_NAME}`,
+    },
+    {
+        name: "promote-success",
+        argv: ["promote", "<FILE>"],
+        fileRel: `vbrief/proposed/${FIXTURE_NAME}`,
+    },
+];
+export function buildArgv(repo, testCase) {
+    return testCase.argv.map((arg) => {
+        if (arg === "<FILE>" && testCase.fileRel !== undefined) {
+            return join(repo, testCase.fileRel);
+        }
+        return arg;
+    });
+}
+function runPythonScope(deftRoot, repo, argv) {
+    return runCapture("uv", [
+        "run",
+        "python",
+        join(deftRoot, "scripts", "scope_lifecycle.py"),
+        ...argv,
+        "--project-root",
+        repo,
+    ], deftRoot);
+}
+function runTsScope(deftRoot, repo, argv) {
+    return runCapture("node", [
+        join(deftRoot, "packages", "core", "dist", "scope", "cli.js"),
+        ...argv,
+        "--project-root",
+        repo,
+    ], deftRoot);
+}
+export function diffCase(python, ts, caseName) {
+    return {
+        caseName,
+        exitMismatch: python.exitCode !== ts.exitCode,
+        stdoutMismatch: normalizeOutput(python.stdout) !== normalizeOutput(ts.stdout),
+        stderrMismatch: normalizeOutput(python.stderr) !== normalizeOutput(ts.stderr),
+        pythonExit: python.exitCode,
+        tsExit: ts.exitCode,
+        pythonStdout: python.stdout,
+        pythonStderr: python.stderr,
+        tsStdout: ts.stdout,
+        tsStderr: ts.stderr,
+    };
+}
+function setupFixtureRepo(testCase) {
+    const repo = mkdtempSync(join(tmpdir(), "deft-scope-parity-"));
+    mkdirSync(join(repo, "vbrief"), { recursive: true });
+    if (testCase.fileRel?.includes("/proposed/")) {
+        writeFixture(repo, "proposed", "proposed");
+    }
+    if (testCase.fileRel?.includes("/active/")) {
+        writeFixture(repo, "active", "running");
+    }
+    return repo;
+}
+export function runParity() {
+    const deftRoot = resolveDeftRoot();
+    const diffs = [];
+    for (const testCase of PARITY_CASES) {
+        const mutates = testCase.name === "promote-success";
+        const pyRepo = setupFixtureRepo(testCase);
+        const tsRepo = mutates ? setupFixtureRepo(testCase) : pyRepo;
+        try {
+            const pyArgv = buildArgv(pyRepo, testCase);
+            const tsArgv = buildArgv(tsRepo, testCase);
+            const py = runPythonScope(deftRoot, pyRepo, pyArgv);
+            const ts = runTsScope(deftRoot, tsRepo, tsArgv);
+            diffs.push(diffCase(py, ts, testCase.name));
+        }
+        finally {
+            rmSync(pyRepo, { recursive: true, force: true });
+            if (tsRepo !== pyRepo) {
+                rmSync(tsRepo, { recursive: true, force: true });
+            }
+        }
+    }
+    const ok = diffs.every((d) => !d.exitMismatch && !d.stdoutMismatch && !d.stderrMismatch);
+    return { ok, diffs };
+}
+export function renderReport(result) {
+    if (result.ok) {
+        return `scope-lifecycle parity: CLEAN -- Python and TS agree on ${result.diffs.length} scenario(s).`;
+    }
+    const lines = ["scope-lifecycle parity: DIVERGENCE"];
+    for (const d of result.diffs) {
+        if (d.exitMismatch || d.stdoutMismatch || d.stderrMismatch) {
+            lines.push(`  scenario: ${d.caseName}`);
+            if (d.exitMismatch) {
+                lines.push(`    exit mismatch: python=${d.pythonExit} ts=${d.tsExit}`);
+            }
+            if (d.stdoutMismatch) {
+                lines.push(`    python stdout: ${normalizeOutput(d.pythonStdout)}`);
+                lines.push(`    ts stdout:     ${normalizeOutput(d.tsStdout)}`);
+            }
+            if (d.stderrMismatch) {
+                lines.push(`    python stderr: ${normalizeOutput(d.pythonStderr)}`);
+                lines.push(`    ts stderr:     ${normalizeOutput(d.tsStderr)}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+export function runParityCli() {
+    try {
+        const result = runParity();
+        if (result.ok) {
+            process.stdout.write(`${renderReport(result)}\n`);
+            return 0;
+        }
+        process.stderr.write(`${renderReport(result)}\n`);
+        return 1;
+    }
+    catch (err) {
+        const msg = String(err).replace(/\r?\n/g, " ");
+        process.stderr.write(`scope-lifecycle parity: harness error -- ${msg}\n`);
+        return 2;
+    }
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(runParityCli());
+}
+//# sourceMappingURL=scope-lifecycle-parity.js.map

package/dist/scope-lifecycle.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** Run scope lifecycle with argv; returns process exit code. */
+export declare function run(argv: string[]): number;
+//# sourceMappingURL=scope-lifecycle.d.ts.map

package/dist/scope-lifecycle.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Thin CLI entry for scope lifecycle (#1726).
+ * Delegates to packages/core/dist/scope/cli.js.
+ */
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function coreCliPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), "../../core/dist/scope/cli.js");
+}
+/** Run scope lifecycle with argv; returns process exit code. */
+export function run(argv) {
+    const result = spawnSync(process.execPath, [coreCliPath(), ...argv], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (typeof result.stdout === "string" && result.stdout.length > 0) {
+        process.stdout.write(result.stdout);
+    }
+    if (typeof result.stderr === "string" && result.stderr.length > 0) {
+        process.stderr.write(result.stderr);
+    }
+    return result.status ?? 2;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=scope-lifecycle.js.map

package/dist/session-parity.d.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+export interface Capture {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface Fixture {
+    readonly root: string;
+    readonly head: string;
+}
+export interface ParityCase {
+    readonly name: string;
+    readonly setup: () => Fixture;
+    readonly tier: "quick" | "gated";
+    readonly bypass: boolean;
+    readonly nowIso: string;
+    readonly runner?: (command: readonly string[], projectRoot: string) => {
+        code: number;
+        stdout: string;
+        stderr: string;
+    };
+}
+export declare const PARITY_CASES: readonly ParityCase[];
+export interface ParityDiff {
+    readonly name: string;
+    readonly exitMismatch: boolean;
+    readonly stdoutMismatch: boolean;
+    readonly pythonExit: number;
+    readonly tsExit: number;
+    readonly pythonStdout: string;
+    readonly tsStdout: string;
+}
+export interface ParityResult {
+    readonly ok: boolean;
+    readonly diffs: ParityDiff[];
+}
+export declare function runParity(): ParityResult;
+export declare function renderReport(result: ParityResult): string;
+//# sourceMappingURL=session-parity.d.ts.map