@deftai/directive-core 0.55.0

package/dist/pr-wait-mergeable/main.js

@@ -0,0 +1,213 @@
+import { parseProtected } from "../pr-protected-issues/parse.js";
+import { waitMergeableAndMerge } from "./cascade.js";
+import { EXIT_CONFIG_ERROR, EXIT_MERGED, EXIT_TIMEOUT_OR_ESCALATION } from "./constants.js";
+import { toResultDict } from "./result.js";
+/** Match Python json.dumps(..., indent=2) default ensure_ascii=True. */
+function pythonJsonDumps(value) {
+    const json = JSON.stringify(value, null, 2);
+    return json.replace(/[\u007f-\uffff]/g, (ch) => {
+        const code = ch.charCodeAt(0);
+        return `\\u${code.toString(16).padStart(4, "0")}`;
+    });
+}
+export function parseWaitMergeableArgs(argv) {
+    let prNumber = null;
+    let repo = null;
+    let capMinutes = 60;
+    const protectedValues = [];
+    let emitJson = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--json") {
+            emitJson = true;
+        }
+        else if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    prNumber,
+                    repo,
+                    capMinutes,
+                    protectedValues,
+                    emitJson,
+                    error: "argument --repo: expected one argument",
+                };
+            }
+            repo = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--repo=")) {
+            repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--cap-minutes") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    prNumber,
+                    repo,
+                    capMinutes,
+                    protectedValues,
+                    emitJson,
+                    error: "argument --cap-minutes: expected one argument",
+                };
+            }
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed)) {
+                return {
+                    prNumber,
+                    repo,
+                    capMinutes,
+                    protectedValues,
+                    emitJson,
+                    error: `invalid --cap-minutes value: ${value}`,
+                };
+            }
+            capMinutes = parsed;
+            i += 1;
+        }
+        else if (arg?.startsWith("--cap-minutes=")) {
+            const value = arg.slice("--cap-minutes=".length);
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed)) {
+                return {
+                    prNumber,
+                    repo,
+                    capMinutes,
+                    protectedValues,
+                    emitJson,
+                    error: `invalid --cap-minutes value: ${value}`,
+                };
+            }
+            capMinutes = parsed;
+        }
+        else if (arg === "--protected") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return {
+                    prNumber,
+                    repo,
+                    capMinutes,
+                    protectedValues,
+                    emitJson,
+                    error: "argument --protected: expected one argument",
+                };
+            }
+            protectedValues.push(value);
+            i += 1;
+        }
+        else if (arg?.startsWith("--protected=")) {
+            protectedValues.push(arg.slice("--protected=".length));
+        }
+        else if (arg?.startsWith("-")) {
+            return {
+                prNumber,
+                repo,
+                capMinutes,
+                protectedValues,
+                emitJson,
+                error: `unrecognized arguments: ${arg}`,
+            };
+        }
+        else if (prNumber === null) {
+            const n = Number(arg);
+            if (!Number.isInteger(n)) {
+                return {
+                    prNumber,
+                    repo,
+                    capMinutes,
+                    protectedValues,
+                    emitJson,
+                    error: `invalid PR number: ${arg}`,
+                };
+            }
+            prNumber = n;
+        }
+        else {
+            return {
+                prNumber,
+                repo,
+                capMinutes,
+                protectedValues,
+                emitJson,
+                error: `unrecognized arguments: ${arg}`,
+            };
+        }
+    }
+    if (prNumber === null) {
+        return {
+            prNumber,
+            repo,
+            capMinutes,
+            protectedValues,
+            emitJson,
+            error: "the following arguments are required: pr_number",
+        };
+    }
+    return { prNumber, repo, capMinutes, protectedValues, emitJson };
+}
+function summaryLabelForExit(exitCode) {
+    switch (exitCode) {
+        case EXIT_MERGED:
+            return "MERGED";
+        case EXIT_TIMEOUT_OR_ESCALATION:
+            return "TIMEOUT-OR-ESCALATION";
+        case EXIT_CONFIG_ERROR:
+            return "CONFIG-ERROR";
+        default:
+            return "UNKNOWN";
+    }
+}
+export function runWaitMergeable(argv, options = {}) {
+    const args = parseWaitMergeableArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`Error: ${args.error}\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    const repo = args.repo ?? process.env.GH_REPO ?? null;
+    if (repo === null || repo.length === 0) {
+        process.stderr.write("Error: --repo OWNER/REPO is required (or set $GH_REPO).\n");
+        return EXIT_CONFIG_ERROR;
+    }
+    let protectedIssues;
+    try {
+        protectedIssues = parseProtected(args.protectedValues);
+    }
+    catch (exc) {
+        const message = exc instanceof Error ? exc.message : String(exc);
+        process.stderr.write(`Error: ${message}\n`);
+        return EXIT_CONFIG_ERROR;
+    }
+    const result = waitMergeableAndMerge(args.prNumber, repo, {
+        capMinutes: args.capMinutes,
+        protected: protectedIssues,
+        protectedFn: options.protectedFn,
+        monitorFn: options.monitorFn,
+        mergeFn: options.mergeFn,
+    });
+    const summaryLabel = summaryLabelForExit(result.exitCode);
+    process.stderr.write(`[pr_wait_mergeable] PR #${result.prNumber} repo=${result.repo} ` +
+        `result=${summaryLabel} outcome=${result.outcome}\n`);
+    if (args.emitJson) {
+        process.stdout.write(`${pythonJsonDumps(toResultDict(result))}\n`);
+    }
+    else {
+        const lines = [];
+        lines.push(`PR #${result.prNumber} wait-mergeable-and-merge result: ${summaryLabel}`);
+        lines.push(`  outcome: ${result.outcome}`);
+        if (result.error !== null) {
+            lines.push(`  error:   ${result.error}`);
+        }
+        if (result.mergeStdout.trim().length > 0) {
+            lines.push("  merge stdout:");
+            for (const line of result.mergeStdout.trim().split("\n")) {
+                lines.push(`    ${line}`);
+            }
+        }
+        process.stdout.write(`${lines.join("\n")}\n`);
+    }
+    return result.exitCode;
+}
+export function cmdPrWaitMergeable(argv, options = {}) {
+    return runWaitMergeable(argv, options);
+}
+//# sourceMappingURL=main.js.map

package/dist/pr-wait-mergeable/result.d.ts

@@ -0,0 +1,9 @@
+import type { WaitMergeableResult } from "./types.js";
+export declare function toResultDict(result: WaitMergeableResult): Record<string, unknown>;
+export declare function makeResult(fields: Omit<WaitMergeableResult, "monitorResult" | "protectedCheck" | "mergeStdout" | "mergeStderr"> & {
+    readonly monitorResult?: Record<string, unknown>;
+    readonly protectedCheck?: Record<string, unknown>;
+    readonly mergeStdout?: string;
+    readonly mergeStderr?: string;
+}): WaitMergeableResult;
+//# sourceMappingURL=result.d.ts.map

package/dist/pr-wait-mergeable/result.js

@@ -0,0 +1,38 @@
+export function toResultDict(result) {
+    const payload = {
+        pr_number: result.prNumber,
+        repo: result.repo,
+        outcome: result.outcome,
+        exit_code: result.exitCode,
+    };
+    if (Object.keys(result.monitorResult).length > 0) {
+        payload.monitor_result = result.monitorResult;
+    }
+    if (Object.keys(result.protectedCheck).length > 0) {
+        payload.protected_check = result.protectedCheck;
+    }
+    if (result.mergeStdout.length > 0) {
+        payload.merge_stdout = result.mergeStdout;
+    }
+    if (result.mergeStderr.length > 0) {
+        payload.merge_stderr = result.mergeStderr;
+    }
+    if (result.error !== null) {
+        payload.error = result.error;
+    }
+    return payload;
+}
+export function makeResult(fields) {
+    return {
+        monitorResult: fields.monitorResult ?? {},
+        protectedCheck: fields.protectedCheck ?? {},
+        mergeStdout: fields.mergeStdout ?? "",
+        mergeStderr: fields.mergeStderr ?? "",
+        prNumber: fields.prNumber,
+        repo: fields.repo,
+        outcome: fields.outcome,
+        exitCode: fields.exitCode,
+        error: fields.error,
+    };
+}
+//# sourceMappingURL=result.js.map

package/dist/pr-wait-mergeable/types.d.ts

@@ -0,0 +1,16 @@
+export interface WaitMergeableResult {
+    readonly prNumber: number;
+    readonly repo: string | null;
+    readonly outcome: string;
+    readonly exitCode: number;
+    readonly monitorResult: Record<string, unknown>;
+    readonly protectedCheck: Record<string, unknown>;
+    readonly mergeStdout: string;
+    readonly mergeStderr: string;
+    readonly error: string | null;
+}
+export type SubprocessTriple = readonly [number, string, string];
+export type ProtectedCheckFn = (prNumber: number, repo: string | null, protectedIssues: readonly number[]) => SubprocessTriple;
+export type MonitorFn = (prNumber: number, repo: string, capMinutes: number) => SubprocessTriple;
+export type MergeFn = (prNumber: number, repo: string | null) => SubprocessTriple;
+//# sourceMappingURL=types.d.ts.map

package/dist/pr-wait-mergeable/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/pr-wait-mergeable/wrappers.d.ts

@@ -0,0 +1,26 @@
+import type { SubprocessTriple } from "./types.js";
+export interface CaptureExecResult {
+    readonly returncode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** UTF-8-safe subprocess capture via spawnSync (no shell) — mirrors #1366. */
+export declare function captureExec(executable: string, args: readonly string[], timeoutMs: number): CaptureExecResult;
+export interface RunProtectedCheckOptions {
+    readonly nodeExecutable?: string;
+    readonly timeout?: number;
+}
+/** Invoke pr-protected-issues CLI and return (returncode, stdout, stderr). */
+export declare function runProtectedCheck(prNumber: number, repo: string | null, protectedIssues: readonly number[], options?: RunProtectedCheckOptions): SubprocessTriple;
+export interface RunMonitorOptions {
+    readonly nodeExecutable?: string;
+    readonly timeout?: number;
+}
+/** Invoke pr-monitor CLI with --json and return (returncode, stdout, stderr). */
+export declare function runMonitor(prNumber: number, repo: string, capMinutes: number, options?: RunMonitorOptions): SubprocessTriple;
+export interface RunGhMergeOptions {
+    readonly timeout?: number;
+}
+/** Invoke ``gh pr merge --squash --delete-branch --admin``. */
+export declare function runGhMerge(prNumber: number, repo: string | null, options?: RunGhMergeOptions): SubprocessTriple;
+//# sourceMappingURL=wrappers.d.ts.map

package/dist/pr-wait-mergeable/wrappers.js

@@ -0,0 +1,103 @@
+import { spawnSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveBinary } from "../scm/binary.js";
+import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
+/** UTF-8-safe subprocess capture via spawnSync (no shell) — mirrors #1366. */
+export function captureExec(executable, args, timeoutMs) {
+    const result = spawnSync(executable, args, {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: SUBPROCESS_MAX_BUFFER,
+        env: process.env,
+    });
+    if (result.error !== undefined) {
+        const code = result.error.code;
+        if (code === "ENOENT") {
+            return {
+                returncode: -1,
+                stdout: "",
+                stderr: `executable not found: ${executable}`,
+            };
+        }
+        if (code === "ETIMEDOUT") {
+            return {
+                returncode: -1,
+                stdout: "",
+                stderr: `timed out after ${timeoutMs}ms`,
+            };
+        }
+        return {
+            returncode: -1,
+            stdout: "",
+            stderr: String(result.error.message ?? result.error),
+        };
+    }
+    return {
+        returncode: result.status ?? -1,
+        stdout: typeof result.stdout === "string" ? result.stdout : "",
+        stderr: typeof result.stderr === "string" ? result.stderr : "",
+    };
+}
+function cliScriptPath(name) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, "../../../cli/dist", `${name}.js`);
+}
+/** Invoke pr-protected-issues CLI and return (returncode, stdout, stderr). */
+export function runProtectedCheck(prNumber, repo, protectedIssues, options = {}) {
+    const node = options.nodeExecutable ?? process.execPath;
+    const cmd = [
+        cliScriptPath("pr-protected-issues"),
+        String(prNumber),
+        "--protected",
+        protectedIssues.map(String).join(","),
+    ];
+    if (repo) {
+        cmd.push("--repo", repo);
+    }
+    const result = captureExec(node, cmd, (options.timeout ?? 60) * 1000);
+    return [result.returncode, result.stdout, result.stderr];
+}
+/** Invoke pr-monitor CLI with --json and return (returncode, stdout, stderr). */
+export function runMonitor(prNumber, repo, capMinutes, options = {}) {
+    const node = options.nodeExecutable ?? process.execPath;
+    const timeoutSec = options.timeout ?? capMinutes * 60 + 60;
+    const cmd = [
+        cliScriptPath("pr-monitor"),
+        String(prNumber),
+        "--repo",
+        repo,
+        "--cap-minutes",
+        String(capMinutes),
+        "--json",
+    ];
+    const result = captureExec(node, cmd, timeoutSec * 1000);
+    return [result.returncode, result.stdout, result.stderr];
+}
+/** Invoke ``gh pr merge --squash --delete-branch --admin``. */
+export function runGhMerge(prNumber, repo, options = {}) {
+    const timeoutSec = options.timeout ?? 120;
+    let binary;
+    try {
+        binary = resolveBinary();
+    }
+    catch {
+        return [-1, "", "gh CLI not found. Install GitHub CLI."];
+    }
+    const args = ["pr", "merge", String(prNumber), "--squash", "--delete-branch", "--admin"];
+    if (repo) {
+        args.push("--repo", repo);
+    }
+    const result = captureExec(binary, args, timeoutSec * 1000);
+    if (result.returncode === -1) {
+        if (result.stderr.includes("timed out after")) {
+            return [-1, "", `gh pr merge timed out after ${timeoutSec}s`];
+        }
+        if (result.stderr.includes("executable not found")) {
+            return [-1, "", "gh CLI not found. Install GitHub CLI."];
+        }
+    }
+    return [result.returncode, result.stdout, result.stderr];
+}
+//# sourceMappingURL=wrappers.js.map

package/dist/preflight/evaluate.d.ts

@@ -0,0 +1,22 @@
+/** Canonical eligibility folder — only vbrief/active/ may spawn implementation. */
+export declare const ACTIVE_FOLDER = "active";
+/** Canonical eligibility status — only `running` signals an active handoff. */
+export declare const ELIGIBLE_STATUS = "running";
+/** Actionable redirect appended to every reject path (#810). */
+export declare const ACTIVATE_HINT = "Run `task vbrief:activate {path}` before spawning an implementation agent.";
+/** Result of a vBRIEF preflight evaluation; mirrors the Python `evaluate` tuple. */
+export interface EvaluateResult {
+    readonly exitCode: 0 | 1;
+    readonly message: string;
+}
+/** Substitute `{path}` without `$`-pattern expansion in user paths (#1721). */
+export declare function formatActivateHint(path: string): string;
+/**
+ * Pure evaluator — returns `{ exitCode, message }`. Never throws; every error
+ * path collapses to exit 1 with an actionable message. Faithful to
+ * `scripts/preflight_implementation.py::evaluate`.
+ */
+export declare function evaluate(vbriefPath: string): EvaluateResult;
+/** Structured `--json` payload (sorted keys), mirroring Python `_emit_json`. */
+export declare function emitJson(vbriefPath: string, exitCode: number, message: string): string;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/preflight/evaluate.js

@@ -0,0 +1,137 @@
+import { readFileSync, statSync } from "node:fs";
+import { basename, dirname } from "node:path";
+/** Canonical eligibility folder — only vbrief/active/ may spawn implementation. */
+export const ACTIVE_FOLDER = "active";
+/** Canonical eligibility status — only `running` signals an active handoff. */
+export const ELIGIBLE_STATUS = "running";
+/** Actionable redirect appended to every reject path (#810). */
+export const ACTIVATE_HINT = "Run `task vbrief:activate {path}` before spawning an implementation agent.";
+/** Substitute `{path}` without `$`-pattern expansion in user paths (#1721). */
+export function formatActivateHint(path) {
+    return ACTIVATE_HINT.replace("{path}", () => path);
+}
+function buildReject(path, reason) {
+    return `${reason}\n  ${formatActivateHint(path)}`;
+}
+/** Map Node `JSON.parse` errors to CPython `json.JSONDecodeError.msg` for parity (#1721). */
+function nodeJsonErrorToPythonMsg(nodeMessage) {
+    if (nodeMessage.includes("Expected property name") ||
+        nodeMessage.includes("Expected double-quoted property name")) {
+        return "Expecting property name enclosed in double quotes";
+    }
+    if (nodeMessage.startsWith("Unexpected token") ||
+        nodeMessage.startsWith("Unexpected end of JSON input")) {
+        return "Expecting value";
+    }
+    if (nodeMessage.includes("Unexpected non-whitespace character after JSON")) {
+        return "Extra data";
+    }
+    const atPos = nodeMessage.indexOf(" at position ");
+    return atPos >= 0 ? nodeMessage.slice(0, atPos) : nodeMessage;
+}
+/**
+ * Pure evaluator — returns `{ exitCode, message }`. Never throws; every error
+ * path collapses to exit 1 with an actionable message. Faithful to
+ * `scripts/preflight_implementation.py::evaluate`.
+ */
+export function evaluate(vbriefPath) {
+    const path = vbriefPath;
+    let st;
+    try {
+        st = statSync(vbriefPath);
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            return {
+                exitCode: 1,
+                message: buildReject(path, `vBRIEF not found at ${path}.`),
+            };
+        }
+        return {
+            exitCode: 1,
+            message: buildReject(path, `Could not read vBRIEF at ${path}: ${String(e.message)}.`),
+        };
+    }
+    if (!st.isFile()) {
+        return {
+            exitCode: 1,
+            message: buildReject(path, `vBRIEF path ${path} is not a regular file.`),
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(vbriefPath, "utf8");
+    }
+    catch (err) {
+        const e = err;
+        return {
+            exitCode: 1,
+            message: buildReject(path, `Could not read vBRIEF at ${path}: ${String(e.message)}.`),
+        };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch (err) {
+        const e = err;
+        const lineCol = /\(line (\d+) column \d+\)/.exec(e.message);
+        const line = lineCol ? Number(lineCol[1]) : 1;
+        const pyMsg = nodeJsonErrorToPythonMsg(e.message);
+        return {
+            exitCode: 1,
+            message: buildReject(path, `vBRIEF at ${path} is not valid JSON: ${pyMsg} (line ${line}).`),
+        };
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return {
+            exitCode: 1,
+            message: buildReject(path, `vBRIEF at ${path} top-level value is not a JSON object.`),
+        };
+    }
+    const folder = basename(dirname(vbriefPath));
+    if (folder !== ACTIVE_FOLDER) {
+        return {
+            exitCode: 1,
+            message: buildReject(path, `vBRIEF is in ${folder}/ -- only vbrief/active/ is eligible for implementation.`),
+        };
+    }
+    const record = payload;
+    const plan = record.plan;
+    if (plan === null || typeof plan !== "object" || Array.isArray(plan)) {
+        return {
+            exitCode: 1,
+            message: buildReject(path, `vBRIEF at ${path} lacks a \`plan\` object -- malformed.`),
+        };
+    }
+    const planRecord = plan;
+    const status = planRecord.status;
+    if (typeof status !== "string" || status.length === 0) {
+        return {
+            exitCode: 1,
+            message: buildReject(path, `vBRIEF at ${path} lacks \`plan.status\` -- malformed.`),
+        };
+    }
+    if (status !== ELIGIBLE_STATUS) {
+        return {
+            exitCode: 1,
+            message: buildReject(path, `plan.status is '${status}' -- only '${ELIGIBLE_STATUS}' is eligible for implementation.`),
+        };
+    }
+    return {
+        exitCode: 0,
+        message: `OK ${path} -- ready for implementation.`,
+    };
+}
+/** Structured `--json` payload (sorted keys), mirroring Python `_emit_json`. */
+export function emitJson(vbriefPath, exitCode, message) {
+    const payload = {
+        ready: exitCode === 0,
+        exit_code: exitCode,
+        vbrief_path: vbriefPath,
+        message,
+    };
+    return JSON.stringify(payload, Object.keys(payload).sort());
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/preflight/index.d.ts

@@ -0,0 +1,3 @@
+export type { EvaluateResult } from "./evaluate.js";
+export { ACTIVATE_HINT, ACTIVE_FOLDER, ELIGIBLE_STATUS, emitJson, evaluate, formatActivateHint, } from "./evaluate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/preflight/index.js

@@ -0,0 +1,2 @@
+export { ACTIVATE_HINT, ACTIVE_FOLDER, ELIGIBLE_STATUS, emitJson, evaluate, formatActivateHint, } from "./evaluate.js";
+//# sourceMappingURL=index.js.map

package/dist/preflight-cache/evaluate.d.ts

@@ -0,0 +1,40 @@
+/**
+ * preflight-cache/evaluate.ts -- Detection-bound cache-freshness gate (#1127).
+ *
+ * TypeScript port of scripts/preflight_cache.py. Checks whether the triage
+ * cache is fresh, missing (bootstrap state), or stale. Subscription-aware:
+ * respects plan.policy.triageScope[] when present in PROJECT-DEFINITION.
+ *
+ * Exit codes (three-state, mirrors preflight_cache.py):
+ *   0 -- cache fresh (or bootstrap state with --allow-missing-bootstrap)
+ *   1 -- cache stale / blocking condition found
+ *   2 -- config error (cache missing and --allow-missing-bootstrap not set)
+ */
+export declare const CACHE_DIR_NAME = ".deft-cache";
+export declare const DEFAULT_SOURCE = "github-issue";
+export declare const CANDIDATES_RELPATH: string;
+export declare const DEFAULT_MAX_AGE_HOURS = 24;
+export declare const ENV_MAX_AGE_HOURS = "DEFT_CACHE_MAX_AGE_HOURS";
+export declare const ENV_TRIAGE_REPO = "DEFT_TRIAGE_REPO";
+export declare const REQUIRED_DECISION = "accept";
+export interface GateResult {
+    readonly code: number;
+    readonly message: string;
+}
+export interface EvaluateOptions {
+    source?: string;
+    repo?: string | null;
+    maxAgeHours?: number | null;
+    forIssue?: number | null;
+    allowStale?: boolean;
+    allowMissingBootstrap?: boolean;
+    /** Injectable clock for tests. */
+    nowFn?: () => Date;
+}
+/**
+ * Evaluate cache freshness for the given project root.
+ *
+ * Faithful port of scripts/preflight_cache.py::evaluate().
+ */
+export declare function evaluate(projectRoot: string, options?: EvaluateOptions): GateResult;
+//# sourceMappingURL=evaluate.d.ts.map