@deftai/directive-core 0.55.0

package/dist/doctor/main.js

@@ -0,0 +1,387 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { contentRoot } from "../content-root.js";
+import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
+import { runChecks } from "./checks.js";
+import { EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
+import { decideThrottle, formatIsoZ, readState, renderDoctorStatusLine, writeState, } from "./doctor-state.js";
+import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } from "./flags.js";
+import { pythonJsonDump } from "./json.js";
+import { createPlainSink } from "./output.js";
+import { resolveDefaultFrameworkRoot, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
+import { runPayloadStalenessCheck } from "./payload-staleness.js";
+import { classifyTaskfileInclude, formatMissingIncludeSnippet, resolveConsumerTaskfile, } from "./taskfile.js";
+import { defaultWhich } from "./which.js";
+export function cmdDoctor(args, seams = {}) {
+    const flags = parseDoctorFlags(args);
+    if (flags.unknown.length > 0) {
+        const sink = createPlainSink();
+        sink.error(formatUnknownFlagsError(flags.unknown));
+        sink.info(formatAllowedFlagsHint());
+        return 2;
+    }
+    const sessionMode = flags.session;
+    const fixMode = flags.fix && !sessionMode;
+    const jsonMode = flags.json;
+    const quietMode = flags.quiet;
+    const fullMode = flags.full;
+    const projectRoot = resolvePath(flags.projectRoot ?? process.cwd());
+    const frameworkRoot = seams.frameworkRoot ?? resolveDefaultFrameworkRoot();
+    const whichFn = seams.whichFn ?? defaultWhich;
+    const nowFn = seams.now ?? (() => new Date());
+    if (!fullMode) {
+        const state = (seams.readState ?? readState)(projectRoot);
+        const decision = decideThrottle(state, nowFn());
+        if (decision.skip) {
+            const hint = decision.dirty
+                ? "run `deft doctor --full` to re-probe or address findings"
+                : "--full forces";
+            if (jsonMode) {
+                const payload = {
+                    status: "throttle-skipped",
+                    last_run_at: formatIsoZ(decision.lastRunAt),
+                    last_exit_code: decision.lastExitCode,
+                    last_finding_count: decision.lastFindingCount,
+                    last_error_count: decision.lastErrorCount,
+                    next_eligible_at: formatIsoZ(decision.nextEligibleAt),
+                    hint,
+                };
+                process.stdout.write(`${pythonJsonDump(payload)}\n`);
+            }
+            else {
+                process.stdout.write(`${renderDoctorStatusLine(decision, nowFn())}\n`);
+            }
+            return decision.dirty ? 1 : 0;
+        }
+    }
+    const findings = [];
+    const addFinding = (finding) => {
+        findings.push(finding);
+    };
+    const sink = createPlainSink({ jsonMode, quietMode });
+    if (!jsonMode) {
+        sink.header(`Deft CLI v${resolveVersion(frameworkRoot)} - Doctor`);
+        sink.blank();
+    }
+    sink.info("Checking system dependencies...");
+    if (!jsonMode) {
+        sink.blank();
+    }
+    const checkCommand = (cmd, name, required = false, installUrl = "") => {
+        if (whichFn(cmd)) {
+            sink.success(`${name} is installed`);
+            return;
+        }
+        const urlHint = installUrl ? ` - install: ${installUrl}` : "";
+        if (required) {
+            const message = `${name} not found - required${urlHint}`;
+            sink.error(message);
+            addFinding({
+                severity: "error",
+                message,
+                check: "dependency",
+                tool: cmd,
+                suggestion: installUrl || null,
+            });
+            return;
+        }
+        const message = cmd === "task"
+            ? `${name} not found - install from https://taskfile.dev`
+            : `${name} not found${urlHint}`;
+        sink.warn(message);
+        addFinding({
+            severity: "warning",
+            message,
+            check: "dependency",
+            tool: cmd,
+            suggestion: installUrl || null,
+        });
+    };
+    checkCommand("uv", "uv (Astral Python runner)", true, UV_INSTALL_URL);
+    checkCommand("git", "git", true);
+    checkCommand("python3", "python3");
+    checkCommand("go", "go");
+    checkCommand("node", "node");
+    if (!jsonMode) {
+        sink.blank();
+    }
+    sink.info("Checking install integrity...");
+    runInstallIntegrityChecks(projectRoot, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
+    sink.info("Checking AGENTS.md managed-section freshness...");
+    runAgentsMdFreshnessCheck(projectRoot, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
+    sink.info("Checking payload staleness from install manifest...");
+    runPayloadStalenessCheck(projectRoot, sink, addFinding, {
+        frameworkRoot,
+        readText: seams.readText,
+        isFile: seams.isFile,
+        runGitLsRemote: seams.runGitLsRemote,
+    });
+    if (!jsonMode) {
+        sink.blank();
+    }
+    sink.info("Checking Deft structure...");
+    const isDir = seams.isDir ??
+        ((p) => {
+            try {
+                return statSync(p).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    // #1875: shippable-content dirs resolve under content/ in a source checkout
+    // and at the root in a flattened consumer deposit; engine/lifecycle dirs stay
+    // at the framework root in both layouts.
+    const contentBase = contentRoot(frameworkRoot);
+    const layoutChecks = [
+        ...EXPECTED_CONTENT_DIRS.map((d) => [d, contentBase]),
+        ...EXPECTED_FRAMEWORK_DIRS.map((d) => [d, frameworkRoot]),
+    ];
+    for (const [dirName, base] of layoutChecks) {
+        const dirPath = join(base, dirName);
+        if (isDir(dirPath)) {
+            sink.success(`Directory: ${dirName}/`);
+        }
+        else {
+            const message = `Missing directory: ${dirName}/`;
+            sink.warn(message);
+            addFinding({
+                severity: "warning",
+                message,
+                check: "framework-layout",
+                directory: dirName,
+            });
+        }
+    }
+    if (!jsonMode) {
+        sink.blank();
+    }
+    sink.info("Checking optional root Taskfile.yml include...");
+    runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams);
+    const errorCount = findings.filter((f) => f.severity === "error").length;
+    const warningCount = findings.filter((f) => f.severity === "warning").length;
+    const exitCode = errorCount > 0 ? 1 : 0;
+    const persist = seams.writeState ?? writeState;
+    persist(projectRoot, {
+        exitCode,
+        findingCount: findings.filter((f) => f.severity !== "skip").length,
+        errorCount,
+        now: nowFn(),
+    });
+    if (jsonMode) {
+        const payload = {
+            status: "completed",
+            ok: exitCode === 0,
+            findings,
+            summary: { errors: errorCount, warnings: warningCount },
+            project_root: projectRoot,
+        };
+        process.stdout.write(`${pythonJsonDump(payload)}\n`);
+        return exitCode;
+    }
+    sink.blank();
+    if (errorCount === 0 && warningCount === 0) {
+        sink.finalSuccess("System check passed!");
+        return 0;
+    }
+    if (errorCount) {
+        sink.finalError(`System check failed with ${errorCount} error(s)` +
+            (warningCount ? ` and ${warningCount} warning(s)` : "") +
+            ".");
+        return 1;
+    }
+    sink.finalWarn(`System check completed with ${warningCount} warning(s).`);
+    return 0;
+}
+function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
+    if (runningInsideDeftRepo(projectRoot, seams)) {
+        sink.info("Skipping install-integrity checks -- running inside the deft framework repo (no install manifest in the source checkout).");
+        return;
+    }
+    try {
+        const isDir = seams.isDir ??
+            ((p) => {
+                try {
+                    return statSync(p).isDirectory();
+                }
+                catch {
+                    return false;
+                }
+            });
+        const isFile = seams.isFile ?? ((p) => existsSync(p));
+        const readText = seams.readText ??
+            ((p) => {
+                try {
+                    if (!existsSync(p))
+                        return null;
+                    return readFileSync(p, "utf8");
+                }
+                catch {
+                    return null;
+                }
+            });
+        const result = runChecks(projectRoot, { isDir, isFile, readText });
+        for (const entry of result.checks ?? []) {
+            const name = String(entry.name ?? "install-integrity");
+            const status = String(entry.status ?? "");
+            const detail = String(entry.detail ?? "");
+            if (status === "pass") {
+                sink.success(`${name}: pass`);
+                continue;
+            }
+            if (status === "skip") {
+                sink.info(`${name}: skip -- ${detail}`);
+                continue;
+            }
+            if (status === "error") {
+                sink.error(`${name}: error -- ${detail}`);
+            }
+            else {
+                sink.error(`${name}: fail -- ${detail}`);
+            }
+            addFinding({
+                severity: "error",
+                message: detail || `${name} ${status}`,
+                check: `install-integrity:${name}`,
+                install_check: name,
+                status,
+                data: entry.data ?? {},
+            });
+        }
+        for (const err of result.errors ?? []) {
+            sink.error(String(err));
+            addFinding({
+                severity: "error",
+                message: String(err),
+                check: "install-integrity",
+            });
+        }
+    }
+    catch (exc) {
+        const message = `Install-integrity probe unavailable: ${exc instanceof Error ? exc.name : "Error"}: ${exc}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: "install-integrity" });
+    }
+}
+function runAgentsMdFreshnessCheck(projectRoot, sink, addFinding, seams) {
+    const checkName = "agents-md-managed-section-fresh";
+    if (runningInsideDeftRepo(projectRoot, seams) ||
+        !hasV3ManagedMarker(projectRoot, seams.readText)) {
+        const skipReason = "no managed-section markers (likely maintainer repo)";
+        sink.info(`${checkName}: skip -- ${skipReason}`);
+        addFinding({ severity: "skip", message: skipReason, check: checkName, status: "skip" });
+        return;
+    }
+    try {
+        const planFn = seams.agentsRefreshPlan ?? ((root) => agentsRefreshPlan(root));
+        const plan = planFn(projectRoot);
+        const state = String(plan.state ?? "");
+        if (state === "current") {
+            sink.success(`${checkName}: current`);
+            return;
+        }
+        if (state === "stale" || state === "missing" || state === "absent") {
+            const message = `AGENTS.md managed section is ${state} -- run \`deft agents:refresh\` to bring it to the current template.`;
+            sink.warn(message);
+            addFinding({
+                severity: "warning",
+                message,
+                check: checkName,
+                status: state,
+                suggestion: "deft agents:refresh",
+            });
+            return;
+        }
+        const message = `AGENTS.md freshness check could not run (state='${state}'). Inspect the framework template or AGENTS.md file permissions.`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: checkName, status: state });
+    }
+    catch (exc) {
+        const message = `${checkName}: probe failed -- ${exc instanceof Error ? exc.name : "Error"}: ${exc}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: checkName });
+    }
+}
+function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams) {
+    if (runningInsideDeftRepo(projectRoot, seams)) {
+        sink.info("Skipping Taskfile include check -- running inside the deft framework repo (the repo's own Taskfile.yml is the surface).");
+        return;
+    }
+    const includeStatus = classifyTaskfileInclude(projectRoot);
+    if (includeStatus === "ok") {
+        sink.success("Root Taskfile.yml includes the deft framework");
+        return;
+    }
+    if (includeStatus === "missing-file") {
+        let includeMissing = true;
+        const target = join(projectRoot, "Taskfile.yml");
+        const message = "Root Taskfile.yml missing. This is OK for package-manager installs that use the `deft X` surface directly. To also enable the optional `task deft:X` surface, paste this into " +
+            `${target}:`;
+        sink.info(message);
+        if (!jsonMode) {
+            sink.blank();
+            sink.raw(TASKFILE_INCLUDE_SNIPPET);
+        }
+        const isTty = seams.isTty ?? (() => process.stdin.isTTY === true);
+        const readYn = seams.readYn ?? (() => false);
+        const writeText = seams.writeText ?? ((p, c) => writeFileSync(p, c, { encoding: "utf8" }));
+        if (fixMode && !jsonMode && isTty()) {
+            if (readYn(`Create ${target} with the canonical include now?`, false)) {
+                try {
+                    writeText(target, TASKFILE_INCLUDE_SNIPPET);
+                    sink.success(`Wrote ${target}`);
+                    includeMissing = false;
+                }
+                catch (exc) {
+                    sink.error(`Failed to write ${target}: ${exc}`);
+                }
+            }
+            else {
+                sink.info("Skipped Taskfile.yml creation -- paste the snippet above when you are ready.");
+            }
+        }
+        if (includeMissing) {
+            addFinding({
+                severity: "warning",
+                message: "Root Taskfile.yml missing; optional Taskfile include unavailable",
+                check: "taskfile-include",
+                file: target,
+                suggestion: TASKFILE_INCLUDE_SNIPPET,
+            });
+        }
+        return;
+    }
+    if (includeStatus === "missing-include") {
+        const message = "Root Taskfile.yml exists but does not include the deft framework. The `deft X` surface still works; add this to the Taskfile `includes:` block only if you want the optional `task deft:X` surface (doctor NEVER mutates an existing user-owned Taskfile):";
+        sink.warn(message);
+        if (!jsonMode) {
+            sink.blank();
+            sink.raw(formatMissingIncludeSnippet());
+        }
+        const tf = resolveConsumerTaskfile(projectRoot);
+        addFinding({
+            severity: "warning",
+            message: "Root Taskfile.yml does not include the deft framework",
+            check: "taskfile-include",
+            file: tf,
+            suggestion: formatMissingIncludeSnippet(),
+        });
+        return;
+    }
+    const taskfilePath = resolveConsumerTaskfile(projectRoot) ?? join(projectRoot, "Taskfile.yml");
+    const message = `Root Taskfile.yml at ${taskfilePath} exists but could not be read -- check file permissions.`;
+    sink.warn(message);
+    addFinding({
+        severity: "warning",
+        message,
+        check: "taskfile-include",
+        file: taskfilePath,
+    });
+}
+//# sourceMappingURL=main.js.map

package/dist/doctor/manifest.d.ts

@@ -0,0 +1,11 @@
+import { readTextSafe } from "./paths.js";
+export declare function parseManifest(text: string): Record<string, string>;
+export declare function parseInstallManifest(text: string): Record<string, string>;
+export declare function manifestTagToVersion(manifest: Record<string, string>): string | null;
+export declare function manifestCandidatePaths(projectRoot: string, installRoot: string | null): string[];
+export declare function locateManifest(projectRoot: string, installRoot: string | null, isFile?: (p: string) => boolean): string | null;
+export declare function parseInstallRootFromAgentsMd(text: string): string | null;
+export declare function extractManagedSection(text: string): string | null;
+export declare function isDeprecationRedirectStub(text: string): boolean;
+export declare function readManifestAt(path: string | null, readText?: typeof readTextSafe): string | null;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/doctor/manifest.js

@@ -0,0 +1,114 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { parseManifestKeyValueLine, stripEdgeQuotes } from "../text/redos-safe.js";
+import { readTextSafe } from "./paths.js";
+export function parseManifest(text) {
+    const parsed = {};
+    for (const line of text.split("\n")) {
+        const row = parseManifestKeyValueLine(line);
+        if (row === null) {
+            continue;
+        }
+        parsed[row.key] = row.value;
+    }
+    return parsed;
+}
+export function parseInstallManifest(text) {
+    const data = {};
+    for (const line of text.split("\n")) {
+        const stripped = line.trim();
+        if (!stripped || !stripped.includes(":")) {
+            continue;
+        }
+        const colon = stripped.indexOf(":");
+        const k = stripped.slice(0, colon).trim();
+        let v = stripped.slice(colon + 1).trim();
+        v = stripEdgeQuotes(v);
+        if (k) {
+            data[k] = v;
+        }
+    }
+    return data;
+}
+export function manifestTagToVersion(manifest) {
+    for (const key of ["tag", "ref"]) {
+        const raw = manifest[key];
+        if (typeof raw !== "string") {
+            continue;
+        }
+        const candidate = raw.trim().replace(/^v/, "");
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return null;
+}
+export function manifestCandidatePaths(projectRoot, installRoot) {
+    const raw = [];
+    if (installRoot) {
+        raw.push(join(projectRoot, installRoot, "VERSION"));
+    }
+    raw.push(join(projectRoot, ".deft", "core", "VERSION"));
+    raw.push(join(projectRoot, ".deft", "VERSION"));
+    raw.push(join(projectRoot, "deft", "VERSION"));
+    const seen = new Set();
+    const ordered = [];
+    for (const candidate of raw) {
+        if (!seen.has(candidate)) {
+            seen.add(candidate);
+            ordered.push(candidate);
+        }
+    }
+    return ordered;
+}
+export function locateManifest(projectRoot, installRoot, isFile = existsSync) {
+    for (const candidate of manifestCandidatePaths(projectRoot, installRoot)) {
+        if (isFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+const INSTALLED_IN_RE = /Deft is installed in\s+(\S+?)\/?\./;
+const FULL_GUIDELINES_RE = /Full guidelines:\s+(\S+)\/main\.md/;
+export function parseInstallRootFromAgentsMd(text) {
+    let match = INSTALLED_IN_RE.exec(text);
+    if (match?.[1]) {
+        return match[1].trim();
+    }
+    match = FULL_GUIDELINES_RE.exec(text);
+    if (match?.[1]) {
+        return match[1].trim();
+    }
+    return null;
+}
+const AGENTS_MANAGED_OPEN_RE = /<!--\s*deft:managed-section\s+v(2|3)(?:\s+([^>]*?))?\s*-->/;
+export function extractManagedSection(text) {
+    const normalised = text.replace(/\r\n/g, "\n");
+    const openMatch = AGENTS_MANAGED_OPEN_RE.exec(normalised);
+    if (!openMatch) {
+        return null;
+    }
+    const openIdx = openMatch.index;
+    const closeIdx = normalised.indexOf("<!-- /deft:managed-section -->", openMatch.index + openMatch[0].length);
+    if (closeIdx < 0) {
+        return null;
+    }
+    const end = closeIdx + "<!-- /deft:managed-section -->".length;
+    return normalised.slice(openIdx, end);
+}
+export function isDeprecationRedirectStub(text) {
+    const lines = text.replace(/\r\n/g, "\n").trimStart().split("\n");
+    const sentinels = new Set([
+        "<!-- deft:deprecated-redirect -->",
+        "<!-- deft:deprecated-skill-redirect -->",
+    ]);
+    return lines.slice(0, 8).some((line) => sentinels.has(line.trim()));
+}
+export function readManifestAt(path, readText = readTextSafe) {
+    if (!path) {
+        return null;
+    }
+    return readText(path);
+}
+//# sourceMappingURL=manifest.js.map

package/dist/doctor/output.d.ts

@@ -0,0 +1,19 @@
+export interface OutputSink {
+    info(msg: string): void;
+    success(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    header(text: string): void;
+    blank(): void;
+    raw(text: string): void;
+    /** Final summary success -- shown even in --quiet mode (mirrors Python `success()` direct call). */
+    finalSuccess(msg: string): void;
+    finalError(msg: string): void;
+    finalWarn(msg: string): void;
+}
+export declare function createPlainSink(options?: {
+    jsonMode?: boolean;
+    quietMode?: boolean;
+    write?: (text: string) => void;
+}): OutputSink;
+//# sourceMappingURL=output.d.ts.map

package/dist/doctor/output.js

@@ -0,0 +1,49 @@
+export function createPlainSink(options = {}) {
+    const write = options.write ?? ((t) => process.stdout.write(t));
+    const jsonMode = options.jsonMode ?? false;
+    const quietMode = options.quietMode ?? false;
+    return {
+        info(msg) {
+            if (!jsonMode)
+                write(`ℹ ${msg}\n`);
+        },
+        success(msg) {
+            if (!jsonMode && !quietMode)
+                write(`✓ ${msg}\n`);
+        },
+        warn(msg) {
+            if (!jsonMode)
+                write(`⚠ ${msg}\n`);
+        },
+        error(msg) {
+            if (!jsonMode)
+                write(`✗ ${msg}\n`);
+        },
+        header(text) {
+            if (!jsonMode) {
+                write(`\n${"=".repeat(60)}\n  ${text}\n${"=".repeat(60)}\n`);
+            }
+        },
+        blank() {
+            if (!jsonMode)
+                write("\n");
+        },
+        raw(text) {
+            if (!jsonMode)
+                write(text.endsWith("\n") ? text : `${text}\n`);
+        },
+        finalSuccess(msg) {
+            if (!jsonMode)
+                write(`✓ ${msg}\n`);
+        },
+        finalError(msg) {
+            if (!jsonMode)
+                write(`✗ ${msg}\n`);
+        },
+        finalWarn(msg) {
+            if (!jsonMode)
+                write(`⚠ ${msg}\n`);
+        },
+    };
+}
+//# sourceMappingURL=output.js.map

package/dist/doctor/paths.d.ts

@@ -0,0 +1,16 @@
+/** Resolve a user-supplied path string to an absolute path. */
+export declare function resolvePath(pathStr: string, cwd?: string): string;
+/** Best-effort version string (mirrors Python `_resolve_version`). */
+export declare function resolveVersion(frameworkRoot?: string): string;
+/** Return the deft framework repo root (the directory containing `main.md`). */
+export declare function resolveDefaultFrameworkRoot(): string;
+/** Directory containing doctor implementation (Python: scripts/). */
+export declare function resolveScriptDir(frameworkRoot?: string): string;
+export declare function readTextSafe(path: string, readText?: typeof defaultReadText): string | null;
+declare function defaultReadText(path: string): string | null;
+export declare function runningInsideDeftRepo(projectRoot: string, seams?: {
+    isDir?: (p: string) => boolean;
+    isFile?: (p: string) => boolean;
+}): boolean;
+export {};
+//# sourceMappingURL=paths.d.ts.map