@deftai/directive-core 0.107.0 → 0.108.0

package/dist/verify-env/node-runtime.d.ts

@@ -1,6 +1,10 @@
-/** Node/pnpm presence contract for TS-backed consumer gates (#1828 / #1530). */
-export declare const NODE_RUNTIME_TOOL_NAMES: readonly ["node", "pnpm"];
+/** Node/package-manager presence contract for TS-backed consumer gates. */
+import type { PackageManager } from "../resolution/package-manager.js";
+/** All supported Node/package-manager tool names across consumer projects. */
+export declare const NODE_RUNTIME_TOOL_NAMES: readonly ["node", "npm", "pnpm"];
 export declare const NODE_RUNTIME_REMEDIATION = "Node.js and pnpm are required for TS-backed deft gates. Install Node 20+ (see .nvmrc), then run: corepack enable && corepack prepare pnpm@latest --activate. See UPGRADING.md \u00A7 Node runtime.";
-/** Append remediation lines when node or pnpm is among the missing tools. */
-export declare function nodeRuntimeRemediationLines(failed: readonly string[]): readonly string[];
+/** npm ships with the supported Node distribution; Corepack/pnpm is not required. */
+export declare const NPM_RUNTIME_REMEDIATION = "Node.js and npm are required for TS-backed deft gates. Install or repair Node 20+ (see .nvmrc; npm is bundled), then re-run the consumer check. See UPGRADING.md \u00A7 Node runtime.";
+/** Append remediation lines for node or the package manager selected by the project. */
+export declare function nodeRuntimeRemediationLines(failed: readonly string[], packageManager?: PackageManager): readonly string[];
 //# sourceMappingURL=node-runtime.d.ts.map

package/dist/verify-env/node-runtime.js

@@ -1,10 +1,13 @@
-/** Node/pnpm presence contract for TS-backed consumer gates (#1828 / #1530). */
-export const NODE_RUNTIME_TOOL_NAMES = ["node", "pnpm"];
+/** Node/package-manager presence contract for TS-backed consumer gates. */
+/** All supported Node/package-manager tool names across consumer projects. */
+export const NODE_RUNTIME_TOOL_NAMES = ["node", "npm", "pnpm"];
 export const NODE_RUNTIME_REMEDIATION = "Node.js and pnpm are required for TS-backed deft gates. Install Node 20+ (see .nvmrc), then run: corepack enable && corepack prepare pnpm@latest --activate. See UPGRADING.md § Node runtime.";
-/** Append remediation lines when node or pnpm is among the missing tools. */
-export function nodeRuntimeRemediationLines(failed) {
-    if (failed.some((name) => NODE_RUNTIME_TOOL_NAMES.includes(name))) {
-        return [NODE_RUNTIME_REMEDIATION];
+/** npm ships with the supported Node distribution; Corepack/pnpm is not required. */
+export const NPM_RUNTIME_REMEDIATION = "Node.js and npm are required for TS-backed deft gates. Install or repair Node 20+ (see .nvmrc; npm is bundled), then re-run the consumer check. See UPGRADING.md § Node runtime.";
+/** Append remediation lines for node or the package manager selected by the project. */
+export function nodeRuntimeRemediationLines(failed, packageManager = "pnpm") {
+    if (failed.includes("node") || failed.includes(packageManager)) {
+        return [packageManager === "npm" ? NPM_RUNTIME_REMEDIATION : NODE_RUNTIME_REMEDIATION];
     }
     return [];
 }

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

@@ -1,13 +1,14 @@
+import { type PackageManager, type PackageManagerResolutionSource } from "../resolution/package-manager.js";
 export interface ToolCheck {
     readonly name: string;
     readonly command: readonly string[];
 }
 export declare const MAINTAINER_TOOLS: readonly ToolCheck[];
-/** Consumer npm-deposit toolchain (#2022 Phase 3) -- no Python/go/uv maintainer tools. */
+/** Consumer prerequisites shared by npm and pnpm projects. */
 export declare const CONSUMER_TOOLS: readonly ToolCheck[];
 /** @deprecated use MAINTAINER_TOOLS */
 export declare const TOOLS: readonly ToolCheck[];
-export type CommandRunner = (command: readonly string[], timeoutMs: number) => {
+export type CommandRunner = (command: readonly string[], timeoutMs: number, options?: CommandRunnerOptions) => {
     returncode: number;
     stdout: string;
     stderr: string;
@@ -15,11 +16,38 @@ export type CommandRunner = (command: readonly string[], timeoutMs: number) => {
     error: "not-found" | "exception";
     message: string;
 };
+export interface CommandRunnerOptions {
+    /** Working directory whose package-manager contract the probe must observe. */
+    readonly cwd?: string;
+    /** Environment used for PATH lookup and subprocess execution. */
+    readonly env?: NodeJS.ProcessEnv;
+}
 export interface ToolchainCheckResult {
     readonly lines: readonly string[];
     readonly exitCode: 0 | 1;
+    readonly packageManager?: PackageManager;
+    readonly packageManagerSource?: PackageManagerResolutionSource;
+}
+export interface ToolchainExecFileOptions {
+    readonly encoding: "utf8";
+    readonly timeout: number;
+    readonly stdio: ["ignore", "pipe", "pipe"];
+    readonly shell: boolean;
+    readonly windowsVerbatimArguments?: boolean;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export type ToolchainExecFileSync = (bin: string, args: readonly string[], options: ToolchainExecFileOptions) => string;
+export interface DefaultCommandRunnerOptions extends CommandRunnerOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly execFileSync?: ToolchainExecFileSync;
+    readonly exists?: (path: string) => boolean;
 }
-export declare function defaultCommandRunner(command: readonly string[], timeoutMs: number): {
+/** Child-env transport for Windows shim paths (#3814 option F). */
+export declare const RESOLVED_PACKAGE_MANAGER_SHIM_ENV = "DEFT_RESOLVED_PACKAGE_MANAGER_SHIM";
+export declare function childEnvWithResolvedPackageManagerShim(baseEnv: NodeJS.ProcessEnv, shimPath: string): NodeJS.ProcessEnv;
+/** Execute one fixed tool argv with Windows `.cmd` fallback. */
+export declare function defaultCommandRunner(command: readonly string[], timeoutMs: number, options?: DefaultCommandRunnerOptions): {
     returncode: number;
     stdout: string;
     stderr: string;
@@ -29,6 +57,10 @@ export declare function defaultCommandRunner(command: readonly string[], timeout
 };
 export interface ToolchainCheckOptions {
     readonly consumer?: boolean;
+    /** Consumer project root used for package.json/lockfile resolution. */
+    readonly projectRoot?: string;
+    /** Environment map used for package-manager precedence. */
+    readonly env?: NodeJS.ProcessEnv;
 }
 /** Run maintainer or consumer toolchain probe (mirrors scripts/toolchain-check.py). */
 export declare function runToolchainCheck(runner?: CommandRunner, options?: ToolchainCheckOptions, tools?: readonly ToolCheck[]): ToolchainCheckResult;

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

@@ -1,4 +1,8 @@
 import * as childProcess from "node:child_process";
+import { win32 } from "node:path";
+import { pythonSplitlines } from "../encoding/text.js";
+import { packageManagerSourceLabel, resolveProjectPackageManager, sanitizeSingleLineDiagnostic, } from "../resolution/package-manager.js";
+import { resolveCommandOnPath } from "./command-spawn.js";
 import { nodeRuntimeRemediationLines } from "./node-runtime.js";
 export const MAINTAINER_TOOLS = [
     { name: "go", command: ["go", "version"] },
@@ -8,87 +12,202 @@ export const MAINTAINER_TOOLS = [
     { name: "node", command: ["node", "--version"] },
     { name: "pnpm", command: ["pnpm", "--version"] },
 ];
-/** Consumer npm-deposit toolchain (#2022 Phase 3) -- no Python/go/uv maintainer tools. */
+/** Consumer prerequisites shared by npm and pnpm projects. */
 export const CONSUMER_TOOLS = [
     { name: "git", command: ["git", "--version"] },
     { name: "gh", command: ["gh", "--version"] },
     { name: "node", command: ["node", "--version"] },
-    { name: "pnpm", command: ["pnpm", "--version"] },
-    { name: "task", command: ["task", "--version"] },
 ];
+const PACKAGE_MANAGER_TOOLS = {
+    npm: { name: "npm", command: ["npm", "--version"] },
+    pnpm: { name: "pnpm", command: ["pnpm", "--version"] },
+};
 /** @deprecated use MAINTAINER_TOOLS */
 export const TOOLS = MAINTAINER_TOOLS;
 const DEFAULT_TIMEOUT_MS = 10_000;
-export function defaultCommandRunner(command, timeoutMs) {
+function executionFailure(error) {
+    return error;
+}
+function failedExecution(error) {
+    const failure = executionFailure(error);
+    return {
+        returncode: typeof failure.status === "number" ? failure.status : 1,
+        stdout: typeof failure.stdout === "string" ? failure.stdout : "",
+        stderr: typeof failure.stderr === "string" ? failure.stderr : String(failure.message ?? error),
+    };
+}
+function windowsShellReportsMissing(error) {
+    const failure = executionFailure(error);
+    if (failure.code === "ENOENT")
+        return true;
+    const diagnostic = `${failure.stderr ?? ""}\n${failure.message ?? ""}`;
+    return /is not recognized as an internal or external command|command not found/i.test(diagnostic);
+}
+function isFixedWindowsPackageManagerProbe(bin, args) {
+    return (bin === "npm" || bin === "pnpm") && args.length === 1 && args[0] === "--version";
+}
+/** Child-env transport for Windows shim paths (#3814 option F). */
+export const RESOLVED_PACKAGE_MANAGER_SHIM_ENV = "DEFT_RESOLVED_PACKAGE_MANAGER_SHIM";
+export function childEnvWithResolvedPackageManagerShim(baseEnv, shimPath) {
+    const childEnv = { ...baseEnv };
+    const targetLower = RESOLVED_PACKAGE_MANAGER_SHIM_ENV.toLowerCase();
+    for (const key of Object.keys(childEnv)) {
+        if (key.toLowerCase() === targetLower) {
+            delete childEnv[key];
+        }
+    }
+    childEnv[RESOLVED_PACKAGE_MANAGER_SHIM_ENV] = shimPath;
+    return childEnv;
+}
+function windowsCommandInterpreter(env) {
+    return win32.join(env.SystemRoot ?? "C:\\Windows", "System32", "cmd.exe");
+}
+/** Execute one fixed tool argv with Windows `.cmd` fallback. */
+export function defaultCommandRunner(command, timeoutMs, options = {}) {
     const bin = command[0] ?? "";
     const args = command.slice(1);
-    const trySpawn = (shell) => childProcess.execFileSync(bin, args, {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const execFileSync = options.execFileSync ??
+        ((file, fileArgs, execOptions) => childProcess.execFileSync(file, [...fileArgs], execOptions));
+    const execOptions = {
         encoding: "utf8",
         timeout: timeoutMs,
         stdio: ["ignore", "pipe", "pipe"],
-        shell,
-    });
+        shell: false,
+        cwd: options.cwd,
+        env,
+    };
+    // Windows package-manager shims are commonly .cmd files. Resolve an
+    // absolute PATH candidate first so cmd.exe cannot select a repo-local shim,
+    // then invoke the fixed `--version` probe through the system interpreter.
+    if (platform === "win32" && isFixedWindowsPackageManagerProbe(bin, args)) {
+        const resolvedBin = resolveCommandOnPath(bin, {
+            env,
+            platform,
+            exists: options.exists,
+        });
+        if (resolvedBin === null) {
+            return { error: "not-found", message: "" };
+        }
+        const isCommandShim = /\.(?:cmd|bat)$/i.test(resolvedBin);
+        const executable = isCommandShim ? windowsCommandInterpreter(env) : resolvedBin;
+        const shimEnv = isCommandShim ? childEnvWithResolvedPackageManagerShim(env, resolvedBin) : env;
+        const commandLine = `"%${RESOLVED_PACKAGE_MANAGER_SHIM_ENV}%" --version`;
+        const executableArgs = isCommandShim ? ["/d", "/s", "/c", `"${commandLine}"`] : args;
+        // Mirror Node's cmd.exe shell plan: the outer command quote satisfies /s,
+        // while verbatim arguments prevent libuv from re-escaping the command line.
+        const commandOptions = isCommandShim
+            ? { ...execOptions, env: shimEnv, windowsVerbatimArguments: true }
+            : execOptions;
+        try {
+            const stdout = execFileSync(executable, executableArgs, commandOptions);
+            return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
+        }
+        catch (error) {
+            if (windowsShellReportsMissing(error)) {
+                return { error: "not-found", message: "" };
+            }
+            return failedExecution(error);
+        }
+    }
     try {
-        const stdout = trySpawn(false);
+        const stdout = execFileSync(bin, args, execOptions);
         return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
     }
     catch (err) {
-        const e = err;
-        // win32: npm global shims are `.cmd` and need shell/PATHEXT (#2467 / #2415).
-        if (e.code === "ENOENT" && process.platform === "win32") {
-            try {
-                const stdout = trySpawn(true);
-                return { returncode: 0, stdout: typeof stdout === "string" ? stdout : "", stderr: "" };
-            }
-            catch {
-                // Shell still failed — binary is absent (cmd.exe often exits 1, not ENOENT).
-                return { error: "not-found", message: "" };
-            }
-        }
+        const e = executionFailure(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),
-        };
+        return failedExecution(err);
     }
 }
 /** Run maintainer or consumer toolchain probe (mirrors scripts/toolchain-check.py). */
 export function runToolchainCheck(runner = defaultCommandRunner, options = {}, tools) {
-    const selectedTools = tools ?? (options.consumer ? CONSUMER_TOOLS : MAINTAINER_TOOLS);
     const lines = [];
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const env = options.env ?? process.env;
+    let packageManager = "pnpm";
+    let packageManagerSource;
+    let selectedTools;
+    if (tools !== undefined) {
+        selectedTools = tools;
+    }
+    else if (options.consumer) {
+        const resolution = resolveProjectPackageManager({
+            projectRoot,
+            env,
+        });
+        if (!resolution.ok) {
+            lines.push(`  package manager: ERROR - ${resolution.message}`);
+            lines.push("");
+            lines.push("Package manager selection failed");
+            return { lines, exitCode: 1 };
+        }
+        packageManager = resolution.packageManager;
+        packageManagerSource = resolution.source;
+        lines.push(`  package manager: ${packageManager} (${packageManagerSourceLabel(packageManagerSource)})`);
+        selectedTools = [...CONSUMER_TOOLS, PACKAGE_MANAGER_TOOLS[packageManager]];
+    }
+    else {
+        selectedTools = MAINTAINER_TOOLS;
+    }
+    const missing = [];
     const failed = [];
     for (const tool of selectedTools) {
-        const result = runner(tool.command, DEFAULT_TIMEOUT_MS);
+        const result = runner(tool.command, DEFAULT_TIMEOUT_MS, { cwd: projectRoot, env });
         if ("error" in result) {
             if (result.error === "not-found") {
-                failed.push(tool.name);
+                missing.push(tool.name);
                 lines.push(`  ${tool.name}: NOT FOUND`);
             }
             else {
                 failed.push(tool.name);
-                lines.push(`  ${tool.name}: ERROR - ${result.message}`);
+                const diagnostic = firstSafeDiagnostic(result.message);
+                lines.push(`  ${tool.name}: ERROR${diagnostic === "" ? "" : ` - ${diagnostic}`}`);
             }
             continue;
         }
-        const version = (result.stdout || result.stderr).trim().split("\n")[0] ?? "";
+        const version = firstSafeOutputLine(result.stdout || result.stderr);
         if (result.returncode === 0) {
             lines.push(`  ${tool.name}: ${version}`);
         }
         else {
             failed.push(tool.name);
-            lines.push(`  ${tool.name}: FAILED (exit ${result.returncode})`);
+            const diagnostic = firstSafeDiagnostic(result.stderr || result.stdout);
+            lines.push(`  ${tool.name}: FAILED (exit ${result.returncode})${diagnostic === "" ? "" : ` - ${diagnostic}`}`);
         }
     }
     lines.push("");
-    if (failed.length > 0) {
-        lines.push(`Missing tools: ${failed.join(", ")}`);
-        lines.push(...nodeRuntimeRemediationLines(failed));
-        return { lines, exitCode: 1 };
+    const unavailable = [...missing, ...failed];
+    if (unavailable.length > 0) {
+        if (missing.length > 0)
+            lines.push(`Missing tools: ${missing.join(", ")}`);
+        if (failed.length > 0)
+            lines.push(`Failed tools: ${failed.join(", ")}`);
+        lines.push(...nodeRuntimeRemediationLines(unavailable, packageManager));
+        return {
+            lines,
+            exitCode: 1,
+            ...(options.consumer ? { packageManager, packageManagerSource } : {}),
+        };
     }
     lines.push("All required tools available");
-    return { lines, exitCode: 0 };
+    return {
+        lines,
+        exitCode: 0,
+        ...(options.consumer ? { packageManager, packageManagerSource } : {}),
+    };
+}
+function firstSafeOutputLine(text) {
+    const first = pythonSplitlines(text)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0);
+    return first === undefined ? "" : sanitizeSingleLineDiagnostic(first);
+}
+function firstSafeDiagnostic(text) {
+    const first = firstSafeOutputLine(text);
+    return /^[A-Z][A-Z0-9_]*=/.test(first) ? "" : first;
 }
 //# sourceMappingURL=toolchain-check.js.map

package/dist/verify-source/project-definition-mutation-boundary.d.ts

@@ -0,0 +1,104 @@
+/**
+ * project-definition-mutation-boundary.ts -- mechanized production inventory for
+ * PROJECT-DEFINITION mutation identity (#3796).
+ *
+ * A convention that mutators "should" use the shared lock is not checkable: a
+ * caller can take the lock and then resolve, read, or write the artifact through
+ * its own path, and a helper-level test still passes while a production family
+ * split-brains. This scanner replaces that convention with a boundary.
+ *
+ * Two things are enforced:
+ *
+ * 1. **Boundary** -- outside the modules that own the protocol, no production
+ *    source may call the raw lock, the raw write sink, or the raw loader, and no
+ *    file that mutates PROJECT-DEFINITION may re-resolve the artifact path. The
+ *    mutation capability is the only way in.
+ * 2. **Inventory** -- the per-file census of mutation call expressions is
+ *    recorded. Adding or removing a mutation site is a deliberate edit to
+ *    {@link PRODUCTION_MUTATION_INVENTORY}, not a silent drift.
+ *
+ * Consumed fail-closed by `project-definition-mutation-boundary.test.ts`.
+ */
+/** The capability that owns load/parse/persist against the captured path. */
+export declare const MUTATION_CAPABILITY_MODULE = "packages/core/src/vbrief-build/project-definition-mutation.ts";
+/** The module that owns the lock protocol and the raw primitives it wraps. */
+export declare const MUTATION_PROTOCOL_MODULE = "packages/core/src/vbrief-build/project-definition-io.ts";
+/**
+ * This scanner. Excluded from its own scan: it names every pattern it looks for
+ * in prose and regex literals, so scanning it would count the rules as call
+ * sites and let the inventory drift by editing the gate.
+ */
+export declare const MUTATION_BOUNDARY_MODULE = "packages/core/src/verify-source/project-definition-mutation-boundary.ts";
+/**
+ * Raw primitives and the only production files allowed to call them. Anything
+ * else reaching for these is a bypass of the captured-path identity.
+ */
+export declare const RAW_MUTATION_CALL_RULES: readonly {
+    readonly label: string;
+    readonly pattern: RegExp;
+    readonly allowedFiles: readonly string[];
+}[];
+/** Resolver calls that would give a mutation section a second artifact identity. */
+export declare const RESOLVER_CALL_PATTERNS: readonly RegExp[];
+/**
+ * Character offsets of each `withProjectDefinitionMutation(...)` argument list.
+ *
+ * Scoping to the section is what keeps the resolver rule precise: resolving the
+ * path *before* acquiring the lock is ordinary pre-check work, while resolving it
+ * *inside* the critical section is the second identity the contract forbids.
+ * String, template, and comment spans are skipped so their braces and parens do
+ * not throw off the match.
+ */
+export declare function extractMutationSections(text: string): Array<[number, number]>;
+/**
+ * Production mutation call expressions, per file.
+ *
+ * The counts are the #3796 census: **18** call expressions across 13 core files
+ * that previously took the shared lock, plus the **2** `packages/cli` policy
+ * writers (`wipCap`, `swarmSubagentBackend`) that previously wrote
+ * PROJECT-DEFINITION with no lock at all. `parity-scenarios.ts` is the fixture
+ * harness for the same protocol and is counted separately below.
+ */
+export declare const PRODUCTION_MUTATION_INVENTORY: Readonly<Record<string, number>>;
+/**
+ * The #3796 census, split by provenance so a drift failure says which family
+ * moved. 18 core call expressions across 13 files already took the shared lock;
+ * the 2 `packages/cli` policy writers did not; `parity-scenarios.ts` is the
+ * fixture harness for the same protocol.
+ */
+export declare const PREVIOUSLY_LOCKED_CORE_CALL_EXPRESSIONS = 18;
+export declare const PREVIOUSLY_LOCKED_CORE_FILES = 13;
+export declare const PREVIOUSLY_UNLOCKED_CLI_WRITERS = 2;
+export declare const PARITY_HARNESS_CALL_EXPRESSIONS = 1;
+export interface MutationBoundaryFinding {
+    readonly path: string;
+    readonly line: number;
+    readonly rule: string;
+    readonly text: string;
+}
+export interface MutationBoundaryScan {
+    readonly findings: readonly MutationBoundaryFinding[];
+    /** Mutation call expressions per production file, posix-relative. */
+    readonly inventory: Readonly<Record<string, number>>;
+    readonly filesScanned: number;
+}
+/**
+ * Scan production TypeScript for mutation-identity bypasses and build the
+ * mutation call-expression inventory. The scan reads the filesystem, not the git
+ * index, so an unstaged or brand-new bypass is still caught.
+ */
+export declare function scanProjectDefinitionMutationBoundary(projectRoot: string): MutationBoundaryScan;
+/** Render findings as a stable, reviewable report. */
+export declare function formatMutationBoundaryFindings(findings: readonly MutationBoundaryFinding[]): string;
+export interface MutationBoundaryVerdict {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+    readonly scan: MutationBoundaryScan;
+}
+/**
+ * The fail-closed verdict: no bypass, and the mutation inventory still matches
+ * the recorded census. Adding or removing a mutation site is a deliberate edit
+ * to {@link PRODUCTION_MUTATION_INVENTORY} and the census constants above.
+ */
+export declare function evaluateProjectDefinitionMutationBoundary(projectRoot: string): MutationBoundaryVerdict;
+//# sourceMappingURL=project-definition-mutation-boundary.d.ts.map