@deftai/directive-core 0.55.0

package/dist/orchestration/pathspec.js

@@ -0,0 +1,95 @@
+/**
+ * Minimal gitignore-style glob matcher (#1419). Linear segment scanner — no
+ * backtracking regex (CodeQL js/polynomial-redos safe).
+ */
+/** Normalise path separators to forward slashes. */
+export function normalizePath(path) {
+    return path.replace(/\\/g, "/");
+}
+function matchSegmentPattern(pattern, segment) {
+    let pi = 0;
+    let si = 0;
+    while (pi < pattern.length) {
+        const pc = pattern[pi];
+        if (pc === "*") {
+            if (pattern[pi + 1] === "*") {
+                return false;
+            }
+            pi += 1;
+            while (si < segment.length) {
+                if (matchSegmentPattern(pattern.slice(pi), segment.slice(si))) {
+                    return true;
+                }
+                si += 1;
+            }
+            return matchSegmentPattern(pattern.slice(pi), "");
+        }
+        if (pc === "?") {
+            if (si >= segment.length) {
+                return false;
+            }
+            pi += 1;
+            si += 1;
+            continue;
+        }
+        if (si >= segment.length || segment[si] !== pc) {
+            return false;
+        }
+        pi += 1;
+        si += 1;
+    }
+    return si === segment.length;
+}
+function splitSegments(path) {
+    const norm = normalizePath(path);
+    if (norm.length === 0) {
+        return [];
+    }
+    return norm.split("/").filter((s) => s.length > 0);
+}
+function matchSegments(patternSegs, pathSegs, pIdx, sIdx) {
+    if (pIdx >= patternSegs.length) {
+        return sIdx >= pathSegs.length;
+    }
+    const pat = patternSegs[pIdx];
+    if (pat === "**") {
+        for (let skip = sIdx; skip <= pathSegs.length; skip += 1) {
+            if (matchSegments(patternSegs, pathSegs, pIdx + 1, skip)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    if (sIdx >= pathSegs.length) {
+        return false;
+    }
+    if (!matchSegmentPattern(pat, pathSegs[sIdx])) {
+        return false;
+    }
+    return matchSegments(patternSegs, pathSegs, pIdx + 1, sIdx + 1);
+}
+/** True when *path* matches the glob *pattern* (anchored full-path match). */
+export function matchPath(pattern, path) {
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        return false;
+    }
+    if (typeof path !== "string" || path.length === 0) {
+        return false;
+    }
+    const patternSegs = splitSegments(pattern);
+    const pathSegs = splitSegments(path);
+    return matchSegments(patternSegs, pathSegs, 0, 0);
+}
+/** True when *path* matches any glob in *patterns*. */
+export function matchAny(patterns, path) {
+    if (!Array.isArray(patterns)) {
+        return false;
+    }
+    for (const p of patterns) {
+        if (typeof p === "string" && p.length > 0 && matchPath(p, path)) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=pathspec.js.map

package/dist/orchestration/probe-session.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Mechanical guard for probe artifact handoff (#1518c). Port of scripts/probe_session.py.
+ */
+export declare const SCHEMA_VERSION = 1;
+export declare const SESSION_RELPATH: readonly [".deft", "probe-session.json"];
+export declare const STATE_INTERROGATE: "interrogate";
+export declare const STATE_COMPLETE: "complete";
+export type ProbeState = typeof STATE_INTERROGATE | typeof STATE_COMPLETE;
+export declare const VALID_DECISION_STATUSES: Set<string>;
+export declare class ProbeHandoffBlockedError extends Error {
+    readonly session: ProbeSession | null;
+    constructor(message: string, session?: ProbeSession | null);
+}
+export interface ResolvedDecision {
+    readonly question: string;
+    readonly answer: string;
+    readonly status: string;
+}
+export interface ProbeSession {
+    readonly schema_version: number;
+    readonly state: ProbeState;
+    readonly target: string;
+    readonly current_branch: string;
+    readonly resolved_decisions: readonly ResolvedDecision[];
+    readonly started_at: Date;
+    readonly completed_at: Date | null;
+}
+export declare function resolvedDecisionToDict(d: ResolvedDecision): Record<string, string>;
+export declare function resolvedDecisionFromDict(raw: unknown): ResolvedDecision | null;
+export declare function sessionToDict(session: ProbeSession): Record<string, unknown>;
+export declare function formatTimestamp(value: Date): string;
+/** Detect git branch (best effort, injectable for tests). */
+export declare function detectGitBranch(projectRoot: string, execGit?: (args: string[]) => {
+    status: number;
+    stdout: string;
+}): string;
+/** Read probe session from project root. */
+export declare function readSession(projectRoot: string): ProbeSession | null;
+/** Atomically persist session to .deft/probe-session.json. */
+export declare function writeSession(projectRoot: string, session: ProbeSession): string;
+export declare function startSession(projectRoot: string, options: {
+    target: string;
+    currentBranch?: string;
+    now?: Date;
+    detectBranch?: typeof detectGitBranch;
+}): ProbeSession;
+export declare function recordDecision(projectRoot: string, options: {
+    question: string;
+    answer: string;
+    status: string;
+}): ProbeSession;
+export declare function setCurrentBranch(projectRoot: string, branch: string): ProbeSession;
+export declare function markComplete(projectRoot: string, now?: Date): ProbeSession;
+export declare function requireHandoffAllowed(projectRoot: string, action: string): ProbeSession;
+export declare function guardProbeArtifact(projectRoot: string, artifactPath: string): ProbeSession;
+export declare function guardPlanProbeRegistration(projectRoot: string): ProbeSession;
+export declare function sessionSummary(session: ProbeSession): Record<string, unknown>;
+export interface ProbeSessionArgs {
+    command?: string;
+    projectRoot: string;
+    target?: string;
+    branch?: string;
+    question?: string;
+    answer?: string;
+    status?: string;
+    path?: string;
+    json?: boolean;
+    error?: string;
+}
+/** Parse probe-session CLI args (simplified subcommand parser). */
+export declare function parseProbeSessionArgs(argv: string[]): ProbeSessionArgs;
+/** Run probe-session CLI; returns exit code. */
+export declare function cmdProbeSession(argv: string[]): number;
+//# sourceMappingURL=probe-session.d.ts.map

package/dist/orchestration/probe-session.js

@@ -0,0 +1,478 @@
+/**
+ * Mechanical guard for probe artifact handoff (#1518c). Port of scripts/probe_session.py.
+ */
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, fdatasyncSync, mkdirSync, openSync, readFileSync, renameSync, writeSync, } from "node:fs";
+import { join, resolve } from "node:path";
+export const SCHEMA_VERSION = 1;
+export const SESSION_RELPATH = [".deft", "probe-session.json"];
+export const STATE_INTERROGATE = "interrogate";
+export const STATE_COMPLETE = "complete";
+export const VALID_DECISION_STATUSES = new Set(["locked", "deferred", "risk-accepted"]);
+export class ProbeHandoffBlockedError extends Error {
+    session;
+    constructor(message, session = null) {
+        super(message);
+        this.name = "ProbeHandoffBlockedError";
+        this.session = session;
+    }
+}
+export function resolvedDecisionToDict(d) {
+    return { question: d.question, answer: d.answer, status: d.status };
+}
+export function resolvedDecisionFromDict(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return null;
+    }
+    const obj = raw;
+    const question = obj.question;
+    const answer = obj.answer;
+    const status = obj.status;
+    if (typeof question !== "string" ||
+        typeof answer !== "string" ||
+        typeof status !== "string" ||
+        !question.trim() ||
+        !answer.trim() ||
+        !status.trim()) {
+        return null;
+    }
+    if (!VALID_DECISION_STATUSES.has(status.trim())) {
+        return null;
+    }
+    return {
+        question: question.trim(),
+        answer: answer.trim(),
+        status: status.trim(),
+    };
+}
+export function sessionToDict(session) {
+    const payload = {
+        schemaVersion: session.schema_version,
+        state: session.state,
+        target: session.target,
+        currentBranch: session.current_branch,
+        resolvedDecisions: session.resolved_decisions.map(resolvedDecisionToDict),
+        startedAt: formatTimestamp(session.started_at),
+    };
+    if (session.completed_at !== null) {
+        payload.completedAt = formatTimestamp(session.completed_at);
+    }
+    return payload;
+}
+function sessionPath(projectRoot) {
+    return join(projectRoot, ...SESSION_RELPATH);
+}
+export function formatTimestamp(value) {
+    return value.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function parseTimestamp(raw) {
+    if (typeof raw !== "string" || !raw) {
+        return null;
+    }
+    const normalised = raw.endsWith("Z") ? `${raw.slice(0, -1)}+00:00` : raw;
+    const parsed = new Date(normalised);
+    if (Number.isNaN(parsed.getTime())) {
+        return null;
+    }
+    return parsed;
+}
+function defaultExecGit(projectRoot, args) {
+    try {
+        const stdout = execFileSync("git", args, {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { status: 0, stdout: typeof stdout === "string" ? stdout : "" };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            status: typeof e.status === "number" ? e.status : 1,
+            stdout: typeof e.stdout === "string" ? e.stdout : "",
+        };
+    }
+}
+/** Detect git branch (best effort, injectable for tests). */
+export function detectGitBranch(projectRoot, execGit) {
+    const run = execGit ?? ((args) => defaultExecGit(projectRoot, args));
+    try {
+        const result = run(["symbolic-ref", "--short", "HEAD"]);
+        if (result.status === 0) {
+            const branch = result.stdout.trim();
+            if (branch) {
+                return branch;
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    try {
+        const revResult = run(["rev-parse", "--short", "HEAD"]);
+        if (revResult.status === 0) {
+            const sha = revResult.stdout.trim();
+            if (sha) {
+                return `detached:${sha}`;
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "";
+}
+/** Read probe session from project root. */
+export function readSession(projectRoot) {
+    const sessionFile = sessionPath(projectRoot);
+    if (!existsSync(sessionFile)) {
+        return null;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(sessionFile, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+        return null;
+    }
+    const obj = payload;
+    if (obj.schemaVersion !== SCHEMA_VERSION) {
+        return null;
+    }
+    const state = obj.state;
+    if (state !== STATE_INTERROGATE && state !== STATE_COMPLETE) {
+        return null;
+    }
+    const target = obj.target;
+    const currentBranch = obj.currentBranch;
+    if (typeof target !== "string" || !target.trim()) {
+        return null;
+    }
+    if (typeof currentBranch !== "string") {
+        return null;
+    }
+    const startedAt = parseTimestamp(obj.startedAt);
+    if (startedAt === null) {
+        return null;
+    }
+    const completedAt = parseTimestamp(obj.completedAt);
+    if (state === STATE_COMPLETE && completedAt === null) {
+        return null;
+    }
+    if (state === STATE_INTERROGATE && completedAt !== null) {
+        return null;
+    }
+    const rawDecisions = obj.resolvedDecisions;
+    if (!Array.isArray(rawDecisions)) {
+        return null;
+    }
+    const decisions = [];
+    for (const item of rawDecisions) {
+        const parsed = resolvedDecisionFromDict(item);
+        if (parsed === null) {
+            return null;
+        }
+        decisions.push(parsed);
+    }
+    return {
+        schema_version: SCHEMA_VERSION,
+        state,
+        target: target.trim(),
+        current_branch: currentBranch.trim(),
+        resolved_decisions: decisions,
+        started_at: startedAt,
+        completed_at: completedAt,
+    };
+}
+/** Atomically persist session to .deft/probe-session.json. */
+export function writeSession(projectRoot, session) {
+    const sessionFile = sessionPath(projectRoot);
+    mkdirSync(join(projectRoot, ".deft"), { recursive: true });
+    const tmpName = join(projectRoot, ".deft", `.probe-session.${randomBytes(8).toString("hex")}.json.tmp`);
+    const sortedPayload = sessionToDict(session);
+    const sortedKeys = Object.keys(sortedPayload).sort();
+    const sortedObj = {};
+    for (const k of sortedKeys) {
+        sortedObj[k] = sortedPayload[k];
+    }
+    const finalContent = `${JSON.stringify(sortedObj, null, 2)}\n`;
+    const fd = openSync(tmpName, "w");
+    try {
+        writeSync(fd, finalContent, undefined, "utf8");
+        try {
+            fdatasyncSync(fd);
+        }
+        catch {
+            // best effort
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmpName, sessionFile);
+    return sessionFile;
+}
+export function startSession(projectRoot, options) {
+    const scope = options.target.trim();
+    if (!scope) {
+        throw new Error("target must be a non-empty scope name");
+    }
+    const branch = (options.currentBranch ?? "").trim() || (options.detectBranch ?? detectGitBranch)(projectRoot);
+    const instant = options.now ?? new Date();
+    const session = {
+        schema_version: SCHEMA_VERSION,
+        state: STATE_INTERROGATE,
+        target: scope,
+        current_branch: branch,
+        resolved_decisions: [],
+        started_at: instant,
+        completed_at: null,
+    };
+    writeSession(projectRoot, session);
+    return session;
+}
+export function recordDecision(projectRoot, options) {
+    const session = readSession(projectRoot);
+    if (session === null) {
+        throw new ProbeHandoffBlockedError("No active probe session. Start one with `uv run python scripts/probe_session.py start --target <scope>`.");
+    }
+    if (session.state !== STATE_INTERROGATE) {
+        throw new ProbeHandoffBlockedError("Probe session is already complete; decisions cannot be appended.", session);
+    }
+    if (!VALID_DECISION_STATUSES.has(options.status)) {
+        throw new Error(`status must be one of ${[...VALID_DECISION_STATUSES].sort().join(", ")}, got ${JSON.stringify(options.status)}`);
+    }
+    const q = options.question.trim();
+    const a = options.answer.trim();
+    if (!q || !a) {
+        throw new Error("question and answer must be non-empty strings");
+    }
+    const updated = {
+        ...session,
+        resolved_decisions: [
+            ...session.resolved_decisions,
+            { question: q, answer: a, status: options.status },
+        ],
+    };
+    writeSession(projectRoot, updated);
+    return updated;
+}
+export function setCurrentBranch(projectRoot, branch) {
+    const session = readSession(projectRoot);
+    if (session === null) {
+        throw new ProbeHandoffBlockedError("No active probe session. Start one with `uv run python scripts/probe_session.py start --target <scope>`.");
+    }
+    if (session.state !== STATE_INTERROGATE) {
+        throw new ProbeHandoffBlockedError("Probe session is already complete; current branch cannot change.", session);
+    }
+    const updated = { ...session, current_branch: branch.trim() };
+    writeSession(projectRoot, updated);
+    return updated;
+}
+export function markComplete(projectRoot, now) {
+    const session = readSession(projectRoot);
+    if (session === null) {
+        throw new ProbeHandoffBlockedError("No active probe session. Start one with `uv run python scripts/probe_session.py start --target <scope>`.");
+    }
+    if (session.state === STATE_COMPLETE) {
+        return session;
+    }
+    const instant = now ?? new Date();
+    const updated = {
+        ...session,
+        state: STATE_COMPLETE,
+        completed_at: instant,
+    };
+    writeSession(projectRoot, updated);
+    return updated;
+}
+function pythonRepr(value) {
+    return `'${value}'`;
+}
+function blockedMessage(session, action) {
+    if (session === null) {
+        return (`Probe handoff blocked for ${action}: no active probe session. ` +
+            "Start interrogation with `uv run python scripts/probe_session.py start --target <scope>` " +
+            "and finish with `... complete` only after transition criteria are met.");
+    }
+    return (`Probe handoff blocked for ${action}: session state is ` +
+        `'${session.state}' (target=${pythonRepr(session.target)}, ` +
+        `currentBranch=${pythonRepr(session.current_branch)}, ` +
+        `resolvedDecisions=${session.resolved_decisions.length}). ` +
+        "Continue interrogation until transition criteria are met, record decisions " +
+        "with `uv run python scripts/probe_session.py record ...`, then run " +
+        "`uv run python scripts/probe_session.py complete` before writing artifacts " +
+        "or updating completedStrategies.probe in plan.vbrief.json.");
+}
+export function requireHandoffAllowed(projectRoot, action) {
+    const session = readSession(projectRoot);
+    if (session === null || session.state !== STATE_COMPLETE) {
+        throw new ProbeHandoffBlockedError(blockedMessage(session, action), session);
+    }
+    return session;
+}
+export function guardProbeArtifact(projectRoot, artifactPath) {
+    return requireHandoffAllowed(projectRoot, `probe artifact write (${artifactPath})`);
+}
+export function guardPlanProbeRegistration(projectRoot) {
+    return requireHandoffAllowed(projectRoot, "completedStrategies.probe registration in plan.vbrief.json");
+}
+export function sessionSummary(session) {
+    return {
+        state: session.state,
+        target: session.target,
+        currentBranch: session.current_branch,
+        resolvedDecisions: session.resolved_decisions.map(resolvedDecisionToDict),
+        startedAt: formatTimestamp(session.started_at),
+        completedAt: session.completed_at !== null ? formatTimestamp(session.completed_at) : null,
+    };
+}
+/** Parse probe-session CLI args (simplified subcommand parser). */
+export function parseProbeSessionArgs(argv) {
+    const parsed = { projectRoot: "." };
+    const rest = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root") {
+            parsed.projectRoot = argv[i + 1] ?? ".";
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--json") {
+            parsed.json = true;
+        }
+        else {
+            rest.push(arg ?? "");
+        }
+    }
+    if (rest.length === 0) {
+        return { ...parsed, error: "command required" };
+    }
+    parsed.command = rest[0];
+    for (let i = 1; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--target") {
+            parsed.target = rest[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--target=")) {
+            parsed.target = arg.slice("--target=".length);
+        }
+        else if (arg === "--branch") {
+            parsed.branch = rest[i + 1];
+            i += 1;
+        }
+        else if (arg?.startsWith("--branch=")) {
+            parsed.branch = arg.slice("--branch=".length);
+        }
+        else if (arg === "--question") {
+            parsed.question = rest[i + 1];
+            i += 1;
+        }
+        else if (arg === "--answer") {
+            parsed.answer = rest[i + 1];
+            i += 1;
+        }
+        else if (arg === "--status") {
+            parsed.status = rest[i + 1];
+            i += 1;
+        }
+        else if (arg === "--path") {
+            parsed.path = rest[i + 1];
+            i += 1;
+        }
+    }
+    return parsed;
+}
+/** Run probe-session CLI; returns exit code. */
+export function cmdProbeSession(argv) {
+    const args = parseProbeSessionArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    try {
+        if (args.command === "start") {
+            if (!args.target) {
+                process.stderr.write("target must be a non-empty scope name\n");
+                return 2;
+            }
+            const session = startSession(projectRoot, {
+                target: args.target,
+                currentBranch: args.branch ?? "",
+            });
+            process.stdout.write(`Probe session started: state=${session.state}, target=${JSON.stringify(session.target)}, currentBranch=${JSON.stringify(session.current_branch)}\n`);
+            return 0;
+        }
+        if (args.command === "record") {
+            const session = recordDecision(projectRoot, {
+                question: args.question ?? "",
+                answer: args.answer ?? "",
+                status: args.status ?? "",
+            });
+            process.stdout.write(`Recorded decision (${session.resolved_decisions.length} total); state=${session.state}\n`);
+            return 0;
+        }
+        if (args.command === "set-branch") {
+            const session = setCurrentBranch(projectRoot, args.branch ?? "");
+            process.stdout.write(`Current branch set to ${JSON.stringify(session.current_branch)}; state=${session.state}\n`);
+            return 0;
+        }
+        if (args.command === "complete") {
+            const session = markComplete(projectRoot);
+            process.stdout.write(`Probe session marked complete for target=${JSON.stringify(session.target)}\n`);
+            return 0;
+        }
+        if (args.command === "status") {
+            const session = readSession(projectRoot);
+            if (session === null) {
+                process.stdout.write("No active probe session.\n");
+                return 0;
+            }
+            if (args.json) {
+                const sorted = sessionSummary(session);
+                process.stdout.write(`${JSON.stringify(sorted, Object.keys(sorted).sort(), 2)}\n`);
+            }
+            else {
+                const summary = sessionSummary(session);
+                process.stdout.write(`state: ${String(summary.state)}\n`);
+                process.stdout.write(`target: ${String(summary.target)}\n`);
+                process.stdout.write(`currentBranch: ${String(summary.currentBranch)}\n`);
+                process.stdout.write(`resolvedDecisions: ${Array.isArray(summary.resolvedDecisions) ? summary.resolvedDecisions.length : 0}\n`);
+            }
+            return 0;
+        }
+        if (args.command === "guard-artifact") {
+            guardProbeArtifact(projectRoot, args.path ?? "");
+            process.stdout.write(`Probe artifact handoff allowed: ${args.path}\n`);
+            return 0;
+        }
+        if (args.command === "guard-plan-registration") {
+            guardPlanProbeRegistration(projectRoot);
+            process.stdout.write("completedStrategies.probe registration allowed\n");
+            return 0;
+        }
+    }
+    catch (err) {
+        if (err instanceof ProbeHandoffBlockedError) {
+            process.stderr.write(`${err.message}\n`);
+            return 1;
+        }
+        if (err instanceof Error) {
+            process.stderr.write(`${err.message}\n`);
+            return 2;
+        }
+        process.stderr.write(String(err));
+        return 2;
+    }
+    process.stderr.write(`Unknown command: ${args.command}\n`);
+    return 2;
+}
+//# sourceMappingURL=probe-session.js.map