@deftai/directive 0.126.0-beta.1 → 0.126.0

package/dist/plan-sequence.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * plan-sequence CLI (#2402): set | current | clear | advance
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { advancePlanSequence, clearPlanSequence, collectTerminalLifecycleOrigins, createPlanSequence, detectTerminalEntryDrift, inspectMissingSequenceKind, missingSequenceKindPayload, parsePlanSequence, readPlanSequence, writePlanSequence, } from "@deftai/directive-core/plan-sequence";
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        action: null,
+        file: null,
+        jsonInline: null,
+        emitJson: false,
+        expectedGeneration: undefined,
+    };
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "--")
+            continue;
+        if (arg === "--json") {
+            parsed.emitJson = true;
+        }
+        else if (arg === "--project-root") {
+            const value = argv[++i];
+            if (value === undefined) {
+                return { ...parsed, error: "--project-root requires a value" };
+            }
+            parsed.projectRoot = value;
+        }
+        else if (arg.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--file") {
+            const value = argv[++i];
+            if (value === undefined) {
+                return { ...parsed, error: "--file requires a path" };
+            }
+            parsed.file = value;
+        }
+        else if (arg.startsWith("--file=")) {
+            parsed.file = arg.slice("--file=".length);
+        }
+        else if (arg === "--from-json") {
+            const value = argv[++i];
+            if (value === undefined) {
+                return { ...parsed, error: "--from-json requires a JSON string" };
+            }
+            parsed.jsonInline = value;
+        }
+        else if (arg === "--expected-generation") {
+            const value = argv[++i];
+            if (value === undefined) {
+                return { ...parsed, error: "--expected-generation requires a non-negative integer" };
+            }
+            const parsedGen = parseExpectedGeneration(value);
+            if (parsedGen === undefined) {
+                return { ...parsed, error: "--expected-generation requires a non-negative integer" };
+            }
+            parsed.expectedGeneration = parsedGen;
+        }
+        else if (arg.startsWith("--expected-generation=")) {
+            const parsedGen = parseExpectedGeneration(arg.slice("--expected-generation=".length));
+            if (parsedGen === undefined) {
+                return { ...parsed, error: "--expected-generation requires a non-negative integer" };
+            }
+            parsed.expectedGeneration = parsedGen;
+        }
+        else if (arg.startsWith("-")) {
+            return { ...parsed, error: `unknown flag: ${arg}` };
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    const action = positionals[0];
+    if (action === "set" || action === "current" || action === "clear" || action === "advance") {
+        parsed.action = action;
+    }
+    else if (action !== undefined) {
+        return { ...parsed, error: `unknown action: ${action} (set|current|clear|advance)` };
+    }
+    else {
+        parsed.error =
+            "usage: plan-sequence <set|current|clear|advance> [--file path] [--project-root path] [--expected-generation n]";
+    }
+    return parsed;
+}
+function parseExpectedGeneration(raw) {
+    if (!/^(0|[1-9]\d*)$/.test(raw))
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0)
+        return undefined;
+    return value;
+}
+function requireExpectedGeneration(parsed) {
+    if (parsed.expectedGeneration === undefined) {
+        return {
+            error: `${parsed.action ?? "plan-sequence"} requires --expected-generation <n>`,
+        };
+    }
+    return parsed.expectedGeneration;
+}
+function loadSetPayload(parsed, root) {
+    const text = parsed.file ? readFileSync(resolve(root, parsed.file), "utf8") : parsed.jsonInline;
+    if (text === null || text === undefined) {
+        throw new Error("plan-sequence set requires --file <path> or --from-json <json>");
+    }
+    const payload = JSON.parse(text);
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        throw new Error("plan-sequence set: --file/--from-json must contain a JSON object");
+    }
+    const raw = payload;
+    if (typeof raw.current_index === "number" || raw.exhausted === true) {
+        return parsePlanSequence(raw);
+    }
+    return createPlanSequence({
+        sequence_id: String(raw.sequence_id),
+        sequence_kind: raw.sequence_kind,
+        entries: raw.entries,
+        authorized_by: String(raw.authorized_by ?? ""),
+        batching_allowed: raw.batching_allowed === true,
+        continuation_past_final: raw.continuation_past_final === true,
+    });
+}
+export function main(argv = process.argv.slice(2)) {
+    const parsed = parseArgs(argv);
+    if (parsed.error || parsed.action === null) {
+        process.stderr.write(`${parsed.error ?? "usage error"}\n`);
+        return 2;
+    }
+    const root = resolve(parsed.projectRoot);
+    try {
+        if (parsed.action === "set") {
+            const expected = requireExpectedGeneration(parsed);
+            if (typeof expected !== "number") {
+                process.stderr.write(`${expected.error}\n`);
+                return 2;
+            }
+            const seq = loadSetPayload(parsed, root);
+            const result = writePlanSequence(root, seq, expected);
+            if (!result.ok) {
+                process.stderr.write(`${result.message}\n`);
+                return 1;
+            }
+            if (parsed.emitJson) {
+                process.stdout.write(`${JSON.stringify({ ok: true, path: result.path, sequence: result.sequence }, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`OK plan-sequence set ${result.sequence.sequence_id} (${result.sequence.entries.length} entries, index=${String(result.sequence.current_index)} generation=${String(result.sequence.generation)})\n`);
+            }
+            return 0;
+        }
+        if (parsed.action === "current") {
+            const missingKind = inspectMissingSequenceKind(root);
+            if (missingKind !== null) {
+                if (parsed.emitJson) {
+                    process.stdout.write(`${JSON.stringify(missingSequenceKindPayload(missingKind), null, 2)}\n`);
+                }
+                else {
+                    process.stderr.write(`${missingKind.message}\n`);
+                }
+                return 1;
+            }
+            const seq = readPlanSequence(root);
+            if (seq === null) {
+                process.stderr.write("No active ordered-plan sequence (.deft/plan-sequence.json missing).\n");
+                return 1;
+            }
+            const drift = detectTerminalEntryDrift(seq, collectTerminalLifecycleOrigins(root));
+            if (parsed.emitJson) {
+                if (drift.drifted) {
+                    process.stdout.write(`${JSON.stringify({
+                        ...seq,
+                        terminal_lifecycle_drift: {
+                            code: drift.code,
+                            message: drift.message,
+                            originPath: drift.originPath,
+                            folder: drift.folder,
+                        },
+                    }, null, 2)}\n`);
+                }
+                else {
+                    process.stdout.write(`${JSON.stringify(seq, null, 2)}\n`);
+                }
+            }
+            else if (drift.drifted) {
+                process.stderr.write(`${drift.message}\n`);
+            }
+            else {
+                const cur = seq.exhausted ? null : seq.entries[seq.current_index];
+                process.stdout.write(`sequence_id=${seq.sequence_id} kind=${seq.sequence_kind} index=${seq.current_index} exhausted=${String(seq.exhausted)} generation=${String(seq.generation)} source_revision=${seq.source_revision}\n`);
+                if (cur) {
+                    const issue = cur.issue !== undefined ? ` (#${cur.issue})` : "";
+                    process.stdout.write(`current: ${cur.kind}:${cur.id}${issue}\n`);
+                }
+                else {
+                    process.stdout.write("current: (exhausted — fresh approval required)\n");
+                }
+            }
+            return drift.drifted ? 1 : 0;
+        }
+        if (parsed.action === "clear") {
+            const expected = requireExpectedGeneration(parsed);
+            if (typeof expected !== "number") {
+                process.stderr.write(`${expected.error}\n`);
+                return 2;
+            }
+            const result = clearPlanSequence(root, expected);
+            if (!result.ok) {
+                process.stderr.write(`${result.message}\n`);
+                return 1;
+            }
+            process.stdout.write(result.removed ? "OK plan-sequence cleared\n" : "OK plan-sequence already absent\n");
+            return 0;
+        }
+        const expected = requireExpectedGeneration(parsed);
+        if (typeof expected !== "number") {
+            process.stderr.write(`${expected.error}\n`);
+            return 2;
+        }
+        const seq = readPlanSequence(root);
+        if (seq === null) {
+            process.stderr.write("No active ordered-plan sequence to advance.\n");
+            return 1;
+        }
+        const next = advancePlanSequence(seq);
+        const result = writePlanSequence(root, next, expected);
+        if (!result.ok) {
+            process.stderr.write(`${result.message}\n`);
+            return 1;
+        }
+        if (parsed.emitJson) {
+            process.stdout.write(`${JSON.stringify(result.sequence, null, 2)}\n`);
+        }
+        else if (result.sequence.exhausted) {
+            process.stdout.write(`OK advanced; sequence exhausted. Fresh operator approval required before another unit. generation=${String(result.sequence.generation)}\n`);
+        }
+        else {
+            const cur = result.sequence.entries[result.sequence.current_index];
+            process.stdout.write(`OK advanced to index=${result.sequence.current_index} (${cur?.kind}:${cur?.id}) generation=${String(result.sequence.generation)}\n`);
+        }
+        return 0;
+    }
+    catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    process.exit(main());
+}
+//# sourceMappingURL=plan-sequence.js.map

package/dist/policy-fixtures.d.ts

@@ -0,0 +1,33 @@
+export interface CommandCapture {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface ParityCase {
+    readonly name: string;
+    readonly argv: string[];
+    readonly env?: Record<string, string | undefined>;
+    readonly fixture?: Record<string, unknown>;
+}
+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 ISO timestamps from audit / JSON envelopes before compare. */
+export declare function normalizeOutput(text: string): string;
+/** Build a throwaway project root with optional PROJECT-DEFINITION plan payload. */
+export declare function buildFixtureRepo(plan?: Record<string, unknown>): 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 renderReport(result: ParityResult): string;
+//# sourceMappingURL=policy-fixtures.d.ts.map

package/dist/policy-fixtures.js

@@ -0,0 +1,118 @@
+/** Test fixtures extracted from legacy parity harness (#2083). */
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Strip volatile ISO timestamps from audit / JSON envelopes before compare. */
+export function normalizeOutput(text) {
+    return text
+        .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z/g, "<TS>")
+        .replace(/PROJECT-DEFINITION not found at [^\s)]+/g, "PROJECT-DEFINITION not found at <ROOT>")
+        .replace(/fail-closed: PROJECT-DEFINITION not found at [^)]+/g, "fail-closed: PROJECT-DEFINITION not found at <ROOT>");
+}
+function writeFixture(root, plan) {
+    const dir = join(root, "xbrief");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "PROJECT-DEFINITION.xbrief.json"), `${JSON.stringify({
+        xBRIEFInfo: { version: "0.8" },
+        plan: { title: "T", status: "running", items: [], ...plan },
+    }, null, 2)}\n`, { encoding: "utf8" });
+}
+/** Build a throwaway project root with optional PROJECT-DEFINITION plan payload. */
+export function buildFixtureRepo(plan) {
+    const root = mkdtempSync(join(tmpdir(), "deft-policy-parity-"));
+    mkdirSync(join(root, "xbrief"), { recursive: true });
+    if (plan !== undefined) {
+        writeFixture(root, plan);
+    }
+    return root;
+}
+/** 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: "resolve-default-missing-pd",
+        argv: ["resolve"],
+        env: { DEFT_ALLOW_DEFAULT_BRANCH_COMMIT: "" },
+    },
+    {
+        name: "resolve-typed-false",
+        argv: ["resolve"],
+        fixture: { policy: { allowDirectCommitsToMaster: false } },
+        env: { DEFT_ALLOW_DEFAULT_BRANCH_COMMIT: "" },
+    },
+    {
+        name: "resolve-typed-true",
+        argv: ["resolve"],
+        fixture: { policy: { allowDirectCommitsToMaster: true } },
+        env: { DEFT_ALLOW_DEFAULT_BRANCH_COMMIT: "" },
+    },
+    {
+        name: "resolve-legacy-narrative",
+        argv: ["resolve"],
+        fixture: { narratives: { "Allow direct commits to master": "true" } },
+        env: { DEFT_ALLOW_DEFAULT_BRANCH_COMMIT: "" },
+    },
+    {
+        name: "resolve-env-bypass",
+        argv: ["resolve"],
+        fixture: { policy: { allowDirectCommitsToMaster: false } },
+        env: { DEFT_ALLOW_DEFAULT_BRANCH_COMMIT: "1" },
+    },
+    {
+        name: "show-text-defaults",
+        argv: ["show"],
+        fixture: {},
+        env: { DEFT_ALLOW_DEFAULT_BRANCH_COMMIT: "" },
+    },
+    {
+        name: "show-field-wipCap",
+        argv: ["show", "--field", "plan.policy.wipCap"],
+        fixture: { policy: { wipCap: 7 } },
+        env: { DEFT_ALLOW_DEFAULT_BRANCH_COMMIT: "" },
+    },
+    {
+        name: "allow-direct-commits-refuse",
+        argv: ["allow-direct-commits"],
+        fixture: {},
+        env: { DEFT_ALLOW_DEFAULT_BRANCH_COMMIT: "" },
+    },
+    {
+        name: "enforce-branches",
+        argv: ["enforce-branches", "--actor", "parity-test"],
+        fixture: { policy: { allowDirectCommitsToMaster: true } },
+        env: { DEFT_ALLOW_DEFAULT_BRANCH_COMMIT: "" },
+    },
+];
+/** Run all parity cases; returns aggregate result. */
+export function renderReport(result) {
+    if (result.ok) {
+        return `policy parity: CLEAN -- Python and TS agree on ${PARITY_CASES.length} cases.`;
+    }
+    const lines = ["policy 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");
+}
+//# sourceMappingURL=policy-fixtures.js.map

package/dist/policy.d.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { type CeremonyDepth, type HookHost, type SpecGuardEnforcement } from "@deftai/directive-core/policy";
+interface ShowArgs {
+    format: "text" | "json";
+    changedOnly: boolean;
+    field: string | null;
+    projectRoot: string;
+    error?: string;
+}
+interface SetArgs {
+    cmd: "show" | "enforce-branches" | "allow-direct-commits" | "allow-destructive-gh-verbs" | "enforce-destructive-gh-verbs" | "allow-bot-merge" | "enable-value-feedback" | "clear-value-feedback" | "set-ceremony-dial" | "set-spec-guard-enforcement" | "disable-host-hooks" | "disable-directive" | "enable-directive" | "resolve";
+    confirm: boolean;
+    actor: string;
+    note: string;
+    host?: HookHost;
+    projectRoot: string;
+    format: "text" | "json";
+    changedOnly: boolean;
+    field: string | null;
+    /** #3214 ceremony dial override depth for set-ceremony-dial. */
+    ceremonyOverride?: CeremonyDepth | null;
+    /** #3214 ceremony dial enabled flag for set-ceremony-dial. */
+    ceremonyEnabled?: boolean;
+    /** #5350 driftGuard.enforcement target for set-spec-guard-enforcement. */
+    specGuardEnforcement?: SpecGuardEnforcement;
+    /** #4375 audited setter for valueFeedback.upstreamPrompt. */
+    upstreamPrompt?: boolean;
+    error?: string;
+}
+/** Parse policy:show flags (mirrors _policy_show_cli.py). */
+export declare function parseShowArgs(argv: string[]): ShowArgs;
+/** Parse argv for the policy CLI (show + set subcommands). */
+export declare function parseArgs(argv: string[]): SetArgs;
+/** Run the policy CLI; returns process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=policy.d.ts.map