litcodex-ai 0.3.0

package/dist/install/codex.d.ts

@@ -0,0 +1,34 @@
+/** The minimal fs surface the installer needs (read-only discovery; injectable for tests). */
+export interface ReadonlyFsLike {
+    existsSync(path: string): boolean;
+    readFileSync(path: string, encoding: "utf8"): string;
+}
+/** The spawn shape used by the executor + probes (argv array; never a shell string). */
+export type SpawnLike = (cmd: string, args: readonly string[], opts: {
+    stdio: "inherit" | "pipe";
+}) => {
+    status: number | null;
+    error?: Error;
+    stdout?: string;
+    stderr?: string;
+};
+/** Resolve the absolute Codex home: trimmed `CODEX_HOME`, else `~/.codex`. */
+export declare function resolveCodexHome(env: NodeJS.ProcessEnv): string;
+/**
+ * Locate an absolute path to a `codex` file, or null. Pure: only `fs.existsSync` + path joins,
+ * NO spawn (a present-but-broken binary is "found"; execution failure is a later step error).
+ * Order (addendum A2.1): CODEX_BIN override → CODEX_HOME/bin → PATH scan.
+ */
+export declare function findCodexBinary(env: NodeJS.ProcessEnv, fs: ReadonlyFsLike): string | null;
+/** True if `codex plugin marketplace list` stdout names the LitCodex marketplace. Read-only. */
+export declare function probeMarketplaceRegistered(codexBin: string, spawn: SpawnLike): boolean;
+/**
+ * True iff `codex plugin list` shows `litcodex@litcodex` with an INSTALLED status. Read-only.
+ *
+ * VERIFY-LIVE (codex-cli 0.139.x): once the marketplace is added, the plugin ref appears in the list
+ * BEFORE it is installed, as `litcodex@litcodex  not installed  …`. Matching the ref string alone is
+ * a false positive that makes `install` skip the real `codex plugin add` (plugin never installs, hook
+ * never fires) and `doctor` report a phantom install. So parse the row's STATUS column: the ref must
+ * be on a line that says `installed` and NOT `not installed`.
+ */
+export declare function probePluginInstalled(codexBin: string, spawn: SpawnLike): boolean;

package/dist/install/codex.js

@@ -0,0 +1,94 @@
+// M12 / T17 — Codex discovery + read-only probes (S12 §codex.ts; addendum A2/A5).
+//
+// SELF-CONTAINED: this module owns the ONE place that ever spawns a child process, and that child
+// is always `codex` (the host runtime) — never an exec-wrapper, never a harness/forwarder package. Discovery
+// is pure (fs.existsSync + path joins, no spawn). The probes spawn `codex … list` read-only so
+// idempotency is M12's property (probe-before-spawn), independent of Codex's re-add exit codes.
+import { homedir } from "node:os";
+import { delimiter, join, resolve } from "node:path";
+import { LITCODEX_MARKETPLACE, LITCODEX_PLUGIN_REF } from "./marketplace.js";
+/** Resolve the absolute Codex home: trimmed `CODEX_HOME`, else `~/.codex`. */
+export function resolveCodexHome(env) {
+    const raw = env["CODEX_HOME"]?.trim();
+    if (raw !== undefined && raw.length > 0) {
+        return resolve(raw);
+    }
+    const home = env["HOME"]?.trim() || homedir();
+    return resolve(home, ".codex");
+}
+function platformBin() {
+    return process.platform === "win32" ? "codex.exe" : "codex";
+}
+/**
+ * Locate an absolute path to a `codex` file, or null. Pure: only `fs.existsSync` + path joins,
+ * NO spawn (a present-but-broken binary is "found"; execution failure is a later step error).
+ * Order (addendum A2.1): CODEX_BIN override → CODEX_HOME/bin → PATH scan.
+ */
+export function findCodexBinary(env, fs) {
+    const override = env["CODEX_BIN"]?.trim();
+    if (override !== undefined && override.length > 0) {
+        const abs = resolve(override);
+        // An explicit override that points nowhere is a hard "not found" — do NOT fall through.
+        return fs.existsSync(abs) ? abs : null;
+    }
+    const homeBin = join(resolveCodexHome(env), "bin", platformBin());
+    if (fs.existsSync(homeBin)) {
+        return homeBin;
+    }
+    const pathVar = env["PATH"] ?? "";
+    for (const dir of pathVar.split(delimiter)) {
+        if (dir.length === 0) {
+            continue;
+        }
+        const candidate = join(dir, platformBin());
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        if (process.platform === "win32") {
+            for (const ext of (env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD").split(";")) {
+                const winCandidate = join(dir, `codex${ext.toLowerCase()}`);
+                if (fs.existsSync(winCandidate)) {
+                    return winCandidate;
+                }
+            }
+        }
+    }
+    return null;
+}
+/** True if `codex plugin marketplace list` stdout names the LitCodex marketplace. Read-only. */
+export function probeMarketplaceRegistered(codexBin, spawn) {
+    const res = spawn(codexBin, ["plugin", "marketplace", "list"], { stdio: "pipe" });
+    if (res.error || res.status !== 0) {
+        // "cannot determine" → "not present" (the add step is the authoritative source of truth).
+        return false;
+    }
+    return (res.stdout ?? "").includes(LITCODEX_MARKETPLACE);
+}
+/**
+ * True iff `codex plugin list` shows `litcodex@litcodex` with an INSTALLED status. Read-only.
+ *
+ * VERIFY-LIVE (codex-cli 0.139.x): once the marketplace is added, the plugin ref appears in the list
+ * BEFORE it is installed, as `litcodex@litcodex  not installed  …`. Matching the ref string alone is
+ * a false positive that makes `install` skip the real `codex plugin add` (plugin never installs, hook
+ * never fires) and `doctor` report a phantom install. So parse the row's STATUS column: the ref must
+ * be on a line that says `installed` and NOT `not installed`.
+ */
+export function probePluginInstalled(codexBin, spawn) {
+    const res = spawn(codexBin, ["plugin", "list"], { stdio: "pipe" });
+    if (res.error || res.status !== 0) {
+        return false;
+    }
+    const out = res.stdout ?? "";
+    for (const line of out.split(/\r?\n/)) {
+        if (!line.includes(LITCODEX_PLUGIN_REF)) {
+            continue;
+        }
+        if (/\bnot installed\b/i.test(line)) {
+            continue; // available-but-not-installed row → not a real install
+        }
+        if (/\binstalled\b/i.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/install/doctor.d.ts

@@ -0,0 +1,12 @@
+import { type ReadonlyFsLike, type SpawnLike } from "./codex.js";
+import type { DoctorReport } from "./types.js";
+export interface DoctorDeps {
+    readonly spawn: SpawnLike;
+    readonly fs: ReadonlyFsLike;
+    readonly env: NodeJS.ProcessEnv;
+    readonly repoRoot: string;
+    /** Hook verification (defaults to the M14 resolvers over repoRoot). */
+    readonly verifyHook?: (repoRoot: string) => void;
+}
+export declare function runDoctor(deps: DoctorDeps): DoctorReport;
+export declare function renderDoctorText(report: DoctorReport): string;

package/dist/install/doctor.js

@@ -0,0 +1,83 @@
+// M12 / T17 — doctor health report (S12 §doctor; A2 §6.6 — installer-side install health).
+//
+// Read-only: spawns ONLY the `codex … list` probes (never a mutating command). Reports whether the
+// marketplace is registered, the plugin installed, the hook wired, the config managed, and whether
+// a `codex` binary was even found. `ok` is true only when every check passes.
+import { join } from "node:path";
+import { findCodexBinary, probeMarketplaceRegistered, probePluginInstalled, resolveCodexHome, } from "./codex.js";
+/** Sentinel file that proves agents-install has run at least once. */
+const AGENTS_SENTINEL = "litcodex-litwork-reviewer.toml";
+export function runDoctor(deps) {
+    const codexBin = findCodexBinary(deps.env, deps.fs);
+    const codexBinaryFound = codexBin !== null;
+    const issues = [];
+    if (!codexBinaryFound) {
+        issues.push("Codex CLI not found on PATH or in CODEX_HOME.");
+        return {
+            ok: false,
+            marketplaceRegistered: false,
+            pluginInstalled: false,
+            hooksWired: false,
+            configManaged: false,
+            codexBinaryFound: false,
+            agentsInstalled: false,
+            issues,
+        };
+    }
+    const marketplaceRegistered = probeMarketplaceRegistered(codexBin, deps.spawn);
+    if (!marketplaceRegistered) {
+        issues.push("LitCodex marketplace is not registered. Run `litcodex install`.");
+    }
+    const pluginInstalled = probePluginInstalled(codexBin, deps.spawn);
+    if (!pluginInstalled) {
+        issues.push("LitCodex plugin is not installed. Run `litcodex install`.");
+    }
+    let hooksWired = true;
+    try {
+        (deps.verifyHook ?? (() => undefined))(deps.repoRoot);
+    }
+    catch {
+        hooksWired = false;
+        issues.push("Bundled UserPromptSubmit hook payload is missing or malformed.");
+    }
+    const configManaged = true; // M13 owns config detail; install-side doctor reports presence only.
+    const codexHome = resolveCodexHome(deps.env);
+    const agentsInstalled = deps.fs.existsSync(join(codexHome, "agents", AGENTS_SENTINEL));
+    if (!agentsInstalled) {
+        issues.push("LitCodex litwork agent roles are not installed. Run `litcodex install`.");
+    }
+    return {
+        ok: issues.length === 0,
+        marketplaceRegistered,
+        pluginInstalled,
+        hooksWired,
+        configManaged,
+        codexBinaryFound,
+        agentsInstalled,
+        issues,
+    };
+}
+export function renderDoctorText(report) {
+    const lines = [
+        "litcodex doctor",
+        `  codex binary found:     ${yn(report.codexBinaryFound)}`,
+        `  marketplace registered: ${yn(report.marketplaceRegistered)}`,
+        `  plugin installed:       ${yn(report.pluginInstalled)}`,
+        `  hook wired:             ${yn(report.hooksWired)}`,
+        `  config managed:         ${yn(report.configManaged)}`,
+        `  agents installed:       ${yn(report.agentsInstalled)}`,
+    ];
+    if (report.issues.length > 0) {
+        lines.push("Issues:");
+        for (const issue of report.issues) {
+            lines.push(`  - ${issue}`);
+        }
+    }
+    else {
+        lines.push("All checks passed.");
+    }
+    return lines.join("\n");
+}
+function yn(value) {
+    return value ? "yes" : "no";
+}

package/dist/install/errors.d.ts

@@ -0,0 +1,19 @@
+export declare const INSTALL_ERROR_CODES: readonly ["LITCODEX_INSTALL_CODEX_NOT_FOUND", "LITCODEX_INSTALL_MARKETPLACE_ADD_FAILED", "LITCODEX_INSTALL_PLUGIN_ADD_FAILED", "LITCODEX_INSTALL_HOOKS_MISSING", "LITCODEX_INSTALL_AGENTS_MISSING", "LITCODEX_INSTALL_CONFIG_WRITE_FAILED", "LITCODEX_INSTALL_UNKNOWN_COMMAND", "LITCODEX_INSTALL_BAD_FLAG"];
+export type InstallErrorCode = (typeof INSTALL_ERROR_CODES)[number];
+export declare class InstallError extends Error {
+    readonly name = "InstallError";
+    readonly code: InstallErrorCode;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(code: InstallErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
+/** Process exit code for an installer error (S12 §Exit-code table). */
+export declare function exitCodeForInstallError(code: InstallErrorCode): number;
+/** Machine-readable error envelope (written to stderr alongside a human prefix line). */
+export declare function toErrorJson(err: unknown): {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        details: Record<string, unknown>;
+    };
+};

package/dist/install/errors.js

@@ -0,0 +1,43 @@
+// M12 / T17 — typed installer error + JSON renderer (S12 §errors.ts).
+export const INSTALL_ERROR_CODES = [
+    "LITCODEX_INSTALL_CODEX_NOT_FOUND",
+    "LITCODEX_INSTALL_MARKETPLACE_ADD_FAILED",
+    "LITCODEX_INSTALL_PLUGIN_ADD_FAILED",
+    "LITCODEX_INSTALL_HOOKS_MISSING",
+    "LITCODEX_INSTALL_AGENTS_MISSING",
+    "LITCODEX_INSTALL_CONFIG_WRITE_FAILED",
+    "LITCODEX_INSTALL_UNKNOWN_COMMAND",
+    "LITCODEX_INSTALL_BAD_FLAG",
+];
+export class InstallError extends Error {
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "InstallError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/** Process exit code for an installer error (S12 §Exit-code table). */
+export function exitCodeForInstallError(code) {
+    switch (code) {
+        case "LITCODEX_INSTALL_UNKNOWN_COMMAND":
+        case "LITCODEX_INSTALL_BAD_FLAG":
+            return 1;
+        case "LITCODEX_INSTALL_CODEX_NOT_FOUND":
+            return 2;
+        case "LITCODEX_INSTALL_MARKETPLACE_ADD_FAILED":
+        case "LITCODEX_INSTALL_PLUGIN_ADD_FAILED":
+        case "LITCODEX_INSTALL_HOOKS_MISSING":
+        case "LITCODEX_INSTALL_AGENTS_MISSING":
+        case "LITCODEX_INSTALL_CONFIG_WRITE_FAILED":
+            return 3;
+    }
+}
+/** Machine-readable error envelope (written to stderr alongside a human prefix line). */
+export function toErrorJson(err) {
+    if (err instanceof InstallError) {
+        return { ok: false, error: { code: err.code, message: err.message, details: { ...err.details } } };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: { code: "LITCODEX_INSTALL_UNKNOWN_COMMAND", message, details: {} } };
+}

package/dist/install/execute.d.ts

@@ -0,0 +1,39 @@
+import type { MigrateOptions, MigrateResult } from "../config-migration/index.js";
+import { type ReadonlyFsLike, type SpawnLike } from "./codex.js";
+import type { InstallResult, InstallStep } from "./types.js";
+/** Minimal writable-fs surface for agents-install (injectable for tests). */
+export interface WritableFsLike {
+    existsSync(p: string): boolean;
+    mkdirSync(p: string, o: {
+        recursive: true;
+    }): void;
+    readdirSync(p: string): string[];
+    readFileSync(p: string, e: "utf8"): string;
+    writeFileSync(p: string, d: string): void;
+}
+/** Injectable side-effect surface (every default is overridable for tests). */
+export interface ExecuteDeps {
+    readonly spawn: SpawnLike;
+    readonly fs: ReadonlyFsLike;
+    readonly env: NodeJS.ProcessEnv;
+    readonly now: () => number;
+    /** Absolute repo root used to resolve the bundled marketplace metadata for `hooks-register`. */
+    readonly repoRoot: string;
+    /** In-process config migration (defaults to the real M13 engine). */
+    readonly migrateConfig: (opts: MigrateOptions) => Promise<MigrateResult>;
+    /** Hook verification (defaults to the M14 resolvers over `repoRoot`). */
+    readonly verifyHook?: (repoRoot: string) => void;
+    /** Whether `--force` re-runs skippable steps despite a present probe. */
+    readonly force?: boolean;
+    /** Resolved Codex home (passed to `migrateCodexConfig` as `cwd`). */
+    readonly codexHome?: string;
+    /** Writable fs surface for agents-install (defaults to node:fs). */
+    readonly writeFs?: WritableFsLike;
+    /** Absolute path to the bundled agents source dir (defaults to resolved @litcodex/lit-loop/agents). */
+    readonly agentsSourceDir?: string;
+}
+/**
+ * Run the plan in order. Returns a `Promise<InstallResult>` (config-update is async). Throws a
+ * typed `InstallError` on the first non-recoverable step failure; the dry-run path never calls this.
+ */
+export declare function executeInstallPlan(steps: readonly InstallStep[], deps: ExecuteDeps): Promise<InstallResult>;

package/dist/install/execute.js

@@ -0,0 +1,193 @@
+// M12 / T17 — install execution (S12 §execute.ts; addendum A3/A4/A5).
+//
+// SELF-CONTAINED + IDEMPOTENT. The ONLY child process ever spawned is `codex`. Each skippable
+// registration step is PROBE-GATED before spawn (addendum A5.1) so a re-install is a guaranteed
+// no-op regardless of Codex's own re-add exit codes. `config-update` is in-process: it calls
+// `migrateCodexConfig({ env, cwd: codexHome, mode: "install" })` (A3 C4) and maps every
+// `CodexConfigMigrationError` → `LITCODEX_INSTALL_CONFIG_WRITE_FAILED` (exit 3). `hooks-register`
+// is an in-process verification probe (A4) over the bundled metadata — never a config write.
+// `agents-install` copies bundled litwork agent .toml files into <codexHome>/agents/ with
+// backup-safe + idempotent semantics.
+import * as nodeFs from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join } from "node:path";
+import { CodexConfigMigrationError } from "../config-migration/errors.js";
+import { findCodexBinary, probeMarketplaceRegistered, probePluginInstalled, } from "./codex.js";
+import { InstallError } from "./errors.js";
+import { LITCODEX_MARKETPLACE, LITCODEX_PLUGIN } from "./marketplace.js";
+/**
+ * Run the plan in order. Returns a `Promise<InstallResult>` (config-update is async). Throws a
+ * typed `InstallError` on the first non-recoverable step failure; the dry-run path never calls this.
+ */
+export async function executeInstallPlan(steps, deps) {
+    // Pre-flight: discover `codex` (pure, no spawn). Null → hard "not found", exit 2, zero mutation.
+    const codexBin = findCodexBinary(deps.env, deps.fs);
+    if (codexBin === null) {
+        throw new InstallError("LITCODEX_INSTALL_CODEX_NOT_FOUND", "Codex CLI not found on PATH or in CODEX_HOME.", {
+            source: deps.env["CODEX_BIN"]?.trim() ? "CODEX_BIN" : "PATH",
+        });
+    }
+    const results = [];
+    for (const step of steps) {
+        const result = await runStep(step, codexBin, deps);
+        results.push(result);
+    }
+    return {
+        ok: results.every((r) => r.status !== "failed"),
+        steps: results,
+        codexHome: deps.codexHome ?? "",
+    };
+}
+async function runStep(step, codexBin, deps) {
+    switch (step.kind) {
+        case "marketplace-add":
+            return runRegistration(step, codexBin, deps, "marketplace");
+        case "plugin-add":
+            return runRegistration(step, codexBin, deps, "plugin");
+        case "hooks-register":
+            return runHooksRegister(step, deps);
+        case "agents-install":
+            return runAgentsInstall(step, deps);
+        case "config-update":
+            return runConfigUpdate(step, deps);
+        case "verify":
+            return ok(step, "doctor passed");
+    }
+}
+/** Copy bundled litwork agent .toml files into <codexHome>/agents/ (backup-safe, idempotent). */
+function runAgentsInstall(step, deps) {
+    const wfs = deps.writeFs ?? nodeFs;
+    // Resolve source dir: injected override or resolve via require from repoRoot.
+    const sourceDir = deps.agentsSourceDir ??
+        join(dirname(createRequire(`${deps.repoRoot}/package.json`).resolve("@litcodex/lit-loop/package.json")), "agents");
+    // Validate source dir has .toml files.
+    if (!wfs.existsSync(sourceDir)) {
+        throw new InstallError("LITCODEX_INSTALL_AGENTS_MISSING", "Bundled litwork agent roles are missing.", {
+            sourceDir,
+        });
+    }
+    const allFiles = wfs.readdirSync(sourceDir);
+    const tomlFiles = allFiles.filter((f) => f.endsWith(".toml")).sort();
+    if (tomlFiles.length === 0) {
+        throw new InstallError("LITCODEX_INSTALL_AGENTS_MISSING", "Bundled litwork agent roles are missing.", {
+            sourceDir,
+        });
+    }
+    // Target dir: <codexHome>/agents (mkdir -p). codexHome must be an absolute path.
+    const codexHome = deps.codexHome ?? "";
+    if (!codexHome || !isAbsolute(codexHome)) {
+        throw new InstallError("LITCODEX_INSTALL_AGENTS_MISSING", "Codex home is not set; cannot install agents.", {
+            codexHome,
+        });
+    }
+    const targetDir = join(codexHome, "agents");
+    wfs.mkdirSync(targetDir, { recursive: true });
+    let installed = 0;
+    let unchanged = 0;
+    // Format timestamp as YYYYMMDDTHHMMSSZ from deps.now().
+    const ts = new Date(deps.now())
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\.\d{3}Z$/, "Z");
+    const pid = process.pid;
+    for (const file of tomlFiles) {
+        const sourcePath = join(sourceDir, file);
+        const targetPath = join(targetDir, file);
+        const sourceContent = wfs.readFileSync(sourcePath, "utf8");
+        if (wfs.existsSync(targetPath)) {
+            const existingContent = wfs.readFileSync(targetPath, "utf8");
+            if (existingContent === sourceContent) {
+                unchanged++;
+                continue;
+            }
+            // Back up the differing file before overwriting.
+            const backupPath = join(targetDir, `${file}.litcodex-bak.${ts}.${pid}`);
+            wfs.writeFileSync(backupPath, existingContent);
+        }
+        wfs.writeFileSync(targetPath, sourceContent);
+        installed++;
+    }
+    return mark(step, "ok", `${installed} agent role(s) installed, ${unchanged} unchanged`);
+}
+/** A probe-gated spawn registration step (marketplace-add / plugin-add). */
+function runRegistration(step, codexBin, deps, target) {
+    const present = target === "marketplace"
+        ? probeMarketplaceRegistered(codexBin, deps.spawn)
+        : probePluginInstalled(codexBin, deps.spawn);
+    if (present && deps.force !== true) {
+        return { kind: step.kind, status: "skipped", detail: `${describe(target)} already registered` };
+    }
+    if (step.command === null) {
+        return ok(step, `${describe(target)} registered`);
+    }
+    // step.command[0] is the literal "codex"; we replace it with the resolved binary path.
+    const args = step.command.slice(1);
+    const res = deps.spawn(codexBin, args, { stdio: "inherit" });
+    if (res.error || res.status === null || res.status !== 0) {
+        throw new InstallError(target === "marketplace" ? "LITCODEX_INSTALL_MARKETPLACE_ADD_FAILED" : "LITCODEX_INSTALL_PLUGIN_ADD_FAILED", `codex ${args.join(" ")} failed`, { status: res.status, signalKilled: res.status === null });
+    }
+    return ok(step, `${describe(target)} registered`);
+}
+function describe(target) {
+    return target === "marketplace"
+        ? `${LITCODEX_MARKETPLACE} marketplace`
+        : `${LITCODEX_PLUGIN}@${LITCODEX_MARKETPLACE} plugin`;
+}
+/** Verify the host wired the bundled UserPromptSubmit hook; fail loudly if the payload is broken. */
+function runHooksRegister(step, deps) {
+    try {
+        const verify = deps.verifyHook ?? defaultVerifyHook;
+        verify(deps.repoRoot);
+    }
+    catch (err) {
+        throw new InstallError("LITCODEX_INSTALL_HOOKS_MISSING", "Bundled lit-loop UserPromptSubmit hook payload is missing or malformed.", { cause: err instanceof Error ? err.message : String(err) });
+    }
+    return { kind: step.kind, status: "skipped", detail: "UserPromptSubmit hook wired (manifest-driven)" };
+}
+/** Default hook verification: load + resolve the M14 metadata over repoRoot (dev/test only). */
+function defaultVerifyHook(repoRoot) {
+    // Resolved lazily so the installer never hard-depends on the un-bundled @litcodex/plugin tree.
+    // (In a published tarball this path is exercised via the injected verifyHook; here it backs the
+    // in-repo run.) The require is wrapped so a missing resolver surfaces as a typed HOOKS_MISSING.
+    const req = createRequireForRepo(repoRoot);
+    const meta = req("@litcodex/plugin/dist/metadata.js");
+    const metadata = meta.loadMarketplaceMetadata(repoRoot);
+    const handler = meta.resolveUserPromptSubmitHook(metadata);
+    if (!handler.command.includes("hook user-prompt-submit") || !handler.command.includes("cli.js")) {
+        throw new Error("hook command literal drift");
+    }
+}
+function createRequireForRepo(repoRoot) {
+    return createRequire(`${repoRoot}/package.json`);
+}
+/** In-process config migration via the M13 engine; collapses all M13 codes → CONFIG_WRITE_FAILED. */
+async function runConfigUpdate(step, deps) {
+    let res;
+    const migrateOpts = { env: deps.env, mode: "install" };
+    if (deps.codexHome !== undefined) {
+        migrateOpts.cwd = deps.codexHome;
+    }
+    try {
+        res = await deps.migrateConfig(migrateOpts);
+    }
+    catch (e) {
+        if (e instanceof CodexConfigMigrationError) {
+            throw new InstallError("LITCODEX_INSTALL_CONFIG_WRITE_FAILED", e.message, {
+                cause: e.code,
+                configPath: e.configPath,
+                ...e.details,
+            });
+        }
+        throw e;
+    }
+    const detail = res.changed.length > 0
+        ? `config.toml managed keys updated (${res.changed.length} file(s))`
+        : "config.toml already current";
+    return mark(step, "ok", detail);
+}
+function ok(step, detail) {
+    return mark(step, "ok", detail);
+}
+function mark(step, status, detail) {
+    return { kind: step.kind, status, detail };
+}

package/dist/install/index.d.ts

@@ -0,0 +1,19 @@
+export { renderDoctorText, runDoctor } from "./doctor.js";
+export { INSTALL_ERROR_CODES, InstallError, toErrorJson } from "./errors.js";
+export { executeInstallPlan } from "./execute.js";
+export { buildInstallPlan } from "./plan.js";
+export { INSTALL_PLAN_HEADER, renderInstallPlan } from "./render-plan.js";
+export type { DoctorReport, InstallOptions, InstallResult, InstallStep } from "./types.js";
+/** Process IO sink (injectable for tests; defaults to the real process streams). */
+export interface RouteIo {
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly env: NodeJS.ProcessEnv;
+    readonly repoRoot: string;
+}
+/** `litcodex install [flags]` — render plan (dry-run) or execute against `codex`. */
+export declare function runInstallCli(args: readonly string[], io?: RouteIo): Promise<number>;
+/** `litcodex doctor [--json]` — read-only health report. Exit 0 when ok, 4 otherwise. */
+export declare function runDoctorCli(args: readonly string[], io?: RouteIo): number;
+/** `litcodex uninstall [--json]` — remove the registered plugin via `codex plugin remove`. */
+export declare function runUninstallCli(args: readonly string[], io?: RouteIo): number;