@deftai/directive-core 0.68.1 → 0.70.0

package/dist/deposit/contain.d.ts

@@ -0,0 +1,41 @@
+/**
+ * contain.ts — deposit-boundary symlink-escape guard (#2305).
+ *
+ * The framework deposit derives its destination as
+ * `deftDir = join(projectDir, ".deft/core")` and copies the (trusted) content
+ * payload into it. If a malicious project repo commits `.deft` (or `.deft/core`,
+ * or a parent) as a symlink that escapes the tree — e.g. `.deft -> ../../evil` —
+ * the deposit would write/replace framework content THROUGH that symlink,
+ * outside the resolved project tree, under the victim's account.
+ *
+ * `assertDepositContained` refuses that: it anchors on `realpath(projectDir)`,
+ * walks each existing component from the project root down to `deftDir`, rejects
+ * any component that is a symlink escaping the project tree, and asserts the
+ * deepest existing ancestor of `deftDir` resolves back UNDER the project tree
+ * using path-SEGMENT containment (not string `startsWith`).
+ *
+ * Callers MUST invoke it BEFORE the first copy/mkdir/reconstitute so a refusal
+ * deposits nothing.
+ *
+ * Refs #2305.
+ */
+/** Non-zero exit code for a deposit-containment refusal (needs-action). */
+export declare const DEPOSIT_CONTAINMENT_REFUSED_EXIT_CODE = 2;
+/** Thrown by the deposit/refresh path when the destination escapes the tree. */
+export declare class DepositContainmentError extends Error {
+    readonly projectDir: string;
+    readonly deftDir: string;
+    readonly offendingPath: string;
+    constructor(message: string, details: {
+        projectDir: string;
+        deftDir: string;
+        offendingPath: string;
+    });
+}
+/**
+ * Refuse the deposit when `.deft` / `.deft/core` (or a parent) is a symlink that
+ * escapes the resolved project tree. Throws {@link DepositContainmentError};
+ * MUST be called BEFORE any deposit write so a refusal deposits nothing.
+ */
+export declare function assertDepositContained(projectDir: string, deftDir: string): void;
+//# sourceMappingURL=contain.d.ts.map

package/dist/deposit/contain.js

@@ -0,0 +1,113 @@
+/**
+ * contain.ts — deposit-boundary symlink-escape guard (#2305).
+ *
+ * The framework deposit derives its destination as
+ * `deftDir = join(projectDir, ".deft/core")` and copies the (trusted) content
+ * payload into it. If a malicious project repo commits `.deft` (or `.deft/core`,
+ * or a parent) as a symlink that escapes the tree — e.g. `.deft -> ../../evil` —
+ * the deposit would write/replace framework content THROUGH that symlink,
+ * outside the resolved project tree, under the victim's account.
+ *
+ * `assertDepositContained` refuses that: it anchors on `realpath(projectDir)`,
+ * walks each existing component from the project root down to `deftDir`, rejects
+ * any component that is a symlink escaping the project tree, and asserts the
+ * deepest existing ancestor of `deftDir` resolves back UNDER the project tree
+ * using path-SEGMENT containment (not string `startsWith`).
+ *
+ * Callers MUST invoke it BEFORE the first copy/mkdir/reconstitute so a refusal
+ * deposits nothing.
+ *
+ * Refs #2305.
+ */
+import { lstatSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+/** Non-zero exit code for a deposit-containment refusal (needs-action). */
+export const DEPOSIT_CONTAINMENT_REFUSED_EXIT_CODE = 2;
+/** Thrown by the deposit/refresh path when the destination escapes the tree. */
+export class DepositContainmentError extends Error {
+    projectDir;
+    deftDir;
+    offendingPath;
+    constructor(message, details) {
+        super(message);
+        this.name = "DepositContainmentError";
+        this.projectDir = details.projectDir;
+        this.deftDir = details.deftDir;
+        this.offendingPath = details.offendingPath;
+    }
+}
+/**
+ * Path-SEGMENT containment: is `child` equal to `parent` or nested under it?
+ * Uses `path.relative` so `/foo` is NOT treated as containing `/foobar`
+ * (`relative("/foo", "/foobar")` is `"../foobar"`, which is rejected).
+ */
+function isContained(parent, child) {
+    if (parent === child) {
+        return true;
+    }
+    const rel = relative(parent, child);
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+ * Refuse the deposit when `.deft` / `.deft/core` (or a parent) is a symlink that
+ * escapes the resolved project tree. Throws {@link DepositContainmentError};
+ * MUST be called BEFORE any deposit write so a refusal deposits nothing.
+ */
+export function assertDepositContained(projectDir, deftDir) {
+    const projectAbs = resolve(projectDir);
+    let projectReal;
+    try {
+        projectReal = realpathSync(projectAbs);
+    }
+    catch {
+        // The project directory does not exist yet (e.g. `directive init <new-path>`).
+        // Nothing under it can exist, so there is no pre-existing symlink to escape
+        // through -- the downstream init flow creates fresh, clean directories. Let
+        // the deposit proceed; a missing content payload / mkdir failure surfaces its
+        // own error later.
+        return;
+    }
+    const deftAbs = resolve(deftDir);
+    const rel = relative(projectAbs, deftAbs);
+    if (rel.length === 0 || rel.startsWith("..") || isAbsolute(rel)) {
+        throw new DepositContainmentError(`deposit refused: deposit target ${deftAbs} is not nested under the project tree ${projectAbs}`, { projectDir: projectAbs, deftDir: deftAbs, offendingPath: deftAbs });
+    }
+    const segments = rel.split(/[\\/]+/).filter((segment) => segment.length > 0);
+    let current = projectAbs;
+    let deepestExistingReal = projectReal;
+    for (const segment of segments) {
+        current = join(current, segment);
+        let info;
+        try {
+            info = lstatSync(current);
+        }
+        catch {
+            // This component does not exist yet; nothing below it can exist either.
+            break;
+        }
+        if (info.isSymbolicLink()) {
+            let linkReal;
+            try {
+                linkReal = realpathSync(current);
+            }
+            catch {
+                throw new DepositContainmentError(`deposit refused: ${current} is a broken/dangling symlink on the deposit path`, { projectDir: projectAbs, deftDir: deftAbs, offendingPath: current });
+            }
+            if (!isContained(projectReal, linkReal)) {
+                throw new DepositContainmentError(`deposit refused: ${current} is a symlink escaping the project tree ` +
+                    `(resolves to ${linkReal}, outside ${projectReal})`, { projectDir: projectAbs, deftDir: deftAbs, offendingPath: current });
+            }
+            deepestExistingReal = linkReal;
+        }
+        else {
+            deepestExistingReal = realpathSync(current);
+        }
+    }
+    // Defense-in-depth: the deepest EXISTING ancestor of deftDir must resolve back
+    // under the project tree (segment containment, not string startsWith).
+    if (!isContained(projectReal, deepestExistingReal)) {
+        throw new DepositContainmentError(`deposit refused: deposit path escapes the project tree ` +
+            `(${deepestExistingReal} is outside ${projectReal})`, { projectDir: projectAbs, deftDir: deftAbs, offendingPath: deepestExistingReal });
+    }
+}
+//# sourceMappingURL=contain.js.map

package/dist/deposit/copy-tree.js

@@ -8,7 +8,7 @@
  * Refs #1942 S1, #1477.
  */
 import { createReadStream, createWriteStream } from "node:fs";
-import { chmod, mkdir, readdir, stat } from "node:fs/promises";
+import { chmod, lstat, mkdir, readdir, stat } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { pipeline } from "node:stream/promises";
 const DEFAULT_FILE_MODE = 0o644;
@@ -34,7 +34,13 @@ async function copyDirContents(src, dst) {
     for (const entry of entries) {
         const srcPath = join(src, entry.name);
         const dstPath = join(dst, entry.name);
-        const srcStat = await stat(srcPath);
+        // #2305: lstat (not stat) so a symlinked entry is NOT followed silently.
+        // The deposit copies regular files/dirs only; a symlink in the (trusted)
+        // payload is skipped rather than dereferenced.
+        const srcStat = await lstat(srcPath);
+        if (srcStat.isSymbolicLink()) {
+            continue;
+        }
         if (srcStat.isDirectory()) {
             await copyDirContents(srcPath, dstPath);
         }

package/dist/doctor/checks.d.ts

@@ -19,6 +19,17 @@ export declare function checkLegacyLayout(projectRoot: string, seams?: CheckSeam
  * been stamped npm-managed. Local-only (no network).
  */
 export declare function checkCanonicalVendoredNpmSignpost(projectRoot: string, seams?: CheckSeams): CheckResult;
+/**
+ * #2294: report whether the located install manifest can surface a version.
+ * A legacy `deft-install` deposit made without a release pin writes empty
+ * `tag`/`ref` and only a short `sha`, leaving the framework version silently
+ * unreportable. Since the Go installer is a frozen legacy bridge (#1912) and
+ * the Python/Go rails are retired (#1933/#2022/#2068), the fix is doctor-side:
+ * turn the silent blank into a visible, actionable finding. Advisory only --
+ * exit-code-exempt like `canonical-vendored-npm-signpost` -- because a sha-only
+ * deposit is still a working install, just an unpinned one.
+ */
+export declare function checkManifestVersionReportable(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
 export declare function deriveExitCode(checks: readonly CheckResult[], errors: readonly string[]): number;
 export declare function runChecksImpl(projectRoot: string, seams?: CheckSeams & {
     isDir?: (p: string) => boolean;

package/dist/doctor/checks.js

@@ -4,7 +4,7 @@ import { detectCanonicalVendoredManifest, isNpmManaged, NPM_MANAGED_SENTINEL_KEY
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { findSkillPathsInText } from "../text/redos-safe.js";
 import { CANONICAL_UPGRADE_COMMAND, GO_BRIDGE_RELEASES_URL, UPGRADING_DOC_URL, } from "./constants.js";
-import { isDeprecationRedirectStub, locateManifest, manifestCandidatePaths, manifestTagToVersion, parseInstallManifest, parseInstallRootFromAgentsMd, parseManifest, } from "./manifest.js";
+import { isDeprecationRedirectStub, locateManifest, manifestCandidatePaths, manifestReportableVersion, manifestTagToVersion, parseInstallManifest, parseInstallRootFromAgentsMd, parseManifest, } from "./manifest.js";
 import { readTextSafe } from "./paths.js";
 function readText(path, seams) {
     return (seams.readText ?? readTextSafe)(path);
@@ -366,11 +366,82 @@ export function checkCanonicalVendoredNpmSignpost(projectRoot, seams = {}) {
         },
     };
 }
+/**
+ * #2294: report whether the located install manifest can surface a version.
+ * A legacy `deft-install` deposit made without a release pin writes empty
+ * `tag`/`ref` and only a short `sha`, leaving the framework version silently
+ * unreportable. Since the Go installer is a frozen legacy bridge (#1912) and
+ * the Python/Go rails are retired (#1933/#2022/#2068), the fix is doctor-side:
+ * turn the silent blank into a visible, actionable finding. Advisory only --
+ * exit-code-exempt like `canonical-vendored-npm-signpost` -- because a sha-only
+ * deposit is still a working install, just an unpinned one.
+ */
+export function checkManifestVersionReportable(projectRoot, installRoot, seams = {}) {
+    const isFile = seams.isFile ?? ((p) => readText(p, seams) !== null);
+    const manifestPath = locateManifest(projectRoot, installRoot, isFile);
+    if (manifestPath === null) {
+        return {
+            name: "manifest-version-reportable",
+            status: "skip",
+            detail: "No install manifest found; no framework version to report.",
+            data: { manifest_path: null },
+        };
+    }
+    const text = readText(manifestPath, seams);
+    if (text === null) {
+        return {
+            name: "manifest-version-reportable",
+            status: "skip",
+            detail: `Install manifest at ${manifestPath} is unreadable.`,
+            data: { manifest_path: manifestPath },
+        };
+    }
+    const manifest = parseInstallManifest(text);
+    const reportable = manifestReportableVersion(manifest);
+    if (reportable.version !== null) {
+        return {
+            name: "manifest-version-reportable",
+            status: "pass",
+            detail: `Framework version resolves to ${reportable.version} (from manifest ${reportable.source}) at ${manifestPath}.`,
+            data: {
+                manifest_path: manifestPath,
+                version: reportable.version,
+                source: reportable.source,
+            },
+        };
+    }
+    if (reportable.sha !== null) {
+        const shortSha = reportable.sha.slice(0, 8);
+        return {
+            name: "manifest-version-reportable",
+            status: "fail",
+            detail: `Install manifest at ${manifestPath} carries no semver tag/ref (sha ${shortSha} only), ` +
+                "so the framework version is unreportable. This happens on legacy `deft-install` deposits " +
+                `made without a release pin (#2294). Run \`${CANONICAL_UPGRADE_COMMAND}\` then \`directive update\` ` +
+                `to obtain a pinned npm-managed manifest. See ${UPGRADING_DOC_URL}.`,
+            data: {
+                manifest_path: manifestPath,
+                version: null,
+                source: reportable.source,
+                sha: reportable.sha,
+                upgrade_command: CANONICAL_UPGRADE_COMMAND,
+                upgrading_doc_url: UPGRADING_DOC_URL,
+            },
+        };
+    }
+    return {
+        name: "manifest-version-reportable",
+        status: "skip",
+        detail: `Install manifest at ${manifestPath} has neither a semver tag/ref nor a sha; no provenance to report.`,
+        data: { manifest_path: manifestPath, version: null, sha: null, source: reportable.source },
+    };
+}
 export function deriveExitCode(checks, errors) {
+    const exitExempt = new Set(["canonical-vendored-npm-signpost", "manifest-version-reportable"]);
     if (errors.length > 0 || checks.some((c) => c.status === "error")) {
         return 2;
     }
-    if (checks.some((c) => c.status === "fail" && c.name !== "canonical-vendored-npm-signpost")) {
+    if (checks.some((c) => c.status === "fail" && !exitExempt.has(c.name))) {
         return 1;
     }
     return 0;
@@ -402,6 +473,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
             data: { agents_md_path: agentsMdPath },
         });
         checks.push(checkManifestAgreement(projectRoot, null, seams));
+        checks.push(checkManifestVersionReportable(projectRoot, null, seams));
         checks.push(checkLegacyLayout(projectRoot, seams));
         checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
         return {
@@ -415,6 +487,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
     checks.push(checkQuickStartResolves(projectRoot, installRoot, seams));
     checks.push(checkSkillPathsResolve(projectRoot, agentsMdText, seams));
     checks.push(checkManifestAgreement(projectRoot, installRoot, seams));
+    checks.push(checkManifestVersionReportable(projectRoot, installRoot, seams));
     checks.push(checkInstallPathConsistency(projectRoot, installRoot, seams));
     checks.push(checkLegacyLayout(projectRoot, seams));
     checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));

package/dist/doctor/constants.d.ts

@@ -1,3 +1,4 @@
+import { type PackageManager } from "../resolution/package-manager.js";
 export declare const UV_INSTALL_URL = "https://docs.astral.sh/uv/";
 export declare const UPGRADING_DOC_URL = "https://github.com/deftai/directive/blob/master/content/UPGRADING.md";
 export declare const GO_BRIDGE_RELEASES_URL = "https://github.com/deftai/directive/releases";
@@ -18,6 +19,14 @@ export declare const DEFT_REPO_POSITIVE_MARKERS: readonly ["content/templates/ag
 export declare const EXPECTED_CONTENT_DIRS: readonly ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
 export declare const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
+/**
+ * Render the canonical upgrade one-liner for the active package manager (#2197).
+ * Defaults to npm (`CANONICAL_UPGRADE_COMMAND`) so existing callers are
+ * unchanged; pass `pnpm` to emit the pnpm form
+ * (`pnpm add -g @deftai/directive@latest`). Consumed by the doctor
+ * payload-staleness recommendation (`payload-staleness.ts`).
+ */
+export declare function upgradeCommandFor(pm?: PackageManager): string;
 /** Vendored npm-managed deposit: global bump plus in-place `.deft/core/` refresh (#2115). */
 export declare const VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest && deft update";
 export declare const CLEAN_WINDOW_HOURS = 24;

package/dist/doctor/constants.js

@@ -1,3 +1,4 @@
+import { ENGINE_PACKAGE, renderGlobalInstall, } from "../resolution/package-manager.js";
 export const UV_INSTALL_URL = "https://docs.astral.sh/uv/";
 // Stable, version-neutral upgrade signposts (#1912). Core principle: never bake
 // the upgrade command/version into the artifact being upgraded -- bake in a
@@ -60,6 +61,16 @@ export const DEFT_REPO_POSITIVE_MARKERS = [
 export const EXPECTED_CONTENT_DIRS = ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
 export const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
+/**
+ * Render the canonical upgrade one-liner for the active package manager (#2197).
+ * Defaults to npm (`CANONICAL_UPGRADE_COMMAND`) so existing callers are
+ * unchanged; pass `pnpm` to emit the pnpm form
+ * (`pnpm add -g @deftai/directive@latest`). Consumed by the doctor
+ * payload-staleness recommendation (`payload-staleness.ts`).
+ */
+export function upgradeCommandFor(pm = "npm") {
+    return renderGlobalInstall(pm, `${ENGINE_PACKAGE}@latest`);
+}
 /** Vendored npm-managed deposit: global bump plus in-place `.deft/core/` refresh (#2115). */
 export const VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND = `${CANONICAL_UPGRADE_COMMAND} && deft update`;
 export const CLEAN_WINDOW_HOURS = 24;

package/dist/doctor/main.d.ts

@@ -1,3 +1,49 @@
-import type { DoctorSeams } from "./types.js";
+import { type ResolutionFacts } from "../resolution/index.js";
+import { createPlainSink } from "./output.js";
+import type { DoctorSeams, Finding, ResolutionSummary } from "./types.js";
 export declare function cmdDoctor(args: readonly string[], seams?: DoctorSeams): number;
+/**
+ * Never emit a bare `task ...` remediation in a project without Taskfile wiring
+ * (#2267). The `directive` surface always works; `task deft:X` is optional and
+ * only present when the consumer wired the include. `plan()` already emits the
+ * `directive` / `npx` / `npm` surface, so this guard is a defensive invariant:
+ * any `task`-prefixed command is rewritten to the `directive` surface unless the
+ * project actually has the include.
+ */
+/**
+ * Detect Taskfile wiring through the injected seam (#2267). Mirrors
+ * `classifyTaskfileInclude` but routes the filesystem read through
+ * `seams.readText` so the resolution decision stays deterministic + injectable
+ * in tests -- unlike a direct `classifyTaskfileInclude(projectRoot)` call, which
+ * bypasses every other seam-flowed probe in `runResolutionDecision`.
+ */
+export declare function resolveTaskfileWiring(projectRoot: string, seams: DoctorSeams): boolean;
+export declare function enforceDirectiveSurface(command: string | null, hasTaskfileWiring: boolean): string | null;
+/** Human-facing operating mode derived from the orthogonal fact-set. */
+export declare function resolveOperatingMode(facts: ResolutionFacts): string;
+/**
+ * Single engine/pin/VERSION reconciliation line. `reconcileVersions` flags
+ * content-behind/ahead and engine-behind; engine-ahead skew is folded in here so
+ * the line is the one version-state summary the operator reads.
+ */
+export declare function resolveReconciliationLine(facts: ResolutionFacts): string;
+/**
+ * Probe `.deft/.cli/<platform>` across platforms and report presence + skew. A
+ * partial install, or a mix of present + absent platforms, is engine skew: a
+ * gate can pass on one platform and fail on another. Read-only.
+ */
+export declare function resolvePlatformSkew(projectRoot: string, seams: DoctorSeams): {
+    line: string;
+    skewDetected: boolean;
+    findings: Finding[];
+};
+/**
+ * The single read-only decision surface (#2267). Reuses the shared keystone
+ * `classify()` + `plan()` (the ONE classifier) to emit the operating mode, the
+ * engine/pin/VERSION reconciliation, cross-platform skew, and exactly ONE
+ * primary `Next command:` with a root-cause + remediation rationale. Secondary
+ * migration advice (`plan()` warnings) is suppressed until the primary blocker
+ * clears. Mutates nothing.
+ */
+export declare function runResolutionDecision(projectRoot: string, jsonMode: boolean, sink: ReturnType<typeof createPlainSink>, addFinding: (f: Finding) => void, seams: DoctorSeams): ResolutionSummary;
 //# sourceMappingURL=main.d.ts.map