@deftai/directive-core 0.68.1 → 0.69.0

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

@@ -43,6 +43,24 @@ export declare function resolveInitGitignoreLines(projectDir: string, gitLsFiles
 export declare function ensureInitGitignoreLines(projectDir: string, io: InitDepositIo, options?: {
     gitLsFiles?: GitLsFiles;
 }): EnsureInitGitignoreResult;
+/**
+ * The reconciled ignore set for the vendored→hybrid un-commit (#2269): the
+ * canonical baseline (which already covers `.deft/.cli/`, `.deft/ritual-state.json`,
+ * and the `.deft-cache/` path) plus the `.deft/core/` deposit entry that
+ * greenfield init born-ignores. `package.json` is deliberately absent — the
+ * committed pin MUST stay tracked so content can be reconstituted after the
+ * deposit is un-committed.
+ */
+export declare const UNTRACK_CORE_GITIGNORE_LINES: readonly string[];
+/**
+ * Reconcile `.gitignore` for the `migrate --untrack-core` path: force the
+ * `.deft/core/` deposit entry (init leaves a tracked deposit alone, but
+ * un-track has just removed it from the index, so it MUST now be ignored) plus
+ * the canonical baseline, and never ignore the committed `package.json` pin.
+ * Idempotent: a second run over an already-reconciled `.gitignore` makes no
+ * change.
+ */
+export declare function ensureUntrackCoreGitignoreLines(projectDir: string, io: InitDepositIo): EnsureInitGitignoreResult;
 /**
  * Copy the content package into `.deft/core`, reporting whether the deposit was
  * absent before copy (reconstitution). Always refreshes when present.

package/dist/init-deposit/gitignore.js

@@ -22,6 +22,7 @@ const DEFT_CORE_COVERING_LINES = new Set([".deft/core/", ".deft/core"]);
  */
 export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft-cache/",
+    ".deft/.cli/",
     ".deft/ritual-state.json",
     ".deft/last-session.json",
     ".deft/routing.local.json",
@@ -95,14 +96,20 @@ export function resolveInitGitignoreLines(projectDir, gitLsFiles = defaultGitLsF
     };
 }
 /**
- * Ensure the consumer `.gitignore` carries the canonical baseline plus, for
- * greenfield installs, the `.deft/core/` ignore entry. Heals forbidden blanket
- * `vbrief/.eval/` lines (#1464). Never un-commits a tracked deposit (#1941).
+ * Ignore entries the deft framework MUST NEVER add to `.gitignore`. The
+ * committed `package.json` pin (#2264) is the reconstitution anchor for the
+ * un-committed deposit; ignoring it would silently drop the pin from version
+ * control and break `migrate --untrack-core`'s reconstitution guarantee (#2269).
  */
-export function ensureInitGitignoreLines(projectDir, io, options = {}) {
-    const gitLsFiles = options.gitLsFiles ?? defaultGitLsFiles;
-    const { lines: targetLines, includeDeftCore } = resolveInitGitignoreLines(projectDir, gitLsFiles);
-    const tracked = isDepositTrackedInGit(projectDir, gitLsFiles);
+const NEVER_IGNORE_LINES = new Set(["package.json", "/package.json"]);
+/**
+ * Read, heal, and reconcile `.gitignore` against `targetLines`. Shared by the
+ * greenfield-init and the vendored→hybrid un-commit reconcilers so the
+ * read/heal/append/write path lives in exactly one place. Pure of any caller
+ * messaging — the callers decide what to print from the returned record. The
+ * `package.json` pin is filtered out unconditionally (#2269 invariant).
+ */
+function reconcileGitignoreFile(projectDir, targetLines, includeDeftCoreRationale) {
     const path = join(projectDir, ".gitignore");
     let existing = "";
     if (existsSync(path)) {
@@ -134,16 +141,20 @@ export function ensureInitGitignoreLines(projectDir, io, options = {}) {
     }
     const additions = [];
     for (const line of targetLines) {
+        // Invariant (#2269): never ignore the committed package.json pin.
+        if (NEVER_IGNORE_LINES.has(line.trim()))
+            continue;
         if (!gitignoreCoversLine(present, line)) {
             additions.push(line);
         }
     }
     if (!blanketRemoved && additions.length === 0) {
-        io.printf(".gitignore already covers the canonical deft entries — skipping.\n");
         return {
             changed: false,
+            additions,
+            blanketRemoved,
             deftCoreIgnored: gitignoreCoversLine(present, GITIGNORE_DEFT_CORE_LINE),
-            skippedDeftCoreBecauseTracked: tracked === true,
+            alreadyCovered: true,
         };
     }
     let healed = kept.join("\n");
@@ -159,7 +170,7 @@ export function ensureInitGitignoreLines(projectDir, io, options = {}) {
             body += "\n";
         }
         body += DEFT_FRAMEWORK_GITIGNORE_HEADER;
-        if (includeDeftCore && additions.includes(GITIGNORE_DEFT_CORE_LINE)) {
+        if (includeDeftCoreRationale && additions.includes(GITIGNORE_DEFT_CORE_LINE)) {
             body += DEFT_CORE_GITIGNORE_RATIONALE;
         }
         for (const add of additions) {
@@ -172,22 +183,90 @@ export function ensureInitGitignoreLines(projectDir, io, options = {}) {
     catch (cause) {
         throw new Error(`could not write .gitignore: ${String(cause)}`);
     }
-    if (additions.length > 0) {
-        io.printf(`.gitignore updated with canonical entries: ${additions.join(", ")}\n`);
+    const finalPresent = collectPresentGitignoreLines(body);
+    return {
+        changed: true,
+        additions,
+        blanketRemoved,
+        deftCoreIgnored: gitignoreCoversLine(finalPresent, GITIGNORE_DEFT_CORE_LINE),
+        alreadyCovered: false,
+    };
+}
+/**
+ * Ensure the consumer `.gitignore` carries the canonical baseline plus, for
+ * greenfield installs, the `.deft/core/` ignore entry. Heals forbidden blanket
+ * `vbrief/.eval/` lines (#1464). Never un-commits a tracked deposit (#1941).
+ */
+export function ensureInitGitignoreLines(projectDir, io, options = {}) {
+    const gitLsFiles = options.gitLsFiles ?? defaultGitLsFiles;
+    const { lines: targetLines, includeDeftCore } = resolveInitGitignoreLines(projectDir, gitLsFiles);
+    const tracked = isDepositTrackedInGit(projectDir, gitLsFiles);
+    const res = reconcileGitignoreFile(projectDir, targetLines, includeDeftCore);
+    if (res.alreadyCovered) {
+        io.printf(".gitignore already covers the canonical deft entries — skipping.\n");
+        return {
+            changed: false,
+            deftCoreIgnored: res.deftCoreIgnored,
+            skippedDeftCoreBecauseTracked: tracked === true,
+        };
     }
-    if (blanketRemoved) {
+    if (res.additions.length > 0) {
+        io.printf(`.gitignore updated with canonical entries: ${res.additions.join(", ")}\n`);
+    }
+    if (res.blanketRemoved) {
         io.printf(".gitignore healed: removed forbidden blanket vbrief/.eval/ line (#1464).\n");
     }
     if (tracked === true) {
         io.printf(".deft/core is tracked in git — leaving it tracked; vendored→hybrid un-commit is #1941.\n");
     }
-    const finalPresent = collectPresentGitignoreLines(body);
     return {
         changed: true,
-        deftCoreIgnored: gitignoreCoversLine(finalPresent, GITIGNORE_DEFT_CORE_LINE),
+        deftCoreIgnored: res.deftCoreIgnored,
         skippedDeftCoreBecauseTracked: tracked === true,
     };
 }
+/**
+ * The reconciled ignore set for the vendored→hybrid un-commit (#2269): the
+ * canonical baseline (which already covers `.deft/.cli/`, `.deft/ritual-state.json`,
+ * and the `.deft-cache/` path) plus the `.deft/core/` deposit entry that
+ * greenfield init born-ignores. `package.json` is deliberately absent — the
+ * committed pin MUST stay tracked so content can be reconstituted after the
+ * deposit is un-committed.
+ */
+export const UNTRACK_CORE_GITIGNORE_LINES = [
+    ...CANONICAL_GITIGNORE_BASELINE,
+    GITIGNORE_DEFT_CORE_LINE,
+];
+/**
+ * Reconcile `.gitignore` for the `migrate --untrack-core` path: force the
+ * `.deft/core/` deposit entry (init leaves a tracked deposit alone, but
+ * un-track has just removed it from the index, so it MUST now be ignored) plus
+ * the canonical baseline, and never ignore the committed `package.json` pin.
+ * Idempotent: a second run over an already-reconciled `.gitignore` makes no
+ * change.
+ */
+export function ensureUntrackCoreGitignoreLines(projectDir, io) {
+    const res = reconcileGitignoreFile(projectDir, UNTRACK_CORE_GITIGNORE_LINES, false);
+    if (res.alreadyCovered) {
+        io.printf(".gitignore already ignores .deft/core/ and the canonical deft entries — skipping.\n");
+        return {
+            changed: false,
+            deftCoreIgnored: res.deftCoreIgnored,
+            skippedDeftCoreBecauseTracked: false,
+        };
+    }
+    if (res.additions.length > 0) {
+        io.printf(`.gitignore updated with canonical entries: ${res.additions.join(", ")}\n`);
+    }
+    if (res.blanketRemoved) {
+        io.printf(".gitignore healed: removed forbidden blanket vbrief/.eval/ line (#1464).\n");
+    }
+    return {
+        changed: true,
+        deftCoreIgnored: res.deftCoreIgnored,
+        skippedDeftCoreBecauseTracked: false,
+    };
+}
 /**
  * Copy the content package into `.deft/core`, reporting whether the deposit was
  * absent before copy (reconstitution). Always refreshes when present.

package/dist/init-deposit/headless-manifest.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `directive init --headless` — manifest emitter for no-shell consumer products
+ * (#2268 / epic #2203).
+ *
+ * Hosted consumer products (e.g. deftai/deftvisage#1036) have no shell or npm
+ * access to the end user's machine. This module serialises the merged keystone
+ * `plan()` schema into a `{ version, files: [{ path, content, encoding }] }`
+ * manifest with ALL execution side effects suppressed: no interactive prompts,
+ * no git operations, no git-hook installation, and no filesystem writes outside
+ * the explicit `--output` target. It makes no git-repo assumption and runs
+ * against an empty / non-existent directory.
+ *
+ * Single-sourcing (the #2268 acceptance): the manifest is DERIVED from `plan()`
+ * — the collected file set is threaded through `plan(..., { files })` and read
+ * back out of {@link ResolutionPlan.files}. There is no separate "what would
+ * init produce" reimplementation; the collectors here are the manifest-only,
+ * read-only counterparts of the executing deposit path in `scaffold.ts` /
+ * `init-deposit.ts` (they reuse the same render helpers WITHOUT filesystem or
+ * git writes).
+ *
+ * On registry / content-resolution failure the CLI wrapper exits non-zero and
+ * emits a JSON error object so the calling backend can treat it as non-fatal
+ * (never a crash or a partial write).
+ */
+import type { ResolutionFile } from "@deftai/directive-types";
+/** The five xBRIEF lifecycle folders scaffolded into a fresh project. */
+export declare const HEADLESS_XBRIEF_LIFECYCLE_DIRS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+/** A single file entry in the headless manifest. */
+export type HeadlessManifestFile = ResolutionFile;
+/** The serialised headless manifest shape. */
+export interface HeadlessManifest {
+    /** Resolved framework version the manifest was built against. */
+    readonly version: string;
+    /** All files a consumer backend should materialise for a fresh install. */
+    readonly files: readonly HeadlessManifestFile[];
+}
+/**
+ * JSON error object emitted on a registry / content-resolution failure. The
+ * calling backend treats a non-zero exit + this object as non-fatal.
+ */
+export interface HeadlessManifestErrorObject {
+    readonly success: false;
+    readonly error: string;
+    readonly error_code: string;
+}
+/** Injectable seams; defaults are the real content-package resolution path. */
+export interface HeadlessManifestSeams {
+    /** Resolve the installed content-package root. Default: real npm resolution. */
+    readonly resolveContentRoot?: () => Promise<string>;
+    /** Override the resolved version (default: read the content package.json). */
+    readonly readVersion?: (contentRoot: string) => string;
+    /** Deterministic UTC ISO timestamp for the VERSION marker (default: now). */
+    readonly nowIso?: () => string;
+    /** Deterministic managed-section session id (default: fixed headless token). */
+    readonly newSession?: () => string;
+}
+/**
+ * Build the headless manifest. Reads the content package read-only, collects
+ * the fresh-install file set (payload + version-consistent AGENTS.md + xBRIEF
+ * scaffold + pinned package.json), threads it through `plan()` so the manifest
+ * is single-sourced from the resolution schema, and returns the serialisable
+ * shape. Performs NO filesystem writes and NO git operations.
+ *
+ * Throws (never partially writes) on content-resolution failure; the CLI
+ * wrapper converts the throw into a JSON error object + non-zero exit.
+ */
+export declare function buildHeadlessManifest(seams?: HeadlessManifestSeams): Promise<HeadlessManifest>;
+export interface RunInitHeadlessCliOptions {
+    /** Explicit `--output` target, or null to emit the manifest to stdout. */
+    readonly outputPath: string | null;
+    readonly writeOut: (text: string) => void;
+    readonly writeErr: (text: string) => void;
+    readonly seams?: HeadlessManifestSeams;
+    /**
+     * Filesystem write seam (test-only). The default creates the parent directory
+     * and writes the file; an injected seam OWNS all filesystem contact (including
+     * directory creation), so the manifest write stays fully isolatable in tests.
+     */
+    readonly writeFile?: (path: string, data: string) => void;
+}
+/**
+ * CLI-facing entrypoint for `directive init --headless`. Emits the manifest to
+ * `--output` (the ONLY permitted filesystem write) or stdout, and on failure
+ * writes a JSON error object to stdout and returns exit code 1.
+ */
+export declare function runInitHeadlessCli(options: RunInitHeadlessCliOptions): Promise<number>;
+//# sourceMappingURL=headless-manifest.d.ts.map

package/dist/init-deposit/headless-manifest.js

@@ -0,0 +1,261 @@
+/**
+ * `directive init --headless` — manifest emitter for no-shell consumer products
+ * (#2268 / epic #2203).
+ *
+ * Hosted consumer products (e.g. deftai/deftvisage#1036) have no shell or npm
+ * access to the end user's machine. This module serialises the merged keystone
+ * `plan()` schema into a `{ version, files: [{ path, content, encoding }] }`
+ * manifest with ALL execution side effects suppressed: no interactive prompts,
+ * no git operations, no git-hook installation, and no filesystem writes outside
+ * the explicit `--output` target. It makes no git-repo assumption and runs
+ * against an empty / non-existent directory.
+ *
+ * Single-sourcing (the #2268 acceptance): the manifest is DERIVED from `plan()`
+ * — the collected file set is threaded through `plan(..., { files })` and read
+ * back out of {@link ResolutionPlan.files}. There is no separate "what would
+ * init produce" reimplementation; the collectors here are the manifest-only,
+ * read-only counterparts of the executing deposit path in `scaffold.ts` /
+ * `init-deposit.ts` (they reuse the same render helpers WITHOUT filesystem or
+ * git writes).
+ *
+ * On registry / content-resolution failure the CLI wrapper exits non-zero and
+ * emits a JSON error object so the calling backend can treat it as non-fatal
+ * (never a crash or a partial write).
+ */
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { ContentPackageNotFoundError, resolveInstalledContentRoot, } from "../deposit/resolve-content.js";
+import { readCorePackageVersion } from "../engine-version.js";
+import { agentsRefreshPlan } from "../platform/agents-md.js";
+import { plan } from "../resolution/plan.js";
+import { CANONICAL_INSTALL_ROOT } from "./constants.js";
+import { buildInstallManifestText, PIN_DEPENDENCY_NAME } from "./scaffold.js";
+/** POSIX-relative path of the payload VERSION marker inside the manifest. */
+const PAYLOAD_VERSION_PATH = `${CANONICAL_INSTALL_ROOT}/VERSION`;
+/** Provenance stamp written into the emitted `.deft/core/VERSION` marker. */
+const HEADLESS_FETCHED_BY = "directive-init-headless";
+/** The five xBRIEF lifecycle folders scaffolded into a fresh project. */
+export const HEADLESS_XBRIEF_LIFECYCLE_DIRS = [
+    "proposed",
+    "pending",
+    "active",
+    "completed",
+    "cancelled",
+];
+const XBRIEF_LIFECYCLE_GITKEEP = `# Keeps this xbrief/ lifecycle directory present in version control so the
+# deft-directive-setup pre-cutover guard does not fire on a fresh headless
+# install. Emitted by \`directive init --headless\` (#2268).
+`;
+function defaultNowIso() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** Read the resolved version from the content package.json (engine fallback). */
+function resolveVersion(contentRoot, seams) {
+    if (seams.readVersion)
+        return seams.readVersion(contentRoot);
+    try {
+        const parsed = JSON.parse(readFileSync(join(contentRoot, "package.json"), "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const version = parsed.version;
+            if (version?.trim())
+                return version.trim();
+        }
+    }
+    catch {
+        // Fall through to the engine version.
+    }
+    return readCorePackageVersion();
+}
+/**
+ * Decide the manifest encoding for a file's raw bytes. UTF-8 text round-trips
+ * losslessly; anything else (or bytes carrying a NUL) is base64 so binary
+ * payload assets survive JSON serialisation without corruption.
+ */
+function encodeBytes(buf) {
+    if (!buf.includes(0)) {
+        const text = buf.toString("utf8");
+        if (Buffer.from(text, "utf8").equals(buf)) {
+            return { content: text, encoding: "utf-8" };
+        }
+    }
+    return { content: buf.toString("base64"), encoding: "base64" };
+}
+/** POSIX-normalise a path (manifest paths are always forward-slash). */
+function toPosix(p) {
+    return sep === "/" ? p : p.split(sep).join("/");
+}
+/**
+ * Walk the content-package tree read-only and collect one manifest entry per
+ * file, prefixed with the canonical install root. The manifest-only counterpart
+ * of `reconstituteDepositFromContent` — it materialises bytes into memory
+ * instead of copying them onto disk.
+ */
+function collectPayloadFiles(contentRoot) {
+    const out = [];
+    const stack = [contentRoot];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                const rel = toPosix(relative(contentRoot, full));
+                const { content, encoding } = encodeBytes(readFileSync(full));
+                out.push({ path: `${CANONICAL_INSTALL_ROOT}/${rel}`, content, encoding });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Render the version-consistent `.deft/core/VERSION` marker. The `sha=` slot is
+ * stamped with the resolved version (headless mode has no git checkout), which
+ * is what keeps the emitted AGENTS.md managed section and the payload provably
+ * consistent against a single resolved version.
+ */
+function collectVersionFile(version, nowIso) {
+    const tag = version.startsWith("v") ? version : `v${version}`;
+    const body = buildInstallManifestText({
+        ref: tag,
+        sha: version,
+        tag,
+        installRoot: CANONICAL_INSTALL_ROOT,
+        fetchedAt: nowIso,
+        fetchedBy: HEADLESS_FETCHED_BY,
+    });
+    return { path: PAYLOAD_VERSION_PATH, content: body, encoding: "utf-8" };
+}
+/**
+ * Render the greenfield AGENTS.md (unmanaged header + attributed managed
+ * section) from the SAME content root as the payload, so the managed section
+ * can never drift from the deposited framework version. The managed-section
+ * `sha=` is stamped with the resolved version for version-consistency.
+ */
+function collectAgentsMdFile(contentRoot, version, nowIso, sessionId) {
+    const agentsResult = agentsRefreshPlan("headless-project", {
+        frameworkRoot: contentRoot,
+        resolveSha: () => version,
+        nowIso: () => nowIso,
+        newSession: () => sessionId,
+        readAgents: () => null,
+    });
+    const newContent = agentsResult.new_content;
+    if (typeof newContent !== "string") {
+        throw new Error(`AGENTS.md render produced no content (state: ${String(agentsResult.state)})`);
+    }
+    return { path: "AGENTS.md", content: newContent, encoding: "utf-8" };
+}
+/** The five xBRIEF lifecycle `.gitkeep` files (empty dirs can't ride a manifest). */
+function collectXbriefScaffoldFiles() {
+    return HEADLESS_XBRIEF_LIFECYCLE_DIRS.map((sub) => ({
+        path: `xbrief/${sub}/.gitkeep`,
+        content: XBRIEF_LIFECYCLE_GITKEEP,
+        encoding: "utf-8",
+    }));
+}
+/** The pinned `package.json` devDependency snippet (exact, private workspace). */
+function collectPackageJsonFile(version) {
+    const pinVersion = version.trim().replace(/^v/i, "");
+    const pkg = {
+        private: true,
+        devDependencies: { [PIN_DEPENDENCY_NAME]: pinVersion },
+    };
+    return {
+        path: "package.json",
+        content: `${JSON.stringify(pkg, null, 2)}\n`,
+        encoding: "utf-8",
+    };
+}
+/**
+ * Greenfield fact-set for the headless manifest. `hasDeftCore: false` routes
+ * `plan()` to `init` mode (Row 2), before any engine/pin reconciliation — no
+ * git-repo assumption, no reachable-engine requirement.
+ */
+function headlessGreenfieldFacts() {
+    return {
+        hasGit: false,
+        hasAppCode: false,
+        hasDeftCore: false,
+        deftCorePayloadVersion: null,
+        hasManagedSection: false,
+        managedSectionSha: null,
+        hasVbrief: false,
+        hasXbrief: false,
+        preCutoverArtifacts: false,
+        engineReachable: false,
+        engineVersion: null,
+        pinVersion: null,
+    };
+}
+/**
+ * Build the headless manifest. Reads the content package read-only, collects
+ * the fresh-install file set (payload + version-consistent AGENTS.md + xBRIEF
+ * scaffold + pinned package.json), threads it through `plan()` so the manifest
+ * is single-sourced from the resolution schema, and returns the serialisable
+ * shape. Performs NO filesystem writes and NO git operations.
+ *
+ * Throws (never partially writes) on content-resolution failure; the CLI
+ * wrapper converts the throw into a JSON error object + non-zero exit.
+ */
+export async function buildHeadlessManifest(seams = {}) {
+    const resolveContentRoot = seams.resolveContentRoot ?? resolveInstalledContentRoot;
+    const contentRoot = await resolveContentRoot();
+    const version = resolveVersion(contentRoot, seams);
+    const nowIso = (seams.nowIso ?? defaultNowIso)();
+    const sessionId = (seams.newSession ?? (() => "headlessmanif"))();
+    const payload = collectPayloadFiles(contentRoot).filter((file) => file.path !== PAYLOAD_VERSION_PATH);
+    const files = [
+        ...payload,
+        collectVersionFile(version, nowIso),
+        collectAgentsMdFile(contentRoot, version, nowIso, sessionId),
+        ...collectXbriefScaffoldFiles(),
+        collectPackageJsonFile(version),
+    ].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    // Single-source the manifest from plan(): the collected set rides the
+    // ResolutionPlan.files channel, and we read it back out — no reimplementation.
+    const resolved = plan(headlessGreenfieldFacts(), {}, { files });
+    return { version, files: resolved.files };
+}
+/**
+ * CLI-facing entrypoint for `directive init --headless`. Emits the manifest to
+ * `--output` (the ONLY permitted filesystem write) or stdout, and on failure
+ * writes a JSON error object to stdout and returns exit code 1.
+ */
+export async function runInitHeadlessCli(options) {
+    try {
+        const manifest = await buildHeadlessManifest(options.seams);
+        const serialized = `${JSON.stringify(manifest, null, 2)}\n`;
+        if (options.outputPath) {
+            const abs = resolve(options.outputPath);
+            const writeFile = options.writeFile ??
+                ((path, data) => {
+                    mkdirSync(dirname(path), { recursive: true });
+                    writeFileSync(path, data);
+                });
+            writeFile(abs, serialized);
+            options.writeErr(`directive init --headless: wrote ${manifest.files.length}-file manifest (v${manifest.version}) to ${abs}\n`);
+        }
+        else {
+            options.writeOut(serialized);
+        }
+        return 0;
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        const error_code = cause instanceof ContentPackageNotFoundError
+            ? "content_resolution_failed"
+            : "headless_manifest_failed";
+        const errorObject = {
+            success: false,
+            error: message,
+            error_code,
+        };
+        options.writeOut(`${JSON.stringify(errorObject, null, 2)}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=headless-manifest.js.map

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

@@ -1,6 +1,9 @@
+export * from "./headless-manifest.js";
 export * from "./init-deposit.js";
+export * from "./init-dispatch.js";
 export * from "./legacy-detect.js";
 export * from "./migrate.js";
 export * from "./refresh.js";
 export * from "./scaffold.js";
+export * from "./untrack-core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/init-deposit/index.js

@@ -1,6 +1,9 @@
+export * from "./headless-manifest.js";
 export * from "./init-deposit.js";
+export * from "./init-dispatch.js";
 export * from "./legacy-detect.js";
 export * from "./migrate.js";
 export * from "./refresh.js";
 export * from "./scaffold.js";
+export * from "./untrack-core.js";
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,90 @@
+/**
+ * Universal adoption dispatcher for `directive init` (#2265 / epic #2203).
+ *
+ * `directive init` is the ONE entrypoint a first-time adopter runs regardless of
+ * their directory state. This module classifies the directory via the shared
+ * keystone `classify()`/`plan()` fact-set (#2264, consumed read-only) and
+ * dispatches to exactly one of four paths, always printing a concise state
+ * summary plus exactly one recommended next action:
+ *
+ *   - `scaffold`           — empty greenfield dir; deposit Directive.
+ *   - `brownfield-install` — app code but no Directive deposit; install support
+ *                            beside the app code without disturbing it.
+ *   - `delegate-update`    — already initialized; DELEGATE to `update` with an
+ *                            explicit disclosure line. init never silently
+ *                            refreshes under its own name (the #2199 anti-pattern)
+ *                            and never re-scaffolds an existing install.
+ *   - `route-migrate`      — legacy / pre-cutover layout; route to `migrate`.
+ *
+ * Logic is single-sourced: each delegate branch CALLS the existing narrow verb
+ * (`runInitDepositCli` / `runRefreshDepositCli` / `runMigrateCli`) — the
+ * dispatcher never re-implements deposit, refresh, or migrate behavior.
+ */
+import type { ResolutionFacts, ResolutionPlan } from "@deftai/directive-types";
+import { type ClassifySeams } from "../resolution/index.js";
+import { type RunInitDepositCliOptions } from "./init-deposit.js";
+import { type RunMigrateCliOptions } from "./migrate.js";
+import { type RunRefreshDepositCliOptions } from "./refresh.js";
+import type { InitDepositIo } from "./scaffold.js";
+/** The four adoption paths `directive init` dispatches into. */
+export type InitDispatchDecision = "scaffold" | "brownfield-install" | "delegate-update" | "route-migrate";
+/** Human-readable state label per decision, used in the printed summary. */
+export declare const INIT_DISPATCH_STATE_LABEL: Record<InitDispatchDecision, string>;
+/**
+ * Explicit disclosure printed BEFORE delegating an already-initialized project
+ * to `update`. Its presence is what keeps `init` from silently masquerading as
+ * `update` (the #2199 anti-pattern): the user always sees that init delegated.
+ */
+export declare const UPDATE_DELEGATION_DISCLOSURE = "Existing install detected \u2014 refreshing via `update` (init delegates to update; it does not re-scaffold).";
+/**
+ * Collapse the shared resolution {@link ResolutionPlan} + fact-set onto one of
+ * the four init dispatch decisions. There is no second classifier: `plan.mode`
+ * is the single source of truth, and the empty-vs-brownfield split reads the
+ * `hasAppCode`/`hasGit` facts already produced by `classify()`.
+ */
+export declare function decideInitDispatch(facts: ResolutionFacts, resolutionPlan: ResolutionPlan): InitDispatchDecision;
+export interface InitDispatchClassification {
+    readonly decision: InitDispatchDecision;
+    readonly plan: ResolutionPlan;
+    readonly facts: ResolutionFacts;
+}
+/**
+ * Run the up-front dispatch classifier. Reuses the keystone `classify()`
+ * fact-set + `plan()` precedence table — no second classifier lives here.
+ */
+export declare function classifyInitDispatch(projectDir: string, classifySeams?: ClassifySeams): InitDispatchClassification;
+/** The single recommended next-action line for a decision. */
+export declare function initDispatchNextAction(decision: InitDispatchDecision, resolutionPlan: ResolutionPlan): string;
+/** Print the concise state summary + exactly one recommended next action. */
+export declare function printInitDispatchSummary(io: InitDepositIo, decision: InitDispatchDecision, resolutionPlan: ResolutionPlan): void;
+/** Machine-readable payload emitted for `--dry-run`/`--plan` (no execution). */
+export declare function buildInitDispatchDryRunJson(projectDir: string, classification: InitDispatchClassification): Record<string, unknown>;
+/**
+ * Injectable delegate seams. Defaults are the real narrow-verb CLIs; tests
+ * inject fakes to assert single-sourced delegation without touching the fs.
+ */
+export interface InitDispatchSeams {
+    readonly classifySeams?: ClassifySeams;
+    readonly runScaffold?: (options: RunInitDepositCliOptions) => Promise<number>;
+    readonly runRefresh?: (options: RunRefreshDepositCliOptions) => Promise<number>;
+    readonly runMigrate?: (options: RunMigrateCliOptions) => number;
+}
+export interface RunInitDispatchCliOptions {
+    readonly projectDir: string;
+    readonly jsonOut: boolean;
+    readonly nonInteractive: boolean;
+    /** `--dry-run`/`--plan`: print the classified plan without executing. */
+    readonly dryRun: boolean;
+    readonly writeOut: (text: string) => void;
+    readonly writeErr: (text: string) => void;
+    readonly seams?: InitDispatchSeams;
+}
+/**
+ * CLI-facing entrypoint for `directive init`. Classifies, prints a state summary
+ * + one next action, then either stops (`--dry-run`) or delegates to the narrow
+ * verb for the resolved decision. The summary/disclosure use the `printf`
+ * channel (stderr under `--json`) so that in JSON mode stdout stays a SINGLE
+ * JSON object — the delegate's result, or the dry-run plan.
+ */
+export declare function runInitDispatchCli(options: RunInitDispatchCliOptions): Promise<number>;
+//# sourceMappingURL=init-dispatch.d.ts.map