@litfamily/litcodex 1.0.0

package/dist/install/index.js

@@ -0,0 +1,403 @@
+// M12 / T17 — installer barrel + process-facing route entrypoints (S12 §cli routes).
+//
+// These are the functions the top-level dispatcher (src/cli.ts) calls for the `install`/`doctor`/
+// `uninstall` routes. They own the ONE real default `spawn` (always `codex`, never an exec-wrapper), parse
+// argv into typed `InstallOptions`, and return an integer exit code. `--dry-run` returns BEFORE any
+// spawn or fs write (renders the plan only). Unknown/bad flags exit 1.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import readline from "node:readline/promises";
+import { migrateCodexConfig, readLitCodexOutputStyleId } from "../config-migration/index.js";
+import { humanLabel, preflightLabel, renderBanner, renderInstallFailure, renderInstallReceipt, renderPreflightIntro, renderStepIntro, renderStepResult, Spinner, shouldDecorate, } from "../ui.js";
+import { codexSpawnInvocation, resolveCodexHome } from "./codex.js";
+import { renderDoctorText, runDoctor } from "./doctor.js";
+import { exitCodeForInstallError, InstallError, toErrorJson } from "./errors.js";
+import { executeInstallPlan } from "./execute.js";
+import { listPayloadEntries, readRegularFileBuffer } from "./file-walk.js";
+import { promptModelRoute, renderModelRouteSummary, waitForModelRouteConfirmation } from "./install-model-prompt.js";
+import { hasExplicitModelRouteFlags, parseInstallOptions } from "./install-options.js";
+import { renderPlainInstallResult } from "./install-output.js";
+import { resolveBundledMarketplaceSource } from "./package-root.js";
+import { buildInstallPlan } from "./plan.js";
+import { renderInstallPlan } from "./render-plan.js";
+import { createBlockingSpinnerMotion } from "./spinner-motion.js";
+import { runUninstall } from "./uninstall.js";
+export { renderDoctorText, runDoctor } from "./doctor.js";
+export { INSTALL_ERROR_CODES, InstallError, toErrorJson } from "./errors.js";
+export { executeInstallPlan } from "./execute.js";
+export { renderCapability } from "./install-output.js";
+export { buildInstallPlan } from "./plan.js";
+export { INSTALL_PLAN_HEADER, renderInstallPlan } from "./render-plan.js";
+/** The real default spawn: argv array, with Windows script shims routed through ComSpec. */
+const realSpawn = (cmd, args, opts) => {
+    const invocation = codexSpawnInvocation(cmd, args, opts.env ?? process.env);
+    const res = spawnSync(invocation.command, [...invocation.args], {
+        stdio: opts.stdio,
+        encoding: "utf8",
+        timeout: opts.timeout,
+        shell: invocation.shell,
+        windowsVerbatimArguments: invocation.windowsVerbatimArguments || opts.windowsVerbatimArguments === true,
+        ...(opts.env === undefined ? {} : { env: opts.env }),
+    });
+    const out = {
+        status: res.status,
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? "",
+    };
+    if (res.error) {
+        out.error = res.error;
+    }
+    return out;
+};
+const realFs = {
+    existsSync,
+    readFileSync: (p, enc) => readFileSync(p, enc),
+    readFileBufferSync: readRegularFileBuffer,
+    listFilesRecursive: listPayloadEntries,
+};
+const realWriteFs = {
+    existsSync,
+    mkdirSync: (p, o) => {
+        mkdirSync(p, o);
+    },
+    readdirSync: (p) => readdirSync(p),
+    readFileSync: (p, e) => readFileSync(p, e),
+    writeFileSync: (p, d) => {
+        writeFileSync(p, d);
+    },
+};
+function defaultIo() {
+    return {
+        stdout: process.stdout,
+        stderr: process.stderr,
+        env: process.env,
+        repoRoot: process.cwd(),
+    };
+}
+const STYLE_MENU = [
+    { styleId: "off", label: "None / keep current", hint: "Leave output style unchanged" },
+    { styleId: "asd-ste100", label: "ASD-STE100 (English)", hint: "Simplified Technical English" },
+    {
+        styleId: "asd-ste100-ko",
+        label: "ASD-STE100 (한국어)",
+        hint: "Simplified Technical English (Korean)",
+    },
+    { styleId: "eli5", label: "ELI5 (English)", hint: "Explain Like I'm 5" },
+    { styleId: "eli5-ko", label: "ELI5 (한국어)", hint: "ELI5 (Korean)" },
+];
+const PACKAGE_VERSION = createRequire(import.meta.url)("../../package.json").version;
+function formatStyleChoice(index, label, hint) {
+    return `  ${String(index).padStart(2, " ")}. ${label} - ${hint}`;
+}
+async function chooseStyleIndex(rl, stdout, defaultIndex) {
+    stdout.write("\nChoose an output style for LitCodex responses.\n");
+    for (const [i, choice] of STYLE_MENU.entries()) {
+        stdout.write(`${formatStyleChoice(i, choice.label, choice.hint)}\n`);
+    }
+    const answer = ((await rl.question(`Select 0-${String(STYLE_MENU.length - 1)} [${String(defaultIndex)}]: `)) ?? "").trim();
+    if (answer.length === 0)
+        return defaultIndex;
+    const selected = Number.parseInt(answer, 10);
+    if (Number.isInteger(selected) && selected >= 0 && selected < STYLE_MENU.length)
+        return selected;
+    throw new InstallError("LITCODEX_INSTALL_BAD_FLAG", `Invalid style selection: ${answer}`, { flag: "--style" });
+}
+function interactiveInstall(opts, io) {
+    const isTTY = process.stdin.isTTY === true && Boolean(io.stdout.isTTY);
+    return isTTY && !opts.noTui && !opts.json && !opts.yes && !opts.dryRun && io.env["CI"] === undefined;
+}
+function installReadline(opts, io) {
+    return readline.createInterface({
+        input: process.stdin,
+        output: io.stdout,
+        // Plain prompts must not re-enable readline's cursor escapes just because stdout is a TTY.
+        terminal: shouldDecorate({
+            isTty: Boolean(io.stdout.isTTY),
+            env: io.env,
+            noTui: opts.noTui,
+            json: opts.json,
+        }),
+    });
+}
+/**
+ * Contract §Prompt order: lead model+effort then helper model+effort, before the product's own
+ * style prompt. Skipped (defaults kept) for --yes, non-TTY, --json, --no-tui, CI, or any explicit
+ * model-route flag. Returns the (possibly updated) options plus whether prompting happened.
+ */
+async function promptModelRouteIfNeeded(args, opts, io) {
+    if (!interactiveInstall(opts, io) || hasExplicitModelRouteFlags(args)) {
+        return { opts, prompted: false };
+    }
+    const rl = installReadline(opts, io);
+    try {
+        const route = await promptModelRoute(rl, io.stdout);
+        return {
+            opts: {
+                ...opts,
+                profile: route.profile,
+                leadModel: route.leadModel,
+                effort: route.effort,
+                subagentModel: route.subagentModel,
+                subagentEffort: route.subagentEffort,
+            },
+            prompted: true,
+        };
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Contract §Summary card: print the route and wait for Enter before the first write. */
+async function confirmModelRouteSummary(opts, io, color) {
+    io.stdout.write(renderModelRouteSummary(opts, opts.codexHome));
+    const rl = installReadline(opts, io);
+    try {
+        await waitForModelRouteConfirmation(rl, color);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function promptOutputStyleIfNeeded(opts, io) {
+    if (opts.style !== undefined)
+        return opts.style;
+    if (!interactiveInstall(opts, io))
+        return undefined;
+    let currentStyleId;
+    try {
+        const configContent = readFileSync(join(opts.codexHome, "config.toml"), "utf8");
+        currentStyleId = readLitCodexOutputStyleId(configContent);
+    }
+    catch {
+        // config absent or unreadable — leave default at 0
+    }
+    const defaultIndex = currentStyleId !== undefined
+        ? Math.max(0, STYLE_MENU.findIndex((m) => m.styleId === currentStyleId))
+        : 0;
+    const rl = installReadline(opts, io);
+    try {
+        const index = await chooseStyleIndex(rl, io.stdout, defaultIndex);
+        return STYLE_MENU[index]?.styleId ?? "off";
+    }
+    finally {
+        rl.close();
+    }
+}
+function emitError(io, err) {
+    const json = toErrorJson(err);
+    io.stderr.write(`${JSON.stringify(json)}\n`);
+    io.stderr.write(`[litcodex] ${json.error.message}\n`);
+    return err instanceof InstallError ? exitCodeForInstallError(err.code) : 1;
+}
+function writeCommandBanner(io, args) {
+    if (args.includes("--json") || args.includes("--no-tui"))
+        return;
+    io.stdout.write(renderBanner({
+        version: PACKAGE_VERSION,
+        env: io.env,
+        color: shouldDecorate({
+            isTty: Boolean(io.stdout.isTTY),
+            env: io.env,
+            noTui: args.includes("--no-tui"),
+            json: args.includes("--json"),
+        }) && !args.includes("--dry-run"),
+    }));
+}
+/** `litcodex install [flags]` — render plan (dry-run) or execute against `codex`. */
+export async function runInstallCli(args, io = defaultIo()) {
+    let opts;
+    try {
+        opts = parseInstallOptions(args, io);
+    }
+    catch (err) {
+        return emitError(io, err instanceof Error ? err : new Error(String(err)));
+    }
+    const decorate = shouldDecorate({
+        isTty: Boolean(io.stdout.isTTY),
+        env: io.env,
+        noTui: opts.noTui,
+        json: opts.json,
+    });
+    const banner = !opts.json && !opts.noTui
+        ? renderBanner({ version: PACKAGE_VERSION, env: io.env, color: decorate && !opts.dryRun })
+        : "";
+    if (banner)
+        io.stdout.write(banner);
+    let prompted = false;
+    let effectiveStyle;
+    try {
+        const routePrompt = await promptModelRouteIfNeeded(args, opts, io);
+        opts = routePrompt.opts;
+        prompted = routePrompt.prompted;
+        effectiveStyle = await promptOutputStyleIfNeeded(opts, io);
+        if (prompted)
+            await confirmModelRouteSummary(opts, io, decorate);
+    }
+    catch (err) {
+        return emitError(io, err instanceof Error ? err : new Error(String(err)));
+    }
+    const plan = buildInstallPlan(opts);
+    if (opts.dryRun) {
+        // ZERO spawns, ZERO fs writes: render and return.
+        io.stdout.write(`${renderInstallPlan(plan)}\n`);
+        return 0;
+    }
+    let result;
+    let activeSpinner;
+    let activityPending = false;
+    let marketplaceSource;
+    try {
+        if (!args.includes("--repo"))
+            marketplaceSource = resolveBundledMarketplaceSource();
+        const executeDeps = {
+            spawn: realSpawn,
+            fs: realFs,
+            env: io.env,
+            now: () => Date.now(),
+            repoRoot: io.repoRoot,
+            migrateConfig: migrateCodexConfig,
+            force: opts.force,
+            codexHome: opts.codexHome,
+            writeFs: realWriteFs,
+            profile: opts.profile,
+            leadModel: opts.leadModel,
+            effort: opts.effort,
+            subagentModel: opts.subagentModel,
+            subagentEffort: opts.subagentEffort,
+            ...(effectiveStyle === undefined ? {} : { style: effectiveStyle }),
+            reconfigure: opts.reconfigure,
+            enforceCapabilityPreflight: true,
+            ...(marketplaceSource === undefined ? {} : { marketplaceSourceDir: marketplaceSource.root }),
+        };
+        if (decorate) {
+            io.stdout.write(`${renderPreflightIntro(opts.codexHome, true)}\n`);
+            const motion = io.stdout === process.stdout ? createBlockingSpinnerMotion(process.stdout.fd) : undefined;
+            const spinner = new Spinner(io.stdout, true, motion);
+            activeSpinner = spinner;
+            let stepIndex = 0;
+            result = await executeInstallPlan(plan, {
+                ...executeDeps,
+                onPreflightStart: (stage) => {
+                    activityPending = true;
+                    spinner.start(preflightLabel(stage));
+                },
+                onPreflightEnd: (preflightResult) => {
+                    const label = `${preflightLabel(preflightResult.stage)}: ${preflightResult.detail}`;
+                    if (preflightResult.status === "ok")
+                        spinner.succeed(label);
+                    else
+                        spinner.skip(label);
+                    activityPending = false;
+                },
+                onStepStart: (step) => {
+                    activityPending = true;
+                    io.stdout.write(`${renderStepIntro(step, stepIndex, plan.length, opts.codexHome, true)}\n`);
+                    spinner.start(humanLabel(step.kind));
+                },
+                onStepEnd: (stepResult) => {
+                    const label = humanLabel(stepResult.kind);
+                    const completedLabel = `${label}: ${stepResult.detail}`;
+                    switch (stepResult.status) {
+                        case "ok":
+                            spinner.succeed(completedLabel);
+                            break;
+                        case "skipped":
+                            spinner.skip(completedLabel);
+                            break;
+                        case "failed":
+                            spinner.fail(completedLabel);
+                            break;
+                    }
+                    io.stdout.write(renderStepResult(stepResult, true));
+                    io.stdout.write("\n");
+                    stepIndex += 1;
+                    activityPending = false;
+                },
+            });
+        }
+        else {
+            result = await executeInstallPlan(plan, executeDeps);
+        }
+    }
+    catch (err) {
+        if (decorate) {
+            if (activityPending)
+                activeSpinner?.fail("Current operation stopped");
+            io.stderr.write(renderInstallFailure(toErrorJson(err), true));
+            return err instanceof InstallError ? exitCodeForInstallError(err.code) : 1;
+        }
+        return emitError(io, err instanceof Error ? err : new Error(String(err)));
+    }
+    finally {
+        marketplaceSource?.cleanup();
+    }
+    if (opts.json) {
+        io.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    else if (decorate) {
+        io.stdout.write(renderInstallReceipt(result, {
+            model: opts.leadModel,
+            effort: opts.effort,
+            subagentModel: opts.subagentModel,
+            subagentEffort: opts.subagentEffort,
+            color: true,
+        }));
+    }
+    else
+        io.stdout.write(renderPlainInstallResult(result));
+    return result.ok ? 0 : 3;
+}
+/**
+ * `litcodex doctor [--json]` — read-only health report. Exit 0 when ok, 4 otherwise.
+ * Doctor diagnostics never modify Codex config, install state, or plugin state. The top-level CLI
+ * envelope around an eligible successful interactive doctor may display a cached advisory notice
+ * and schedule a detached fixed-registry refresh that writes only `~/.litcodex/update-check.json`
+ * and its product-owned locks. Failed, --json, --dry-run, non-TTY, CI, and opt-out doctor runs remain
+ * side-effect-free.
+ */
+export function runDoctorCli(args, io = defaultIo()) {
+    const json = args.includes("--json");
+    writeCommandBanner(io, args);
+    const report = runDoctor({ spawn: realSpawn, fs: realFs, env: io.env, repoRoot: io.repoRoot });
+    if (json) {
+        io.stdout.write(`${JSON.stringify(report)}\n`);
+    }
+    else {
+        io.stdout.write(`${renderDoctorText(report)}\n`);
+    }
+    return report.ok ? 0 : 4;
+}
+/** `litcodex uninstall [--json]` — remove the registered plugin via `codex plugin remove`. */
+export function runUninstallCli(args, io = defaultIo()) {
+    const json = args.includes("--json");
+    writeCommandBanner(io, args);
+    const codexHome = resolveCodexHome(io.env);
+    const env = io.env;
+    const codexBin = env["CODEX_BIN"]?.trim() && existsSync(env["CODEX_BIN"].trim()) ? env["CODEX_BIN"].trim() : "codex";
+    const result = runUninstall({
+        codexBin,
+        codexHome,
+        spawn: realSpawn,
+        fs: {
+            existsSync,
+            readdirSync: (path) => readdirSync(path),
+            rmSync,
+            readFileSync: (path, enc) => readFileSync(path, enc),
+            writeFileSync: (path, data) => {
+                writeFileSync(path, data);
+            },
+        },
+    });
+    if (json) {
+        io.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    else if (result.ok) {
+        io.stdout.write("litcodex uninstall: complete\n");
+    }
+    else {
+        io.stderr.write("[litcodex] uninstall: codex plugin remove failed\n");
+    }
+    return result.ok ? 0 : 3;
+}

package/dist/install/install-model-prompt.d.ts

@@ -0,0 +1,28 @@
+import type readline from "node:readline/promises";
+import type { Gpt56Profile, ReasoningEffort } from "../config-migration/gpt56-policy.js";
+export interface ModelRouteSelection {
+    readonly profile: Gpt56Profile;
+    readonly leadModel: string;
+    readonly effort: ReasoningEffort;
+    readonly subagentModel: string;
+    readonly subagentEffort: ReasoningEffort;
+}
+interface ConfirmationReader {
+    readonly question: (prompt: string) => Promise<string>;
+}
+interface MenuRow {
+    readonly model: string;
+    readonly profile: Gpt56Profile;
+    readonly effort: ReasoningEffort;
+    readonly note: string;
+}
+export declare const LEAD_MENU_ROWS: readonly MenuRow[];
+export declare const HELPER_MENU_ROWS: readonly MenuRow[];
+export declare function renderLeadModelMenu(): string;
+export declare function renderHelperModelMenu(): string;
+/** Contract §Summary card: printed before any write; the caller waits for Enter. */
+export declare function renderModelRouteSummary(route: Pick<ModelRouteSelection, "leadModel" | "effort" | "subagentModel" | "subagentEffort">, codexHome: string): string;
+export declare function waitForModelRouteConfirmation(rl: ConfirmationReader, color: boolean): Promise<void>;
+/** Run the contract's lead + helper prompts. The caller decides when prompting is allowed. */
+export declare function promptModelRoute(rl: readline.Interface, stdout: NodeJS.WritableStream): Promise<ModelRouteSelection>;
+export {};

package/dist/install/install-model-prompt.js

@@ -0,0 +1,82 @@
+// Installer model/effort prompts per the LitFamily installer choice contract
+// (plans/references/installer-choice-contract.md, 2026-08-29). LitCodex offers the OpenAI GPT-5.6
+// family only; every menu row is a supported model+effort pair, so a forbidden pair (luna+xhigh)
+// is never listed. Numbered readline menus, zero-based, default in brackets, no TUI library.
+import { dim } from "../ui-style.js";
+import { InstallError } from "./errors.js";
+export const LEAD_MENU_ROWS = [
+    { model: "gpt-6-astra", profile: "astra", effort: "xhigh", note: "— deepest reasoning, recommended lead" },
+    { model: "gpt-6-astra", profile: "astra", effort: "low", note: "— lower latency" },
+    { model: "gpt-6-astra", profile: "astra", effort: "medium", note: "" },
+    { model: "gpt-6-astra", profile: "astra", effort: "high", note: "" },
+    { model: "gpt-6-astra", profile: "astra", effort: "max", note: "" },
+    { model: "gpt-5.6-sol", profile: "sol", effort: "xhigh", note: "— deepest reasoning, slowest (recommended lead)" },
+    { model: "gpt-5.6-luna", profile: "luna", effort: "max", note: "— balanced (recommended helper)" },
+    { model: "gpt-5.6-sol", profile: "sol", effort: "high", note: "— same model, faster" },
+    { model: "gpt-5.6-terra", profile: "terra", effort: "xhigh", note: "" },
+];
+export const HELPER_MENU_ROWS = [
+    { model: "gpt-5.6-luna", profile: "luna", effort: "max", note: "— balanced (recommended helper)" },
+    { model: "gpt-6-astra", profile: "astra", effort: "low", note: "— explicit Astra helper" },
+    { model: "gpt-6-astra", profile: "astra", effort: "medium", note: "" },
+    { model: "gpt-6-astra", profile: "astra", effort: "high", note: "" },
+    { model: "gpt-6-astra", profile: "astra", effort: "xhigh", note: "" },
+    { model: "gpt-6-astra", profile: "astra", effort: "max", note: "" },
+    { model: "gpt-5.6-sol", profile: "sol", effort: "high", note: "— same model, faster" },
+    { model: "gpt-5.6-terra", profile: "terra", effort: "xhigh", note: "" },
+];
+function menuLine(index, row) {
+    return `   ${String(index)}. ${row.model.padEnd(13)} · ${row.effort.padEnd(8)}${row.note}`.replace(/\s+$/, "");
+}
+export function renderLeadModelMenu() {
+    return ["Choose the LEAD model (plans and reviews).", ...LEAD_MENU_ROWS.map((row, i) => menuLine(i, row))].join("\n");
+}
+export function renderHelperModelMenu() {
+    return [
+        "Choose the HELPER model (spawned/delegated agents).",
+        ...HELPER_MENU_ROWS.map((row, i) => menuLine(i, row)),
+    ].join("\n");
+}
+/** Contract §Summary card: printed before any write; the caller waits for Enter. */
+export function renderModelRouteSummary(route, codexHome) {
+    return [
+        "",
+        "  ╭─ MODEL ROUTE",
+        "  │ Provider   openai",
+        `  │ Lead       ${route.leadModel} · ${route.effort}`,
+        `  │ Helpers    ${route.subagentModel} · ${route.subagentEffort}`,
+        `  │ Writes     ${codexHome}/config.toml  (managed keys only)`,
+        "  ╰─ Enter to continue · Ctrl-C to abort (nothing written yet)",
+        "",
+    ].join("\n");
+}
+export async function waitForModelRouteConfirmation(rl, color) {
+    await rl.question(`  ${dim("Press Enter to install · Ctrl-C to abort:", color)} `);
+}
+async function chooseIndex(rl, stdout, menu, rowCount, defaultIndex) {
+    stdout.write(`\n${menu}\n`);
+    const answer = ((await rl.question(`Select 0-${String(rowCount - 1)} [${String(defaultIndex)}]: `)) ?? "").trim();
+    if (answer.length === 0)
+        return defaultIndex;
+    const selected = Number.parseInt(answer, 10);
+    if (Number.isInteger(selected) && selected >= 0 && selected < rowCount)
+        return selected;
+    throw new InstallError("LITCODEX_INSTALL_BAD_FLAG", `Invalid model selection: ${answer}`, { flag: "--model" });
+}
+/** Run the contract's lead + helper prompts. The caller decides when prompting is allowed. */
+export async function promptModelRoute(rl, stdout) {
+    const leadIndex = await chooseIndex(rl, stdout, renderLeadModelMenu(), LEAD_MENU_ROWS.length, 0);
+    const lead = LEAD_MENU_ROWS[leadIndex] ?? LEAD_MENU_ROWS[0];
+    const helperIndex = await chooseIndex(rl, stdout, renderHelperModelMenu(), HELPER_MENU_ROWS.length, 0);
+    const helper = HELPER_MENU_ROWS[helperIndex] ?? HELPER_MENU_ROWS[0];
+    if (lead === undefined || helper === undefined) {
+        throw new InstallError("LITCODEX_INSTALL_BAD_FLAG", "Model menu selection failed.", { flag: "--model" });
+    }
+    return {
+        profile: lead.profile,
+        leadModel: lead.model,
+        effort: lead.effort,
+        subagentModel: helper.model,
+        subagentEffort: helper.effort,
+    };
+}

package/dist/install/install-options.d.ts

@@ -0,0 +1,9 @@
+import type { InstallOptions } from "./types.js";
+export declare const OUTPUT_STYLE_IDS: readonly ["off", "asd-ste100", "asd-ste100-ko", "eli5", "eli5-ko"];
+export type OutputStyleId = (typeof OUTPUT_STYLE_IDS)[number];
+export declare function parseInstallOptions(args: readonly string[], context: {
+    readonly env: NodeJS.ProcessEnv;
+    readonly repoRoot: string;
+}): InstallOptions;
+/** True when any model-route flag was passed explicitly (prompting must then be skipped). */
+export declare function hasExplicitModelRouteFlags(args: readonly string[]): boolean;