@deftai/directive-core 0.68.1 → 0.70.0

package/dist/resolution/classify.js

@@ -0,0 +1,138 @@
+/**
+ * Orthogonal fact-set classifier for the resolution spine (#2264 / epic #2203).
+ *
+ * `classify()` returns a flat, independent fact-set — never a single collapsed
+ * enum. `plan()` owns the collapse into one recommended action, so there is
+ * exactly one precedence table in the system.
+ *
+ * It REUSES the existing detectors rather than re-implementing them:
+ *  - pre-cutover artifacts    -> `../vbrief-validate/precutover.ts`
+ *  - managed-section sha      -> `../platform/agents-md.ts::parseManagedSectionAttrs`
+ *  - deposited payload version-> `../doctor/manifest.ts` + `../init-deposit/constants.ts`
+ *  - committed pin            -> `./pin.ts`
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { locateManifest, manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
+import { CANONICAL_INSTALL_ROOT } from "../init-deposit/constants.js";
+import { extractManagedSection, parseManagedSectionAttrs } from "../platform/agents-md.js";
+import { detectPreCutover } from "../vbrief-validate/precutover.js";
+import { readPin } from "./pin.js";
+/** App-source markers used for the `hasAppCode` heuristic. */
+const APP_CODE_MARKERS = [
+    "package.json",
+    "pyproject.toml",
+    "go.mod",
+    "Cargo.toml",
+    "pom.xml",
+    "build.gradle",
+    "Gemfile",
+    "src",
+];
+const SEMVER_IN_TEXT_RE = /(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/;
+function defaultIsFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultIsDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultReadText(p) {
+    try {
+        if (!existsSync(p))
+            return null;
+        return readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function probeEngineVersion(binary) {
+    try {
+        const out = execFileSync(binary, ["--version"], {
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const match = SEMVER_IN_TEXT_RE.exec(out);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Default engine probe: try `directive --version`, then `deft --version`. */
+export function defaultEngineProbe() {
+    for (const binary of ["directive", "deft"]) {
+        const version = probeEngineVersion(binary);
+        if (version !== null) {
+            return { reachable: true, version };
+        }
+    }
+    return { reachable: false, version: null };
+}
+function detectAppCode(cwd, isFile, isDir) {
+    return APP_CODE_MARKERS.some((marker) => marker === "src" ? isDir(join(cwd, marker)) : isFile(join(cwd, marker)));
+}
+function readManagedSection(cwd, readText) {
+    const text = readText(join(cwd, "AGENTS.md"));
+    if (text === null)
+        return { hasManagedSection: false, managedSectionSha: null };
+    const section = extractManagedSection(text);
+    if (section === null)
+        return { hasManagedSection: false, managedSectionSha: null };
+    const attrs = parseManagedSectionAttrs(section);
+    return { hasManagedSection: true, managedSectionSha: attrs?.sha ?? null };
+}
+function readPayloadVersion(cwd, hasDeftCore, isFile, readText) {
+    if (!hasDeftCore)
+        return null;
+    const manifestPath = locateManifest(cwd, CANONICAL_INSTALL_ROOT, isFile);
+    if (manifestPath === null)
+        return null;
+    const text = readText(manifestPath);
+    if (text === null)
+        return null;
+    return manifestTagToVersion(parseInstallManifest(text));
+}
+/**
+ * Classify a project directory into the orthogonal resolution fact-set. All I/O
+ * is behind injectable seams so callers (tests, sandboxed runtimes) can supply a
+ * deterministic view of the filesystem and the engine-reachability probe.
+ */
+export function classify(cwd, seams = {}) {
+    const isFile = seams.isFile ?? defaultIsFile;
+    const isDir = seams.isDir ?? defaultIsDir;
+    const readText = seams.readText ?? defaultReadText;
+    const engineProbe = seams.engineProbe ?? defaultEngineProbe;
+    const preCutoverProbe = seams.preCutoverProbe ?? ((dir) => detectPreCutover(dir).preCutover);
+    const hasDeftCore = isDir(join(cwd, CANONICAL_INSTALL_ROOT));
+    const { hasManagedSection, managedSectionSha } = readManagedSection(cwd, readText);
+    const engine = engineProbe();
+    const pin = readPin(cwd, { isFile, readText });
+    return {
+        hasGit: isDir(join(cwd, ".git")) || isFile(join(cwd, ".git")),
+        hasAppCode: detectAppCode(cwd, isFile, isDir),
+        hasDeftCore,
+        deftCorePayloadVersion: readPayloadVersion(cwd, hasDeftCore, isFile, readText),
+        hasManagedSection,
+        managedSectionSha,
+        hasVbrief: isDir(join(cwd, "vbrief")),
+        hasXbrief: isDir(join(cwd, "xbrief")),
+        preCutoverArtifacts: preCutoverProbe(cwd),
+        engineReachable: engine.reachable,
+        engineVersion: engine.version,
+        pinVersion: pin.pinVersion,
+    };
+}
+//# sourceMappingURL=classify.js.map

package/dist/resolution/engine-ladder.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Global-first engine-resolution ladder for the resolution spine (#2264, from #2124).
+ *
+ * The defect this closes is `execution-env != install-env`: an agent can read
+ * every rule in `.deft/core/` yet execute no gate because the engine that is
+ * reachable in the environment it is ACTUALLY running in is absent or stale.
+ * The ladder detects that mismatch and self-heals only then:
+ *
+ *   1. global `deft` reachable AND >= pin                       -> use it
+ *   2. local `.deft/.cli/<platform>` reachable, intact, >= pin  -> use it
+ *   3. must install:
+ *      a. registry up + global prefix writable                 -> npm i -g @deftai/directive@<pin>
+ *      b. registry up + global prefix NOT writable (sandbox)    -> npm install --prefix .deft/.cli/<platform>
+ *      c. registry down + staged tarball                        -> install from staged payload
+ *      d. registry down + no tarball                            -> hard-fail ("stage this")
+ *
+ * `decideEngineLadder` is a PURE decision function (no I/O). The side-effecting
+ * install is factored behind an injected runner in `resolveEngine` so the whole
+ * self-heal path is unit-testable without touching the network.
+ */
+import type { IntegrityResult } from "./integrity.js";
+export type LadderRung = "global" | "local" | "install-global" | "install-sandbox" | "install-staged" | "hard-fail";
+export interface LocalEngineFacts {
+    /** Version reported by the local engine, or null. */
+    readonly version: string | null;
+    /** Integrity classification of `.deft/.cli/<platform>`. */
+    readonly integrity: IntegrityResult;
+}
+export interface LadderFacts {
+    /** Canonical committed pin. */
+    readonly pinVersion: string | null;
+    /** Version of the globally-reachable engine, or null when absent. */
+    readonly globalEngineVersion: string | null;
+    /** Local engine facts, or null when never installed. */
+    readonly localEngine: LocalEngineFacts | null;
+    /** The npm registry is reachable. */
+    readonly registryUp: boolean;
+    /** The global npm prefix is writable (false inside a sandbox). */
+    readonly globalPrefixWritable: boolean;
+    /** A pre-staged tarball / vendored payload is available for offline install. */
+    readonly stagedTarballAvailable: boolean;
+    /** Platform id (for trace / install target). */
+    readonly platform: string;
+}
+export interface LadderDecision {
+    readonly rung: LadderRung;
+    /** True when the engine is resolved WITHOUT an install (global or local). */
+    readonly usable: boolean;
+    /** Version the ladder resolved to when usable, else null. */
+    readonly resolvedVersion: string | null;
+    /** Structured trace of every rung evaluated. */
+    readonly trace: string;
+    /** One-line reason for the chosen rung. */
+    readonly reason: string;
+}
+/**
+ * Pure global-first ladder decision. Emits a structured trace describing each
+ * rung it evaluated and why it was skipped or chosen.
+ */
+export declare function decideEngineLadder(facts: LadderFacts): LadderDecision;
+/** Outcome of a side-effecting engine install. */
+export interface EngineInstallOutcome {
+    readonly installed: boolean;
+    /** Version the install produced, or null on failure. */
+    readonly version: string | null;
+    readonly detail: string;
+}
+/** Injected side-effecting install runner (npm i -g / --prefix / staged). */
+export type EngineInstallRunner = (context: {
+    readonly rung: Extract<LadderRung, "install-global" | "install-sandbox" | "install-staged">;
+    readonly pinVersion: string | null;
+    readonly platform: string;
+}) => EngineInstallOutcome;
+/** Injected content re-projection (`update`) run after a fresh install. */
+export type ReprojectRunner = (version: string | null) => void;
+export interface ResolveEngineOptions {
+    readonly installRunner?: EngineInstallRunner;
+    readonly reproject?: ReprojectRunner;
+}
+export interface EngineResolution {
+    readonly decision: LadderDecision;
+    /** The install outcome when a rung required an install, else null. */
+    readonly installOutcome: EngineInstallOutcome | null;
+    /** The engine version resolved after any install, or null when unresolved. */
+    readonly resolvedVersion: string | null;
+    /** True when the ladder healed a mismatch (installed) with zero manual steps. */
+    readonly selfHealed: boolean;
+    /** Full structured trace including any install + re-projection. */
+    readonly trace: string;
+}
+/**
+ * Resolve the engine by composing the pure ladder decision with an injected
+ * install runner. When a rung requires an install, the runner performs it and
+ * (on success) the re-projection runner forward-migrates content — yielding the
+ * "self-heals with zero manual npm/PATH steps" behavior with a structured trace.
+ */
+export declare function resolveEngine(facts: LadderFacts, options?: ResolveEngineOptions): EngineResolution;
+//# sourceMappingURL=engine-ladder.d.ts.map

package/dist/resolution/engine-ladder.js

@@ -0,0 +1,185 @@
+/**
+ * Global-first engine-resolution ladder for the resolution spine (#2264, from #2124).
+ *
+ * The defect this closes is `execution-env != install-env`: an agent can read
+ * every rule in `.deft/core/` yet execute no gate because the engine that is
+ * reachable in the environment it is ACTUALLY running in is absent or stale.
+ * The ladder detects that mismatch and self-heals only then:
+ *
+ *   1. global `deft` reachable AND >= pin                       -> use it
+ *   2. local `.deft/.cli/<platform>` reachable, intact, >= pin  -> use it
+ *   3. must install:
+ *      a. registry up + global prefix writable                 -> npm i -g @deftai/directive@<pin>
+ *      b. registry up + global prefix NOT writable (sandbox)    -> npm install --prefix .deft/.cli/<platform>
+ *      c. registry down + staged tarball                        -> install from staged payload
+ *      d. registry down + no tarball                            -> hard-fail ("stage this")
+ *
+ * `decideEngineLadder` is a PURE decision function (no I/O). The side-effecting
+ * install is factored behind an injected runner in `resolveEngine` so the whole
+ * self-heal path is unit-testable without touching the network.
+ */
+import { semverGte } from "./pin.js";
+function fmt(version) {
+    return version ?? "absent";
+}
+/**
+ * Pure global-first ladder decision. Emits a structured trace describing each
+ * rung it evaluated and why it was skipped or chosen.
+ */
+export function decideEngineLadder(facts) {
+    const { pinVersion } = facts;
+    const steps = [];
+    // Rung 1: global engine.
+    if (facts.globalEngineVersion !== null && semverGte(facts.globalEngineVersion, pinVersion)) {
+        steps.push(`global: ${fmt(facts.globalEngineVersion)} >= pin ${fmt(pinVersion)} -> use`);
+        return {
+            rung: "global",
+            usable: true,
+            resolvedVersion: facts.globalEngineVersion,
+            trace: steps.join("; "),
+            reason: `global engine ${facts.globalEngineVersion} satisfies pin ${fmt(pinVersion)}`,
+        };
+    }
+    if (facts.globalEngineVersion === null) {
+        steps.push("global: absent");
+    }
+    else {
+        steps.push(`global: ${facts.globalEngineVersion} < pin ${fmt(pinVersion)}`);
+    }
+    // Rung 2: local sandbox engine (must be intact AND >= pin).
+    const local = facts.localEngine;
+    if (local !== null) {
+        if (!local.integrity.usable) {
+            steps.push(local.integrity.partial
+                ? `local: partial install -> not-usable`
+                : `local: ${local.integrity.reason}`);
+        }
+        else if (!semverGte(local.version, pinVersion)) {
+            steps.push(`local: ${fmt(local.version)} < pin ${fmt(pinVersion)}`);
+        }
+        else {
+            steps.push(`local: ${fmt(local.version)} >= pin ${fmt(pinVersion)} -> use`);
+            return {
+                rung: "local",
+                usable: true,
+                resolvedVersion: local.version,
+                trace: steps.join("; "),
+                reason: `local engine ${local.version} satisfies pin ${fmt(pinVersion)}`,
+            };
+        }
+    }
+    else {
+        steps.push("local: absent");
+    }
+    // Rung 3: must install.
+    if (facts.registryUp && facts.globalPrefixWritable) {
+        steps.push(`install: npm i -g @deftai/directive@${fmt(pinVersion)}`);
+        return {
+            rung: "install-global",
+            usable: false,
+            resolvedVersion: null,
+            trace: steps.join("; "),
+            reason: "registry up and global prefix writable -> global install",
+        };
+    }
+    if (facts.registryUp && !facts.globalPrefixWritable) {
+        steps.push(`install: npm install --prefix .deft/.cli/${facts.platform} @deftai/directive@${fmt(pinVersion)}`);
+        return {
+            rung: "install-sandbox",
+            usable: false,
+            resolvedVersion: null,
+            trace: steps.join("; "),
+            reason: "registry up but global prefix not writable (sandbox) -> --prefix install",
+        };
+    }
+    if (!facts.registryUp && facts.stagedTarballAvailable) {
+        steps.push("install: staged tarball / vendored payload");
+        return {
+            rung: "install-staged",
+            usable: false,
+            resolvedVersion: null,
+            trace: steps.join("; "),
+            reason: "registry down but staged tarball available -> offline install",
+        };
+    }
+    steps.push("hard-fail: registry down and no staged tarball");
+    return {
+        rung: "hard-fail",
+        usable: false,
+        resolvedVersion: null,
+        trace: steps.join("; "),
+        reason: "registry down and no staged tarball -- stage a payload to proceed",
+    };
+}
+const INSTALL_RUNGS = new Set([
+    "install-global",
+    "install-sandbox",
+    "install-staged",
+]);
+/**
+ * Resolve the engine by composing the pure ladder decision with an injected
+ * install runner. When a rung requires an install, the runner performs it and
+ * (on success) the re-projection runner forward-migrates content — yielding the
+ * "self-heals with zero manual npm/PATH steps" behavior with a structured trace.
+ */
+export function resolveEngine(facts, options = {}) {
+    const decision = decideEngineLadder(facts);
+    const steps = [decision.trace];
+    if (decision.usable) {
+        return {
+            decision,
+            installOutcome: null,
+            resolvedVersion: decision.resolvedVersion,
+            selfHealed: false,
+            trace: steps.join("; "),
+        };
+    }
+    if (decision.rung === "hard-fail" || !INSTALL_RUNGS.has(decision.rung)) {
+        return {
+            decision,
+            installOutcome: null,
+            resolvedVersion: null,
+            selfHealed: false,
+            trace: steps.join("; "),
+        };
+    }
+    const runner = options.installRunner;
+    if (!runner) {
+        steps.push("install: deferred (no install runner supplied)");
+        return {
+            decision,
+            installOutcome: null,
+            resolvedVersion: null,
+            selfHealed: false,
+            trace: steps.join("; "),
+        };
+    }
+    const outcome = runner({
+        rung: decision.rung,
+        pinVersion: facts.pinVersion,
+        platform: facts.platform,
+    });
+    if (!outcome.installed) {
+        steps.push(`install failed: ${outcome.detail}`);
+        return {
+            decision,
+            installOutcome: outcome,
+            resolvedVersion: null,
+            selfHealed: false,
+            trace: steps.join("; "),
+        };
+    }
+    steps.push(`installed ${decision.rung} -> ${fmt(outcome.version)}`);
+    if (options.reproject) {
+        options.reproject(outcome.version);
+        steps.push(`re-projected content ${fmt(outcome.version)}`);
+    }
+    return {
+        decision,
+        installOutcome: outcome,
+        resolvedVersion: outcome.version,
+        selfHealed: true,
+        trace: steps.join("; "),
+    };
+}
+//# sourceMappingURL=engine-ladder.js.map

package/dist/resolution/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolution spine (keystone #2264 / epic #2203) — shared library primitives.
+ *
+ * The classifier (`classify`) produces the orthogonal fact-set; `plan()` applies
+ * one ordered precedence table and emits the versioned public resolution-plan-v1
+ * schema (the single source of truth). The engine ladder, local-engine integrity
+ * check, three-band skew policy, and pin/VERSION/sha reconciliation are the
+ * supporting primitives that init / update / doctor / headless (children B–E)
+ * consume — this module ships them; it does NOT rewire verb behavior.
+ */
+export { RESOLUTION_ENCODINGS, RESOLUTION_MODES, RESOLUTION_PLAN_SCHEMA_VERSION, type ResolutionEncoding, type ResolutionFacts, type ResolutionFile, type ResolutionMode, type ResolutionNextAction, type ResolutionPlan, } from "@deftai/directive-types";
+export { type ClassifySeams, classify, defaultEngineProbe, type EngineProbeResult, } from "./classify.js";
+export { decideEngineLadder, type EngineInstallOutcome, type EngineInstallRunner, type EngineResolution, type LadderDecision, type LadderFacts, type LadderRung, type LocalEngineFacts, type ReprojectRunner, type ResolveEngineOptions, resolveEngine, } from "./engine-ladder.js";
+export { checkLocalEngineIntegrity, type IntegrityResult, type IntegritySeams, LOCAL_ENGINE_MARKERS, LOCAL_ENGINE_ROOT, localEnginePlatformDir, } from "./integrity.js";
+export { DEFAULT_PACKAGE_MANAGER, type DetectPackageManagerInput, detectPackageManager, ENGINE_PACKAGE, PACKAGE_MANAGERS, type PackageManager, type PackageManagerCommands, renderEphemeral, renderGlobalInstall, renderPackageManagerCommands, renderProjectInstall, } from "./package-manager.js";
+export { compareSemver, isExactPin, PIN_DEPENDENCY_NAME, type PinReadResult, type PinReadSeams, parseSemver, type ReconcileInputs, type ReconcileResult, readPin, reconcileVersions, type SemverTriple, semverGte, } from "./pin.js";
+export { type PlanOptions, plan } from "./plan.js";
+export { ACCEPT_ENGINE_SKEW_ENV, DEFAULT_ENGINE_SKEW_WINDOW, evaluateSkew, type SkewBand, type SkewDecision, type SkewOptions, type SkewResult, } from "./skew-policy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/resolution/index.js

@@ -0,0 +1,19 @@
+/**
+ * Resolution spine (keystone #2264 / epic #2203) — shared library primitives.
+ *
+ * The classifier (`classify`) produces the orthogonal fact-set; `plan()` applies
+ * one ordered precedence table and emits the versioned public resolution-plan-v1
+ * schema (the single source of truth). The engine ladder, local-engine integrity
+ * check, three-band skew policy, and pin/VERSION/sha reconciliation are the
+ * supporting primitives that init / update / doctor / headless (children B–E)
+ * consume — this module ships them; it does NOT rewire verb behavior.
+ */
+export { RESOLUTION_ENCODINGS, RESOLUTION_MODES, RESOLUTION_PLAN_SCHEMA_VERSION, } from "@deftai/directive-types";
+export { classify, defaultEngineProbe, } from "./classify.js";
+export { decideEngineLadder, resolveEngine, } from "./engine-ladder.js";
+export { checkLocalEngineIntegrity, LOCAL_ENGINE_MARKERS, LOCAL_ENGINE_ROOT, localEnginePlatformDir, } from "./integrity.js";
+export { DEFAULT_PACKAGE_MANAGER, detectPackageManager, ENGINE_PACKAGE, PACKAGE_MANAGERS, renderEphemeral, renderGlobalInstall, renderPackageManagerCommands, renderProjectInstall, } from "./package-manager.js";
+export { compareSemver, isExactPin, PIN_DEPENDENCY_NAME, parseSemver, readPin, reconcileVersions, semverGte, } from "./pin.js";
+export { plan } from "./plan.js";
+export { ACCEPT_ENGINE_SKEW_ENV, DEFAULT_ENGINE_SKEW_WINDOW, evaluateSkew, } from "./skew-policy.js";
+//# sourceMappingURL=index.js.map

package/dist/resolution/integrity.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Local-engine integrity check for the resolution spine (#2264, from #2124).
+ *
+ * A locally-installed engine at `.deft/.cli/<platform>` is only usable when the
+ * install completed. A present-but-partial directory (an interrupted
+ * `npm install --prefix`) must be treated as NOT-USABLE — otherwise the ladder
+ * would select a half-installed engine and fail at execution time instead of
+ * falling through to a clean re-install.
+ */
+/** Root of the sandbox-local engine install, relative to the project root. */
+export declare const LOCAL_ENGINE_ROOT = ".deft/.cli";
+/**
+ * Marker paths (relative to the platform install dir) that MUST all exist for a
+ * local engine to count as a completed, usable install. `package.json` marks the
+ * install root; the `directive` bin under `node_modules/.bin` marks that npm
+ * finished linking the executable.
+ */
+export declare const LOCAL_ENGINE_MARKERS: readonly string[];
+export interface IntegritySeams {
+    readonly isFile?: (p: string) => boolean;
+    readonly isDir?: (p: string) => boolean;
+    readonly platform?: string;
+}
+export interface IntegrityResult {
+    /** The install is complete and the engine may be selected. */
+    readonly usable: boolean;
+    /** The platform install directory exists at all (vs. wholly absent). */
+    readonly present: boolean;
+    /** Present but missing required markers (interrupted install). */
+    readonly partial: boolean;
+    /** Absolute-relative platform install directory that was probed. */
+    readonly platformDir: string;
+    /** Marker paths that were missing. */
+    readonly missingMarkers: readonly string[];
+    /** Human-facing reason. */
+    readonly reason: string;
+}
+/** Resolve the platform-specific local engine directory (e.g. `.deft/.cli/linux`). */
+export declare function localEnginePlatformDir(projectRoot: string, platform?: string): string;
+/**
+ * Classify the local engine install at `.deft/.cli/<platform>`.
+ *
+ * - wholly absent            -> `{ usable: false, present: false, partial: false }`
+ * - present, all markers     -> `{ usable: true,  present: true,  partial: false }`
+ * - present, missing markers -> `{ usable: false, present: true,  partial: true  }`
+ */
+export declare function checkLocalEngineIntegrity(projectRoot: string, seams?: IntegritySeams): IntegrityResult;
+//# sourceMappingURL=integrity.d.ts.map

package/dist/resolution/integrity.js

@@ -0,0 +1,80 @@
+/**
+ * Local-engine integrity check for the resolution spine (#2264, from #2124).
+ *
+ * A locally-installed engine at `.deft/.cli/<platform>` is only usable when the
+ * install completed. A present-but-partial directory (an interrupted
+ * `npm install --prefix`) must be treated as NOT-USABLE — otherwise the ladder
+ * would select a half-installed engine and fail at execution time instead of
+ * falling through to a clean re-install.
+ */
+import { existsSync } from "node:fs";
+import { platform as osPlatform } from "node:os";
+import { join } from "node:path";
+/** Root of the sandbox-local engine install, relative to the project root. */
+export const LOCAL_ENGINE_ROOT = ".deft/.cli";
+/**
+ * Marker paths (relative to the platform install dir) that MUST all exist for a
+ * local engine to count as a completed, usable install. `package.json` marks the
+ * install root; the `directive` bin under `node_modules/.bin` marks that npm
+ * finished linking the executable.
+ */
+export const LOCAL_ENGINE_MARKERS = [
+    "package.json",
+    join("node_modules", ".bin", "directive"),
+];
+function defaultIsFile(p) {
+    try {
+        return existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the platform-specific local engine directory (e.g. `.deft/.cli/linux`). */
+export function localEnginePlatformDir(projectRoot, platform) {
+    const plat = platform ?? osPlatform();
+    return join(projectRoot, LOCAL_ENGINE_ROOT, plat);
+}
+/**
+ * Classify the local engine install at `.deft/.cli/<platform>`.
+ *
+ * - wholly absent            -> `{ usable: false, present: false, partial: false }`
+ * - present, all markers     -> `{ usable: true,  present: true,  partial: false }`
+ * - present, missing markers -> `{ usable: false, present: true,  partial: true  }`
+ */
+export function checkLocalEngineIntegrity(projectRoot, seams = {}) {
+    const isFile = seams.isFile ?? defaultIsFile;
+    const isDir = seams.isDir ?? seams.isFile ?? defaultIsFile;
+    const platformDir = localEnginePlatformDir(projectRoot, seams.platform);
+    const rootPresent = isDir(platformDir);
+    const missingMarkers = LOCAL_ENGINE_MARKERS.filter((marker) => !isFile(join(platformDir, marker)));
+    if (!rootPresent && missingMarkers.length === LOCAL_ENGINE_MARKERS.length) {
+        return {
+            usable: false,
+            present: false,
+            partial: false,
+            platformDir,
+            missingMarkers,
+            reason: `no local engine at ${platformDir}`,
+        };
+    }
+    if (missingMarkers.length > 0) {
+        return {
+            usable: false,
+            present: true,
+            partial: true,
+            platformDir,
+            missingMarkers,
+            reason: `partial local engine at ${platformDir} (missing: ${missingMarkers.join(", ")}) -- treated as not-usable`,
+        };
+    }
+    return {
+        usable: true,
+        present: true,
+        partial: false,
+        platformDir,
+        missingMarkers: [],
+        reason: `intact local engine at ${platformDir}`,
+    };
+}
+//# sourceMappingURL=integrity.js.map

package/dist/resolution/package-manager.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Package-manager abstraction for the resolution spine (#2197, from #2264).
+ *
+ * The documented install/upgrade path historically hard-coded npm
+ * (`npm i -g @deftai/directive`). pnpm-managed setups have no first-class
+ * flow, and mixing an npm global into a pnpm environment breaks PATH/shim/store
+ * consistency. This module makes the *command rendering* package-manager aware
+ * so the resolution plan and doctor emit the right form for the active manager.
+ *
+ * Two load-bearing facts keep this small (locked on issue #2197):
+ *   1. NO additional registry. pnpm resolves from the same npm registry
+ *      (`registry.npmjs.org`) by default; the published `@deftai/directive`
+ *      tarball is unchanged. No renderer here ever emits a `--registry` flag.
+ *   2. The internal `.deft/.cli/<platform>` sandbox vendoring STAYS on npm
+ *      (its `node_modules/.bin` layout is validated by `integrity.ts` and is
+ *      gitignored / package-manager-invisible). Only the global, project-local,
+ *      ephemeral, and upgrade command forms vary by package manager.
+ *
+ * Every function here is PURE (no I/O): detection consumes an injected fact-set
+ * so the whole surface is unit-testable without touching the filesystem or env.
+ */
+export type PackageManager = "npm" | "pnpm";
+export declare const PACKAGE_MANAGERS: readonly PackageManager[];
+export declare const DEFAULT_PACKAGE_MANAGER: PackageManager;
+/** Canonical published engine package name. */
+export declare const ENGINE_PACKAGE = "@deftai/directive";
+export interface DetectPackageManagerInput {
+    /** Environment map (reads `DEFT_PACKAGE_MANAGER` and `npm_config_user_agent`). */
+    readonly env?: NodeJS.ProcessEnv;
+    /** The `packageManager` field from the project package.json (Corepack), if any. */
+    readonly packageManagerField?: string | null;
+    /** Whether a `pnpm-lock.yaml` is present at the project root. */
+    readonly pnpmLockPresent?: boolean;
+}
+/**
+ * Detect the active package manager. Precedence (first match wins):
+ *   1. `DEFT_PACKAGE_MANAGER` env override
+ *   2. `packageManager` field / Corepack shim
+ *   3. `pnpm-lock.yaml` present
+ *   4. `npm_config_user_agent` (set by the manager that spawned the process)
+ *   5. default: npm
+ */
+export declare function detectPackageManager(input?: DetectPackageManagerInput): PackageManager;
+/**
+ * Render a global install command, e.g. `npm i -g @deftai/directive@0.65.0`
+ * (npm) or `pnpm add -g @deftai/directive@0.65.0` (pnpm). `spec` is the full
+ * package spec including any `@version` suffix.
+ */
+export declare function renderGlobalInstall(pm: PackageManager, spec?: string): string;
+/**
+ * Render a project-local (dev-dependency) install command. pnpm-managed repos
+ * that prefer not to install globally use this.
+ */
+export declare function renderProjectInstall(pm: PackageManager, spec?: string): string;
+/**
+ * Render an ephemeral (no-install) invocation, e.g. `npx @deftai/directive update`
+ * (npm) or `pnpm dlx @deftai/directive update` (pnpm).
+ */
+export declare function renderEphemeral(pm: PackageManager, subcommand: string, pkg?: string): string;
+export interface PackageManagerCommands {
+    readonly packageManager: PackageManager;
+    /** Global install of the engine at the given spec. */
+    readonly globalInstall: string;
+    /** Project-local (dev-dependency) install of the engine. */
+    readonly projectInstall: string;
+    /** Ephemeral `update` invocation. */
+    readonly ephemeralUpdate: string;
+    /** The canonical upgrade one-liner (global install of `@latest`). */
+    readonly upgradeOneLiner: string;
+}
+/**
+ * Render the full command matrix for a package manager at a given spec
+ * (defaults to `@latest`). Single-sourced so docs, doctor, and the plan all
+ * derive from the same renderers.
+ */
+export declare function renderPackageManagerCommands(pm: PackageManager, spec?: string): PackageManagerCommands;
+//# sourceMappingURL=package-manager.d.ts.map