@litfamily/litcodex 1.0.0

package/dist/install/install-options.js

@@ -0,0 +1,164 @@
+import { unsafeEffectiveRoute } from "../config-migration/gpt56-policy.js";
+import { resolveCodexHome } from "./codex.js";
+import { InstallError } from "./errors.js";
+import { managedMarketplaceRoot } from "./marketplace.js";
+const KNOWN_FLAGS = new Set([
+    "--dry-run",
+    "--no-tui",
+    "--codex-autonomous",
+    "--force",
+    "--json",
+    "--repo",
+    "--model",
+    "--effort",
+    "--subagent-model",
+    "--subagent-effort",
+    "--style",
+    "--yes",
+    "--reconfigure",
+    "--no-auto-update",
+    "--managed-upgrade",
+]);
+const LEAD_MODEL_CHOICES = {
+    "gpt-6-astra": { id: "gpt-6-astra", profile: "astra", defaultEffort: "xhigh" },
+    astra: { id: "gpt-6-astra", profile: "astra", defaultEffort: "xhigh" },
+    sol: { id: "gpt-5.6-sol", profile: "sol", defaultEffort: "xhigh" },
+    "gpt-5.6": { id: "gpt-5.6", profile: "sol", defaultEffort: "high" },
+    luna: { id: "gpt-5.6-luna", profile: "luna", defaultEffort: "max" },
+    terra: { id: "gpt-5.6-terra", profile: "terra", defaultEffort: "xhigh" },
+};
+const HELPER_MODEL_CHOICES = {
+    "gpt-6-astra": { id: "gpt-6-astra", profile: "astra", defaultEffort: "xhigh" },
+    astra: { id: "gpt-6-astra", profile: "astra", defaultEffort: "xhigh" },
+    luna: { id: "gpt-5.6-luna", profile: "luna", defaultEffort: "max" },
+    "gpt-5.6": { id: "gpt-5.6", profile: "sol", defaultEffort: "high" },
+    terra: { id: "gpt-5.6-terra", profile: "terra", defaultEffort: "xhigh" },
+};
+export const OUTPUT_STYLE_IDS = ["off", "asd-ste100", "asd-ste100-ko", "eli5", "eli5-ko"];
+export function parseInstallOptions(args, context) {
+    const valueIndexes = new Set(["--repo", "--model", "--effort", "--subagent-model", "--subagent-effort", "--style"]
+        .map((flag) => args.indexOf(flag) + 1)
+        .filter((index) => index > 0));
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token !== undefined && !valueIndexes.has(index) && token.startsWith("--") && !KNOWN_FLAGS.has(token)) {
+            throw badFlag(`unknown flag "${token}"`, token);
+        }
+    }
+    const codexHome = resolveCodexHome(context.env);
+    const style = styleChoice(args);
+    const lead = modelChoice(args);
+    const effort = effortChoice(args, lead);
+    const subagent = subagentModelChoice(args);
+    const subagentEffort = subagentEffortChoice(args, subagent);
+    return {
+        dryRun: args.includes("--dry-run"),
+        noTui: args.includes("--no-tui"),
+        autonomous: args.includes("--codex-autonomous"),
+        force: args.includes("--force"),
+        json: args.includes("--json"),
+        yes: args.includes("--yes"),
+        profile: lead.profile,
+        leadModel: lead.id,
+        effort,
+        subagentModel: subagent.id,
+        subagentEffort,
+        ...(style === undefined ? {} : { style }),
+        reconfigure: args.includes("--reconfigure") || args.includes("--managed-upgrade"),
+        codexHome,
+        repoUrl: repoUrl(args, codexHome),
+        repoRoot: context.repoRoot,
+    };
+}
+/** True when any model-route flag was passed explicitly (prompting must then be skipped). */
+export function hasExplicitModelRouteFlags(args) {
+    return ["--model", "--effort", "--subagent-model", "--subagent-effort"].some((flag) => args.includes(flag));
+}
+function modelChoice(args) {
+    const index = args.indexOf("--model");
+    const fallback = LEAD_MODEL_CHOICES["gpt-6-astra"];
+    if (index === -1)
+        return fallback;
+    const value = args[index + 1];
+    const choice = value === undefined ? undefined : LEAD_MODEL_CHOICES[value];
+    if (choice === undefined) {
+        throw badFlag("--model requires one of: gpt-6-astra, sol, gpt-5.6, luna, terra", "--model");
+    }
+    return choice;
+}
+function subagentModelChoice(args) {
+    const index = args.indexOf("--subagent-model");
+    const fallback = HELPER_MODEL_CHOICES["luna"];
+    if (index === -1)
+        return fallback;
+    const value = args[index + 1];
+    const choice = value === undefined ? undefined : HELPER_MODEL_CHOICES[value];
+    if (choice === undefined) {
+        throw badFlag("--subagent-model requires one of: gpt-6-astra, luna, gpt-5.6, terra", "--subagent-model");
+    }
+    return choice;
+}
+function effortChoice(args, lead) {
+    return pairedEffort(args, "--effort", lead);
+}
+function subagentEffortChoice(args, subagent) {
+    return pairedEffort(args, "--subagent-effort", subagent);
+}
+/** Resolve an effort flag against its model and fail closed on a policy-forbidden pair. */
+function pairedEffort(args, flag, model) {
+    const index = args.indexOf(flag);
+    let effort = model.defaultEffort;
+    if (index !== -1) {
+        const value = args[index + 1];
+        if (model.profile === "astra") {
+            if (!isAstraEffort(value)) {
+                throw badFlag(`${flag} requires one of: low, medium, high, xhigh, max`, flag);
+            }
+            effort = value;
+        }
+        else if (!isGpt56Effort(value)) {
+            throw badFlag(`${flag} requires one of: high, xhigh, max`, flag);
+        }
+        else {
+            effort = value;
+        }
+    }
+    const unsafe = unsafeEffectiveRoute({ model: model.id, model_reasoning_effort: effort });
+    if (unsafe !== null) {
+        throw badFlag(unsafe, flag);
+    }
+    return effort;
+}
+function isAstraEffort(value) {
+    return value === "low" || value === "medium" || value === "high" || value === "xhigh" || value === "max";
+}
+function isGpt56Effort(value) {
+    return value === "high" || value === "xhigh" || value === "max";
+}
+function styleChoice(args) {
+    const index = args.indexOf("--style");
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    if (value !== "off" &&
+        value !== "asd-ste100" &&
+        value !== "asd-ste100-ko" &&
+        value !== "eli5" &&
+        value !== "eli5-ko") {
+        throw badFlag("--style requires one of: off, asd-ste100, asd-ste100-ko, eli5, eli5-ko", "--style");
+    }
+    return value;
+}
+function repoUrl(args, codexHome) {
+    const index = args.indexOf("--repo");
+    if (index === -1)
+        return managedMarketplaceRoot(codexHome);
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+        throw badFlag("--repo requires a value (a local marketplace path or a git URL)", "--repo");
+    }
+    return value;
+}
+function badFlag(message, flag) {
+    return new InstallError("LITCODEX_INSTALL_BAD_FLAG", message, { flag });
+}

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

@@ -0,0 +1,4 @@
+import type { CapabilityReport } from "./host-capabilities.js";
+import type { InstallResult } from "./types.js";
+export declare function renderCapability(report: CapabilityReport): string;
+export declare function renderPlainInstallResult(result: InstallResult): string;

package/dist/install/install-output.js

@@ -0,0 +1,12 @@
+export function renderCapability(report) {
+    return `${report.status}; reason=${report.reason}; source=${report.observedSource}`;
+}
+export function renderPlainInstallResult(result) {
+    const lines = result.steps.map((step) => `${step.status} ${step.kind}: ${step.detail}`);
+    if (result.capabilities !== undefined) {
+        lines.push(`capability concurrency: ${renderCapability(result.capabilities.concurrency)}`);
+        lines.push(`probe-only explicit context/auto-compaction override: ${renderCapability(result.capabilities.autoCompaction)}`);
+    }
+    lines.push("litcodex install: complete");
+    return `${lines.join("\n")}\n`;
+}

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

@@ -0,0 +1,13 @@
+import type { InstallErrorEnvelope } from "./errors.js";
+import type { InstallResult, InstallStep, InstallStepResult } from "./types.js";
+export declare function renderStepIntro(step: InstallStep, index: number, total: number, codexHome: string, color: boolean): string;
+export declare function renderPreflightIntro(codexHome: string, color: boolean): string;
+export declare function renderStepResult(result: InstallStepResult, color: boolean): string;
+export declare function renderInstallReceipt(result: InstallResult, opts: {
+    readonly model: string;
+    readonly effort: import("../config-migration/gpt56-policy.js").ReasoningEffort;
+    readonly subagentModel?: string;
+    readonly subagentEffort?: string;
+    readonly color: boolean;
+}): string;
+export declare function renderInstallFailure(envelope: InstallErrorEnvelope, color: boolean): string;

package/dist/install/install-presentation.js

@@ -0,0 +1,165 @@
+import { amber, bold, dim, green, orange, red } from "../ui-style.js";
+import { routingReport } from "./agent-routing.js";
+const STEP_PRESENTATION = {
+    "marketplace-add": {
+        title: "MARKETPLACE",
+        purpose: "Prepare a stable local plugin source (no GitHub login required)",
+    },
+    "plugin-add": { title: "PLUGIN", purpose: "Install the LitCodex hooks, skills, and runtime components" },
+    "hooks-register": { title: "HOOKS", purpose: "Confirm Codex can route the UserPromptSubmit lifecycle hook" },
+    "agents-install": {
+        title: "SUBAGENTS",
+        purpose: "Install six selectable roles plus the native generic default route",
+    },
+    "config-update": {
+        title: "CONFIG",
+        purpose: "Apply recognized model and concurrency settings while retaining host-owned limits",
+    },
+    verify: { title: "HEALTH CHECK", purpose: "Verify the installed plugin, agents, config, and host capabilities" },
+};
+export function renderStepIntro(step, index, total, codexHome, color) {
+    const presentation = STEP_PRESENTATION[step.kind];
+    const ordinal = `${String(index + 1).padStart(2, "0")} / ${String(total).padStart(2, "0")}`;
+    return [
+        `  ${dim(ordinal, color)}  ${bold(amber(presentation.title, color), color)}`,
+        `       ${presentation.purpose}`,
+        `       ${dim(`target  ${stepTarget(step.kind, codexHome)}`, color)}`,
+    ].join("\n");
+}
+export function renderPreflightIntro(codexHome, color) {
+    return [
+        `  ${orange("╭─ PREPARING INSTALL", color)}`,
+        row("01 · Host", "host compatibility and model-context discovery"),
+        row("02 · Config", "read-only config validation against Codex strict schema"),
+        row("03 · Package", "package staging for the local marketplace"),
+        detailRow("Target", codexHome, color),
+        detailRow("Timing", "Each strict host probe may take up to 60 seconds.", color),
+        `  ${orange("╰─ Config writes begin only at install step 05 / 06", color)}`,
+        "",
+    ].join("\n");
+}
+export function renderStepResult(result, color) {
+    if (result.receipts === undefined || result.receipts.length === 0)
+        return "";
+    return `${result.receipts.map((line) => `       ${dim("│ codex", color)}  ${line}`).join("\n")}\n`;
+}
+export function renderInstallReceipt(result, opts) {
+    const model = opts.model;
+    const config = result.steps.find((step) => step.kind === "config-update")?.detail ?? "not reported";
+    const modelLabel = config.includes("preserved") ? "Requested model" : "Model";
+    const agents = result.steps.find((step) => step.kind === "agents-install")?.detail ?? "not reported";
+    const routes = result.steps.find((step) => step.kind === "agents-install")?.agentRoutes ?? [];
+    const routing = routingReport(routes);
+    const concurrency = result.capabilities?.concurrency;
+    const compaction = result.capabilities?.autoCompaction;
+    const contexts = result.capabilities?.modelContexts;
+    const context = contexts?.[model === "gpt-5.6-sol" ? "gpt-5.6" : model] ?? null;
+    const counts = summarizeSteps(result.steps);
+    const lines = [
+        "",
+        `  ${orange("╭─ INSTALL RECEIPT", opts.color)}`,
+        row("Status", result.ok ? green("Ready for Codex", opts.color) : red("Action required", opts.color)),
+        row("Codex host", hostLabel(concurrency?.observedSource)),
+        row(modelLabel, `${model} · ${opts.effort}`),
+        row("Subagent route", opts.subagentModel === undefined
+            ? "host default"
+            : `${opts.subagentModel} · ${opts.subagentEffort ?? "max"} (selected helper route)`),
+        row("Marketplace", `${result.codexHome}/marketplaces/litcodex`),
+        row("Subagents", agents),
+        row("Installed TOMLs", routing.installedTomls),
+        row("Preserved routes", routing.preservedRoutes),
+        row("Spawn override", routing.spawnOverride),
+        row("Effective child", routing.effectiveChild),
+        row("Config", config),
+        row("Concurrency", capabilityLimit(concurrency?.limit, "threads", concurrency?.status)),
+        row("Context", context === null
+            ? "host default (unset) · probe metadata unavailable"
+            : compaction?.status === "hard"
+                ? `host default (unset) · probe-only explicit override accepted at ${formatNumber(context)} tokens`
+                : `host default (unset) · metadata observed at ${formatNumber(context)} tokens · override probe ${compaction?.status ?? "unavailable"}`),
+        row("Auto-compact", compaction?.status === "hard"
+            ? "host default (unset) · probe-only explicit override accepted · hard"
+            : `host default (unset) · probe ${compaction?.status ?? "unavailable"}`),
+        row("Steps", `${counts.ok} completed · ${counts.skipped} no change · ${counts.failed} failed`),
+    ];
+    if (concurrency !== undefined)
+        lines.push(detailRow("Concurrency proof", concurrency.reason, opts.color));
+    if (compaction !== undefined)
+        lines.push(detailRow("Compaction proof", compaction.reason, opts.color));
+    if (config.includes("preserved"))
+        lines.push(detailRow("Next", "Review `litcodex install --dry-run`; use --reconfigure only by intent.", opts.color));
+    if (result.ok)
+        lines.push(`  ${orange("╰─ Installation complete", opts.color)}`);
+    lines.push("");
+    return lines.join("\n");
+}
+export function renderInstallFailure(envelope, color) {
+    const hostDetail = failureHostDetail(envelope.error.details);
+    return [
+        "",
+        `  ${red("╭─ INSTALL STOPPED", color)}`,
+        row("Code", envelope.error.code),
+        row("Reason", envelope.error.message),
+        row("Codex", hostDetail),
+        row("Safety", "No later install steps were run."),
+        row("Next", "Resolve the reason above, then rerun `litcodex install`."),
+        `  ${red("╰─ Exit without reporting success", color)}`,
+        "",
+    ].join("\n");
+}
+function stepTarget(kind, codexHome) {
+    switch (kind) {
+        case "marketplace-add":
+            return `${codexHome}/marketplaces/litcodex`;
+        case "plugin-add":
+            return "litcodex@litcodex";
+        case "hooks-register":
+            return "UserPromptSubmit";
+        case "agents-install":
+            return `${codexHome}/agents`;
+        case "config-update":
+            return `${codexHome}/config.toml`;
+        case "verify":
+            return "litcodex doctor";
+    }
+}
+function summarizeSteps(steps) {
+    return {
+        ok: steps.filter((step) => step.status === "ok").length,
+        skipped: steps.filter((step) => step.status === "skipped").length,
+        failed: steps.filter((step) => step.status === "failed").length,
+    };
+}
+function capabilityLimit(limit, unit, status) {
+    return limit === undefined
+        ? `host default · ${status ?? "unavailable"}`
+        : `${formatNumber(limit)} ${unit} · ${status}`;
+}
+function formatNumber(value) {
+    return new Intl.NumberFormat("en-US").format(value);
+}
+function hostLabel(observedSource) {
+    return observedSource?.match(/codex-cli\s+\S+/)?.[0] ?? observedSource ?? "not reported";
+}
+function failureHostDetail(details) {
+    const stderr = details["stderr"];
+    if (typeof stderr === "string" && stderr.trim().length > 0)
+        return stderr.trim();
+    const capabilities = details["capabilities"];
+    if (!isRecord(capabilities))
+        return "No additional host output.";
+    const concurrency = capabilities["concurrency"];
+    if (!isRecord(concurrency))
+        return "No additional host output.";
+    const fields = [concurrency["status"], concurrency["reason"], concurrency["observedSource"]].filter((value) => typeof value === "string" && value.length > 0);
+    return fields.length === 0 ? "No additional host output." : fields.join(" · ");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function row(label, value) {
+    return `  │ ${label.padEnd(13)} ${value}`;
+}
+function detailRow(label, value, color) {
+    return `  │ ${dim(label.padEnd(13), color)} ${dim(value, color)}`;
+}

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

@@ -0,0 +1,25 @@
+import type { InstallPreflightStage, InstallStepKind } from "./types.js";
+export interface SpinnerMotion {
+    readonly start: (label: string) => () => void;
+}
+export declare class Spinner {
+    private readonly stream;
+    private readonly color;
+    private timer;
+    private frameIndex;
+    private label;
+    private readonly motion;
+    private stopMotion;
+    constructor(stream: NodeJS.WritableStream, color: boolean, motion?: SpinnerMotion);
+    start(label: string): void;
+    succeed(label?: string): void;
+    fail(label?: string): void;
+    skip(label?: string): void;
+    stop(): void;
+    private render;
+    private finish;
+    private clearTimer;
+    private clearMotion;
+}
+export declare function humanLabel(kind: InstallStepKind): string;
+export declare function preflightLabel(stage: InstallPreflightStage): string;

package/dist/install/install-ui.js

@@ -0,0 +1,109 @@
+import { amber, CLEAR_LINE, dim, green, red } from "../ui-style.js";
+const BRAILLE_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+export class Spinner {
+    constructor(stream, color, motion) {
+        this.timer = null;
+        this.frameIndex = 0;
+        this.label = "";
+        this.stopMotion = null;
+        this.stream = stream;
+        this.color = color;
+        this.motion = motion;
+    }
+    start(label) {
+        this.clearTimer();
+        this.clearMotion();
+        this.label = label;
+        if (!this.color)
+            return;
+        if (this.motion !== undefined) {
+            this.stopMotion = this.motion.start(label);
+            return;
+        }
+        this.frameIndex = 0;
+        this.render();
+        this.timer = setInterval(() => {
+            this.frameIndex = (this.frameIndex + 1) % BRAILLE_FRAMES.length;
+            this.render();
+        }, SPINNER_INTERVAL_MS);
+    }
+    succeed(label) {
+        this.finish(label ?? this.label, "ok");
+    }
+    fail(label) {
+        this.finish(label ?? this.label, "failed");
+    }
+    skip(label) {
+        this.finish(label ?? this.label, "skipped");
+    }
+    stop() {
+        this.clearTimer();
+        this.clearMotion();
+        if (this.color)
+            this.stream.write(CLEAR_LINE);
+    }
+    render() {
+        const frame = amber(BRAILLE_FRAMES[this.frameIndex] ?? BRAILLE_FRAMES[0], this.color);
+        this.stream.write(`${CLEAR_LINE}  ${frame} ${this.label}`);
+    }
+    finish(label, status) {
+        this.clearTimer();
+        this.clearMotion();
+        if (this.color)
+            this.stream.write(`${CLEAR_LINE}  ${statusIcon(status, true)} ${label}\n`);
+        else
+            this.stream.write(`${statusIcon(status, false)} ${label}\n`);
+    }
+    clearTimer() {
+        if (this.timer === null)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    clearMotion() {
+        if (this.stopMotion === null)
+            return;
+        this.stopMotion();
+        this.stopMotion = null;
+    }
+}
+function statusIcon(status, color) {
+    if (color) {
+        switch (status) {
+            case "ok":
+                return green("✓", true);
+            case "failed":
+                return red("✗", true);
+            case "skipped":
+                return dim("○", true);
+        }
+    }
+    switch (status) {
+        case "ok":
+            return "[ok]";
+        case "failed":
+            return "[fail]";
+        case "skipped":
+            return "[skip]";
+    }
+}
+const STEP_LABELS = {
+    "marketplace-add": "Registering marketplace",
+    "plugin-add": "Installing plugin",
+    "hooks-register": "Wiring UserPromptSubmit hook",
+    "agents-install": "Installing litwork agents",
+    "config-update": "Updating Codex config",
+    verify: "Running doctor",
+};
+export function humanLabel(kind) {
+    return STEP_LABELS[kind];
+}
+const PREFLIGHT_LABELS = {
+    "host-capabilities": "[1/3] Inspecting Codex host capabilities",
+    "config-dry-run": "[2/3] Validating managed config (read-only)",
+    "marketplace-payload": "[3/3] Preparing bundled marketplace payload",
+};
+export function preflightLabel(stage) {
+    return PREFLIGHT_LABELS[stage];
+}

package/dist/install/marketplace-payload.d.ts

@@ -0,0 +1,10 @@
+export interface MaterializeMarketplaceOptions {
+    readonly sourceRoot: string;
+    readonly targetRoot: string;
+}
+export interface MaterializeMarketplaceResult {
+    readonly changed: boolean;
+    readonly version: string;
+}
+/** Validate and atomically install the package-bundled marketplace into CODEX_HOME. */
+export declare function materializeManagedMarketplace(opts: MaterializeMarketplaceOptions): MaterializeMarketplaceResult;