@deftai/directive 0.55.0

package/dist/preflight-cache.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot?: string;
+    source?: string;
+    repo?: string;
+    maxAgeHours?: number;
+    forIssue?: number;
+    allowStale?: boolean;
+    allowMissingBootstrap?: boolean;
+    quiet?: boolean;
+    error?: string;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=preflight-cache.d.ts.map

package/dist/preflight-cache.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * preflight-cache.ts -- CLI for the cache-freshness gate (#1127).
+ *
+ * Usage:
+ *   deft-ts preflight-cache --project-root <path> --allow-missing-bootstrap
+ *   deft-ts preflight-cache --project-root <path> --for-issue <N>
+ *
+ * Thin shim -- delegates to @deftai/directive-core/preflight-cache.
+ */
+import { fileURLToPath } from "node:url";
+import { evaluate } from "@deftai/directive-core/preflight-cache";
+export function parseArgs(argv) {
+    const parsed = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i] ?? "";
+        if (arg === "--project-root") {
+            const next = argv[i + 1];
+            if (next === undefined)
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            parsed.projectRoot = next;
+            i++;
+        }
+        else if (arg.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--source") {
+            const next = argv[i + 1];
+            if (next === undefined)
+                return { ...parsed, error: "argument --source: expected one argument" };
+            parsed.source = next;
+            i++;
+        }
+        else if (arg === "--repo") {
+            const next = argv[i + 1];
+            if (next === undefined)
+                return { ...parsed, error: "argument --repo: expected one argument" };
+            parsed.repo = next;
+            i++;
+        }
+        else if (arg === "--max-age-hours") {
+            const next = argv[i + 1];
+            if (next === undefined)
+                return { ...parsed, error: "argument --max-age-hours: expected one argument" };
+            parsed.maxAgeHours = Number.parseInt(next, 10);
+            i++;
+        }
+        else if (arg === "--for-issue") {
+            const next = argv[i + 1];
+            if (next === undefined)
+                return { ...parsed, error: "argument --for-issue: expected one argument" };
+            parsed.forIssue = Number.parseInt(next, 10);
+            i++;
+        }
+        else if (arg === "--allow-stale") {
+            parsed.allowStale = true;
+        }
+        else if (arg === "--allow-missing-bootstrap") {
+            parsed.allowMissingBootstrap = true;
+        }
+        else if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`preflight-cache: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = args.projectRoot ?? ".";
+    const result = evaluate(projectRoot, {
+        source: args.source,
+        repo: args.repo,
+        maxAgeHours: args.maxAgeHours ?? null,
+        forIssue: args.forIssue ?? null,
+        allowStale: args.allowStale ?? false,
+        allowMissingBootstrap: args.allowMissingBootstrap ?? false,
+    });
+    const quiet = args.quiet ?? false;
+    if (result.code === 0) {
+        if (!quiet) {
+            if (result.message.startsWith("⚠")) {
+                process.stderr.write(`${result.message}\n`);
+            }
+            else {
+                process.stdout.write(`${result.message}\n`);
+            }
+        }
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.code;
+}
+/* v8 ignore start -- entry guard */
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+/* v8 ignore stop */
+//# sourceMappingURL=preflight-cache.js.map

package/dist/preflight-gh.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    mode?: "self-test" | "command" | "pre-push-stdin";
+    command?: string;
+    defaultBranches?: Set<string>;
+    quiet?: boolean;
+    error?: string;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function run(argv: string[]): number | Promise<number>;
+export {};
+//# sourceMappingURL=preflight-gh.d.ts.map

package/dist/preflight-gh.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * preflight-gh.ts -- CLI for the destructive-gh-verb gate (#1019).
+ *
+ * Usage:
+ *   deft-ts preflight-gh --self-test
+ *   deft-ts preflight-gh --command "<gh ...>"
+ *   deft-ts preflight-gh --pre-push-stdin  (reads from stdin)
+ *
+ * Thin shim -- delegates to @deftai/directive-core/preflight-gh.
+ */
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_BRANCHES, ENV_BYPASS, evaluateCommand, runSelfTest, } from "@deftai/directive-core/preflight-gh";
+export function parseArgs(argv) {
+    const parsed = { defaultBranches: new Set(DEFAULT_BRANCHES) };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i] ?? "";
+        if (arg === "--self-test") {
+            parsed.mode = "self-test";
+        }
+        else if (arg === "--pre-push-stdin") {
+            parsed.mode = "pre-push-stdin";
+        }
+        else if (arg === "--command") {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                return { ...parsed, error: "argument --command: expected one argument" };
+            }
+            parsed.mode = "command";
+            parsed.command = next;
+            i++;
+        }
+        else if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--default-branch") {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                return { ...parsed, error: "argument --default-branch: expected one argument" };
+            }
+            parsed.defaultBranches ??= new Set();
+            parsed.defaultBranches.add(next);
+            i++;
+        }
+        else if (arg === "--project-root") {
+            // accepted for parity with preflight_branch.py; ignored here
+            i++;
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`preflight-gh: ${args.error}\n`);
+        return 2;
+    }
+    const quiet = args.quiet ?? false;
+    const branches = args.defaultBranches ?? new Set(DEFAULT_BRANCHES);
+    if (args.mode === "self-test") {
+        const [code, msg] = runSelfTest();
+        if (code === 0) {
+            if (!quiet)
+                process.stdout.write(`${msg}\n`);
+        }
+        else {
+            process.stderr.write(`${msg}\n`);
+        }
+        return code;
+    }
+    if (args.mode === "command" && args.command !== undefined) {
+        const [code, msg] = evaluateCommand(args.command, branches);
+        if (code === 0) {
+            if (!quiet)
+                process.stdout.write(`${msg}\n`);
+        }
+        else {
+            process.stderr.write(`${msg}\n`);
+        }
+        return code;
+    }
+    if (args.mode === "pre-push-stdin") {
+        return runPrePushStdin(branches, quiet);
+    }
+    process.stderr.write("preflight-gh: one of --self-test / --command / --pre-push-stdin required\n");
+    return 2;
+}
+function parsePrePushLines(text) {
+    return text
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .flatMap((l) => {
+        const parts = l.split(/\s+/);
+        if (parts.length !== 4)
+            return [];
+        return [
+            {
+                localRef: parts[0] ?? "",
+                localOid: parts[1] ?? "",
+                remoteRef: parts[2] ?? "",
+                remoteOid: parts[3] ?? "",
+            },
+        ];
+    });
+}
+const ZERO_OID_RE = /^0+$/;
+function evaluatePrePush(refs, branches) {
+    if (refs.length === 0) {
+        return [0, "✓ deft destructive-gh-verb gate (pre-push): no refs in stdin -- nothing to gate."];
+    }
+    const branchesLower = new Set([...branches].map((b) => b.toLowerCase()));
+    const blocked = [];
+    for (const { localRef, localOid, remoteRef, remoteOid } of refs) {
+        const branch = remoteRef.replace(/^refs\/heads\//, "");
+        if (!branchesLower.has(branch.toLowerCase()))
+            continue;
+        if (ZERO_OID_RE.test(remoteOid)) {
+            blocked.push(`create ${branch} (local=${localRef})`);
+        }
+        else if (ZERO_OID_RE.test(localOid)) {
+            blocked.push(`delete ${branch}`);
+        }
+        else {
+            blocked.push(`update ${branch} (local=${localRef})`);
+        }
+    }
+    if (blocked.length === 0) {
+        return [
+            0,
+            "✓ deft destructive-gh-verb gate (pre-push): no pushes to default branches detected -- proceeding.",
+        ];
+    }
+    const bypass = (process.env[ENV_BYPASS] ?? "").trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(bypass)) {
+        return [
+            0,
+            `⚠ deft destructive-gh-verb gate (pre-push): default-branch push detected (${blocked.join("; ")}) but ${ENV_BYPASS}=1 is set -- policy bypassed for this invocation.`,
+        ];
+    }
+    return [
+        1,
+        [
+            "❌ deft destructive-gh-verb gate (pre-push): refusing to push directly to the default branch.",
+            `  Detail: ${blocked.join("; ")}`,
+            "",
+            "  How to proceed:",
+            "    • push to a feature branch and open a PR",
+            `    • or set the env-var bypass for this shell:  ${ENV_BYPASS}=1`,
+            "  See scm/github.md (## Destructive gh verbs (#1019)).",
+        ].join("\n"),
+    ];
+}
+function runPrePushStdin(branches, quiet) {
+    return new Promise((resolve) => {
+        const lines = [];
+        const rl = createInterface({ input: process.stdin });
+        rl.on("line", (l) => lines.push(l));
+        rl.on("close", () => {
+            const refs = parsePrePushLines(lines.join("\n"));
+            const [code, msg] = evaluatePrePush(refs, branches);
+            if (code === 0) {
+                if (!quiet)
+                    process.stdout.write(`${msg}\n`);
+            }
+            else {
+                process.stderr.write(`${msg}\n`);
+            }
+            resolve(code);
+        });
+    });
+}
+/* v8 ignore start -- entry guard */
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    const result = run(process.argv.slice(2));
+    if (result instanceof Promise) {
+        result.then((code) => process.exit(code)).catch(() => process.exit(2));
+    }
+    else {
+        process.exit(result);
+    }
+}
+/* v8 ignore stop */
+//# sourceMappingURL=preflight-gh.js.map

package/dist/probe-session.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function run(argv: string[]): number;
+//# sourceMappingURL=probe-session.d.ts.map

package/dist/probe-session.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { cmdProbeSession } from "@deftai/directive-core/orchestration";
+export function run(argv) {
+    return cmdProbeSession(argv);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=probe-session.js.map

package/dist/release-e2e-parity.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+export interface CommandCapture {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ParityScenario {
+    readonly name: string;
+    readonly argv: readonly string[];
+    readonly compareStdout?: boolean;
+}
+export interface ParityDiff {
+    readonly name: string;
+    readonly exitMismatch: boolean;
+    readonly outputMismatch: boolean;
+    readonly pythonExit: number;
+    readonly tsExit: number;
+    readonly pythonOutput: string;
+    readonly tsOutput: string;
+    readonly stream: "stdout" | "stderr";
+}
+export interface ParityResult {
+    readonly ok: boolean;
+    readonly diffs: ParityDiff[];
+}
+export declare const PARITY_SCENARIOS: readonly ParityScenario[];
+/** Normalise volatile repo slugs and ISO dates in stderr while preserving semantics. */
+export declare function normaliseStderr(text: string): string;
+export declare function runParity(): ParityResult;
+export declare function renderReport(result: ParityResult): string;
+//# sourceMappingURL=release-e2e-parity.d.ts.map

package/dist/release-e2e-parity.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Golden-output parity harness (#1729): runs BOTH the Python oracle
+ * (`scripts/release_e2e.py`) and the ported TS release:e2e CLI with
+ * identical argv, then diffs exit codes and normalised stderr/stdout.
+ */
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const PARITY_SCENARIOS = [
+    { name: "help", argv: ["--help"], compareStdout: true },
+    { name: "dry-run", argv: ["--dry-run"] },
+    { name: "dry-run-keep-repo", argv: ["--dry-run", "--keep-repo"] },
+    {
+        name: "dry-run-project-root",
+        argv: ["--dry-run", "--owner", "deftai", "--project-root", "/tmp/deft-e2e-parity-root"],
+    },
+];
+/** Normalise volatile repo slugs and ISO dates in stderr while preserving semantics. */
+export function normaliseStderr(text) {
+    return text
+        .replace(/deftai-release-test-\d{14}-[0-9a-f]{6}/g, "deftai-release-test-YYYYMMDDHHMMSS-uuid6")
+        .replace(/\d{4}-\d{2}-\d{2}/g, "YYYY-MM-DD");
+}
+function runCapture(cmd, args, cwd) {
+    const result = spawnSync(cmd, args, {
+        cwd,
+        encoding: "utf8",
+        env: {
+            ...process.env,
+            DEFT_CACHE_DISABLE: "1",
+            PYTHONUTF8: "1",
+        },
+        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 runScenario(deftRoot, scenario) {
+    const argv = [...scenario.argv];
+    const py = runCapture("uv", ["run", "python", join(deftRoot, "scripts", "release_e2e.py"), ...argv], deftRoot);
+    const ts = runCapture("node", [join(deftRoot, "packages", "cli", "dist", "release-e2e.js"), ...argv], deftRoot);
+    const stream = scenario.compareStdout ? "stdout" : "stderr";
+    let pythonOutput = stream === "stdout" ? py.stdout : py.stderr;
+    let tsOutput = stream === "stdout" ? ts.stdout : ts.stderr;
+    if (stream === "stderr") {
+        pythonOutput = normaliseStderr(pythonOutput);
+        tsOutput = normaliseStderr(tsOutput);
+    }
+    return {
+        name: scenario.name,
+        exitMismatch: py.exitCode !== ts.exitCode,
+        outputMismatch: pythonOutput !== tsOutput,
+        pythonExit: py.exitCode,
+        tsExit: ts.exitCode,
+        pythonOutput,
+        tsOutput,
+        stream,
+    };
+}
+export function runParity() {
+    const deftRoot = resolveDeftRoot();
+    const diffs = PARITY_SCENARIOS.map((scenario) => runScenario(deftRoot, scenario));
+    const ok = diffs.every((d) => !d.exitMismatch && !d.outputMismatch);
+    return { ok, diffs };
+}
+export function renderReport(result) {
+    if (result.ok) {
+        return `release-e2e parity: CLEAN -- Python and TS agree on ${result.diffs.length} scenario(s).`;
+    }
+    const lines = ["release-e2e parity: DIVERGENCE"];
+    for (const d of result.diffs) {
+        if (d.exitMismatch || d.outputMismatch) {
+            lines.push(`  scenario: ${d.name}`);
+            if (d.exitMismatch) {
+                lines.push(`    exit mismatch: python=${d.pythonExit} ts=${d.tsExit}`);
+            }
+            if (d.outputMismatch) {
+                lines.push(`    stream: ${d.stream}`);
+                lines.push(`    python (${d.pythonOutput.length} bytes):`);
+                lines.push(d.pythonOutput);
+                lines.push(`    ts (${d.tsOutput.length} bytes):`);
+                lines.push(d.tsOutput);
+            }
+        }
+    }
+    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(`release-e2e parity: harness error -- ${msg}\n`);
+        process.exit(2);
+    }
+}
+//# sourceMappingURL=release-e2e-parity.js.map

package/dist/release-e2e.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function run(argv: string[]): number;
+//# sourceMappingURL=release-e2e.d.ts.map

package/dist/release-e2e.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { cmdReleaseE2e } from "../../core/dist/release-e2e/main.js";
+export function run(argv) {
+    return cmdReleaseE2e(argv);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=release-e2e.js.map

package/dist/release-parity.d.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+export declare const SAMPLE_CHANGELOG = " Changelog\n\nAll notable changes to the project.\n\n## [Unreleased]\n\n### Added\n- New release automation (#74)\n\n### Changed\n- Refactored module X\n\n### Fixed\n- Bug Y\n\n## [0.20.2] - 2026-04-24\n\n### Added\n- Prior change\n\n## [0.20.0] - 2026-04-23\n\n### Added\n- Older change\n\n[Unreleased]: https://github.com/deftai/directive/compare/v0.20.2...HEAD\n[0.20.2]: https://github.com/deftai/directive/compare/v0.20.0...v0.20.2\n[0.20.0]: https://github.com/deftai/directive/compare/v0.19.0...v0.20.0\n";
+export interface ScenarioResult {
+    readonly name: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ParityScenario {
+    readonly name: string;
+    readonly argv: readonly string[];
+    readonly setup?: (root: string) => void;
+    readonly compareStdout?: boolean;
+}
+export interface ParityResult {
+    readonly ok: boolean;
+    readonly scenarios: Array<{
+        readonly name: string;
+        readonly exitMismatch: boolean;
+        readonly pythonExit: number;
+        readonly tsExit: number;
+        readonly outputMismatch: boolean;
+        readonly pythonOutput: string;
+        readonly tsOutput: string;
+        readonly stream: "stdout" | "stderr";
+    }>;
+}
+export declare const PARITY_SCENARIOS: readonly ParityScenario[];
+/** Normalise volatile ISO dates in stderr while preserving semantics. */
+export declare function normaliseStderr(text: string): string;
+export declare function pickOutput(result: ScenarioResult, stream: "stdout" | "stderr"): string;
+export declare function diffParity(python: ScenarioResult, ts: ScenarioResult, stream: "stdout" | "stderr"): {
+    exitMismatch: boolean;
+    outputMismatch: boolean;
+    pythonOutput: string;
+    tsOutput: string;
+};
+export declare function runParity(): ParityResult;
+export declare function renderReport(result: ParityResult): string;
+//# sourceMappingURL=release-parity.d.ts.map