@deftai/directive-core 0.55.2 → 0.56.1

package/dist/cache/errors.d.ts

@@ -2,9 +2,12 @@
 export declare class CacheError extends Error {
     constructor(message: string);
 }
+/** Format like Python ``KeyError`` str() for golden parity with the oracle. */
+export declare function keyErrorMessage(inner: string): string;
 /** Cache miss for the requested (source, key). */
 export declare class CacheNotFoundError extends Error {
-    constructor(message: string);
+    readonly innerMessage: string;
+    constructor(inner: string);
 }
 /** meta.json failed schema validation on read or write. */
 export declare class CacheValidationError extends Error {

package/dist/cache/errors.js

@@ -5,10 +5,16 @@ export class CacheError extends Error {
         this.name = "CacheError";
     }
 }
+/** Format like Python ``KeyError`` str() for golden parity with the oracle. */
+export function keyErrorMessage(inner) {
+    return `"${inner.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
 /** Cache miss for the requested (source, key). */
 export class CacheNotFoundError extends Error {
-    constructor(message) {
-        super(message);
+    innerMessage;
+    constructor(inner) {
+        super(keyErrorMessage(inner));
+        this.innerMessage = inner;
         this.name = "CacheNotFoundError";
     }
 }

package/dist/cache/fetch.d.ts

@@ -51,6 +51,9 @@ export declare function runFetchAll(options: {
     limit?: number;
     labels?: readonly string[];
     author?: string | null;
+    force?: boolean;
+    contentDriftNumbers?: readonly number[];
+    probeDriftFn?: typeof probeCacheDrift;
     isFresh?: (metaPath: string) => boolean;
     doPut?: (key: string, raw: Record<string, unknown>) => void;
 }): FetchAllReportImpl;
@@ -65,6 +68,9 @@ export declare function cacheFetchAll(options: {
     labels?: readonly string[];
     author?: string | null;
     cacheRoot?: string;
+    force?: boolean;
+    contentDriftNumbers?: readonly number[];
+    probeDriftFn?: typeof probeCacheDrift;
 }): FetchAllReportImpl;
 export declare class StateRefreshReportImpl implements StateRefreshReport {
     revisited: number;
@@ -97,5 +103,49 @@ export declare function cacheRefreshClosed(options: {
     delayMs?: number;
     limit?: number;
     cacheRoot?: string;
+    openNumbers?: Set<number>;
+    listOpenFn?: (repo: string, limit: number) => Set<number>;
 }): StateRefreshReportImpl;
+export declare const DEFAULT_SELF_HEAL_TTL_SECONDS = 3600;
+export declare const SELF_HEAL_STATE_FILENAME = "self-heal-state.json";
+export declare const DEFAULT_MAX_CONTENT_DRIFT_CHECKS = 25;
+export interface CacheDriftProbeResult {
+    readonly stateDriftNumbers: readonly number[];
+    readonly contentDriftNumbers: readonly number[];
+}
+/** Diff cached-open issue numbers vs the live open set and TTL-fresh content drift. */
+export declare function probeCacheDrift(options: {
+    repo: string;
+    source?: string;
+    cacheRoot?: string;
+    limit?: number;
+    includeContentDrift?: boolean;
+    maxContentDriftChecks?: number;
+    listOpenFn?: (repo: string, limit: number) => Set<number>;
+    fetchSingleFn?: (repo: string, n: number) => Record<string, unknown>;
+    isFreshFn?: (metaPath: string) => boolean;
+}): CacheDriftProbeResult;
+export interface SelfHealResult {
+    readonly skipped: boolean;
+    readonly skipReason: string | null;
+    readonly drift: CacheDriftProbeResult | null;
+    readonly refresh: StateRefreshReportImpl | null;
+}
+/** TTL-bounded closed-reconcile for session ritual / triage:welcome self-healing (#1886). */
+export declare function maybeSelfHealCache(projectRoot: string, options?: {
+    repo?: string | null;
+    source?: string;
+    cacheRoot?: string;
+    ttlSeconds?: number;
+    nowFn?: () => Date;
+    listOpenFn?: (repo: string, limit: number) => Set<number>;
+    fetchSingleFn?: (repo: string, n: number) => Record<string, unknown>;
+    refreshFn?: (opts: {
+        source: string;
+        repo: string;
+        cacheRoot: string;
+        openNumbers: Set<number>;
+    }) => StateRefreshReportImpl;
+    writeState?: boolean;
+}): SelfHealResult;
 //# sourceMappingURL=fetch.d.ts.map

package/dist/cache/fetch.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { GhRestError, InvalidRepoError, restIssueView, runGhApi, } from "../scm/gh-rest.js";
 import { DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS } from "./constants.js";
@@ -198,6 +198,31 @@ function listIssuesRest(repo, options) {
         throw err;
     }
 }
+function resolveContentDriftNumbers(options) {
+    if (options.force)
+        return new Set();
+    if (options.contentDriftNumbers !== undefined) {
+        return new Set(options.contentDriftNumbers);
+    }
+    try {
+        const probeOpts = {
+            repo: options.repo,
+            source: options.source,
+            cacheRoot: options.cacheRoot,
+        };
+        if (options.fetchSingleFn)
+            probeOpts.fetchSingleFn = options.fetchSingleFn;
+        const listOpenNumbers = options.listOpenNumbers;
+        if (listOpenNumbers) {
+            probeOpts.listOpenFn = () => listOpenNumbers;
+        }
+        const drift = (options.probeDriftFn ?? probeCacheDrift)(probeOpts);
+        return new Set(drift.contentDriftNumbers);
+    }
+    catch {
+        return new Set();
+    }
+}
 export function runFetchAll(options) {
     const issues = listIssuesRest(options.repo, {
         state: options.state ?? "open",
@@ -205,6 +230,13 @@ export function runFetchAll(options) {
         labels: options.labels ?? [],
         author: options.author ?? null,
     });
+    const issueByNumber = new Map();
+    for (const issue of issues) {
+        const number = issue.number;
+        if (typeof number === "number" && number > 0) {
+            issueByNumber.set(number, issue);
+        }
+    }
     const report = new FetchAllReportImpl();
     const total = issues.length;
     const cacheRoot = options.cacheRoot ?? ".deft-cache";
@@ -217,6 +249,21 @@ export function runFetchAll(options) {
         ((key, raw) => {
             cachePut(source, key, raw, { ttlSeconds, cacheRoot });
         });
+    const contentDriftNumbers = resolveContentDriftNumbers({
+        force: options.force,
+        repo: options.repo,
+        source,
+        cacheRoot,
+        contentDriftNumbers: options.contentDriftNumbers,
+        probeDriftFn: options.probeDriftFn,
+        fetchSingleFn: (repo, n) => {
+            const fromList = issueByNumber.get(n);
+            if (fromList !== undefined)
+                return normaliseRestIssue(fromList);
+            return singleIssueFetcherImpl(repo, n);
+        },
+        listOpenNumbers: new Set(issueByNumber.keys()),
+    });
     if (total >= PROGRESS_EVERY_N) {
         emitFetchProgress(options.repo, "enumerated", 0, total, report);
     }
@@ -234,7 +281,9 @@ export function runFetchAll(options) {
         else {
             const key = `${options.repo}/${number}`;
             const edir = entryDir(source, key, cacheRoot);
-            if (isFreshFn(join(edir, "meta.json"))) {
+            const metaPath = join(edir, "meta.json");
+            const skipFresh = !options.force && isFreshFn(metaPath) && !contentDriftNumbers.has(number);
+            if (skipFresh) {
                 report.alreadyFresh += 1;
             }
             else {
@@ -284,6 +333,9 @@ export function cacheFetchAll(options) {
         limit: options.limit,
         labels: options.labels,
         author: options.author,
+        force: options.force,
+        contentDriftNumbers: options.contentDriftNumbers,
+        probeDriftFn: options.probeDriftFn,
     });
 }
 export class StateRefreshReportImpl {
@@ -395,7 +447,9 @@ export function scanCachedOpenEntries(repo, source, cacheRoot) {
 export function cacheRefreshClosed(options) {
     const cacheRoot = options.cacheRoot ?? ".deft-cache";
     const cachedOpen = scanCachedOpenEntries(options.repo, options.source, cacheRoot);
-    const openNumbers = listOpenIssueNumbers(options.repo, { limit: options.limit ?? 1000 });
+    const limit = options.limit ?? 1000;
+    const openNumbers = options.openNumbers ??
+        (options.listOpenFn ?? ((repo, listLimit) => listOpenIssueNumbers(repo, { limit: listLimit })))(options.repo, limit);
     return runStateRefresh({
         repo: options.repo,
         openNumbers,
@@ -410,4 +464,171 @@ export function cacheRefreshClosed(options) {
         },
     });
 }
+export const DEFAULT_SELF_HEAL_TTL_SECONDS = 3600;
+export const SELF_HEAL_STATE_FILENAME = "self-heal-state.json";
+export const DEFAULT_MAX_CONTENT_DRIFT_CHECKS = 25;
+function issueContentFingerprint(raw) {
+    const labels = (raw.labels ?? [])
+        .map((label) => String(label.name ?? ""))
+        .filter(Boolean)
+        .sort();
+    return JSON.stringify({
+        body: raw.body ?? "",
+        labels,
+        state: typeof raw.state === "string" ? raw.state.toLowerCase() : raw.state,
+        title: raw.title ?? "",
+    });
+}
+function scanCacheForSingleRepo(cacheRoot, source) {
+    const base = join(cacheRoot, source);
+    if (!existsSync(base))
+        return null;
+    const pairs = [];
+    for (const ownerEntry of readdirSync(base, { withFileTypes: true })) {
+        if (!ownerEntry.isDirectory())
+            continue;
+        const ownerDir = join(base, ownerEntry.name);
+        try {
+            for (const repoEntry of readdirSync(ownerDir, { withFileTypes: true })) {
+                if (!repoEntry.isDirectory())
+                    continue;
+                pairs.push([ownerEntry.name, repoEntry.name]);
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    if (pairs.length === 1 && pairs[0]) {
+        return `${pairs[0][0]}/${pairs[0][1]}`;
+    }
+    return null;
+}
+/** Diff cached-open issue numbers vs the live open set and TTL-fresh content drift. */
+export function probeCacheDrift(options) {
+    const source = options.source ?? "github-issue";
+    const cacheRoot = options.cacheRoot ?? ".deft-cache";
+    const limit = options.limit ?? 1000;
+    const includeContentDrift = options.includeContentDrift !== false;
+    const maxContentDriftChecks = options.maxContentDriftChecks ?? DEFAULT_MAX_CONTENT_DRIFT_CHECKS;
+    const listOpen = options.listOpenFn ??
+        ((repo, listLimit) => listOpenIssueNumbers(repo, { limit: listLimit }));
+    const fetchSingle = options.fetchSingleFn ?? singleIssueFetcherImpl;
+    const isFreshFn = options.isFreshFn ?? ((metaPath) => isFresh(metaPath));
+    const cachedOpen = scanCachedOpenEntries(options.repo, source, cacheRoot);
+    const liveOpen = listOpen(options.repo, limit);
+    const stateDriftNumbers = [];
+    const contentDriftNumbers = [];
+    let contentChecks = 0;
+    for (const [number, cachedRaw] of cachedOpen) {
+        if (!liveOpen.has(number)) {
+            stateDriftNumbers.push(number);
+            continue;
+        }
+        if (!includeContentDrift || contentChecks >= maxContentDriftChecks)
+            continue;
+        const parts = options.repo.split("/", 2);
+        const owner = parts[0] ?? "";
+        const name = parts[1] ?? "";
+        const metaPath = join(cacheRoot, source, owner, name, String(number), "meta.json");
+        if (!isFreshFn(metaPath))
+            continue;
+        contentChecks += 1;
+        try {
+            const live = normaliseRestIssue(fetchSingle(options.repo, number));
+            if (issueContentFingerprint(cachedRaw) !== issueContentFingerprint(live)) {
+                contentDriftNumbers.push(number);
+            }
+        }
+        catch {
+            /* probe best-effort */
+        }
+    }
+    stateDriftNumbers.sort((a, b) => a - b);
+    contentDriftNumbers.sort((a, b) => a - b);
+    return { stateDriftNumbers, contentDriftNumbers };
+}
+function readSelfHealState(cacheRoot) {
+    const path = join(cacheRoot, SELF_HEAL_STATE_FILENAME);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8").trim();
+        if (raw.length === 0)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        const stamp = parsed.last_reconcile_at;
+        if (typeof stamp !== "string")
+            return null;
+        const parsedDate = new Date(stamp);
+        return Number.isNaN(parsedDate.getTime()) ? null : parsedDate;
+    }
+    catch {
+        return null;
+    }
+}
+function writeSelfHealState(cacheRoot, when) {
+    const path = join(cacheRoot, SELF_HEAL_STATE_FILENAME);
+    writeFileSync(path, `${JSON.stringify({ last_reconcile_at: when.toISOString() })}\n`, "utf8");
+}
+/** TTL-bounded closed-reconcile for session ritual / triage:welcome self-healing (#1886). */
+export function maybeSelfHealCache(projectRoot, options = {}) {
+    const source = options.source ?? "github-issue";
+    const cacheRoot = options.cacheRoot ?? join(projectRoot, ".deft-cache");
+    const now = options.nowFn?.() ?? new Date();
+    const ttlSeconds = options.ttlSeconds ?? DEFAULT_SELF_HEAL_TTL_SECONDS;
+    const repo = options.repo ?? scanCacheForSingleRepo(cacheRoot, source);
+    if (repo === null) {
+        return { skipped: true, skipReason: "repo-not-resolved", drift: null, refresh: null };
+    }
+    const lastHeal = readSelfHealState(cacheRoot);
+    const ttlExpired = lastHeal === null || now.getTime() - lastHeal.getTime() >= ttlSeconds * 1000;
+    if (!ttlExpired) {
+        return { skipped: true, skipReason: "ttl-fresh-no-drift", drift: null, refresh: null };
+    }
+    const limit = 1000;
+    const listOpen = options.listOpenFn ??
+        ((repo, listLimit) => listOpenIssueNumbers(repo, { limit: listLimit }));
+    let openNumbers;
+    try {
+        openNumbers = listOpen(repo, limit);
+    }
+    catch {
+        return { skipped: true, skipReason: "drift-probe-failed", drift: null, refresh: null };
+    }
+    let drift;
+    try {
+        drift = probeCacheDrift({
+            repo,
+            source,
+            cacheRoot,
+            limit,
+            listOpenFn: () => openNumbers,
+            fetchSingleFn: options.fetchSingleFn,
+            includeContentDrift: false,
+        });
+    }
+    catch {
+        return { skipped: true, skipReason: "drift-probe-failed", drift: null, refresh: null };
+    }
+    const refreshFn = options.refreshFn ??
+        ((opts) => cacheRefreshClosed({
+            source: opts.source,
+            repo: opts.repo,
+            cacheRoot: opts.cacheRoot,
+            openNumbers: opts.openNumbers,
+        }));
+    try {
+        const refresh = refreshFn({ source, repo, cacheRoot, openNumbers });
+        if (options.writeState !== false && refresh.refreshFailed === 0) {
+            writeSelfHealState(cacheRoot, now);
+        }
+        return { skipped: false, skipReason: null, drift, refresh };
+    }
+    catch {
+        return { skipped: true, skipReason: "refresh-failed", drift, refresh: null };
+    }
+}
 //# sourceMappingURL=fetch.js.map

package/dist/cache/main.js

@@ -109,7 +109,7 @@ function cmdGet(args) {
     }
     catch (err) {
         if (err instanceof CacheNotFoundError) {
-            process.stderr.write(`cache:get miss: ${JSON.stringify(err.message)}\n`);
+            process.stderr.write(`cache:get miss: ${err.message}\n`);
             return 1;
         }
         throw err;
@@ -150,7 +150,8 @@ function cmdFetchAll(args) {
     let limit = 1000;
     const labels = [];
     let author;
-    let refreshClosed = false;
+    let skipRefreshClosed = false;
+    let force = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === "--source") {
@@ -189,8 +190,11 @@ function cmdFetchAll(args) {
             author = args[i + 1];
             i += 1;
         }
-        else if (arg === "--refresh-closed") {
-            refreshClosed = true;
+        else if (arg === "--no-refresh-closed") {
+            skipRefreshClosed = true;
+        }
+        else if (arg === "--force" || arg === "--ignore-ttl") {
+            force = true;
         }
     }
     if (!source || !repo) {
@@ -207,10 +211,11 @@ function cmdFetchAll(args) {
         limit,
         labels: normaliseLabelFilter(labels),
         author: author ?? null,
+        force,
     });
     process.stdout.write(`${report.toJson()}\n`);
     let rc = report.issuesFailed === 0 ? 0 : 1;
-    if (refreshClosed) {
+    if (!skipRefreshClosed) {
         const refresh = cacheRefreshClosed({
             source,
             repo,

package/dist/cache/operations.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
+import { pyRepr } from "../scm/py-format.js";
 import { ALLOWED_SOURCES, REPO_RE, SOURCE_TTL_SECONDS } from "./constants.js";
 import { CacheCapBreachedError, CacheError, CacheNotFoundError, CacheValidationError, } from "./errors.js";
 import { appendAudit, atomicWriteText, fileSize, removeEntryDir, touchMtime } from "./io.js";
@@ -183,10 +184,11 @@ export function cacheGet(source, key, options = {}) {
     const cacheRoot = options.cacheRoot ?? ".deft-cache";
     const allowStale = options.allowStale ?? true;
     const edir = entryDir(source, key, cacheRoot);
-    const metaPath = join(edir, "meta.json");
-    if (!existsSync(metaPath)) {
-        throw new CacheNotFoundError(`cache miss for source='${source}' key='${key}' (expected meta.json at ${metaPath})`);
+    const metaRelPath = `${source}/${key}/meta.json`;
+    if (!existsSync(join(edir, "meta.json"))) {
+        throw new CacheNotFoundError(`cache miss for source=${pyRepr(source)} key=${pyRepr(key)} (expected meta.json at ${metaRelPath})`);
     }
+    const metaPath = join(edir, "meta.json");
     let meta;
     try {
         meta = JSON.parse(readFileSync(metaPath, "utf8"));
@@ -199,7 +201,7 @@ export function cacheGet(source, key, options = {}) {
     const expires = parseIso(String(meta.expires_at));
     const isStale = clock.now() > expires;
     if (isStale && !allowStale) {
-        throw new CacheNotFoundError(`cache entry stale for source='${source}' key='${key}'; expires_at=${meta.expires_at} (pass --allow-stale to override)`);
+        throw new CacheNotFoundError(`cache entry stale for source=${pyRepr(source)} key=${pyRepr(key)}; expires_at=${meta.expires_at} (pass --allow-stale to override)`);
     }
     meta.stale = isStale;
     touchMtime(metaPath);

package/dist/deposit/copy-tree.d.ts

@@ -0,0 +1,16 @@
+/**
+ * copy-tree.ts — recursively copy a directory tree with file-mode preservation.
+ *
+ * Mirrors cmd/deft-install/setup.go `copyDir` / `copyFile` (#1477): intermediate
+ * directories are created mode 0o755; files keep their source permission bits
+ * (including the executable bit for hooks and the `run` launcher).
+ *
+ * Refs #1942 S1, #1477.
+ */
+/**
+ * Recursively copy `src` into `dst`, preserving nested structure and file modes.
+ *
+ * The contents of `src` are placed under `dst` (equivalent to Go `copyDir`).
+ */
+export declare function copyTree(src: string, dst: string): Promise<void>;
+//# sourceMappingURL=copy-tree.d.ts.map

package/dist/deposit/copy-tree.js

@@ -0,0 +1,58 @@
+/**
+ * copy-tree.ts — recursively copy a directory tree with file-mode preservation.
+ *
+ * Mirrors cmd/deft-install/setup.go `copyDir` / `copyFile` (#1477): intermediate
+ * directories are created mode 0o755; files keep their source permission bits
+ * (including the executable bit for hooks and the `run` launcher).
+ *
+ * Refs #1942 S1, #1477.
+ */
+import { createReadStream, createWriteStream } from "node:fs";
+import { chmod, mkdir, readdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pipeline } from "node:stream/promises";
+const DEFAULT_FILE_MODE = 0o644;
+const DEFAULT_DIR_MODE = 0o755;
+async function copyFilePreserveMode(src, dst) {
+    let mode = DEFAULT_FILE_MODE;
+    try {
+        const info = await stat(src);
+        mode = info.mode & 0o777;
+    }
+    catch {
+        // Stat failure is non-fatal — fall back to 0o644 (mirrors Go copyFile).
+    }
+    await mkdir(dirname(dst), { recursive: true, mode: DEFAULT_DIR_MODE });
+    await pipeline(createReadStream(src), createWriteStream(dst, { mode }));
+    // createWriteStream mode applies on create; chmod ensures the final bits match
+    // the source even when the destination file already existed.
+    await chmod(dst, mode);
+}
+async function copyDirContents(src, dst) {
+    await mkdir(dst, { recursive: true, mode: DEFAULT_DIR_MODE });
+    const entries = await readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(src, entry.name);
+        const dstPath = join(dst, entry.name);
+        const srcStat = await stat(srcPath);
+        if (srcStat.isDirectory()) {
+            await copyDirContents(srcPath, dstPath);
+        }
+        else {
+            await copyFilePreserveMode(srcPath, dstPath);
+        }
+    }
+}
+/**
+ * Recursively copy `src` into `dst`, preserving nested structure and file modes.
+ *
+ * The contents of `src` are placed under `dst` (equivalent to Go `copyDir`).
+ */
+export async function copyTree(src, dst) {
+    const srcInfo = await stat(src);
+    if (!srcInfo.isDirectory()) {
+        throw new Error(`copyTree: source ${src} is not a directory`);
+    }
+    await copyDirContents(src, dst);
+}
+//# sourceMappingURL=copy-tree.js.map

package/dist/deposit/resolve-content.d.ts

@@ -0,0 +1,28 @@
+/**
+ * resolve-content.ts — resolve the installed @deftai/directive-content package root.
+ *
+ * Used by the TS-native init/update deposit path (#1942 S1) to locate the npm
+ * content package before copying its tree into `.deft/core/`. Mirrors the
+ * package-resolution half of the Go installer's content fetch, but reads from
+ * the local node_modules install instead of a GitHub tarball.
+ *
+ * Refs #1942, #11, #1477.
+ */
+export declare const CONTENT_PACKAGE_NAME = "@deftai/directive-content";
+/** Thrown when {@link resolveInstalledContentRoot} cannot resolve the content package. */
+export declare class ContentPackageNotFoundError extends Error {
+    readonly name = "ContentPackageNotFoundError";
+}
+type ResolveSpecifier = (specifier: string) => Promise<string>;
+/**
+ * Walk upward from `resolvedEntry` until a `package.json` names
+ * {@link CONTENT_PACKAGE_NAME}; returns that directory.
+ */
+export declare function contentPackageRootFromResolvedEntry(resolvedEntry: string): string;
+/**
+ * Resolve the installed {@link CONTENT_PACKAGE_NAME} package root via Node module
+ * resolution (`import.meta.resolve`).
+ */
+export declare function resolveInstalledContentRoot(resolveSpecifier?: ResolveSpecifier): Promise<string>;
+export {};
+//# sourceMappingURL=resolve-content.d.ts.map

package/dist/deposit/resolve-content.js

@@ -0,0 +1,70 @@
+/**
+ * resolve-content.ts — resolve the installed @deftai/directive-content package root.
+ *
+ * Used by the TS-native init/update deposit path (#1942 S1) to locate the npm
+ * content package before copying its tree into `.deft/core/`. Mirrors the
+ * package-resolution half of the Go installer's content fetch, but reads from
+ * the local node_modules install instead of a GitHub tarball.
+ *
+ * Refs #1942, #11, #1477.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const CONTENT_PACKAGE_NAME = "@deftai/directive-content";
+/** Thrown when {@link resolveInstalledContentRoot} cannot resolve the content package. */
+export class ContentPackageNotFoundError extends Error {
+    name = "ContentPackageNotFoundError";
+}
+async function defaultResolveSpecifier(specifier) {
+    return fileURLToPath(await import.meta.resolve(specifier));
+}
+/**
+ * Walk upward from `resolvedEntry` until a `package.json` names
+ * {@link CONTENT_PACKAGE_NAME}; returns that directory.
+ */
+export function contentPackageRootFromResolvedEntry(resolvedEntry) {
+    let dir = statSync(resolvedEntry).isDirectory() ? resolvedEntry : dirname(resolvedEntry);
+    for (;;) {
+        const pkgJsonPath = join(dir, "package.json");
+        try {
+            if (statSync(pkgJsonPath).isFile()) {
+                const parsed = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+                if (typeof parsed === "object" &&
+                    parsed !== null &&
+                    parsed.name === CONTENT_PACKAGE_NAME) {
+                    return dir;
+                }
+            }
+        }
+        catch {
+            // Missing or unreadable package.json — keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    throw new ContentPackageNotFoundError(`Resolved ${CONTENT_PACKAGE_NAME} entry at ${resolvedEntry}, but no matching package root was found. ` +
+        "Reinstall with `pnpm add @deftai/directive-content` or `npm i @deftai/directive-content`.");
+}
+/**
+ * Resolve the installed {@link CONTENT_PACKAGE_NAME} package root via Node module
+ * resolution (`import.meta.resolve`).
+ */
+export async function resolveInstalledContentRoot(resolveSpecifier = defaultResolveSpecifier) {
+    let resolvedEntry;
+    try {
+        resolvedEntry = await resolveSpecifier(CONTENT_PACKAGE_NAME);
+    }
+    catch (cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        throw new ContentPackageNotFoundError(`${CONTENT_PACKAGE_NAME} is not installed or could not be resolved. ` +
+            "Install it with `pnpm add @deftai/directive-content` or `npm i @deftai/directive-content` " +
+            "so init/update can deposit framework content locally. " +
+            `Resolution error: ${detail}`);
+    }
+    return contentPackageRootFromResolvedEntry(resolvedEntry);
+}
+//# sourceMappingURL=resolve-content.js.map

package/dist/doctor/checks.d.ts

@@ -8,6 +8,12 @@ export declare function checkQuickStartResolves(projectRoot: string, installRoot
 export declare function checkSkillPathsResolve(projectRoot: string, agentsMdText: string, seams?: CheckSeams): CheckResult;
 export declare function checkManifestAgreement(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
 export declare function checkInstallPathConsistency(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
+/**
+ * #1912: signpost a legacy on-disk layout. Carries the STABLE UPGRADING.md URL
+ * only -- no baked Go-installer version or literal upgrade command. Returns
+ * `skip` for the canonical / greenfield layout (nothing to signpost).
+ */
+export declare function checkLegacyLayout(projectRoot: string, 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;