@deftai/directive 0.119.3 → 0.119.4

package/dist/check.d.ts

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
-interface ParsedArgs {
+export interface ParsedArgs {
     frameworkRoot?: string;
-    projectRoot?: string;
+    projectRoot: string;
     noCache?: boolean;
     error?: string;
 }
-export declare function parseArgs(argv: string[]): ParsedArgs;
-export declare function run(argv: string[]): number;
-export {};
+/**
+ * Resolve check's framework-root from `projectRoot` without last-resort
+ * `resolveDefaultFrameworkRoot` (#4722). Returns null on miss (fail-closed).
+ */
+export declare function resolveCheckFrameworkRoot(projectRoot: string, explicitRoot?: string | null): string | null;
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+export declare function run(argv: readonly string[]): number;
 //# sourceMappingURL=check.d.ts.map

package/dist/check.js

@@ -2,53 +2,137 @@
 /**
  * check.ts -- CLI wrapper for the context-aware `task check` orchestrator (#1854, #1713).
  *
- * Usage: deft-ts check --framework-root <path> --project-root <path> [--no-cache]
+ * Usage: deft-ts check [--framework-root <path>] [--project-root <path>] [--no-cache]
+ *
+ * Omitted --project-root defaults to cwd. Omitted --framework-root walks
+ * explicit / DEFT_ROOT / source checkout / .deft/core / legacy deft/ and
+ * fail-closes instead of resolveDefaultFrameworkRoot (#4722).
  */
+import { statSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { dispatchTaskCheck } from "@deftai/directive-core/check";
-export function parseArgs(argv) {
-    const parsed = {};
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i] ?? "";
-        if (arg === "--framework-root") {
-            const next = argv[i + 1];
-            if (next === undefined) {
-                return { ...parsed, error: "argument --framework-root: expected one argument" };
+import { DEFT_REPO_POSITIVE_MARKERS } from "@deftai/directive-core/doctor";
+function isFrameworkSourceCheckoutAt(projectRoot) {
+    try {
+        if (!statSync(join(projectRoot, "main.md")).isFile()) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    return DEFT_REPO_POSITIVE_MARKERS.every((marker) => {
+        try {
+            return statSync(join(projectRoot, marker)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Resolve check's framework-root from `projectRoot` without last-resort
+ * `resolveDefaultFrameworkRoot` (#4722). Returns null on miss (fail-closed).
+ */
+export function resolveCheckFrameworkRoot(projectRoot, explicitRoot) {
+    const explicit = explicitRoot?.trim();
+    if (explicit) {
+        return resolve(explicit);
+    }
+    const envRoot = process.env.DEFT_ROOT?.trim();
+    if (envRoot) {
+        return resolve(envRoot);
+    }
+    const root = resolve(projectRoot);
+    if (isFrameworkSourceCheckoutAt(root)) {
+        return root;
+    }
+    for (const rel of [join(".deft", "core"), "deft"]) {
+        const candidate = join(root, rel);
+        try {
+            if (statSync(candidate).isDirectory()) {
+                return candidate;
             }
-            parsed.frameworkRoot = next;
-            i++;
         }
-        else if (arg.startsWith("--framework-root=")) {
-            parsed.frameworkRoot = arg.slice("--framework-root=".length);
+        catch {
+            // try next candidate
+        }
+    }
+    return null;
+}
+function takeRootOptionValue(argv, index, flag) {
+    const next = argv[index + 1];
+    if (next === undefined || next.length === 0 || next.startsWith("-")) {
+        return { error: `argument ${flag}: expected one argument`, next: index };
+    }
+    return { value: next, next: index + 1 };
+}
+export function parseArgs(argv) {
+    let projectRoot = process.cwd();
+    let explicitFrameworkRoot;
+    let noCache = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i] ?? "";
+        if (arg === "--no-cache") {
+            noCache = true;
         }
         else if (arg === "--project-root") {
-            const next = argv[i + 1];
-            if (next === undefined) {
-                return { ...parsed, error: "argument --project-root: expected one argument" };
+            const taken = takeRootOptionValue(argv, i, "--project-root");
+            if (taken.error !== undefined) {
+                return { projectRoot, error: taken.error };
             }
-            parsed.projectRoot = next;
-            i++;
+            projectRoot = taken.value ?? projectRoot;
+            i = taken.next;
         }
         else if (arg.startsWith("--project-root=")) {
-            parsed.projectRoot = arg.slice("--project-root=".length);
+            const value = arg.slice("--project-root=".length);
+            if (value.length === 0) {
+                return { projectRoot, error: "argument --project-root: expected one argument" };
+            }
+            projectRoot = value;
         }
-        else if (arg === "--no-cache") {
-            parsed.noCache = true;
+        else if (arg === "--framework-root") {
+            const taken = takeRootOptionValue(argv, i, "--framework-root");
+            if (taken.error !== undefined) {
+                return { projectRoot, error: taken.error };
+            }
+            explicitFrameworkRoot = taken.value;
+            i = taken.next;
+        }
+        else if (arg.startsWith("--framework-root=")) {
+            const value = arg.slice("--framework-root=".length);
+            if (value.length === 0) {
+                return { projectRoot, error: "argument --framework-root: expected one argument" };
+            }
+            explicitFrameworkRoot = value;
         }
         else {
-            return { ...parsed, error: `unrecognized argument: ${arg}` };
+            return {
+                projectRoot,
+                error: `unrecognized argument: ${arg}`,
+            };
         }
     }
+    const parsed = { projectRoot };
+    if (noCache) {
+        parsed.noCache = true;
+    }
+    const frameworkRoot = resolveCheckFrameworkRoot(projectRoot, explicitFrameworkRoot);
+    if (frameworkRoot !== null) {
+        parsed.frameworkRoot = frameworkRoot;
+    }
     return parsed;
 }
+const FRAMEWORK_ROOT_MISS = "check: no framework-root at this project (source checkout, .deft/core, or legacy deft/). Run directive init.\n";
 export function run(argv) {
     const args = parseArgs(argv);
     if (args.error !== undefined) {
         process.stderr.write(`check: ${args.error}\n`);
         return 2;
     }
-    if (args.frameworkRoot === undefined || args.projectRoot === undefined) {
-        process.stderr.write("check: --framework-root and --project-root are required\n");
+    if (args.frameworkRoot === undefined) {
+        process.stderr.write(FRAMEWORK_ROOT_MISS);
         return 2;
     }
     return dispatchTaskCheck(args.frameworkRoot, args.projectRoot, { noCache: args.noCache });

package/dist/doctor.d.ts

@@ -2,13 +2,18 @@
 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;
 }
-/** Compare `.deft/core/` against `@deftai/directive-content` (#2804). */
+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[]): number;
+export declare function run(argv: string[]): Promise<number>;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.js

@@ -1,30 +1,73 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+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";
-/** Compare `.deft/core/` against `@deftai/directive-content` (#2804). */
+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, skipped: true };
+        return { absent: [], contentRoot: null, walkRoot, installedRoot, skipped: true };
     }
-    const contentRoot = options.contentRoot ?? resolveContentPackageRoot(projectRoot);
+    const contentRoot = options.contentRoot ?? installedRoot ?? walkRoot;
     if (contentRoot === null || !existsSync(contentRoot)) {
-        return { absent: [], contentRoot: null, skipped: true };
+        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)) {
@@ -39,37 +82,71 @@ export function renderDepositFileSetHygieneLine(projectRoot, result = evaluateDe
     }
     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}. ` +
-        "Run `directive update` to auto-prune these stale deposit files (#2804).");
+        `(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 function run(argv) {
+export async function run(argv) {
     // #2022: surface pre-cutover (pre-v0.20 document model) migration state alongside the
     // core doctor report. Only emit on a valid, human-readable invocation: suppressed under
     // --json (so the machine-readable report stays valid), on --help, and when unknown flags
     // are present (so an invalid invocation still mirrors the core error path exactly).
     const flags = parseDoctorFlags(argv);
     let depositHygieneExit = 0;
-    if (!flags.json && !flags.help && flags.unknown.length === 0) {
-        const projectRoot = flags.projectRoot ?? process.cwd();
-        const depositResult = evaluateDepositFileSetHygiene(projectRoot);
-        process.stdout.write(`${renderPrecutoverLine(projectRoot)}\n`);
-        process.stdout.write(`${renderXbriefMigrationLine(projectRoot)}\n`);
-        process.stdout.write(`${renderStaleHeaderLine(projectRoot)}\n`);
-        process.stdout.write(`${renderDepositFileSetHygieneLine(projectRoot, depositResult)}\n`);
-        const closure = evaluateInstalledDepositClosure(projectRoot);
-        process.stdout.write(`${renderDeclaredDepositClosureLine(closure)}\n`);
-        if (flags.full && !depositResult.skipped && depositResult.absent.length > 0) {
-            depositHygieneExit = 1;
-        }
-        if (flags.full && !closure.skipped && (closure.missing.length > 0 || closure.error !== null)) {
-            depositHygieneExit = 1;
+    const installedRoot = await resolveEngineContentRoot();
+    if (installedRoot !== null) {
+        setDoctorAgentsTemplateRoot(installedRoot);
+    }
+    try {
+        if (!flags.json && !flags.help && flags.unknown.length === 0) {
+            const projectRoot = flags.projectRoot ?? process.cwd();
+            const walkRoot = resolveContentPackageRoot(projectRoot);
+            const depositResult = evaluateDepositFileSetHygiene(projectRoot, {
+                contentRoot: installedRoot ?? undefined,
+                walkRoot,
+                installedRoot,
+            });
+            process.stdout.write(`${renderPrecutoverLine(projectRoot)}\n`);
+            process.stdout.write(`${renderXbriefMigrationLine(projectRoot)}\n`);
+            process.stdout.write(`${renderStaleHeaderLine(projectRoot)}\n`);
+            process.stdout.write(`${renderDepositFileSetHygieneLine(projectRoot, depositResult)}\n`);
+            const closure = evaluateInstalledDepositClosure(projectRoot);
+            process.stdout.write(`${renderDeclaredDepositClosureLine(closure)}\n`);
+            if (flags.full && !depositResult.skipped && depositResult.absent.length > 0) {
+                depositHygieneExit = 1;
+            }
+            if (flags.full &&
+                !closure.skipped &&
+                (closure.missing.length > 0 || closure.error !== null)) {
+                depositHygieneExit = 1;
+            }
         }
+        const doctorExit = cmdDoctor(argv);
+        return Math.max(depositHygieneExit, doctorExit);
+    }
+    finally {
+        setDoctorAgentsTemplateRoot(undefined);
     }
-    const doctorExit = cmdDoctor(argv);
-    return Math.max(depositHygieneExit, doctorExit);
 }
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
-    process.exit(run(process.argv.slice(2)));
+    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/verify-hooks-installed.d.ts

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
-import { type AgentHookHealthResult, type AgentHookReadinessResult, type EvaluateResult } from "@deftai/directive-core/verify-env";
+import { type AgentHookHealthResult, type AgentHookReadinessResult, type EvaluateResult, repairAgentHookRegistrations } from "@deftai/directive-core/verify-env";
 type HookScope = "git" | "agent" | "all";
 interface ParsedArgs {
     projectRoot: string;
     quiet: boolean;
     scope: HookScope;
     live: boolean;
+    repair: boolean;
     error?: string;
 }
 export interface VerifyHooksInstalledCliSeams {
     readonly evaluateGit?: (projectRoot: string) => EvaluateResult;
     readonly evaluateAgent?: (projectRoot: string) => AgentHookHealthResult;
     readonly evaluateReadiness?: (projectRoot: string) => AgentHookReadinessResult;
+    readonly repairRegistrations?: typeof repairAgentHookRegistrations;
     readonly writeOut?: (text: string) => void;
     readonly writeErr?: (text: string) => void;
 }

package/dist/verify-hooks-installed.js

@@ -1,15 +1,23 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { evaluate, evaluateAgentHookReadinessSafely, evaluateAgentHooks, } from "@deftai/directive-core/verify-env";
+import { evaluate, evaluateAgentHookReadiness, evaluateAgentHookReadinessSafely, evaluateAgentHooks, formatAgentHookRepairDisposition, repairAgentHookRegistrations, } from "@deftai/directive-core/verify-env";
 export function parseArgs(argv) {
-    const parsed = { projectRoot: ".", quiet: false, scope: "git", live: false };
+    const parsed = {
+        projectRoot: ".",
+        quiet: false,
+        scope: "git",
+        live: false,
+        repair: false,
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "--quiet")
             parsed.quiet = true;
         else if (arg === "--live")
             parsed.live = true;
+        else if (arg === "--repair")
+            parsed.repair = true;
         else if (arg === "--project-root") {
             const value = argv[i + 1];
             if (value === undefined) {
@@ -46,6 +54,9 @@ export function parseArgs(argv) {
     if (parsed.live && parsed.scope === "git") {
         return { ...parsed, error: "argument --live requires --scope=agent or --scope=all" };
     }
+    if (parsed.repair && parsed.scope === "git") {
+        return { ...parsed, error: "argument --repair requires --scope=agent or --scope=all" };
+    }
     return parsed;
 }
 /** Verify git hooks, structural agent hooks, or functional agent-hook readiness. */
@@ -63,6 +74,48 @@ export function run(argv, seams = {}) {
     const evaluateReadiness = seams.evaluateReadiness
         ? (root) => evaluateAgentHookReadinessSafely(root, seams.evaluateReadiness)
         : evaluateAgentHookReadinessSafely;
+    if (args.repair) {
+        const repair = seams.repairRegistrations ?? repairAgentHookRegistrations;
+        try {
+            let live;
+            const evaluateRepairReadiness = seams.evaluateReadiness
+                ? (root) => evaluateAgentHookReadinessSafely(root, seams.evaluateReadiness)
+                : (root) => evaluateAgentHookReadinessSafely(root, (next) => evaluateAgentHookReadiness(next, { consumerContext: () => true }));
+            const repaired = repair(projectRoot, {
+                reevaluate: (root) => {
+                    live = evaluateRepairReadiness(root);
+                    return live;
+                },
+            });
+            if (live === undefined) {
+                writeErr("agent hook repair refused: live recheck did not run\n");
+                return 2;
+            }
+            if (!args.quiet) {
+                writeOut(`${formatAgentHookRepairDisposition(repaired.written)}\n`);
+                if (live.stream === "stdout")
+                    writeOut(`${live.message}\n`);
+                else
+                    writeErr(`${live.message}\n`);
+            }
+            const gitResults = args.scope === "all" ? [evaluateGit(projectRoot)] : [];
+            if (!args.quiet) {
+                for (const result of gitResults) {
+                    if (result.stream === "stdout")
+                        writeOut(`${result.message}\n`);
+                    else if (result.stream === "stderr")
+                        writeErr(`${result.message}\n`);
+                }
+            }
+            const gitCode = gitResults.length > 0 ? Math.max(...gitResults.map((result) => result.code)) : 0;
+            return Math.max(repaired.after.code, gitCode);
+        }
+        catch (cause) {
+            const detail = cause instanceof Error ? cause.message : String(cause);
+            writeErr(`agent hook repair refused: ${detail}\n`);
+            return 2;
+        }
+    }
     const results = [
         ...(args.scope === "git" || args.scope === "all" ? [evaluateGit(projectRoot)] : []),
         ...(args.scope === "agent" || args.scope === "all"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.119.3",
+  "version": "0.119.4",
   "description": "Directive CLI — npm install path for the Deft Directive framework.",
   "license": "MIT",
   "homepage": "https://deftai.github.io/directive/",
@@ -34,8 +34,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-core": "^0.119.3",
-    "@deftai/directive-content": "^0.119.3"
+    "@deftai/directive-core": "^0.119.4",
+    "@deftai/directive-content": "^0.119.4"
   },
   "scripts": {
     "build": "tsc -b"