@litfamily/litcodex 1.0.0

package/dist/install/agents-install.js

@@ -0,0 +1,211 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, isAbsolute, join } from "node:path";
+import { EXPLICIT_GPT56_SOL_MODEL, GPT56_MODELS, unsafeEffectiveRoute } from "../config-migration/gpt56-policy.js";
+import { agentRouteIssue, installedAgentPath, NATIVE_DEFAULT_AGENT_FILE, parseAgentRoute, rewriteAgentRouteHeader, rewriteAgentRouteModel, } from "./agent-routing.js";
+import { InstallError } from "./errors.js";
+const NODE_FS = {
+    existsSync,
+    lstatSync,
+    mkdirSync: (path, options) => mkdirSync(path, options),
+    readdirSync: (path) => readdirSync(path),
+    readFileSync: (path, encoding) => readFileSync(path, encoding),
+    writeFileSync: (path, data) => writeFileSync(path, data),
+};
+export function runAgentsInstall(step, deps) {
+    const wfs = deps.writeFs ?? NODE_FS;
+    const prepared = deps.preparedAgentSources ?? prepareAgentSources(deps);
+    const codexHome = deps.codexHome ?? "";
+    if (!isAbsolute(codexHome)) {
+        throw missingAgents({ codexHome });
+    }
+    assertSafeAgentPath(wfs, codexHome, true);
+    const targetDir = join(codexHome, "agents");
+    assertSafeAgentPath(wfs, targetDir, true);
+    const installsNativeDefault = prepared.sources.some((source) => source.file === NATIVE_DEFAULT_AGENT_FILE);
+    const legacyDefaultPath = join(targetDir, NATIVE_DEFAULT_AGENT_FILE);
+    if (installsNativeDefault) {
+        assertSafeAgentPath(wfs, legacyDefaultPath, false);
+        if (wfs.existsSync(legacyDefaultPath)) {
+            throw missingAgents({
+                path: legacyDefaultPath,
+                reason: "managed generic default role is still inside the autodiscovered agents directory; refusing to create a duplicate outside it",
+            });
+        }
+    }
+    const timestamp = new Date(deps.now())
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\.\d{3}Z$/, "Z");
+    const actions = [];
+    for (const source of prepared.sources) {
+        const sourceRoute = prepared.agentRoutes.find((route) => route.file === source.file);
+        if (sourceRoute === undefined)
+            throw missingAgents({ file: source.file, reason: "prepared route missing" });
+        const targetPath = installedAgentPath(codexHome, source.file);
+        assertSafeAgentPath(wfs, targetPath, false);
+        if (!wfs.existsSync(targetPath)) {
+            actions.push({ source, targetPath, route: sourceRoute, kind: "install", output: source.content });
+            continue;
+        }
+        const existing = wfs.readFileSync(targetPath, "utf8");
+        if (existing === source.content) {
+            const route = parseExistingRoute(source.file, existing);
+            actions.push({ source, targetPath, route, kind: "unchanged", output: existing });
+            continue;
+        }
+        const existingRoute = parseExistingRoute(source.file, existing);
+        if (deps.reconfigure !== true) {
+            actions.push({ source, targetPath, route: existingRoute, kind: "preserve", output: existing });
+            continue;
+        }
+        actions.push({
+            source,
+            targetPath,
+            route: sourceRoute,
+            kind: "rewrite",
+            output: rewriteAgentRouteHeader(existing, sourceRoute),
+            existing,
+        });
+    }
+    wfs.mkdirSync(targetDir, { recursive: true });
+    let installed = 0;
+    let unchanged = 0;
+    let preserved = 0;
+    const installedRoutes = [];
+    for (const action of actions) {
+        if (action.kind === "preserve") {
+            preserved += 1;
+            installedRoutes.push(action.route);
+            continue;
+        }
+        if (action.kind === "unchanged") {
+            unchanged += 1;
+            installedRoutes.push(action.route);
+            continue;
+        }
+        if (action.existing !== undefined) {
+            const file = action.source.file;
+            wfs.writeFileSync(join(dirname(action.targetPath), `${file}.litcodex-bak.${timestamp}.${process.pid}`), action.existing);
+        }
+        wfs.writeFileSync(action.targetPath, action.output);
+        installed += 1;
+        installedRoutes.push(parseAgentRoute(action.source.file, action.output));
+    }
+    return {
+        kind: step.kind,
+        status: "ok",
+        detail: `${installed} agent role(s) installed, ${unchanged} unchanged, ${preserved} preserved`,
+        agentRoutes: installedRoutes,
+    };
+}
+function assertSafeAgentPath(wfs, path, directory) {
+    if (wfs.lstatSync === undefined)
+        return;
+    let stat;
+    try {
+        stat = wfs.lstatSync(path);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return;
+        throw missingAgents({
+            path,
+            reason: "could not inspect target identity",
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    if (stat.isSymbolicLink()) {
+        throw missingAgents({ path, reason: "refusing to follow a symlink during agent installation" });
+    }
+    if (directory && !stat.isDirectory()) {
+        throw missingAgents({ path, reason: "agent target is not a directory" });
+    }
+    if (!directory && stat.isDirectory()) {
+        throw missingAgents({ path, reason: "agent target is a directory" });
+    }
+}
+function parseExistingRoute(file, content) {
+    try {
+        const route = parseAgentRoute(file, content);
+        const unsafe = unsafeEffectiveRoute({ model: route.model, model_reasoning_effort: route.effort });
+        if (unsafe !== null) {
+            throw new InstallError("LITCODEX_INSTALL_UNSAFE_MODEL_ROUTE", `Existing agent role is invalid: ${unsafe}.`, {
+                file,
+                model: route.model,
+                effort: route.effort,
+            });
+        }
+        return route;
+    }
+    catch (error) {
+        if (error instanceof InstallError)
+            throw error;
+        throw new InstallError("LITCODEX_INSTALL_AGENTS_MISSING", `Existing agent role ${file} is malformed; refusing to overwrite it.`, {
+            file,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+export function prepareAgentSources(deps) {
+    const wfs = deps.writeFs ?? NODE_FS;
+    const sourceDir = deps.agentsSourceDir ?? join(resolveLitLoopDir(deps.repoRoot), "agents");
+    if (!wfs.existsSync(sourceDir)) {
+        throw missingAgents({ sourceDir });
+    }
+    const tomlFiles = wfs
+        .readdirSync(sourceDir)
+        .filter((file) => file.endsWith(".toml"))
+        .sort();
+    if (tomlFiles.length === 0) {
+        throw missingAgents({ sourceDir });
+    }
+    const rewriteAlias = deps.authMode === "chatgpt";
+    const sources = tomlFiles.map((file) => {
+        let content = wfs.readFileSync(join(sourceDir, file), "utf8");
+        if (rewriteAlias) {
+            content = rewriteAgentRouteModel(content, GPT56_MODELS.sol, EXPLICIT_GPT56_SOL_MODEL);
+        }
+        if (file === "litcodex-default.toml" && deps.subagentModel !== undefined) {
+            const effort = deps.subagentEffort ?? "max";
+            const unsafe = unsafeEffectiveRoute({ model: deps.subagentModel, model_reasoning_effort: effort });
+            if (unsafe !== null) {
+                throw new InstallError("LITCODEX_INSTALL_UNSAFE_MODEL_ROUTE", `Selected helper route is invalid: ${unsafe}.`, {
+                    model: deps.subagentModel,
+                    effort,
+                });
+            }
+            content = rewriteAgentRouteHeader(content, { model: deps.subagentModel, effort });
+        }
+        return { file, content };
+    });
+    const agentRoutes = sources.map((source) => parseAgentRoute(source.file, source.content));
+    for (const route of agentRoutes) {
+        const issue = agentRouteIssue(route);
+        if (issue !== null) {
+            throw new InstallError("LITCODEX_INSTALL_UNSAFE_MODEL_ROUTE", `Bundled agent route is invalid: ${issue}.`, {
+                file: route.file,
+                model: route.model,
+                effort: route.effort,
+            });
+        }
+    }
+    return { sources, agentRoutes };
+}
+function resolveLitLoopDir(repoRoot) {
+    for (const anchor of [import.meta.url, `${repoRoot}/package.json`]) {
+        try {
+            return dirname(createRequire(anchor).resolve("@litcodex/lit-loop/package.json"));
+        }
+        catch (error) {
+            if (!(error instanceof Error)) {
+                throw error;
+            }
+            // Try the next package anchor.
+        }
+    }
+    throw missingAgents({ repoRoot });
+}
+function missingAgents(details) {
+    return new InstallError("LITCODEX_INSTALL_AGENTS_MISSING", "Bundled litwork agent roles are missing.", details);
+}

package/dist/install/auth-mode.d.ts

@@ -0,0 +1,4 @@
+import type { ReadonlyFsLike } from "./codex.js";
+export type AuthMode = "chatgpt" | "api-key" | "unknown";
+/** Classify the Codex auth mode from `CODEX_HOME/auth.json`. Never throws. */
+export declare function detectAuthMode(fs: ReadonlyFsLike, codexHome: string): AuthMode;

package/dist/install/auth-mode.js

@@ -0,0 +1,26 @@
+import { join } from "node:path";
+/** Classify the Codex auth mode from `CODEX_HOME/auth.json`. Never throws. */
+export function detectAuthMode(fs, codexHome) {
+    const authPath = join(codexHome, "auth.json");
+    if (!fs.existsSync(authPath))
+        return "unknown";
+    try {
+        const raw = JSON.parse(fs.readFileSync(authPath, "utf8"));
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return "unknown";
+        const record = raw;
+        const tokens = record["tokens"];
+        if (typeof tokens === "object" &&
+            tokens !== null &&
+            !Array.isArray(tokens) &&
+            typeof tokens["id_token"] === "string") {
+            return "chatgpt";
+        }
+        if (typeof record["OPENAI_API_KEY"] === "string")
+            return "api-key";
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/install/bundled-skill-manifests.d.ts

@@ -0,0 +1,25 @@
+export declare const HANDOFF_SOURCE_HASHES: {
+    readonly "SKILL.md": "e5bbd253dfa5b5baa9739dfaebc458003daab43cb27c4a407423da1e7a31dec6";
+    readonly "evals/evals.json": "0a70f0d149e59641100c7dcf8b9f2f1c0ceae57b98518e165f08088f2c2484da";
+    readonly "examples/HANDOFF-example-generic-auth-refactor.md": "43c767e573ac8c8900832d2b7a92ee1e83fd2d3d794fe2c82ecef87e5737f2a3";
+    readonly "templates/HANDOFF.md": "2a795a06e7bb81a57e6675ae70ed26db0dbfdb792c01f0a60f96f02cbef49fbd";
+};
+export declare const SCIENTIFIC_VISUALIZATION_SOURCE_HASHES: {
+    readonly "SKILL.md": "d6084a7e3adf283157820ea20dbe1b46fa22fa1be17b138ab1203be550f4ef68";
+    readonly "assets/color_palettes.py": "ffea28da930406ecb11bbeaebfc530dfac40b772827a7653f449cb3b0bb35309";
+    readonly "assets/nature.mplstyle": "6a7343788bf772b7e1bc813d094f7bafa97c1e5544586e7b76002ad8547229b6";
+    readonly "assets/presentation.mplstyle": "e3ee23f0470d7fb07a0be75cd1210e231becfc2f5267aa404e4186aa077a3339";
+    readonly "assets/publication.mplstyle": "18447af3bc47310d23fc27255413c23d8bbe3ff441463cc54fcecdfacd205bea";
+    readonly "evals/evals.json": "366dc61b6e042f08f28bf33f2534feea80219d771b84497ec7094b30263e935b";
+    readonly "references/color_palettes.md": "0298691c8de8379570488a7b7768663971bc20af1fb05d464c5438d43a21dcfa";
+    readonly "references/journal_requirements.md": "56fdde590a9d778547dbcb609b77d86f1f31865e803bcecca5d8c4c72b91b3c7";
+    readonly "references/matplotlib_examples.md": "c99cd4f83e2452773e9580e2fa0984e61433c7a9b57ca0d2562dc400dfe4f83d";
+    readonly "references/mdanalysis_martini_visualization.md": "abcb3c61f1c3984ba9014d9ae197b726d23c1df844dc90988ecc4d8f0e349bfe";
+    readonly "references/publication_guidelines.md": "d9f5d0f115872c4c190a11d83432d44635e38ef9f1740db471fcc70f4c91dd2c";
+    readonly "references/seaborn_for_publications.md": "2da2147ae8974b4b5d16096c1484b982d5d1e5f91113808ebfd12111a0a6597a";
+    readonly "scripts/figure_export.py": "b22c7708afaf2a1cfa4f821eb9230d4262f1d52948af7f0815855aa9d0960403";
+    readonly "scripts/style_presets.py": "e9d450bd4ab6b11303b02d5029177c8d49466cc597648d12de0ecdb7620f64c4";
+    readonly "tests/test_figure_export.py": "b18414369e6721ad93d417914114d71af006248675eb20bb1f4989c48ec9a58e";
+    readonly "tests/test_style_presets.py": "ff0e190196480848f1fea2398220038771f386ee7967a0ef122b0dfbca3aed46";
+};
+export declare const SCIENTIFIC_VISUALIZATION_SOURCE_MANIFEST = "b1b8f1bf8791daecdbb00dc70631cd955e72976664d302af0bc81e218b9cec3b";

package/dist/install/bundled-skill-manifests.js

@@ -0,0 +1,25 @@
+export const HANDOFF_SOURCE_HASHES = {
+    "SKILL.md": "e5bbd253dfa5b5baa9739dfaebc458003daab43cb27c4a407423da1e7a31dec6",
+    "evals/evals.json": "0a70f0d149e59641100c7dcf8b9f2f1c0ceae57b98518e165f08088f2c2484da",
+    "examples/HANDOFF-example-generic-auth-refactor.md": "43c767e573ac8c8900832d2b7a92ee1e83fd2d3d794fe2c82ecef87e5737f2a3",
+    "templates/HANDOFF.md": "2a795a06e7bb81a57e6675ae70ed26db0dbfdb792c01f0a60f96f02cbef49fbd",
+};
+export const SCIENTIFIC_VISUALIZATION_SOURCE_HASHES = {
+    "SKILL.md": "d6084a7e3adf283157820ea20dbe1b46fa22fa1be17b138ab1203be550f4ef68",
+    "assets/color_palettes.py": "ffea28da930406ecb11bbeaebfc530dfac40b772827a7653f449cb3b0bb35309",
+    "assets/nature.mplstyle": "6a7343788bf772b7e1bc813d094f7bafa97c1e5544586e7b76002ad8547229b6",
+    "assets/presentation.mplstyle": "e3ee23f0470d7fb07a0be75cd1210e231becfc2f5267aa404e4186aa077a3339",
+    "assets/publication.mplstyle": "18447af3bc47310d23fc27255413c23d8bbe3ff441463cc54fcecdfacd205bea",
+    "evals/evals.json": "366dc61b6e042f08f28bf33f2534feea80219d771b84497ec7094b30263e935b",
+    "references/color_palettes.md": "0298691c8de8379570488a7b7768663971bc20af1fb05d464c5438d43a21dcfa",
+    "references/journal_requirements.md": "56fdde590a9d778547dbcb609b77d86f1f31865e803bcecca5d8c4c72b91b3c7",
+    "references/matplotlib_examples.md": "c99cd4f83e2452773e9580e2fa0984e61433c7a9b57ca0d2562dc400dfe4f83d",
+    "references/mdanalysis_martini_visualization.md": "abcb3c61f1c3984ba9014d9ae197b726d23c1df844dc90988ecc4d8f0e349bfe",
+    "references/publication_guidelines.md": "d9f5d0f115872c4c190a11d83432d44635e38ef9f1740db471fcc70f4c91dd2c",
+    "references/seaborn_for_publications.md": "2da2147ae8974b4b5d16096c1484b982d5d1e5f91113808ebfd12111a0a6597a",
+    "scripts/figure_export.py": "b22c7708afaf2a1cfa4f821eb9230d4262f1d52948af7f0815855aa9d0960403",
+    "scripts/style_presets.py": "e9d450bd4ab6b11303b02d5029177c8d49466cc597648d12de0ecdb7620f64c4",
+    "tests/test_figure_export.py": "b18414369e6721ad93d417914114d71af006248675eb20bb1f4989c48ec9a58e",
+    "tests/test_style_presets.py": "ff0e190196480848f1fea2398220038771f386ee7967a0ef122b0dfbca3aed46",
+};
+export const SCIENTIFIC_VISUALIZATION_SOURCE_MANIFEST = "b1b8f1bf8791daecdbb00dc70631cd955e72976664d302af0bc81e218b9cec3b";

package/dist/install/bundled-skills.d.ts

@@ -0,0 +1,7 @@
+import type { ReadonlyFsLike } from "./codex.js";
+export interface BundledSkillReport {
+    readonly handoffInstalled: boolean;
+    readonly scientificVisualizationInstalled: boolean;
+}
+export declare function probeBundledSkills(fs: ReadonlyFsLike, marketplaceRoot: string): BundledSkillReport;
+export declare function payloadExact(fs: Pick<ReadonlyFsLike, "listFilesRecursive" | "readFileBufferSync">, root: string, expectedHashes: Readonly<Record<string, string>>, expectedManifest?: string, manifestPrefix?: string): boolean;

package/dist/install/bundled-skills.js

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { HANDOFF_SOURCE_HASHES, SCIENTIFIC_VISUALIZATION_SOURCE_HASHES, SCIENTIFIC_VISUALIZATION_SOURCE_MANIFEST, } from "./bundled-skill-manifests.js";
+const HANDOFF_FILES = ["SKILL.md"];
+const SCIENTIFIC_VISUALIZATION_FILES = ["SKILL.md", "scripts/dependency-preflight.py"];
+const VENDOR_LEGAL_FILES = [
+    "NOTICE",
+    "licenses/022_handoff-MIT.txt",
+    "licenses/045_scientific-visualization-MIT.txt",
+    "provenance/022_handoff.md",
+    "provenance/045_scientific-visualization.md",
+];
+export function probeBundledSkills(fs, marketplaceRoot) {
+    const pluginRoot = join(marketplaceRoot, "plugins", "litcodex");
+    const skillsRoot = join(pluginRoot, "skills");
+    const vendorRoot = join(pluginRoot, "vendor");
+    const handoffRoot = join(skillsRoot, "lit-handoff");
+    const scientificVisualizationRoot = join(skillsRoot, "lit-scientific-visualization");
+    const vendorComplete = payloadComplete(fs, vendorRoot, VENDOR_LEGAL_FILES);
+    return {
+        handoffInstalled: vendorComplete &&
+            payloadComplete(fs, handoffRoot, HANDOFF_FILES) &&
+            payloadExact(fs, join(vendorRoot, "handoff"), HANDOFF_SOURCE_HASHES),
+        scientificVisualizationInstalled: vendorComplete &&
+            payloadComplete(fs, scientificVisualizationRoot, SCIENTIFIC_VISUALIZATION_FILES) &&
+            payloadExact(fs, join(vendorRoot, "scientific-visualization"), SCIENTIFIC_VISUALIZATION_SOURCE_HASHES, SCIENTIFIC_VISUALIZATION_SOURCE_MANIFEST, "045_scientific-visualization"),
+    };
+}
+function payloadComplete(fs, root, files) {
+    return files.every((path) => fs.existsSync(join(root, path)));
+}
+export function payloadExact(fs, root, expectedHashes, expectedManifest, manifestPrefix) {
+    const listFilesRecursive = fs.listFilesRecursive;
+    const readFileBufferSync = fs.readFileBufferSync;
+    if (listFilesRecursive === undefined || readFileBufferSync === undefined)
+        return false;
+    try {
+        const expectedPaths = Object.keys(expectedHashes).sort();
+        const actualEntries = [...listFilesRecursive(root)].map((entry) => typeof entry === "string"
+            ? { relativePath: normalizeRelativePath(entry), kind: "file" }
+            : { relativePath: normalizeRelativePath(entry.relativePath), kind: entry.kind });
+        if (actualEntries.some((entry) => entry.kind !== "file"))
+            return false;
+        const actualPaths = actualEntries.map((entry) => entry.relativePath).sort();
+        if (!samePaths(actualPaths, expectedPaths))
+            return false;
+        const records = [];
+        for (const path of expectedPaths) {
+            const digest = sha256(readFileBufferSync(join(root, path)));
+            if (digest !== expectedHashes[path])
+                return false;
+            records.push(`${digest}  ${manifestPrefix}/${path}\n`);
+        }
+        return expectedManifest === undefined || sha256(records.join("")) === expectedManifest;
+    }
+    catch (error) {
+        if (error instanceof Error)
+            return false;
+        throw error;
+    }
+}
+function normalizeRelativePath(path) {
+    return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function samePaths(actual, expected) {
+    return actual.length === expected.length && actual.every((path, index) => path === expected[index]);
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}

package/dist/install/capability-preflight-error.d.ts

@@ -0,0 +1,3 @@
+import { InstallError } from "./errors.js";
+import type { HostCapabilities } from "./host-capabilities.js";
+export declare function capabilityPreflightError(capabilities: HostCapabilities, codexBin?: string): InstallError;

package/dist/install/capability-preflight-error.js

@@ -0,0 +1,33 @@
+import { InstallError } from "./errors.js";
+/**
+ * Name the Codex the probe actually ran. The resolved binary is not always the one
+ * the user expects: npx puts `node_modules/.bin` at the front of PATH, so an install
+ * started inside a repository that pins @openai/codex probes that pin instead of the
+ * system Codex, and the failure otherwise reads identically.
+ */
+function resolvedClause(codexBin) {
+    return codexBin === undefined ? "" : ` The resolved Codex was ${codexBin}.`;
+}
+export function capabilityPreflightError(capabilities, codexBin) {
+    const reason = capabilities.concurrency.reason;
+    const resolved = resolvedClause(codexBin);
+    if (reason === "codex-version-too-old") {
+        return new InstallError("LITCODEX_INSTALL_CODEX_VERSION_UNSUPPORTED", `LitCodex requires Codex CLI 0.144.0 or newer; upgrade Codex and rerun install.${resolved}`, { capabilities });
+    }
+    if (reason === "codex-version-unrecognized") {
+        return new InstallError("LITCODEX_INSTALL_CODEX_VERSION_UNSUPPORTED", `Could not determine the Codex CLI version from \`codex --version\` stdout or stderr; verify the Codex executable and rerun install.${resolved}`, { capabilities });
+    }
+    if (reason === "codex-version-prerelease") {
+        return new InstallError("LITCODEX_INSTALL_CODEX_VERSION_UNSUPPORTED", `This Codex CLI build is not a supported stable release; install a stable Codex version and rerun install.${resolved}`, { capabilities });
+    }
+    if (reason === "host-probe-timeout") {
+        return new InstallError("LITCODEX_INSTALL_HOST_PROBE_FAILED", `Codex host validation timed out; no install mutation was attempted.${resolved}`, { capabilities });
+    }
+    // The baseline probe replays the same doctor call with zero LitCodex overrides.
+    // When that also fails, the existing Codex configuration on this machine is what
+    // the resolved binary cannot load, and LitCodex's managed settings are innocent.
+    if (reason === "host-config-incompatible") {
+        return new InstallError("LITCODEX_INSTALL_HOST_CONFIG_INCOMPATIBLE", `The existing Codex configuration on this machine could not be loaded by the Codex that ran, with or without LitCodex settings; no install mutation was attempted.${resolved} This usually means that Codex is older than the one that last wrote the configuration.`, { capabilities });
+    }
+    return new InstallError("LITCODEX_INSTALL_CONFIG_WRITE_FAILED", `Codex strict config rejected LitCodex managed settings; no install mutation was attempted.${resolved}`, { capabilities });
+}

package/dist/install/codex-version.d.ts

@@ -0,0 +1,17 @@
+export type CodexVersionSupport = {
+    readonly kind: "tested";
+    readonly version: string;
+} | {
+    readonly kind: "newer-stable";
+    readonly version: string;
+} | {
+    readonly kind: "too-old";
+    readonly version: string;
+} | {
+    readonly kind: "prerelease";
+    readonly version: string;
+} | {
+    readonly kind: "unrecognized";
+    readonly version: null;
+};
+export declare function classifyCodexVersion(stdout: string | undefined, stderr?: string): CodexVersionSupport;

package/dist/install/codex-version.js

@@ -0,0 +1,37 @@
+const TESTED_CODEX_VERSIONS = ["0.144.0", "0.144.1"];
+const MINIMUM_SUPPORTED = { major: 0, minor: 144, patch: 0 };
+const VERSION_PATTERN = /^[ \t]*codex-cli[ \t]+(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?(?=\s|$)/u;
+export function classifyCodexVersion(stdout, stderr) {
+    const match = findVersion(stdout) ?? findVersion(stderr);
+    const major = numberPart(match?.[1]);
+    const minor = numberPart(match?.[2]);
+    const patch = numberPart(match?.[3]);
+    if (match === undefined || match === null || major === null || minor === null || patch === null) {
+        return { kind: "unrecognized", version: null };
+    }
+    const version = `${major}.${minor}.${patch}${match[4] ?? ""}`;
+    if (match[4] !== undefined)
+        return { kind: "prerelease", version };
+    if (TESTED_CODEX_VERSIONS.some((candidate) => candidate === version)) {
+        return { kind: "tested", version };
+    }
+    return compareVersion({ major, minor, patch }, MINIMUM_SUPPORTED) < 0
+        ? { kind: "too-old", version }
+        : { kind: "newer-stable", version };
+}
+function findVersion(output) {
+    return output?.match(VERSION_PATTERN) ?? null;
+}
+function numberPart(value) {
+    if (value === undefined)
+        return null;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+}
+function compareVersion(left, right) {
+    if (left.major !== right.major)
+        return left.major - right.major;
+    if (left.minor !== right.minor)
+        return left.minor - right.minor;
+    return left.patch - right.patch;
+}

package/dist/install/codex.d.ts

@@ -0,0 +1,56 @@
+import type { PayloadEntry } from "./file-walk.js";
+/** 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;
+    readFileBufferSync?(path: string): Uint8Array;
+    listFilesRecursive?(root: string): readonly (string | PayloadEntry)[];
+}
+export interface SpawnOptions {
+    readonly stdio: "inherit" | "pipe";
+    readonly timeout?: number;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly shell?: false;
+    readonly windowsVerbatimArguments?: boolean;
+}
+export interface CodexSpawnInvocation {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly shell: false;
+    readonly windowsVerbatimArguments: boolean;
+}
+/** The spawn shape used by the executor + probes (argv array; never a shell string). */
+export type SpawnLike = (cmd: string, args: readonly string[], opts: SpawnOptions) => {
+    status: number | null;
+    error?: Error;
+    stdout?: string;
+    stderr?: string;
+};
+export declare function codexSpawnInvocation(command: string, args: readonly string[], env: NodeJS.ProcessEnv, platform?: NodeJS.Platform): CodexSpawnInvocation;
+/** 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, platform?: NodeJS.Platform): string | null;
+/** True if `codex plugin marketplace list` stdout names the LitCodex marketplace. Read-only. */
+export declare function probeMarketplaceRegistered(codexBin: string, spawn: SpawnLike): boolean;
+export interface MarketplaceRegistration {
+    readonly name: string;
+    readonly source: string | null;
+    readonly sourceType: string | null;
+}
+/** Return the registered LitCodex source from Codex's structured marketplace listing. */
+export declare function probeMarketplaceRegistration(codexBin: string, spawn: SpawnLike): MarketplaceRegistration | null;
+/**
+ * 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;