@deftai/directive 0.126.0-beta.1 → 0.126.0

package/dist/doctor.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+export interface DepositFileSetHygieneResult {
+    readonly absent: readonly string[];
+    readonly contentRoot: string | null;
+    readonly walkRoot: string | null;
+    readonly installedRoot: string | null;
+    readonly skipped: boolean;
+}
+export interface EvaluateDepositFileSetOptions {
+    readonly contentRoot?: string;
+    readonly walkRoot?: string | null;
+    readonly installedRoot?: string | null;
+}
+export declare function sameResolvedPath(left: string, right: string): boolean;
+/** Compare `.deft/core/` against `@deftai/directive-content` (#2804 / #4706). */
+export declare function evaluateDepositFileSetHygiene(projectRoot: string, options?: EvaluateDepositFileSetOptions): DepositFileSetHygieneResult;
+export declare function renderDepositFileSetHygieneLine(projectRoot: string, result?: DepositFileSetHygieneResult): string;
+export declare function run(argv: string[]): Promise<number>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveContentPackageRoot } from "@deftai/directive-core/dist/content-root.js";
+import { resolveInstalledContentRoot } from "@deftai/directive-core/dist/deposit/resolve-content.js";
+import { setDoctorAgentsTemplateRoot } from "@deftai/directive-core/dist/doctor/agents-md.js";
+import { parseDoctorFlags } from "@deftai/directive-core/dist/doctor/flags.js";
+import { cmdDoctor } from "@deftai/directive-core/dist/doctor/main.js";
+import { findPackageAbsentDepositPathsSync } from "@deftai/directive-core/dist/init-deposit/hygiene.js";
+import { evaluateInstalledDepositClosure, renderDeclaredDepositClosureLine, } from "@deftai/directive-core/dist/validate-content/deposit-required.js";
+import { renderPrecutoverLine } from "@deftai/directive-core/dist/vbrief-validate/precutover.js";
+import { renderStaleHeaderLine, renderXbriefMigrationLine, } from "@deftai/directive-core/xbrief-migrate";
+export function sameResolvedPath(left, right) {
+    return canonicalizeExistingPath(left) === canonicalizeExistingPath(right);
+}
+function canonicalizeExistingPath(path) {
+    let canonical = resolve(path);
+    try {
+        if (existsSync(canonical))
+            canonical = realpathSync(canonical);
+    }
+    catch {
+        // keep resolve() fallback
+    }
+    return process.platform === "win32" ? canonical.toLowerCase() : canonical;
+}
+function rootsDiverge(walkRoot, installedRoot) {
+    return walkRoot !== null && installedRoot !== null && !sameResolvedPath(walkRoot, installedRoot);
+}
+/** Compare `.deft/core/` against `@deftai/directive-content` (#2804 / #4706). */
+export function evaluateDepositFileSetHygiene(projectRoot, options = {}) {
+    const deftDir = join(projectRoot, ".deft", "core");
+    const walkRoot = options.walkRoot !== undefined ? options.walkRoot : resolveContentPackageRoot(projectRoot);
+    const installedRoot = options.installedRoot ?? null;
+    if (!existsSync(deftDir)) {
+        return { absent: [], contentRoot: null, walkRoot, installedRoot, skipped: true };
+    }
+    const contentRoot = options.contentRoot ?? installedRoot ?? walkRoot;
+    if (contentRoot === null || !existsSync(contentRoot)) {
+        return { absent: [], contentRoot: null, walkRoot, installedRoot, skipped: true };
+    }
+    return {
+        absent: findPackageAbsentDepositPathsSync(deftDir, contentRoot),
+        contentRoot,
+        walkRoot,
+        installedRoot,
+        skipped: false,
+    };
+}
+function hygieneRootDivergenceNote(result) {
+    if (!rootsDiverge(result.walkRoot, result.installedRoot ?? result.contentRoot)) {
+        return "";
+    }
+    const compared = result.contentRoot ?? "";
+    const walk = result.walkRoot ?? "";
+    const installed = result.installedRoot ?? compared;
+    return ` Compared content root: ${compared}. Project walk-root: ${walk}. Engine content root: ${installed}.`;
+}
+function namesUpdatePruneRecovery(result) {
+    const compared = result.contentRoot;
+    const walkRoot = result.walkRoot;
+    if (compared === null || walkRoot === null) {
+        return true;
+    }
+    if (!rootsDiverge(walkRoot, result.installedRoot)) {
+        return true;
+    }
+    return !sameResolvedPath(compared, walkRoot);
+}
+export function renderDepositFileSetHygieneLine(projectRoot, result = evaluateDepositFileSetHygiene(projectRoot)) {
+    const deftDir = join(projectRoot, ".deft", "core");
+    if (!existsSync(deftDir)) {
+        return "Deposit hygiene: none -- no .deft/core deposit.";
+    }
+    if (result.skipped) {
+        return ("Deposit hygiene: skip -- @deftai/directive-content is not installed " +
+            "(cannot compare deposit file-set).");
+    }
+    if (result.absent.length === 0) {
+        return "Deposit hygiene: none -- .deft/core file-set matches @deftai/directive-content.";
+    }
+    const sample = result.absent.slice(0, 5).join(", ");
+    const suffix = result.absent.length > 5 ? ` (+${result.absent.length - 5} more)` : "";
+    const divergence = hygieneRootDivergenceNote(result);
+    const recovery = namesUpdatePruneRecovery(result)
+        ? "Run `directive update` to auto-prune these stale deposit files (#2804)."
+        : "Do not run `directive update` to prune extras versus the project walk-root; that tree is not the engine content update reconciled (#4706). Leftover pin reconstitution is #4710.";
+    return (`Deposit hygiene: fail -- ${result.absent.length} package-absent file(s) in .deft/core ` +
+        `(not shipped by @deftai/directive-content). Examples: ${sample}${suffix}.${divergence} ` +
+        recovery);
+}
+async function resolveEngineContentRoot() {
+    try {
+        const installed = await resolveInstalledContentRoot();
+        return typeof installed === "string" && installed.length > 0 ? installed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function run(argv) {
+    // Human advisory lines stay off --json so the machine report stays one object.
+    // Deposit hygiene is still passed into cmdDoctor, including --json (#4812).
+    const flags = parseDoctorFlags(argv);
+    const installedRoot = await resolveEngineContentRoot();
+    if (installedRoot !== null) {
+        setDoctorAgentsTemplateRoot(installedRoot);
+    }
+    try {
+        if (flags.help || flags.unknown.length > 0) {
+            return cmdDoctor(argv);
+        }
+        const projectRoot = flags.projectRoot ?? process.cwd();
+        const walkRoot = resolveContentPackageRoot(projectRoot);
+        const depositResult = evaluateDepositFileSetHygiene(projectRoot, {
+            contentRoot: installedRoot ?? undefined,
+            walkRoot,
+            installedRoot,
+        });
+        const closure = evaluateInstalledDepositClosure(projectRoot);
+        // Package-absent files stay diagnostic unless --full. A real hygiene failure
+        // (full file-set or declared closure) is the one status cmdDoctor shares.
+        const fileSetFailed = flags.full && !depositResult.skipped && depositResult.absent.length > 0;
+        const closureFailed = flags.full && !closure.skipped && (closure.missing.length > 0 || closure.error !== null);
+        const line = renderDepositFileSetHygieneLine(projectRoot, depositResult);
+        if (!flags.json) {
+            process.stdout.write(`${renderPrecutoverLine(projectRoot)}\n`);
+            process.stdout.write(`${renderXbriefMigrationLine(projectRoot)}\n`);
+            process.stdout.write(`${renderStaleHeaderLine(projectRoot)}\n`);
+            process.stdout.write(`${line}\n`);
+            process.stdout.write(`${renderDeclaredDepositClosureLine(closure)}\n`);
+        }
+        const closureLine = renderDeclaredDepositClosureLine(closure);
+        return cmdDoctor(argv, {
+            depositHygiene: {
+                failed: fileSetFailed || closureFailed,
+                absent: depositResult.absent,
+                line: fileSetFailed ? line : closureFailed ? closureLine : line,
+            },
+        });
+    }
+    finally {
+        setDoctorAgentsTemplateRoot(undefined);
+    }
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    void run(process.argv.slice(2)).then((code) => {
+        process.exit(code);
+    }, (err) => {
+        process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/entrypoint.d.ts

@@ -0,0 +1,6 @@
+/**
+ * True when this module is the process entrypoint, including npm bin symlinks.
+ * Node passes the symlink path in argv[1]; compare via realpath on both sides.
+ */
+export declare function isDirectEntrypoint(moduleUrl: string | URL): boolean;
+//# sourceMappingURL=entrypoint.d.ts.map

package/dist/entrypoint.js

@@ -0,0 +1,19 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * True when this module is the process entrypoint, including npm bin symlinks.
+ * Node passes the symlink path in argv[1]; compare via realpath on both sides.
+ */
+export function isDirectEntrypoint(moduleUrl) {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined)
+        return false;
+    try {
+        const modulePath = fileURLToPath(moduleUrl);
+        return realpathSync(argv1) === realpathSync(modulePath);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=entrypoint.js.map

package/dist/escalation-cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): number;
+export default main;
+//# sourceMappingURL=escalation-cli.d.ts.map

package/dist/escalation-cli.js

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+/**
+ * Escalation CLI (#518 slim / #2948 Wave 5): typed queue under .deft/escalations/.
+ *
+ *   deft escalation:file -- --type cmd_approval --title "…"
+ *   deft escalation:list [--open] [--type <type>] [--format json]
+ *   deft escalation:resolve -- <id> --decision approved|denied|answered|dismissed
+ *   deft escalation:batch-approve [--ids a,b] [--include-dangerous]
+ */
+import { batchApproveEscalations, ESCALATION_TYPES, fileEscalation, isEscalationType, listEscalationsFiltered, resolveEscalation, } from "@deftai/directive-core/escalation";
+function parseArgv(argv) {
+    const base = {
+        cmd: "list",
+        projectRoot: process.cwd(),
+        type: null,
+        title: null,
+        body: null,
+        agentId: "agent",
+        contextRefs: [],
+        slaHours: null,
+        dangerous: false,
+        id: null,
+        ids: [],
+        decision: null,
+        actor: "operator",
+        note: null,
+        answer: null,
+        openOnly: false,
+        includeDangerous: false,
+        format: "text",
+    };
+    const args = [...argv];
+    while (args[0] === "--")
+        args.shift();
+    if (args.length > 0 && !args[0]?.startsWith("-")) {
+        const cmd = args.shift();
+        if (cmd === "file" || cmd === "list" || cmd === "resolve" || cmd === "batch-approve") {
+            base.cmd = cmd;
+        }
+        else if (cmd.startsWith("esc-")) {
+            base.cmd = "resolve";
+            base.id = cmd;
+        }
+        else {
+            return { ...base, error: `unknown escalation subcommand: ${cmd}` };
+        }
+    }
+    while (args[0] === "--")
+        args.shift();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === undefined)
+            break;
+        if (a === "--project-root" || a === "--projectRoot") {
+            base.projectRoot = args[++i] ?? base.projectRoot;
+            continue;
+        }
+        if (a === "--type") {
+            base.type = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--title") {
+            base.title = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--body") {
+            base.body = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--agent" || a === "--agent-id" || a === "--agentId") {
+            base.agentId = args[++i] ?? base.agentId;
+            continue;
+        }
+        if (a === "--context" || a === "--context-refs" || a === "--contextRefs") {
+            const raw = args[++i] ?? "";
+            base.contextRefs = raw
+                .split(/[,\s]+/)
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            continue;
+        }
+        if (a === "--sla-hours" || a === "--slaHours") {
+            const n = Number(args[++i] ?? "");
+            base.slaHours = Number.isFinite(n) ? n : null;
+            continue;
+        }
+        if (a === "--dangerous") {
+            base.dangerous = true;
+            continue;
+        }
+        if (a === "--id") {
+            base.id = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--ids") {
+            const raw = args[++i] ?? "";
+            base.ids = raw
+                .split(/[,\s]+/)
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            continue;
+        }
+        if (a === "--decision") {
+            base.decision = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--actor") {
+            base.actor = args[++i] ?? base.actor;
+            continue;
+        }
+        if (a === "--note") {
+            base.note = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--answer") {
+            base.answer = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--open") {
+            base.openOnly = true;
+            continue;
+        }
+        if (a === "--include-dangerous") {
+            base.includeDangerous = true;
+            continue;
+        }
+        if (a === "--format") {
+            const fmt = (args[++i] ?? "text").toLowerCase();
+            base.format = fmt === "json" ? "json" : "text";
+            continue;
+        }
+        if (!a.startsWith("-") && base.cmd === "resolve" && base.id === null) {
+            base.id = a;
+            continue;
+        }
+        if (a === "--help" || a === "-h") {
+            return { ...base, error: "help" };
+        }
+    }
+    return base;
+}
+function helpText() {
+    return [
+        "Usage:",
+        "  deft escalation:file -- --type <type> --title <text> [--body <text>] [--agent <id>]",
+        "      [--context refs…] [--sla-hours N] [--dangerous] [--format json]",
+        "  deft escalation:list [--open] [--type <type>] [--format json]",
+        "  deft escalation:resolve -- <id> --decision approved|denied|answered|dismissed",
+        "      [--note <text>] [--answer <text>] [--actor <name>]",
+        "  deft escalation:batch-approve [--ids a,b] [--include-dangerous] [--note <text>]",
+        "",
+        `Types: ${ESCALATION_TYPES.join(", ")}`,
+        "Bulk batch-approve is limited to cmd_approval + question (non-dangerous by default).",
+        "design_decision / approval / resource / external require individual resolve.",
+        "Store: .deft/escalations/<id>.json  Contract: content/contracts/escalation.md",
+        "Compose gated actions with deft authz:grant after approval (Wave 1 grants).",
+    ].join("\n");
+}
+export function main(argv = process.argv.slice(2)) {
+    const args = parseArgv(argv);
+    if (args.error === "help") {
+        process.stdout.write(`${helpText()}\n`);
+        return 0;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`escalation: ${args.error}\n`);
+        process.stderr.write(`${helpText()}\n`);
+        return 2;
+    }
+    try {
+        switch (args.cmd) {
+            case "file": {
+                if (args.type === null || args.type.trim().length === 0) {
+                    process.stderr.write("escalation:file requires --type <type>\n");
+                    return 2;
+                }
+                if (args.title === null || args.title.trim().length === 0) {
+                    process.stderr.write("escalation:file requires --title <text>\n");
+                    return 2;
+                }
+                const event = fileEscalation({
+                    projectRoot: args.projectRoot,
+                    type: args.type,
+                    title: args.title,
+                    body: args.body ?? undefined,
+                    agentId: args.agentId,
+                    contextRefs: args.contextRefs,
+                    slaHours: args.slaHours ?? undefined,
+                    dangerous: args.dangerous,
+                    id: args.id ?? undefined,
+                });
+                if (args.format === "json") {
+                    process.stdout.write(`${JSON.stringify(event, null, 2)}\n`);
+                }
+                else {
+                    process.stdout.write(`✓ escalation filed id=${event.id} type=${event.type} status=${event.status}` +
+                        `${event.dangerous ? " dangerous=true" : ""}\n`);
+                    process.stdout.write(`  title=${event.title}\n`);
+                    process.stdout.write(`  store=.deft/escalations/${event.id}.json\n`);
+                }
+                return 0;
+            }
+            case "list": {
+                let typeFilter;
+                if (args.type !== null && args.type.trim().length > 0) {
+                    if (!isEscalationType(args.type.trim().toLowerCase())) {
+                        process.stderr.write(`escalation:list unknown --type '${args.type}'; expected: ${ESCALATION_TYPES.join(", ")}\n`);
+                        return 2;
+                    }
+                    typeFilter = args.type.trim().toLowerCase();
+                }
+                const items = listEscalationsFiltered(args.projectRoot, {
+                    openOnly: args.openOnly,
+                    type: typeFilter,
+                });
+                if (args.format === "json") {
+                    process.stdout.write(`${JSON.stringify(items, null, 2)}\n`);
+                    return 0;
+                }
+                if (items.length === 0) {
+                    process.stdout.write(args.openOnly ? "No open escalations.\n" : "No escalations on disk.\n");
+                    return 0;
+                }
+                process.stdout.write(`Escalations (${items.length}):\n`);
+                for (const e of items) {
+                    const dang = e.dangerous ? " !dangerous" : "";
+                    process.stdout.write(`  - ${e.id} [${e.status}] type=${e.type}${dang} agent=${e.agentId} sla=${e.slaHours}h\n`);
+                    process.stdout.write(`      ${e.title}\n`);
+                    if (e.resolution) {
+                        process.stdout.write(`      → ${e.resolution.decision} by ${e.resolution.resolvedBy} @ ${e.resolution.resolvedAt}\n`);
+                    }
+                }
+                return 0;
+            }
+            case "resolve": {
+                if (args.id === null || args.id.trim().length === 0) {
+                    process.stderr.write("escalation:resolve requires <id>\n");
+                    return 2;
+                }
+                if (args.decision === null || args.decision.trim().length === 0) {
+                    process.stderr.write("escalation:resolve requires --decision approved|denied|answered|dismissed\n");
+                    return 2;
+                }
+                const result = resolveEscalation({
+                    projectRoot: args.projectRoot,
+                    id: args.id,
+                    decision: args.decision,
+                    actor: args.actor,
+                    note: args.note,
+                    answer: args.answer,
+                });
+                if (!result.ok) {
+                    process.stderr.write(`escalation: ${result.message}\n`);
+                    return result.code === "not-found" ? 1 : 2;
+                }
+                if (args.format === "json") {
+                    process.stdout.write(`${JSON.stringify(result.event, null, 2)}\n`);
+                }
+                else {
+                    process.stdout.write(`✓ resolved id=${result.event.id} decision=${result.event.resolution?.decision}\n`);
+                    process.stdout.write("  For gated product actions, mint a Wave 1 grant: deft authz:grant …\n");
+                }
+                return 0;
+            }
+            case "batch-approve": {
+                const batch = batchApproveEscalations({
+                    projectRoot: args.projectRoot,
+                    ids: args.ids.length > 0 ? args.ids : undefined,
+                    actor: args.actor,
+                    note: args.note,
+                    includeDangerous: args.includeDangerous,
+                });
+                if (args.format === "json") {
+                    process.stdout.write(`${JSON.stringify(batch, null, 2)}\n`);
+                }
+                else {
+                    process.stdout.write(`✓ batch-approve approved=${batch.approved.length} skipped=${batch.skipped.length}\n`);
+                    for (const e of batch.approved) {
+                        process.stdout.write(`  + ${e.id} type=${e.type}\n`);
+                    }
+                    for (const s of batch.skipped) {
+                        process.stdout.write(`  - skip ${s.id}: ${s.reason}\n`);
+                    }
+                }
+                return 0;
+            }
+            default:
+                process.stderr.write(`${helpText()}\n`);
+                return 2;
+        }
+    }
+    catch (err) {
+        process.stderr.write(`escalation: ${String(err)}\n`);
+        return 1;
+    }
+}
+export default main;
+if (import.meta.url === `file://${process.argv[1]?.replace(/\\/g, "/")}`) {
+    process.exitCode = main();
+}
+//# sourceMappingURL=escalation-cli.js.map

package/dist/eval-health.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    json: boolean;
+    noPersist: boolean;
+    error?: string;
+}
+/** Parse eval-health CLI args. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run eval:health and return the process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=eval-health.d.ts.map

package/dist/eval-health.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateHealth } from "@deftai/directive-core/eval";
+/** Parse eval-health CLI args. */
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        json: false,
+        noPersist: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--json") {
+            parsed.json = true;
+        }
+        else if (arg === "--no-persist") {
+            parsed.noPersist = 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 eval:health and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`eval:health: ${args.error}\n`);
+        return 2;
+    }
+    const result = evaluateHealth({
+        projectRoot: resolve(args.projectRoot),
+        persist: !args.noPersist,
+    });
+    if (result.report === null) {
+        process.stderr.write(`${result.message}\n`);
+        return result.code;
+    }
+    if (args.json) {
+        process.stdout.write(`${JSON.stringify(result.report, null, 2)}\n`);
+    }
+    else {
+        process.stdout.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=eval-health.js.map

package/dist/eval-report.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    championVersion: string;
+    challengerVersion: string;
+    model: string;
+    json: boolean;
+    error?: string;
+}
+/** Parse eval-report CLI args. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run eval:report and return the process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=eval-report.d.ts.map