@deftai/directive 0.55.0

package/dist/verify-story-ready.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluate, gitPorcelain, parseAllocationSection } from "@deftai/directive-core/story-ready";
+/** Parse verify-story-ready CLI args, mirroring the Python argparse surface. */
+export function parseArgs(argv) {
+    const parsed = {
+        vbriefPath: null,
+        projectRoot: ".",
+        allocationContext: null,
+        allowDirty: false,
+        emitJson: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--allow-dirty") {
+            parsed.allowDirty = true;
+        }
+        else if (arg === "--json") {
+            parsed.emitJson = true;
+        }
+        else if (arg === "--vbrief-path") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --vbrief-path: expected one argument" };
+            }
+            parsed.vbriefPath = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--vbrief-path=")) {
+            parsed.vbriefPath = arg.slice("--vbrief-path=".length);
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--allocation-context") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --allocation-context: expected one argument" };
+            }
+            parsed.allocationContext = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--allocation-context=")) {
+            parsed.allocationContext = arg.slice("--allocation-context=".length);
+        }
+        else if (arg === "--help" || arg === "-h") {
+            return { ...parsed, help: true };
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    if (parsed.vbriefPath === null) {
+        return { ...parsed, error: "argument --vbrief-path is required" };
+    }
+    return parsed;
+}
+const HELP_TEXT = `usage: verify-story-ready [--vbrief-path PATH] [--project-root PATH]
+                          [--allocation-context PATH] [--allow-dirty] [--json]
+
+Deterministic story-start Gate 0 (#1378). Three-state exit: 0 ready / 1 not ready / 2 config error.
+`;
+function emitJson(vbriefPath, exitCode, message, dispatchKind) {
+    const payload = {
+        dispatch_kind: dispatchKind,
+        exit_code: exitCode,
+        message,
+        ready: exitCode === 0,
+        vbrief_path: vbriefPath,
+    };
+    const sorted = Object.fromEntries(Object.keys(payload)
+        .sort()
+        .map((k) => [k, payload[k]]));
+    return JSON.stringify(sorted);
+}
+/** Run the gate and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        process.stdout.write(HELP_TEXT);
+        return 0;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_story_ready: ${args.error}\n`);
+        return 2;
+    }
+    const vbriefPath = resolve(args.vbriefPath);
+    const projectRoot = resolve(args.projectRoot);
+    let allocationContextText = null;
+    if (args.allocationContext !== null) {
+        const envelopePath = resolve(args.allocationContext);
+        try {
+            allocationContextText = readFileSync(envelopePath, "utf8");
+        }
+        catch (err) {
+            const message = `config error: could not read --allocation-context file ${envelopePath}: ${String(err.message ?? err)}.`;
+            if (args.emitJson) {
+                process.stdout.write(`${emitJson(vbriefPath, 2, message, null)}\n`);
+            }
+            else {
+                process.stderr.write(`${message}\n`);
+            }
+            return 2;
+        }
+    }
+    const gitStatus = gitPorcelain(projectRoot);
+    const parsed = parseAllocationSection(allocationContextText);
+    const result = evaluate(vbriefPath, {
+        gitStatus,
+        allocationContext: allocationContextText,
+        allowDirty: args.allowDirty,
+        parsed,
+    });
+    if (args.emitJson) {
+        process.stdout.write(`${emitJson(vbriefPath, result.exitCode, result.message, result.dispatchKind)}\n`);
+    }
+    else if (result.exitCode === 0) {
+        process.stdout.write(`${result.message}\n`);
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.exitCode;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-story-ready.js.map

package/dist/verify-tools.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    install: boolean;
+    yes: boolean;
+    emitJson: boolean;
+    includeTask: boolean;
+    platform: string | undefined;
+    error?: string;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-tools.d.ts.map

package/dist/verify-tools.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { verificationResultToJson, verifyRequiredTools } from "@deftai/directive-core/verify-env";
+export function parseArgs(argv) {
+    const parsed = {
+        install: false,
+        yes: false,
+        emitJson: false,
+        includeTask: false,
+        platform: undefined,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--install")
+            parsed.install = true;
+        else if (arg === "--yes")
+            parsed.yes = true;
+        else if (arg === "--json")
+            parsed.emitJson = true;
+        else if (arg === "--include-task")
+            parsed.includeTask = true;
+        else if (arg === "--platform") {
+            const value = argv[i + 1];
+            if (value === undefined)
+                return { ...parsed, error: "argument --platform: expected one argument" };
+            parsed.platform = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--platform=")) {
+            parsed.platform = arg.slice("--platform=".length);
+        }
+        else {
+            return { ...parsed, error: `unrecognized arguments: ${arg}` };
+        }
+    }
+    return parsed;
+}
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_tools.py: error: ${args.error}\n`);
+        return 2;
+    }
+    const captured = [];
+    const result = verifyRequiredTools({
+        install: args.install,
+        assumeYes: args.yes,
+        includeTask: args.includeTask,
+        platformId: args.platform,
+        outputFn: (line) => {
+            captured.push(line);
+        },
+    });
+    if (args.emitJson) {
+        process.stdout.write(`${verificationResultToJson(result)}\n`);
+    }
+    else {
+        for (const line of captured) {
+            process.stdout.write(`${line}\n`);
+        }
+    }
+    return result.exitCode;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-tools.js.map

package/dist/verify-wip-cap.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    allowOverCap: boolean;
+    quiet: boolean;
+    error?: string;
+}
+/** Parse verify-wip-cap CLI args, mirroring the Python argparse surface. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run the gate and return the process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-wip-cap.d.ts.map

package/dist/verify-wip-cap.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluate } from "@deftai/directive-core/wip-cap";
+/** Parse verify-wip-cap CLI args, mirroring the Python argparse surface. */
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        allowOverCap: false,
+        quiet: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--allow-over-cap") {
+            parsed.allowOverCap = true;
+        }
+        else if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+/** Run the gate and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_wip_cap: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const result = evaluate(projectRoot, {
+        allowOverCap: args.allowOverCap,
+        quiet: args.quiet,
+    });
+    if (result.message.length > 0) {
+        if (result.stream === "stdout") {
+            process.stdout.write(`${result.message}\n`);
+        }
+        else if (result.stream === "stderr") {
+            process.stderr.write(`${result.message}\n`);
+        }
+    }
+    return result.code;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-wip-cap.js.map

package/dist/wip-cap-parity.d.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+export interface CommandCapture {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface WipFixtureOptions {
+    readonly plan?: Record<string, unknown>;
+    readonly pendingFiles?: number;
+    readonly activeFiles?: number;
+}
+export interface ParityCase {
+    readonly name: string;
+    readonly argv: string[];
+    readonly fixture?: WipFixtureOptions;
+}
+export interface ParityDiff {
+    readonly caseName: string;
+    readonly exitMismatch: boolean;
+    readonly stdoutMismatch: boolean;
+    readonly stderrMismatch: boolean;
+    readonly pythonExit: number;
+    readonly tsExit: number;
+}
+export interface ParityResult {
+    readonly ok: boolean;
+    readonly diffs: ParityDiff[];
+}
+/** Strip volatile absolute paths before compare. */
+export declare function normalizeOutput(text: string): string;
+/** Build a throwaway project root with optional PROJECT-DEFINITION and WIP files. */
+export declare function buildFixtureRepo(options?: WipFixtureOptions): string;
+/** Diff one parity case between Python oracle and TS CLI. */
+export declare function diffCase(python: CommandCapture, ts: CommandCapture, caseName: string): ParityDiff;
+export declare const PARITY_CASES: readonly ParityCase[];
+/** Run all parity cases; returns aggregate result. */
+export declare function runParity(): ParityResult;
+export declare function renderReport(result: ParityResult): string;
+//# sourceMappingURL=wip-cap-parity.d.ts.map

package/dist/wip-cap-parity.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * Golden-output parity harness (#1723): builds throwaway fixture repos, runs
+ * BOTH the Python oracle (`scripts/preflight_wip_cap.py`) and the ported TS
+ * verify:wip-cap gate, and diffs exit codes + stdout/stderr (cache-off).
+ *
+ * Exit codes: 0 parity / 1 divergence / 2 harness setup error.
+ */
+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";
+/** Strip volatile absolute paths before compare. */
+export function normalizeOutput(text) {
+    return text.replace(/project_root=[^\s)]+/g, "project_root=<ROOT>");
+}
+function runCapture(cmd, args, cwd, env = {}) {
+    const merged = { ...process.env, ...env };
+    for (const key of Object.keys(merged)) {
+        if (merged[key] === undefined)
+            delete merged[key];
+    }
+    const result = spawnSync(cmd, args, {
+        cwd,
+        encoding: "utf8",
+        env: merged,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        status: result.status ?? 2,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+    };
+}
+function writeProjectDefinition(root, plan) {
+    const dir = join(root, "vbrief");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "PROJECT-DEFINITION.vbrief.json"), `${JSON.stringify({
+        vBRIEFInfo: { version: "0.6" },
+        plan: { title: "T", status: "running", items: [], ...plan },
+    }, null, 2)}\n`, { encoding: "utf8" });
+}
+function writeVbrief(root, folder, name) {
+    const dir = join(root, "vbrief", folder);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, name), `${JSON.stringify({ vBRIEFInfo: { version: "0.6" }, plan: { status: "approved", title: "T", items: [] } })}\n`, { encoding: "utf8" });
+}
+/** Build a throwaway project root with optional PROJECT-DEFINITION and WIP files. */
+export function buildFixtureRepo(options = {}) {
+    const root = mkdtempSync(join(tmpdir(), "deft-wip-cap-parity-"));
+    mkdirSync(join(root, "vbrief"), { recursive: true });
+    if (options.plan !== undefined) {
+        writeProjectDefinition(root, options.plan);
+    }
+    for (let i = 0; i < (options.pendingFiles ?? 0); i += 1) {
+        writeVbrief(root, "pending", `pending-${i}.vbrief.json`);
+    }
+    for (let i = 0; i < (options.activeFiles ?? 0); i += 1) {
+        writeVbrief(root, "active", `active-${i}.vbrief.json`);
+    }
+    return root;
+}
+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 runPythonWipCap(deftRoot, repo, argv) {
+    const cap = runCapture("uv", [
+        "run",
+        "python",
+        join(deftRoot, "scripts", "preflight_wip_cap.py"),
+        ...argv,
+        "--project-root",
+        repo,
+    ], deftRoot);
+    return { exitCode: cap.status, stdout: cap.stdout, stderr: cap.stderr };
+}
+function runTsWipCap(deftRoot, repo, argv) {
+    const cap = runCapture("node", [
+        join(deftRoot, "packages", "cli", "dist", "verify-wip-cap.js"),
+        ...argv,
+        "--project-root",
+        repo,
+    ], deftRoot);
+    return { exitCode: cap.status, stdout: cap.stdout, stderr: cap.stderr };
+}
+/** Diff one parity case between Python oracle and TS CLI. */
+export function diffCase(python, ts, caseName) {
+    const pyOut = normalizeOutput(python.stdout);
+    const tsOut = normalizeOutput(ts.stdout);
+    const pyErr = normalizeOutput(python.stderr);
+    const tsErr = normalizeOutput(ts.stderr);
+    return {
+        caseName,
+        exitMismatch: python.exitCode !== ts.exitCode,
+        stdoutMismatch: pyOut !== tsOut,
+        stderrMismatch: pyErr !== tsErr,
+        pythonExit: python.exitCode,
+        tsExit: ts.exitCode,
+    };
+}
+export const PARITY_CASES = [
+    {
+        name: "within-cap-typed-empty",
+        argv: [],
+        fixture: { plan: { policy: { wipCap: 5 } } },
+    },
+    {
+        name: "within-cap-with-files",
+        argv: [],
+        fixture: {
+            plan: { policy: { wipCap: 5 } },
+            pendingFiles: 2,
+            activeFiles: 1,
+        },
+    },
+    {
+        name: "over-cap-refusal",
+        argv: [],
+        fixture: {
+            plan: { policy: { wipCap: 2 } },
+            pendingFiles: 1,
+            activeFiles: 1,
+        },
+    },
+    {
+        name: "over-cap-allow-flag",
+        argv: ["--allow-over-cap"],
+        fixture: {
+            plan: { policy: { wipCap: 2 } },
+            pendingFiles: 2,
+        },
+    },
+    {
+        name: "malformed-wipCap",
+        argv: [],
+        fixture: { plan: { policy: { wipCap: -1 } } },
+    },
+    {
+        name: "within-cap-quiet",
+        argv: ["--quiet"],
+        fixture: { plan: { policy: { wipCap: 3 } }, pendingFiles: 1 },
+    },
+    {
+        name: "over-cap-allow-quiet",
+        argv: ["--allow-over-cap", "--quiet"],
+        fixture: {
+            plan: { policy: { wipCap: 1 } },
+            pendingFiles: 2,
+        },
+    },
+];
+/** Run all parity cases; returns aggregate result. */
+export function runParity() {
+    const deftRoot = resolveDeftRoot();
+    const diffs = [];
+    for (const testCase of PARITY_CASES) {
+        const pyRepo = buildFixtureRepo(testCase.fixture);
+        const tsRepo = buildFixtureRepo(testCase.fixture);
+        try {
+            const python = runPythonWipCap(deftRoot, pyRepo, testCase.argv);
+            const ts = runTsWipCap(deftRoot, tsRepo, testCase.argv);
+            diffs.push(diffCase(python, ts, testCase.name));
+        }
+        finally {
+            rmSync(pyRepo, { recursive: true, force: true });
+            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 `verify:wip-cap parity: CLEAN -- Python and TS agree on ${PARITY_CASES.length} cases.`;
+    }
+    const lines = ["verify:wip-cap parity: DIVERGENCE"];
+    for (const d of result.diffs) {
+        if (d.exitMismatch || d.stdoutMismatch || d.stderrMismatch) {
+            lines.push(`  case: ${d.caseName}`);
+            if (d.exitMismatch)
+                lines.push(`    exit: python=${d.pythonExit} ts=${d.tsExit}`);
+            if (d.stdoutMismatch)
+                lines.push("    stdout mismatch");
+            if (d.stderrMismatch)
+                lines.push("    stderr mismatch");
+        }
+    }
+    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) {
+        process.stderr.write(`verify:wip-cap parity: harness error -- ${String(err)}\n`);
+        process.exit(2);
+    }
+}
+//# sourceMappingURL=wip-cap-parity.js.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@deftai/directive",
+  "version": "0.55.0",
+  "description": "Directive CLI — npm install path for the Deft Directive framework.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "directive": "./dist/bin.js",
+    "deft": "./dist/bin.js",
+    "deft-ts": "./dist/bin.js",
+    "deft-verify-encoding": "./dist/verify-encoding.js",
+    "deft-encoding-parity": "./dist/parity.js",
+    "deft-policy": "./dist/policy.js",
+    "deft-policy-parity": "./dist/policy-parity.js",
+    "deft-vbrief-preflight": "./dist/vbrief-preflight.js",
+    "deft-vbrief-preflight-parity": "./dist/vbrief-preflight-parity.js",
+    "deft-verify-story-ready": "./dist/verify-story-ready.js",
+    "deft-story-ready-parity": "./dist/story-ready-parity.js",
+    "deft-verify-branch": "./dist/verify-branch.js",
+    "deft-branch-parity": "./dist/branch-parity.js",
+    "deft-verify-wip-cap": "./dist/verify-wip-cap.js",
+    "deft-wip-cap-parity": "./dist/wip-cap-parity.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deftai/directive.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@deftai/directive-core": "^0.55.0"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}