@deftai/directive-core 0.55.0

package/dist/verify-env/toolchain-check.d.ts

@@ -0,0 +1,28 @@
+export interface ToolCheck {
+    readonly name: string;
+    readonly command: readonly string[];
+}
+export declare const TOOLS: readonly ToolCheck[];
+export type CommandRunner = (command: readonly string[], timeoutMs: number) => {
+    returncode: number;
+    stdout: string;
+    stderr: string;
+} | {
+    error: "not-found" | "exception";
+    message: string;
+};
+export interface ToolchainCheckResult {
+    readonly lines: readonly string[];
+    readonly exitCode: 0 | 1;
+}
+export declare function defaultCommandRunner(command: readonly string[], timeoutMs: number): {
+    returncode: number;
+    stdout: string;
+    stderr: string;
+} | {
+    error: "not-found" | "exception";
+    message: string;
+};
+/** Run maintainer toolchain probe (mirrors scripts/toolchain-check.py). */
+export declare function runToolchainCheck(runner?: CommandRunner, tools?: readonly ToolCheck[]): ToolchainCheckResult;
+//# sourceMappingURL=toolchain-check.d.ts.map

package/dist/verify-env/toolchain-check.js

@@ -0,0 +1,68 @@
+import * as childProcess from "node:child_process";
+import { nodeRuntimeRemediationLines } from "./node-runtime.js";
+export const TOOLS = [
+    { name: "go", command: ["go", "version"] },
+    { name: "uv", command: ["uv", "--version"] },
+    { name: "git", command: ["git", "--version"] },
+    { name: "gh", command: ["gh", "--version"] },
+    { name: "node", command: ["node", "--version"] },
+    { name: "pnpm", command: ["pnpm", "--version"] },
+];
+const DEFAULT_TIMEOUT_MS = 10_000;
+export function defaultCommandRunner(command, timeoutMs) {
+    try {
+        const stdout = childProcess.execFileSync(command[0] ?? "", command.slice(1), {
+            encoding: "utf8",
+            timeout: timeoutMs,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            return { error: "not-found", message: "" };
+        }
+        return {
+            returncode: typeof e.status === "number" ? e.status : 1,
+            stdout: typeof e.stdout === "string" ? e.stdout : "",
+            stderr: typeof e.stderr === "string" ? e.stderr : String(e.message ?? err),
+        };
+    }
+}
+/** Run maintainer toolchain probe (mirrors scripts/toolchain-check.py). */
+export function runToolchainCheck(runner = defaultCommandRunner, tools = TOOLS) {
+    const lines = [];
+    const failed = [];
+    for (const tool of tools) {
+        const result = runner(tool.command, DEFAULT_TIMEOUT_MS);
+        if ("error" in result) {
+            if (result.error === "not-found") {
+                failed.push(tool.name);
+                lines.push(`  ${tool.name}: NOT FOUND`);
+            }
+            else {
+                failed.push(tool.name);
+                lines.push(`  ${tool.name}: ERROR - ${result.message}`);
+            }
+            continue;
+        }
+        const version = (result.stdout || result.stderr).trim().split("\n")[0] ?? "";
+        if (result.returncode === 0) {
+            lines.push(`  ${tool.name}: ${version}`);
+        }
+        else {
+            failed.push(tool.name);
+            lines.push(`  ${tool.name}: FAILED (exit ${result.returncode})`);
+        }
+    }
+    lines.push("");
+    if (failed.length > 0) {
+        lines.push(`Missing tools: ${failed.join(", ")}`);
+        lines.push(...nodeRuntimeRemediationLines(failed));
+        return { lines, exitCode: 1 };
+    }
+    lines.push("All required tools available");
+    return { lines, exitCode: 0 };
+}
+//# sourceMappingURL=toolchain-check.js.map

package/dist/verify-env/verify-hooks-installed.d.ts

@@ -0,0 +1,21 @@
+export type OutputStream = "stdout" | "stderr" | "none";
+export interface EvaluateResult {
+    readonly code: 0 | 1 | 2;
+    readonly message: string;
+    readonly stream: OutputStream;
+}
+export declare const REQUIRED_HOOKS: readonly ["pre-commit", "pre-push"];
+export declare const SCRIPTS_PROBE = "preflight_branch.py";
+export declare const GATE_SCRIPTS: readonly ["preflight_branch.py", "verify_encoding.py", "preflight_gh.py"];
+export declare const SCRIPTS_DIR_CANDIDATES: readonly ["scripts", ".deft/core/scripts", "deft/scripts"];
+export type GitConfigReader = (projectRoot: string) => {
+    hooksPath: string | null;
+    error: string | null;
+};
+export interface EvaluateOptions {
+    readonly gitConfigReader?: GitConfigReader;
+    readonly platform?: NodeJS.Platform;
+}
+/** Pure evaluator mirroring scripts/verify_hooks_installed.py::evaluate. */
+export declare function evaluate(projectRoot: string, options?: EvaluateOptions): EvaluateResult;
+//# sourceMappingURL=verify-hooks-installed.d.ts.map

package/dist/verify-env/verify-hooks-installed.js

@@ -0,0 +1,162 @@
+import * as childProcess from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+export const REQUIRED_HOOKS = ["pre-commit", "pre-push"];
+export const SCRIPTS_PROBE = "preflight_branch.py";
+export const GATE_SCRIPTS = [
+    "preflight_branch.py",
+    "verify_encoding.py",
+    "preflight_gh.py",
+];
+export const SCRIPTS_DIR_CANDIDATES = ["scripts", ".deft/core/scripts", "deft/scripts"];
+function defaultGitConfigReader(projectRoot) {
+    try {
+        const stdout = childProcess.execFileSync("git", ["-C", projectRoot, "config", "--get", "core.hooksPath"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const value = stdout.trim();
+        return { hooksPath: value.length > 0 ? value : null, error: null };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            return { hooksPath: null, error: "git executable not found on PATH" };
+        }
+        if (typeof e.status === "number" && e.status !== 0) {
+            return { hooksPath: null, error: null };
+        }
+        return { hooksPath: null, error: null };
+    }
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function resolveScriptsDir(projectRoot) {
+    for (const rel of SCRIPTS_DIR_CANDIDATES) {
+        const candidate = join(projectRoot, rel);
+        if (isFile(join(candidate, SCRIPTS_PROBE))) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function isPosix(platform) {
+    return platform !== "win32";
+}
+function hookExecutable(hookPath) {
+    try {
+        accessSync(hookPath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Pure evaluator mirroring scripts/verify_hooks_installed.py::evaluate. */
+export function evaluate(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const gitReader = options.gitConfigReader ?? defaultGitConfigReader;
+    const platform = options.platform ?? process.platform;
+    if (!isDirectory(root)) {
+        return {
+            code: 2,
+            message: `❌ deft hooks: project root ${root} does not exist (config error).`,
+            stream: "stderr",
+        };
+    }
+    const { hooksPath, error: gitErr } = gitReader(root);
+    if (gitErr) {
+        return {
+            code: 2,
+            message: `❌ deft hooks: cannot read core.hooksPath -- ${gitErr}.\n` +
+                "  Recovery: install git (https://git-scm.com/) so the check can run.",
+            stream: "stderr",
+        };
+    }
+    if (!hooksPath) {
+        return {
+            code: 1,
+            message: "❌ deft hooks not installed: core.hooksPath is unset.\n" +
+                "  Recovery: run `task setup` (or re-run the deft installer).",
+            stream: "stderr",
+        };
+    }
+    let hooksDir = hooksPath;
+    if (!hooksPath.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(hooksPath)) {
+        hooksDir = join(root, hooksPath);
+    }
+    if (!isDirectory(hooksDir)) {
+        return {
+            code: 1,
+            message: `❌ deft hooks wired but NON-FUNCTIONAL: core.hooksPath=${hooksPath} ` +
+                `but the directory ${hooksDir} does not exist (#1463 false-green).\n` +
+                "  Recovery: re-run the deft installer / `task setup` to deposit the hooks.",
+            stream: "stderr",
+        };
+    }
+    const missingHooks = REQUIRED_HOOKS.filter((h) => !isFile(join(hooksDir, h)));
+    if (missingHooks.length > 0) {
+        return {
+            code: 1,
+            message: `❌ deft hooks wired but NON-FUNCTIONAL: ${hooksDir} is missing ` +
+                `${missingHooks.join(", ")} (#1463 false-green).\n` +
+                "  Recovery: re-run the deft installer / `task setup`.",
+            stream: "stderr",
+        };
+    }
+    if (isPosix(platform)) {
+        const nonExec = REQUIRED_HOOKS.filter((h) => !hookExecutable(join(hooksDir, h)));
+        if (nonExec.length > 0) {
+            return {
+                code: 1,
+                message: `❌ deft hooks wired but NON-FUNCTIONAL: ${hooksDir} hook(s) ` +
+                    `${nonExec.join(", ")} are not executable (git mode is not ` +
+                    "100755); git silently skips non-executable hooks on Unix (#1477).\n" +
+                    "  Recovery: re-run the deft installer / `task setup`, or " +
+                    "`chmod +x .githooks/pre-commit .githooks/pre-push`.",
+                stream: "stderr",
+            };
+        }
+    }
+    const scriptsDir = resolveScriptsDir(root);
+    if (scriptsDir === null) {
+        return {
+            code: 1,
+            message: "❌ deft hooks wired but NON-FUNCTIONAL: the gate scripts cannot be resolved.\n" +
+                `  Looked for ${SCRIPTS_PROBE} under: ${SCRIPTS_DIR_CANDIDATES.join(", ")} (relative to ${root}).\n` +
+                "  Recovery: re-run the deft installer so the payload is present.",
+            stream: "stderr",
+        };
+    }
+    const missingScripts = GATE_SCRIPTS.filter((s) => !isFile(join(scriptsDir, s)));
+    if (missingScripts.length > 0) {
+        return {
+            code: 1,
+            message: `❌ deft hooks wired but NON-FUNCTIONAL: ${scriptsDir} is missing ` +
+                `gate script(s): ${missingScripts.join(", ")} (#1463 false-green).\n` +
+                "  Recovery: re-run the deft installer to restore the payload.",
+            stream: "stderr",
+        };
+    }
+    return {
+        code: 0,
+        message: `✓ deft hooks installed and functional: core.hooksPath=${hooksPath}, ` +
+            `hooks ${REQUIRED_HOOKS.join(", ")} present, gate scripts resolve under ${scriptsDir}.`,
+        stream: "stdout",
+    };
+}
+//# sourceMappingURL=verify-hooks-installed.js.map

package/dist/verify-env/verify-no-task-runtime.d.ts

@@ -0,0 +1,20 @@
+export interface Finding {
+    readonly path: string;
+    readonly line: number;
+    readonly message: string;
+}
+export interface ScanOptions {
+    readonly root?: string;
+    readonly pythonFiles?: () => string[];
+}
+export declare function defaultPythonFiles(root: string): string[];
+/** Scan runtime Python files for forbidden go-task dependencies. */
+export declare function scan(options?: ScanOptions): Finding[];
+export interface ScanMainResult {
+    readonly exitCode: 0 | 1;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Format scan results like scripts/verify_no_task_runtime.py::main. */
+export declare function formatScanResult(findings: Finding[]): ScanMainResult;
+//# sourceMappingURL=verify-no-task-runtime.d.ts.map

package/dist/verify-env/verify-no-task-runtime.js

@@ -0,0 +1,383 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const SUBPROCESS_FUNCS = new Set(["run", "check_call", "check_output", "Popen", "call"]);
+function splitDotted(name) {
+    const parts = [];
+    let current = "";
+    for (let i = 0; i < name.length; i += 1) {
+        const ch = name.charCodeAt(i);
+        if (ch === 46) {
+            if (current.length > 0)
+                parts.push(current);
+            current = "";
+        }
+        else {
+            current += name[i];
+        }
+    }
+    if (current.length > 0)
+        parts.push(current);
+    return parts;
+}
+function isNameOrAttr(node, dotted) {
+    const parts = splitDotted(dotted);
+    const nodeParts = splitDotted(node);
+    if (nodeParts.length !== parts.length)
+        return false;
+    for (let i = 0; i < parts.length; i += 1) {
+        if (nodeParts[i] !== parts[i])
+            return false;
+    }
+    return true;
+}
+function stripCommentsOnly(source) {
+    let out = "";
+    let i = 0;
+    let inSingle = false;
+    let inDouble = false;
+    let inTripleSingle = false;
+    let inTripleDouble = false;
+    while (i < source.length) {
+        const ch = source[i];
+        const next3 = source.slice(i, i + 3);
+        if (!inSingle && !inDouble && !inTripleSingle && !inTripleDouble && ch === "#") {
+            while (i < source.length && source.charCodeAt(i) !== 10)
+                i += 1;
+            continue;
+        }
+        if (!inDouble && !inTripleDouble && next3 === "'''" && !inSingle) {
+            inTripleSingle = !inTripleSingle;
+            out += next3;
+            i += 3;
+            continue;
+        }
+        if (!inSingle && !inTripleSingle && next3 === '"""' && !inDouble) {
+            inTripleDouble = !inTripleDouble;
+            out += next3;
+            i += 3;
+            continue;
+        }
+        if (!inDouble && !inTripleDouble && !inTripleSingle && ch === "'" && !inSingle) {
+            inSingle = true;
+            out += ch;
+            i += 1;
+            continue;
+        }
+        if (inSingle && ch === "'" && !inTripleSingle) {
+            inSingle = false;
+            out += ch;
+            i += 1;
+            continue;
+        }
+        if (!inSingle && !inTripleSingle && !inTripleDouble && ch === '"' && !inDouble) {
+            inDouble = true;
+            out += ch;
+            i += 1;
+            continue;
+        }
+        if (inDouble && ch === '"' && !inTripleDouble) {
+            inDouble = false;
+            out += ch;
+            i += 1;
+            continue;
+        }
+        out += ch;
+        i += 1;
+    }
+    return out;
+}
+function extractFirstStringArg(argsText) {
+    const trimmed = argsText.trim();
+    if (trimmed.length === 0)
+        return null;
+    const first = trimmed[0];
+    if (first === '"' || first === "'") {
+        const quote = first;
+        let i = 1;
+        while (i < trimmed.length) {
+            if (trimmed[i] === "\\") {
+                i += 2;
+                continue;
+            }
+            if (trimmed[i] === quote) {
+                return trimmed.slice(1, i);
+            }
+            i += 1;
+        }
+        return null;
+    }
+    if (first === "[" || first === "(") {
+        const close = first === "[" ? "]" : ")";
+        let depth = 0;
+        for (let i = 0; i < trimmed.length; i += 1) {
+            const ch = trimmed[i];
+            if (ch === first)
+                depth += 1;
+            else if (ch === close) {
+                depth -= 1;
+                if (depth === 0) {
+                    const inner = trimmed.slice(1, i).trim();
+                    if (inner.length === 0)
+                        return null;
+                    const head = inner.split(",")[0]?.trim() ?? "";
+                    return extractFirstStringArg(head);
+                }
+            }
+        }
+    }
+    return null;
+}
+function findCallSites(source) {
+    const cleaned = stripCommentsOnly(source);
+    const lines = cleaned.split("\n");
+    const sites = [];
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx += 1) {
+        const line = lines[lineIdx] ?? "";
+        let i = 0;
+        while (i < line.length) {
+            const paren = line.indexOf("(", i);
+            if (paren < 0)
+                break;
+            let funcEnd = paren - 1;
+            while (funcEnd >= 0) {
+                const ch = line.charCodeAt(funcEnd);
+                if (ch === 32 || ch === 9) {
+                    funcEnd -= 1;
+                    continue;
+                }
+                break;
+            }
+            let funcStart = funcEnd;
+            while (funcStart >= 0) {
+                const ch = line.charCodeAt(funcStart);
+                if ((ch >= 65 && ch <= 90) || (ch >= 97 && ch <= 122) || ch === 95 || ch === 46) {
+                    funcStart -= 1;
+                    continue;
+                }
+                break;
+            }
+            const func = line.slice(funcStart + 1, funcEnd + 1).trim();
+            let depth = 1;
+            let j = paren + 1;
+            let argsText = "";
+            while (j < line.length && depth > 0) {
+                const ch = line[j];
+                if (ch === "(")
+                    depth += 1;
+                else if (ch === ")")
+                    depth -= 1;
+                if (depth > 0)
+                    argsText += ch;
+                j += 1;
+            }
+            if (depth === 0 && func.length > 0) {
+                sites.push({
+                    line: lineIdx + 1,
+                    func,
+                    firstArg: extractFirstStringArg(argsText),
+                });
+            }
+            i = j;
+        }
+    }
+    return sites;
+}
+function parseImports(source) {
+    const imports = [];
+    for (const rawLine of source.split("\n")) {
+        const trimmed = rawLine.trim();
+        if (trimmed.startsWith("import ")) {
+            const rest = trimmed.slice("import ".length).split("#")[0]?.trim() ?? "";
+            for (const part of rest.split(",")) {
+                const piece = part.trim();
+                if (piece.length === 0)
+                    continue;
+                const asIdx = piece.indexOf(" as ");
+                if (asIdx >= 0) {
+                    imports.push({
+                        module: piece.slice(0, asIdx).trim(),
+                        name: piece.slice(0, asIdx).trim(),
+                        asname: piece.slice(asIdx + 4).trim(),
+                    });
+                }
+                else {
+                    imports.push({ module: piece, name: piece, asname: null });
+                }
+            }
+        }
+        else if (trimmed.startsWith("from ")) {
+            const withoutComment = trimmed.split("#")[0]?.trim() ?? "";
+            const fromPrefix = "from ";
+            const importIdx = withoutComment.indexOf(" import ");
+            if (importIdx < 0)
+                continue;
+            const module = withoutComment.slice(fromPrefix.length, importIdx).trim();
+            const namesPart = withoutComment.slice(importIdx + " import ".length).trim();
+            for (const part of namesPart.split(",")) {
+                const piece = part.trim();
+                if (piece.length === 0)
+                    continue;
+                const asIdx = piece.indexOf(" as ");
+                if (asIdx >= 0) {
+                    imports.push({
+                        module,
+                        name: piece.slice(0, asIdx).trim(),
+                        asname: piece.slice(asIdx + 4).trim(),
+                    });
+                }
+                else {
+                    imports.push({ module, name: piece, asname: null });
+                }
+            }
+        }
+    }
+    return imports;
+}
+class Visitor {
+    filePath;
+    subprocessNames = new Set(["subprocess"]);
+    subprocessFuncNames = new Set();
+    shutilNames = new Set(["shutil"]);
+    shutilWhichNames = new Set();
+    findings = [];
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    loadImports(source) {
+        for (const imp of parseImports(source)) {
+            if (imp.module === "subprocess" || imp.name === "subprocess") {
+                this.subprocessNames.add(imp.asname ?? imp.name);
+            }
+            if (imp.module === "shutil" || imp.name === "shutil") {
+                this.shutilNames.add(imp.asname ?? imp.name);
+            }
+            if (imp.module === "subprocess" && SUBPROCESS_FUNCS.has(imp.name)) {
+                this.subprocessFuncNames.add(imp.asname ?? imp.name);
+            }
+            if (imp.module === "shutil" && imp.name === "which") {
+                this.shutilWhichNames.add(imp.asname ?? imp.name);
+            }
+        }
+    }
+    visitCalls(sites) {
+        for (const site of sites) {
+            if (site.firstArg !== "task")
+                continue;
+            const func = site.func;
+            const dot = func.lastIndexOf(".");
+            if (dot >= 0) {
+                const attr = func.slice(dot + 1);
+                const value = func.slice(0, dot);
+                if (this.subprocessNames.has(value) && SUBPROCESS_FUNCS.has(attr)) {
+                    this.findings.push({
+                        path: this.filePath,
+                        line: site.line,
+                        message: "runtime subprocess invocation of go-task is forbidden",
+                    });
+                }
+                if (attr === "which" && (isNameOrAttr(value, "shutil") || this.shutilNames.has(value))) {
+                    this.findings.push({
+                        path: this.filePath,
+                        line: site.line,
+                        message: "runtime go-task PATH probe is forbidden",
+                    });
+                }
+            }
+            else if (this.subprocessFuncNames.has(func)) {
+                this.findings.push({
+                    path: this.filePath,
+                    line: site.line,
+                    message: "runtime subprocess invocation of go-task is forbidden",
+                });
+            }
+            else if (this.shutilWhichNames.has(func)) {
+                this.findings.push({
+                    path: this.filePath,
+                    line: site.line,
+                    message: "runtime go-task PATH probe is forbidden",
+                });
+            }
+        }
+    }
+}
+function scanFile(path, root) {
+    let source;
+    try {
+        source = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        return [{ path: relative(root, path), line: 1, message: String(err) }];
+    }
+    try {
+        const visitor = new Visitor(path);
+        visitor.loadImports(source);
+        visitor.visitCalls(findCallSites(source));
+        return visitor.findings.map((f) => ({
+            ...f,
+            path: relative(root, f.path),
+        }));
+    }
+    catch (err) {
+        return [{ path: relative(root, path), line: 1, message: String(err) }];
+    }
+}
+function defaultRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..");
+}
+export function defaultPythonFiles(root) {
+    const files = [];
+    const runPath = join(root, "run");
+    try {
+        statSync(runPath);
+        files.push(runPath);
+    }
+    catch {
+        // skip
+    }
+    const scriptsDir = join(root, "scripts");
+    try {
+        const entries = readdirSync(scriptsDir).sort();
+        for (const name of entries) {
+            if (!name.endsWith(".py"))
+                continue;
+            if (name === "verify_no_task_runtime.py")
+                continue;
+            files.push(join(scriptsDir, name));
+        }
+    }
+    catch {
+        // skip
+    }
+    return files;
+}
+/** Scan runtime Python files for forbidden go-task dependencies. */
+export function scan(options = {}) {
+    const root = resolve(options.root ?? defaultRoot());
+    const listFiles = options.pythonFiles ?? (() => defaultPythonFiles(root));
+    const findings = [];
+    for (const path of listFiles()) {
+        findings.push(...scanFile(path, root));
+    }
+    return findings;
+}
+/** Format scan results like scripts/verify_no_task_runtime.py::main. */
+export function formatScanResult(findings) {
+    if (findings.length === 0) {
+        return {
+            exitCode: 0,
+            stdout: "No runtime go-task subprocess dependencies found\n",
+            stderr: "",
+        };
+    }
+    const lines = ["Runtime go-task dependencies found:"];
+    for (const finding of findings) {
+        lines.push(`  ${finding.path}:${finding.line}: ${finding.message}`);
+    }
+    return {
+        exitCode: 1,
+        stdout: "",
+        stderr: `${lines.join("\n")}\n`,
+    };
+}
+//# sourceMappingURL=verify-no-task-runtime.js.map