@deftai/directive-core 0.55.2 → 0.56.1

package/dist/init-deposit/legacy-detect.js

@@ -0,0 +1,223 @@
+/**
+ * Legacy on-disk layout detection for the npm CLI (#1912 Tier-2).
+ *
+ * The `npx @deftai/directive` CLI is fetched fresh at use-time. Before it
+ * deposits (init) or refreshes (update) the canonical `.deft/core/` vendored
+ * layout, it must detect a LEGACY on-disk layout and REFUSE -- the npm path
+ * never migrates. Stage 1 (the frozen final Go bridge installer) migrates the
+ * old layout; stage 2 (this npm CLI) takes over once the layout is
+ * canonical-vendored.
+ *
+ * Legacy shapes recognized:
+ *  - orphan-deft-version      : `.deft/VERSION` present but `.deft/core/` absent
+ *  - legacy-deft-prefixed     : old `deft/`-prefixed install root
+ *  - git-clone-or-submodule   : framework checked out as a clone / git submodule
+ *  - pre-v0.27-sentinel-agents: pre-v0.27 AGENTS.md without a v2/v3 managed-section
+ *
+ * Reuses the manifest/AGENTS heuristics in ../doctor/manifest.ts -- it does NOT
+ * reinvent them.
+ *
+ * Core principle (locked): never bake the upgrade command/version into the
+ * artifact being upgraded -- bake in a stable pointer resolved fresh. The
+ * refusal therefore signposts a STABLE UPGRADING.md URL, never a baked version.
+ *
+ * Refs #1912, #1669.
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+import { GO_BRIDGE_RELEASES_URL, UPGRADING_DOC_URL } from "../doctor/constants.js";
+import { extractManagedSection, parseInstallRootFromAgentsMd } from "../doctor/manifest.js";
+import { readTextSafe } from "../doctor/paths.js";
+/** Non-zero exit code for a use-time legacy-layout refusal (needs-action). */
+export const LEGACY_LAYOUT_REFUSED_EXIT_CODE = 2;
+const NOT_LEGACY = {
+    legacy: false,
+    kind: null,
+    detail: "Canonical or greenfield layout -- no legacy Deft layout detected.",
+    evidence: [],
+};
+function defaultIsFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function defaultIsDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Does `.gitmodules` reference the deft framework at a deft install path? */
+function gitmodulesReferencesFramework(text) {
+    const normalized = text.replace(/\r\n/g, "\n").toLowerCase();
+    if (normalized.includes("deftai/directive")) {
+        return true;
+    }
+    // A submodule whose path is the framework install dir is a strong signal even
+    // when the url host differs (mirror, fork). Match `path = deft` / `path = .deft`.
+    return /(^|\n)\s*path\s*=\s*\.?deft(\/|\s|$)/.test(normalized);
+}
+/**
+ * Classify the on-disk layout at `projectDir`. Returns `legacy: false` for the
+ * canonical `.deft/core/` vendored layout and for a greenfield project (so init
+ * proceeds); returns `legacy: true` with the matched `kind` for any legacy shape.
+ */
+export function detectLegacyLayout(projectDir, seams = {}) {
+    const isFile = seams.isFile ?? defaultIsFile;
+    const isDir = seams.isDir ?? defaultIsDir;
+    const readText = seams.readText ?? readTextSafe;
+    // Canonical vendored layout present -> the npm path owns it; not legacy. Any
+    // AGENTS.md / manifest drift here is repaired by the healthy refresh path,
+    // not by refusing.
+    if (isDir(join(projectDir, ".deft", "core"))) {
+        return NOT_LEGACY;
+    }
+    // Orphan `.deft/VERSION` (the old pre-`.deft/core/` manifest location) with no
+    // `.deft/core/` directory.
+    if (isFile(join(projectDir, ".deft", "VERSION"))) {
+        return {
+            legacy: true,
+            kind: "orphan-deft-version",
+            detail: "Found an orphan .deft/VERSION manifest with no .deft/core/ directory -- " +
+                "this is a pre-.deft/core/ layout the npm CLI does not migrate.",
+            evidence: [".deft/VERSION"],
+        };
+    }
+    // Legacy `deft/`-prefixed install root: a top-level `deft/` directory carrying
+    // framework markers. Distinguish a git-clone / submodule deposit (a `.git`
+    // inside `deft/`, or a `.gitmodules` pointing at the framework) from a plain
+    // legacy-prefixed vendored copy.
+    const deftDir = join(projectDir, "deft");
+    const deftMarkers = [
+        join(deftDir, "VERSION"),
+        join(deftDir, "main.md"),
+        join(deftDir, "Taskfile.yml"),
+    ];
+    const deftDirIsFramework = isDir(deftDir) && (deftMarkers.some((m) => isFile(m)) || isDir(join(deftDir, "skills")));
+    if (deftDirIsFramework) {
+        const submoduleGit = isFile(join(deftDir, ".git")) || isDir(join(deftDir, ".git"));
+        if (submoduleGit) {
+            return {
+                legacy: true,
+                kind: "git-clone-or-submodule",
+                detail: "Found a deft/ framework directory backed by its own .git (clone or " +
+                    "git submodule) -- the npm CLI does not migrate a clone/submodule deposit.",
+                evidence: ["deft/", "deft/.git"],
+            };
+        }
+        return {
+            legacy: true,
+            kind: "legacy-deft-prefixed",
+            detail: "Found a legacy deft/-prefixed framework install -- the canonical layout " +
+                "is .deft/core/. The npm CLI does not migrate the deft/ -> .deft/core/ move.",
+            evidence: ["deft/"],
+        };
+    }
+    // Git submodule recorded in `.gitmodules` pointing at the framework, even when
+    // the submodule directory has not been checked out.
+    const gitmodulesPath = join(projectDir, ".gitmodules");
+    if (isFile(gitmodulesPath)) {
+        const text = readText(gitmodulesPath);
+        if (text !== null && gitmodulesReferencesFramework(text)) {
+            return {
+                legacy: true,
+                kind: "git-clone-or-submodule",
+                detail: "Found a .gitmodules entry referencing the Deft framework -- a submodule " +
+                    "deposit the npm CLI does not migrate.",
+                evidence: [".gitmodules"],
+            };
+        }
+    }
+    // Pre-v0.27 AGENTS.md: deft-managed but missing a v2/v3 managed-section, or
+    // declaring the legacy `deft/` install root.
+    const agentsText = readText(join(projectDir, "AGENTS.md"));
+    if (agentsText !== null) {
+        const installRoot = parseInstallRootFromAgentsMd(agentsText);
+        if (installRoot === "deft") {
+            return {
+                legacy: true,
+                kind: "legacy-deft-prefixed",
+                detail: "AGENTS.md declares the legacy deft/ install root -- the canonical layout " +
+                    "is .deft/core/. The npm CLI does not migrate the deft/ -> .deft/core/ move.",
+                evidence: ["AGENTS.md (install root: deft)"],
+            };
+        }
+        // Match the OPEN tag only (`<!-- deft:managed-section ...`). A bare
+        // `deft:managed-section` substring also appears in the close tag
+        // (`<!-- /deft:managed-section -->`), so a truncated / mid-write AGENTS.md
+        // carrying only the close tag (or an open tag with no extractable body)
+        // would otherwise be misclassified as a pre-v0.27 legacy layout.
+        const hasManagedMarker = agentsText.includes("<!-- deft:managed-section");
+        if (hasManagedMarker && extractManagedSection(agentsText) === null) {
+            return {
+                legacy: true,
+                kind: "pre-v0.27-sentinel-agents-md",
+                detail: "AGENTS.md carries a pre-v0.27 sentinel-only managed-section (no v2/v3 " +
+                    "managed-section markers) -- run the Go bridge to migrate before the npm CLI.",
+                evidence: ["AGENTS.md (sentinel-only managed-section)"],
+            };
+        }
+    }
+    return NOT_LEGACY;
+}
+/** Thrown by the deposit/refresh core path when a legacy layout is detected. */
+export class LegacyLayoutRefusedError extends Error {
+    detection;
+    constructor(detection) {
+        super(detection.detail);
+        this.name = "LegacyLayoutRefusedError";
+        this.detection = detection;
+    }
+}
+/**
+ * Build the human-facing two-step recovery message. Version-neutral: it
+ * signposts the stable UPGRADING.md doc + the frozen-bridge releases page and
+ * NEVER bakes a Go-installer version or a literal upgrade command.
+ */
+export function buildLegacyRefusalMessage(command, detection) {
+    const rerun = `npx @deftai/directive ${command}`;
+    return (`directive ${command}: refusing to ${command === "init" ? "deposit" : "refresh"} -- ` +
+        "a LEGACY Deft layout was detected.\n\n" +
+        `  Detected: ${detection.detail}` +
+        (detection.kind ? ` (${detection.kind})` : "") +
+        "\n\n" +
+        "The npm CLI does not migrate legacy layouts. Recover in two steps:\n\n" +
+        "  1. Run the frozen final Go bridge installer to migrate this layout to the\n" +
+        "     canonical .deft/core/ vendored layout. The binaries + exact command are\n" +
+        "     documented (version-neutral) at:\n" +
+        `       ${UPGRADING_DOC_URL}\n` +
+        `     Frozen Go bridge releases: ${GO_BRIDGE_RELEASES_URL}\n` +
+        `  2. Re-run \`${rerun}\` once the layout is canonical-vendored.\n\n` +
+        "Why a pointer, not a command: never bake the upgrade command/version into the\n" +
+        "artifact being upgraded -- the links above resolve the current bridge fresh.\n");
+}
+/** Build the machine-readable refusal payload for `--json` callers. */
+export function buildLegacyRefusalJson(command, projectDir, detection) {
+    return {
+        success: false,
+        action: "refuse",
+        refused: true,
+        error_code: "legacy_layout_refused",
+        command,
+        project_dir: projectDir,
+        legacy_layout: true,
+        legacy_layout_kind: detection.kind,
+        detail: detection.detail,
+        evidence: [...detection.evidence],
+        upgrading_doc_url: UPGRADING_DOC_URL,
+        go_bridge_releases_url: GO_BRIDGE_RELEASES_URL,
+    };
+}
+/** One-line doctor signpost carrying the stable URL (no baked version/command). */
+export function legacyLayoutSignpostLine(detection) {
+    return (`Legacy Deft layout detected (${detection.kind ?? "unknown"}): ${detection.detail} ` +
+        "Run the frozen Go bridge installer to migrate to .deft/core/, then use the npm " +
+        `CLI (\`npx @deftai/directive update\`). See ${UPGRADING_DOC_URL} ` +
+        `(frozen bridge: ${GO_BRIDGE_RELEASES_URL}).`);
+}
+//# sourceMappingURL=legacy-detect.js.map

package/dist/init-deposit/migrate.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Stage-2 provenance migration (#1941): stamp a canonical-vendored `.deft/core`
+ * deposit as npm-managed so the npm channel + `directive update` own the payload.
+ *
+ * This is a THIN provenance verb (locked decision F): the on-disk shape is
+ * UNCHANGED. It never normalizes legacy layouts (stage-1 frozen Go guarantees
+ * canonical-vendored input), never moves/renames/trims `.deft/core` content, and
+ * NEVER downloads a payload (#1933 never-first-start decree).
+ *
+ * Flow:
+ *   1. Detect a canonical-vendored `.deft/core/VERSION` deposit (reuse the
+ *      manifest locator in doctor/manifest.ts).
+ *   2. Idempotency: if the manifest already carries the npm-managed handshake
+ *      sentinel (`managed_by: 'npm'`), make zero changes (already-hybrid).
+ *   3. Engine-resolve check: verify the global engine resolves via
+ *      content-root.ts `resolveContentPackageRoot`. If absent, signpost the
+ *      README and return needs-action -- NEVER install/download.
+ *   4. Stamp the sentinel into the manifest, writing a timestamped backup first.
+ *
+ * Three-state result:
+ *   - exitCode 0: migrated OR already-hybrid
+ *   - exitCode 1: needs action (engine missing -> README signpost)
+ *   - exitCode 2: config error (no canonical-vendored deposit / unreadable manifest)
+ *
+ * Refs #1941, #1912 (freeze prerequisite b), #1933 (never-first-start), #1670.
+ */
+/**
+ * The npm-managed handshake sentinel. `directive migrate` adds this key/value to
+ * the install manifest (`.deft/core/VERSION`) to mark the deposit as owned by the
+ * npm content channel. `doctor` (parseInstallManifest reads every colon
+ * key/value line) and future `directive update` recognize it; its presence is
+ * also the idempotency signal that the deposit is already hybrid.
+ */
+export declare const NPM_MANAGED_SENTINEL_KEY = "managed_by";
+export declare const NPM_MANAGED_SENTINEL_VALUE = "npm";
+/** The npm package the README tells operators to install for the engine. */
+export declare const ENGINE_PACKAGE_NAME = "@deftai/directive";
+export type MigrateOutcome = "migrated" | "already-hybrid" | "engine-missing" | "no-deposit" | "manifest-unreadable";
+export interface MigrateResult {
+    readonly outcome: MigrateOutcome;
+    readonly exitCode: 0 | 1 | 2;
+    readonly manifestPath: string | null;
+    readonly backupPath: string | null;
+    readonly sentinelKey: string;
+    readonly message: string;
+}
+export interface MigrateSeams {
+    /** Existence probe (default: node:fs existsSync). */
+    isFile?: (path: string) => boolean;
+    /** Text read returning null on failure (default: node:fs readFileSync, utf8). */
+    readText?: (path: string) => string | null;
+    /** Text write (default: node:fs writeFileSync, utf8). */
+    writeText?: (path: string, text: string) => void;
+    /** ISO-8601 UTC timestamp source for the backup filename (default: Date.now). */
+    nowIso?: () => string;
+    /** Engine-resolve check; returns the resolved content package root or null. */
+    resolveEngine?: () => string | null;
+}
+/**
+ * Locate the canonical-vendored install manifest (`.deft/core/VERSION`).
+ * Returns the path only when the canonical install-root manifest is present;
+ * legacy `.deft/VERSION` / `deft/VERSION` layouts are intentionally NOT
+ * normalized here (stage-1 guarantees canonical-vendored input).
+ */
+export declare function detectCanonicalVendoredManifest(projectRoot: string, isFile?: (path: string) => boolean): string | null;
+/** True when the manifest already carries the npm-managed handshake sentinel. */
+export declare function isNpmManaged(manifest: Record<string, string>): boolean;
+/** Append the npm-managed sentinel line to existing manifest text. */
+export declare function stampManifestText(text: string): string;
+/**
+ * Orchestrate the stage-2 provenance migration for `projectRoot`. Pure of
+ * process exit; the caller maps {@link MigrateResult.exitCode} to a process code.
+ */
+export declare function runMigrate(projectRoot: string, seams?: MigrateSeams): MigrateResult;
+export interface RunMigrateCliOptions {
+    readonly projectDir: string;
+    readonly jsonOut: boolean;
+    readonly writeOut: (text: string) => void;
+    readonly writeErr: (text: string) => void;
+    readonly seams?: MigrateSeams;
+}
+/**
+ * CLI-facing wrapper: runs the migration, emits JSON or human output, maps the
+ * outcome to a 0/1/2 exit code. Engine-missing prints the README signpost to
+ * stderr; config errors print to stderr; success prints to stdout.
+ */
+export declare function runMigrateCli(options: RunMigrateCliOptions): number;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/init-deposit/migrate.js

@@ -0,0 +1,196 @@
+/**
+ * Stage-2 provenance migration (#1941): stamp a canonical-vendored `.deft/core`
+ * deposit as npm-managed so the npm channel + `directive update` own the payload.
+ *
+ * This is a THIN provenance verb (locked decision F): the on-disk shape is
+ * UNCHANGED. It never normalizes legacy layouts (stage-1 frozen Go guarantees
+ * canonical-vendored input), never moves/renames/trims `.deft/core` content, and
+ * NEVER downloads a payload (#1933 never-first-start decree).
+ *
+ * Flow:
+ *   1. Detect a canonical-vendored `.deft/core/VERSION` deposit (reuse the
+ *      manifest locator in doctor/manifest.ts).
+ *   2. Idempotency: if the manifest already carries the npm-managed handshake
+ *      sentinel (`managed_by: 'npm'`), make zero changes (already-hybrid).
+ *   3. Engine-resolve check: verify the global engine resolves via
+ *      content-root.ts `resolveContentPackageRoot`. If absent, signpost the
+ *      README and return needs-action -- NEVER install/download.
+ *   4. Stamp the sentinel into the manifest, writing a timestamped backup first.
+ *
+ * Three-state result:
+ *   - exitCode 0: migrated OR already-hybrid
+ *   - exitCode 1: needs action (engine missing -> README signpost)
+ *   - exitCode 2: config error (no canonical-vendored deposit / unreadable manifest)
+ *
+ * Refs #1941, #1912 (freeze prerequisite b), #1933 (never-first-start), #1670.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveContentPackageRoot } from "../content-root.js";
+import { locateManifest, parseInstallManifest } from "../doctor/manifest.js";
+import { CANONICAL_INSTALL_ROOT } from "./scaffold.js";
+/**
+ * The npm-managed handshake sentinel. `directive migrate` adds this key/value to
+ * the install manifest (`.deft/core/VERSION`) to mark the deposit as owned by the
+ * npm content channel. `doctor` (parseInstallManifest reads every colon
+ * key/value line) and future `directive update` recognize it; its presence is
+ * also the idempotency signal that the deposit is already hybrid.
+ */
+export const NPM_MANAGED_SENTINEL_KEY = "managed_by";
+export const NPM_MANAGED_SENTINEL_VALUE = "npm";
+/** The npm package the README tells operators to install for the engine. */
+export const ENGINE_PACKAGE_NAME = "@deftai/directive";
+function defaultReadText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function migrateModuleDir() {
+    return dirname(fileURLToPath(import.meta.url));
+}
+/**
+ * Default engine-resolve check: walk up from this module's own install location
+ * (a globally-installed engine has the `@deftai/directive-content` package as a
+ * sibling in the same node_modules) and return the resolved content package
+ * root, or null when the engine does not resolve.
+ */
+function defaultResolveEngine() {
+    return resolveContentPackageRoot(migrateModuleDir());
+}
+/** Filesystem-safe rendering of an ISO-8601 timestamp for a backup suffix. */
+function backupSuffix(nowIso) {
+    return nowIso.replace(/:/g, "-");
+}
+/**
+ * Locate the canonical-vendored install manifest (`.deft/core/VERSION`).
+ * Returns the path only when the canonical install-root manifest is present;
+ * legacy `.deft/VERSION` / `deft/VERSION` layouts are intentionally NOT
+ * normalized here (stage-1 guarantees canonical-vendored input).
+ */
+export function detectCanonicalVendoredManifest(projectRoot, isFile = existsSync) {
+    const canonical = join(projectRoot, CANONICAL_INSTALL_ROOT, "VERSION");
+    const located = locateManifest(projectRoot, CANONICAL_INSTALL_ROOT, isFile);
+    return located === canonical ? located : null;
+}
+/** True when the manifest already carries the npm-managed handshake sentinel. */
+export function isNpmManaged(manifest) {
+    return manifest[NPM_MANAGED_SENTINEL_KEY] === NPM_MANAGED_SENTINEL_VALUE;
+}
+/** Append the npm-managed sentinel line to existing manifest text. */
+export function stampManifestText(text) {
+    const base = text.endsWith("\n") || text.length === 0 ? text : `${text}\n`;
+    return `${base}${NPM_MANAGED_SENTINEL_KEY}: '${NPM_MANAGED_SENTINEL_VALUE}'\n`;
+}
+function engineMissingMessage() {
+    return (`directive migrate: the global Deft engine (${ENGINE_PACKAGE_NAME}) does not resolve.\n` +
+        "Install it first, then re-run migrate:\n\n" +
+        `  npm i -g ${ENGINE_PACKAGE_NAME}\n\n` +
+        "See the README (Install / Upgrade) for details. migrate never installs or " +
+        "downloads payload on your behalf (#1933).");
+}
+/**
+ * Orchestrate the stage-2 provenance migration for `projectRoot`. Pure of
+ * process exit; the caller maps {@link MigrateResult.exitCode} to a process code.
+ */
+export function runMigrate(projectRoot, seams = {}) {
+    const isFile = seams.isFile ?? existsSync;
+    const readText = seams.readText ?? defaultReadText;
+    const writeText = seams.writeText ?? ((path, text) => writeFileSync(path, text, "utf8"));
+    const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
+    const resolveEngine = seams.resolveEngine ?? defaultResolveEngine;
+    const manifestPath = detectCanonicalVendoredManifest(projectRoot, isFile);
+    if (manifestPath === null) {
+        return {
+            outcome: "no-deposit",
+            exitCode: 2,
+            manifestPath: null,
+            backupPath: null,
+            sentinelKey: NPM_MANAGED_SENTINEL_KEY,
+            message: `directive migrate: no canonical-vendored ${CANONICAL_INSTALL_ROOT}/VERSION deposit found under ${projectRoot}. Nothing to migrate.`,
+        };
+    }
+    const text = readText(manifestPath);
+    // `parseInstallManifest` always returns a record (never null), so the only
+    // unreadable/empty cases are a failed read or a manifest with no key/value
+    // lines; both map to the same config error.
+    const manifest = text === null ? {} : parseInstallManifest(text);
+    if (text === null || Object.keys(manifest).length === 0) {
+        return {
+            outcome: "manifest-unreadable",
+            exitCode: 2,
+            manifestPath,
+            backupPath: null,
+            sentinelKey: NPM_MANAGED_SENTINEL_KEY,
+            message: `directive migrate: install manifest at ${manifestPath} is empty or unreadable.`,
+        };
+    }
+    if (isNpmManaged(manifest)) {
+        return {
+            outcome: "already-hybrid",
+            exitCode: 0,
+            manifestPath,
+            backupPath: null,
+            sentinelKey: NPM_MANAGED_SENTINEL_KEY,
+            message: `directive migrate: ${manifestPath} is already npm-managed (already hybrid) -- no change.`,
+        };
+    }
+    if (resolveEngine() === null) {
+        return {
+            outcome: "engine-missing",
+            exitCode: 1,
+            manifestPath,
+            backupPath: null,
+            sentinelKey: NPM_MANAGED_SENTINEL_KEY,
+            message: engineMissingMessage(),
+        };
+    }
+    const backupPath = `${manifestPath}.bak.${backupSuffix(nowIso())}`;
+    writeText(backupPath, text);
+    writeText(manifestPath, stampManifestText(text));
+    return {
+        outcome: "migrated",
+        exitCode: 0,
+        manifestPath,
+        backupPath,
+        sentinelKey: NPM_MANAGED_SENTINEL_KEY,
+        message: `directive migrate: stamped ${manifestPath} npm-managed (${NPM_MANAGED_SENTINEL_KEY}: '${NPM_MANAGED_SENTINEL_VALUE}'); backup written to ${backupPath}.`,
+    };
+}
+function buildMigrateSummaryJson(result, projectDir) {
+    return {
+        success: result.exitCode === 0,
+        action: "migrate",
+        outcome: result.outcome,
+        exit_code: result.exitCode,
+        project_dir: projectDir,
+        manifest_path: result.manifestPath,
+        backup_path: result.backupPath,
+        sentinel_key: result.sentinelKey,
+        sentinel_value: NPM_MANAGED_SENTINEL_VALUE,
+        message: result.message,
+    };
+}
+/**
+ * CLI-facing wrapper: runs the migration, emits JSON or human output, maps the
+ * outcome to a 0/1/2 exit code. Engine-missing prints the README signpost to
+ * stderr; config errors print to stderr; success prints to stdout.
+ */
+export function runMigrateCli(options) {
+    const result = runMigrate(options.projectDir, options.seams);
+    if (options.jsonOut) {
+        options.writeOut(`${JSON.stringify(buildMigrateSummaryJson(result, options.projectDir), null, 2)}\n`);
+        return result.exitCode;
+    }
+    if (result.exitCode === 0) {
+        options.writeOut(`${result.message}\n`);
+    }
+    else {
+        options.writeErr(`${result.message}\n`);
+    }
+    return result.exitCode;
+}
+//# sourceMappingURL=migrate.js.map

package/dist/init-deposit/refresh.d.ts

@@ -0,0 +1,50 @@
+/**
+ * TS-native healthy-path refresh for `directive update` (#1942 S3).
+ *
+ * Re-copies the pinned @deftai/directive-content into `.deft/core`, surgically
+ * re-renders the AGENTS.md managed-section, runs #1430 neutralization, and
+ * discloses refresh side-effects + engine/content version skew.
+ *
+ * Refs #1942, #1430, #1671.
+ */
+import { type InitDepositArgs } from "./init-deposit.js";
+import { type LegacyLayoutDetection } from "./legacy-detect.js";
+import { type InitDepositIo } from "./scaffold.js";
+export interface RefreshDepositArgs extends InitDepositArgs {
+    readonly upgrade: boolean;
+}
+export interface RefreshDepositResult {
+    readonly projectDir: string;
+    readonly deftDir: string;
+    readonly contentVersion: string;
+    readonly engineVersion: string;
+    readonly previousDepositVersion: string | null;
+    readonly agentsMdUpdated: boolean;
+    readonly versionSkewNotice: string | null;
+    readonly legacyLayout: boolean;
+}
+export interface RefreshDepositSeams {
+    resolveContentRoot?: () => Promise<string>;
+    copyContent?: (src: string, dst: string) => Promise<void>;
+    readPackageVersion?: () => string;
+    readEngineVersion?: () => string;
+    nowIso?: () => string;
+    gitPorcelain?: (projectRoot: string) => string | null;
+    detectLegacy?: (projectDir: string) => LegacyLayoutDetection;
+}
+/** Framework-managed uncommitted paths after refresh (#1671). */
+export declare function frameworkRefreshSideEffects(projectDir: string, readPorcelain?: (root: string) => string | null): string[];
+export declare function printRefreshSideEffects(io: InitDepositIo, files: readonly string[]): void;
+export declare function buildVersionSkewNotice(engineVersion: string, contentVersion: string, previousDepositVersion: string | null): string | null;
+export declare function buildUpdateSummaryJson(result: RefreshDepositResult, options: RefreshDepositArgs): Record<string, unknown>;
+export declare function printUpdateComplete(result: RefreshDepositResult, io: InitDepositIo): void;
+export declare function runRefreshDeposit(args: RefreshDepositArgs, io: InitDepositIo, seams?: RefreshDepositSeams): Promise<RefreshDepositResult>;
+export interface RunRefreshDepositCliOptions extends RefreshDepositArgs {
+    readonly writeOut: (text: string) => void;
+    readonly writeErr: (text: string) => void;
+    readonly seams?: RefreshDepositSeams;
+}
+/** CLI-facing wrapper: runs refresh, emits JSON or wizard UX, returns exit code. */
+export declare function runRefreshDepositCli(options: RunRefreshDepositCliOptions): Promise<number>;
+export declare function parseUpdateArgv(canonicalArgv: readonly string[], userArgv?: readonly string[]): RefreshDepositArgs;
+//# sourceMappingURL=refresh.d.ts.map