litcodex-ai 0.3.0 → 0.3.2

package/dist/cli.js

@@ -20,6 +20,7 @@ import { runDoctorCli, runInstallCli, runUninstallCli } from "./install/index.js
 import { LITCODEX_REPO_URL } from "./install/marketplace.js";
 import { buildInstallPlan } from "./install/plan.js";
 import { renderInstallPlan } from "./install/render-plan.js";
+import { renderBanner, shouldDecorate } from "./ui.js";
 /** Error code emitted when a subcommand is not in the routing table. */
 export const UNKNOWN_COMMAND_CODE = "LITCODEX_INSTALL_UNKNOWN_COMMAND";
 /** Router usage code (EX_USAGE) for an unknown `config` sub-subcommand. */
@@ -169,7 +170,17 @@ export async function runCli(argv) {
             return runUserPromptSubmitHookCli(process.stdin, process.stdout, process.stderr);
         }
     }
-    return dispatchExit(dispatch(argv));
+    // Reliable post-install greeting: the bare `litcodex` and `litcodex --help` surfaces are where
+    // users actually meet the CLI (npm hides postinstall output by default), so decorate them with
+    // the fire title banner on an interactive TTY. `--version` and error paths stay plain.
+    const result = dispatch(argv);
+    if (!isVersion &&
+        result.exitCode === 0 &&
+        result.stdout.length > 0 &&
+        shouldDecorate({ isTty: Boolean(process.stdout.isTTY), env: process.env })) {
+        process.stdout.write(renderBanner({ version: manifest.version, color: true }));
+    }
+    return dispatchExit(result);
 }
 /** Write a pure dispatch result to the process streams and return its exit code. */
 function dispatchExit(result) {

package/dist/install/execute.d.ts

@@ -1,6 +1,6 @@
 import type { MigrateOptions, MigrateResult } from "../config-migration/index.js";
 import { type ReadonlyFsLike, type SpawnLike } from "./codex.js";
-import type { InstallResult, InstallStep } from "./types.js";
+import type { InstallResult, InstallStep, InstallStepResult } from "./types.js";
 /** Minimal writable-fs surface for agents-install (injectable for tests). */
 export interface WritableFsLike {
     existsSync(p: string): boolean;
@@ -31,6 +31,10 @@ export interface ExecuteDeps {
     readonly writeFs?: WritableFsLike;
     /** Absolute path to the bundled agents source dir (defaults to resolved @litcodex/lit-loop/agents). */
     readonly agentsSourceDir?: string;
+    /** Optional callback fired before each step begins (for TUI spinners). */
+    readonly onStepStart?: (step: InstallStep) => void;
+    /** Optional callback fired after each step completes (for TUI spinners). */
+    readonly onStepEnd?: (result: InstallStepResult) => void;
 }
 /**
  * Run the plan in order. Returns a `Promise<InstallResult>` (config-update is async). Throws a

package/dist/install/execute.js

@@ -29,7 +29,9 @@ export async function executeInstallPlan(steps, deps) {
     }
     const results = [];
     for (const step of steps) {
+        deps.onStepStart?.(step);
         const result = await runStep(step, codexBin, deps);
+        deps.onStepEnd?.(result);
         results.push(result);
     }
     return {

package/dist/install/index.js

@@ -6,8 +6,10 @@
 // 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 { migrateCodexConfig } from "../config-migration/index.js";
+import { humanLabel, renderBanner, Spinner, shouldDecorate } from "../ui.js";
 import { resolveCodexHome } from "./codex.js";
 import { renderDoctorText, runDoctor } from "./doctor.js";
 import { exitCodeForInstallError, InstallError, toErrorJson } from "./errors.js";
@@ -72,25 +74,70 @@ export async function runInstallCli(args, io = defaultIo()) {
     catch (err) {
         return emitError(io, err);
     }
+    const decorate = shouldDecorate({
+        isTty: Boolean(io.stdout.isTTY),
+        env: io.env,
+        noTui: opts.noTui,
+        json: opts.json,
+    });
     const plan = buildInstallPlan(opts);
     if (opts.dryRun) {
         // ZERO spawns, ZERO fs writes: render and return.
+        if (decorate) {
+            const version = createRequire(import.meta.url)("../../package.json").version;
+            io.stdout.write(renderBanner({ version, color: true }));
+        }
         io.stdout.write(`${renderInstallPlan(plan)}\n`);
         return 0;
     }
     let result;
     try {
-        result = await executeInstallPlan(plan, {
-            spawn: realSpawn,
-            fs: realFs,
-            env: io.env,
-            now: () => Date.now(),
-            repoRoot: io.repoRoot,
-            migrateConfig: migrateCodexConfig,
-            force: opts.force,
-            codexHome: opts.codexHome,
-            writeFs: realWriteFs,
-        });
+        if (decorate) {
+            const version = createRequire(import.meta.url)("../../package.json").version;
+            io.stdout.write(renderBanner({ version, color: true }));
+            const spinner = new Spinner(io.stdout, true);
+            result = await executeInstallPlan(plan, {
+                spawn: realSpawn,
+                fs: realFs,
+                env: io.env,
+                now: () => Date.now(),
+                repoRoot: io.repoRoot,
+                migrateConfig: migrateCodexConfig,
+                force: opts.force,
+                codexHome: opts.codexHome,
+                writeFs: realWriteFs,
+                onStepStart: (step) => {
+                    spinner.start(humanLabel(step.kind));
+                },
+                onStepEnd: (stepResult) => {
+                    const label = humanLabel(stepResult.kind);
+                    switch (stepResult.status) {
+                        case "ok":
+                            spinner.succeed(label);
+                            break;
+                        case "skipped":
+                            spinner.skip(label);
+                            break;
+                        case "failed":
+                            spinner.fail(label);
+                            break;
+                    }
+                },
+            });
+        }
+        else {
+            result = await executeInstallPlan(plan, {
+                spawn: realSpawn,
+                fs: realFs,
+                env: io.env,
+                now: () => Date.now(),
+                repoRoot: io.repoRoot,
+                migrateConfig: migrateCodexConfig,
+                force: opts.force,
+                codexHome: opts.codexHome,
+                writeFs: realWriteFs,
+            });
+        }
     }
     catch (err) {
         return emitError(io, err);
@@ -98,6 +145,9 @@ export async function runInstallCli(args, io = defaultIo()) {
     if (opts.json) {
         io.stdout.write(`${JSON.stringify(result)}\n`);
     }
+    else if (decorate) {
+        io.stdout.write(`\n  \x1b[38;2;255;106;0m\u{1F525} litcodex install: complete\x1b[0m\n\n`);
+    }
     else {
         for (const step of result.steps) {
             io.stdout.write(`${step.status} ${step.kind}: ${step.detail}\n`);

package/dist/postinstall.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/postinstall.js

@@ -0,0 +1,35 @@
+// npm postinstall welcome banner for litcodex-ai.
+//
+// Prints a fire/ember-branded welcome + next-steps box ONLY on a real `npm install -g` (not CI,
+// not workspace installs, not dev). Wraps everything so a failure exits 0 silently — a postinstall
+// must never break `npm install`. No network, no fs writes, no deps beyond Node built-ins.
+import { createRequire } from "node:module";
+import { renderBanner } from "./ui.js";
+function main() {
+    // Gate: only show on a real global install, not CI/workspace/dev.
+    if (process.env["npm_config_global"] !== "true")
+        return;
+    if (process.env["CI"])
+        return;
+    const color = Boolean(process.stdout.isTTY) && !process.env["NO_COLOR"];
+    const version = createRequire(import.meta.url)("../package.json").version;
+    const banner = renderBanner({ version, color });
+    process.stdout.write(banner);
+    if (color) {
+        const arrow = "\x1b[38;2;255;106;0m›\x1b[0m";
+        process.stdout.write(`  \x1b[1mGet started\x1b[0m\n`);
+        process.stdout.write(`    ${arrow} \x1b[1mlitcodex install\x1b[0m   \x1b[2mregister the Codex plugin + hook\x1b[0m\n`);
+        process.stdout.write(`    ${arrow} then type \x1b[1mlit\x1b[0m in Codex   \x1b[2mand the loop ignites\x1b[0m 🔥\n\n`);
+    }
+    else {
+        process.stdout.write("  Get started\n");
+        process.stdout.write("    > litcodex install   register the Codex plugin + hook\n");
+        process.stdout.write("    > then type  lit  in Codex   and the loop ignites\n\n");
+    }
+}
+try {
+    main();
+}
+catch {
+    // Never fail npm install.
+}

package/dist/ui.d.ts

@@ -0,0 +1,69 @@
+import type { InstallStepKind } from "./install/types.js";
+/** True when the environment permits ANSI decoration. */
+export declare function shouldDecorate(opts: {
+    isTty: boolean;
+    env: NodeJS.ProcessEnv;
+    noTui?: boolean;
+    json?: boolean;
+}): boolean;
+/** Wrap text in the SGR reset sequence. */
+export declare function reset(text: string): string;
+/** Wrap text in bold. */
+export declare function bold(text: string, color: boolean): string;
+/** Wrap text in dim. */
+export declare function dim(text: string, color: boolean): string;
+/** Apply a 24-bit foreground color via SGR 38;2;r;g;b. */
+export declare function fg(text: string, r: number, g: number, b: number, color: boolean): string;
+export declare function orange(text: string, color: boolean): string;
+export declare function amber(text: string, color: boolean): string;
+export declare function ember(text: string, color: boolean): string;
+export declare function green(text: string, color: boolean): string;
+export declare function red(text: string, color: boolean): string;
+interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Apply a multi-stop RGB gradient across the visible characters of `text`.
+ * ANSI sequences and spaces are skipped (they keep the adjacent color).
+ * When `color` is false, returns the text unchanged.
+ */
+export declare function gradient(text: string, stops: readonly RGB[], color: boolean): string;
+/** The canonical fire/ember gradient: orange #ff6a00 → amber #ffb020 → ember red #d43a00. */
+export declare const FIRE_GRADIENT: readonly RGB[];
+/**
+ * Render the litcodex title banner. Returns a multi-line string.
+ *
+ * Color mode: fire gradient wordmark, dimmed subtitle, box-drawing accents.
+ * Plain mode: clean ASCII art, no escape codes.
+ */
+export declare function renderBanner(opts: {
+    version: string;
+    subtitle?: string;
+    color: boolean;
+}): string;
+export declare class Spinner {
+    private readonly stream;
+    private readonly color;
+    private timer;
+    private frameIdx;
+    private label;
+    constructor(stream: NodeJS.WritableStream, color: boolean);
+    /** Start the spinner with a label. No-op when color is off. */
+    start(label: string): void;
+    /** Mark the current step as succeeded. */
+    succeed(label?: string): void;
+    /** Mark the current step as failed. */
+    fail(label?: string): void;
+    /** Mark the current step as skipped. */
+    skip(label?: string): void;
+    /** Stop the spinner without printing a status line. */
+    stop(): void;
+    private render;
+    private finish;
+    private clearTimer;
+}
+/** Return a human-friendly label for an install step kind. */
+export declare function humanLabel(kind: InstallStepKind): string;
+export {};

package/dist/ui.js

@@ -0,0 +1,264 @@
+// TUI polish — hand-rolled ANSI toolkit for the litcodex CLI (zero deps).
+//
+// Provides a fire/ember-branded title banner, animated per-step spinners, and color helpers.
+// All visual effects are gated behind `shouldDecorate` and are pure no-ops when color/TTY is
+// disabled, so CI/non-TTY/`--json`/`--no-tui` output is byte-identical to the pre-TUI baseline.
+// ── ANSI helpers ─────────────────────────────────────────────────────────────
+const ESC = "\x1b[";
+const RESET_CODE = `${ESC}0m`;
+/** True when the environment permits ANSI decoration. */
+export function shouldDecorate(opts) {
+    if (!opts.isTty)
+        return false;
+    if (opts.env["CI"])
+        return false;
+    if (opts.env["NO_COLOR"])
+        return false;
+    if (opts.noTui)
+        return false;
+    if (opts.json)
+        return false;
+    return true;
+}
+/** Wrap text in the SGR reset sequence. */
+export function reset(text) {
+    return `${text}${RESET_CODE}`;
+}
+/** Wrap text in bold. */
+export function bold(text, color) {
+    return color ? `${ESC}1m${text}${RESET_CODE}` : text;
+}
+/** Wrap text in dim. */
+export function dim(text, color) {
+    return color ? `${ESC}2m${text}${RESET_CODE}` : text;
+}
+/** Apply a 24-bit foreground color via SGR 38;2;r;g;b. */
+export function fg(text, r, g, b, color) {
+    return color ? `${ESC}38;2;${r};${g};${b}m${text}${RESET_CODE}` : text;
+}
+// Named colors (fire/ember palette).
+export function orange(text, color) {
+    return fg(text, 255, 106, 0, color);
+}
+export function amber(text, color) {
+    return fg(text, 255, 176, 32, color);
+}
+export function ember(text, color) {
+    return fg(text, 212, 58, 0, color);
+}
+export function green(text, color) {
+    return fg(text, 80, 200, 80, color);
+}
+export function red(text, color) {
+    return fg(text, 230, 60, 60, color);
+}
+function lerp(a, b, t) {
+    return Math.round(a + (b - a) * t);
+}
+function at(arr, i) {
+    return arr[i];
+}
+function interpolateRgb(stops, t) {
+    if (stops.length === 1)
+        return at(stops, 0);
+    const segCount = stops.length - 1;
+    const seg = Math.min(Math.floor(t * segCount), segCount - 1);
+    const localT = t * segCount - seg;
+    const a = at(stops, seg);
+    const b = at(stops, seg + 1);
+    return { r: lerp(a.r, b.r, localT), g: lerp(a.g, b.g, localT), b: lerp(a.b, b.b, localT) };
+}
+/**
+ * Apply a multi-stop RGB gradient across the visible characters of `text`.
+ * ANSI sequences and spaces are skipped (they keep the adjacent color).
+ * When `color` is false, returns the text unchanged.
+ */
+export function gradient(text, stops, color) {
+    if (!color || stops.length === 0)
+        return text;
+    // Count visible (non-space, non-ANSI) characters to distribute the gradient.
+    const chars = [...text];
+    const visible = [];
+    let inEsc = false;
+    for (let i = 0; i < chars.length; i++) {
+        const ch = chars[i];
+        if (ch === "\x1b") {
+            inEsc = true;
+            continue;
+        }
+        if (inEsc) {
+            if (/[A-Za-z]/.test(ch))
+                inEsc = false;
+            continue;
+        }
+        if (ch !== " ")
+            visible.push(i);
+    }
+    if (visible.length === 0)
+        return text;
+    // Build output with per-visible-char coloring.
+    let out = "";
+    let visIdx = 0;
+    inEsc = false;
+    for (let i = 0; i < chars.length; i++) {
+        const ch = chars[i];
+        if (ch === "\x1b") {
+            inEsc = true;
+            out += ch;
+            continue;
+        }
+        if (inEsc) {
+            out += ch;
+            if (/[A-Za-z]/.test(ch))
+                inEsc = false;
+            continue;
+        }
+        if (ch === " ") {
+            out += ch;
+        }
+        else {
+            const t = visible.length === 1 ? 0 : visIdx / (visible.length - 1);
+            const c = interpolateRgb(stops, t);
+            out += `${ESC}38;2;${c.r};${c.g};${c.b}m${ch}`;
+            visIdx++;
+        }
+    }
+    return `${out}${RESET_CODE}`;
+}
+// ── Fire gradient stops ──────────────────────────────────────────────────────
+/** The canonical fire/ember gradient: orange #ff6a00 → amber #ffb020 → ember red #d43a00. */
+export const FIRE_GRADIENT = [
+    { r: 255, g: 106, b: 0 },
+    { r: 255, g: 176, b: 32 },
+    { r: 212, g: 58, b: 0 },
+];
+// ── Banner ───────────────────────────────────────────────────────────────────
+/**
+ * Render the litcodex title banner. Returns a multi-line string.
+ *
+ * Color mode: fire gradient wordmark, dimmed subtitle, box-drawing accents.
+ * Plain mode: clean ASCII art, no escape codes.
+ */
+export function renderBanner(opts) {
+    const { version, color } = opts;
+    const subtitle = opts.subtitle ?? "loop-native agent harness for Codex";
+    if (color) {
+        // Heavy rule, gradient-filled across its full width (orange → amber → ember).
+        const rule = gradient("━".repeat(46), FIRE_GRADIENT, true);
+        // Letter-spaced wordmark so the gradient breathes across each glyph (echoes the cover).
+        const wordmark = bold(gradient("l  i  t  c  o  d  e  x", FIRE_GRADIENT, true), true);
+        return [
+            "",
+            `  ${rule}`,
+            "",
+            `   ${fg("🔥", 255, 106, 0, true)}  ${wordmark}   ${dim(`v${version}`, true)}`,
+            `       ${dim(subtitle, true)}`,
+            "",
+            `  ${rule}`,
+            "",
+        ].join("\n");
+    }
+    // Plain ASCII — no escape codes, still clean + the same composition.
+    const rule = "━".repeat(46);
+    return ["", `  ${rule}`, "", `   ::  l i t c o d e x   v${version}`, `       ${subtitle}`, "", `  ${rule}`, ""].join("\n");
+}
+// ── Spinner ──────────────────────────────────────────────────────────────────
+const BRAILLE_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+/** Clear the current line and move the cursor to column 0. */
+const CLEAR_LINE = `\r${ESC}2K`;
+export class Spinner {
+    constructor(stream, color) {
+        this.timer = null;
+        this.frameIdx = 0;
+        this.label = "";
+        this.stream = stream;
+        this.color = color;
+    }
+    /** Start the spinner with a label. No-op when color is off. */
+    start(label) {
+        this.label = label;
+        if (!this.color)
+            return;
+        this.frameIdx = 0;
+        this.render();
+        this.timer = setInterval(() => {
+            this.frameIdx = (this.frameIdx + 1) % BRAILLE_FRAMES.length;
+            this.render();
+        }, SPINNER_INTERVAL_MS);
+    }
+    /** Mark the current step as succeeded. */
+    succeed(label) {
+        this.finish(label ?? this.label, "ok");
+    }
+    /** Mark the current step as failed. */
+    fail(label) {
+        this.finish(label ?? this.label, "failed");
+    }
+    /** Mark the current step as skipped. */
+    skip(label) {
+        this.finish(label ?? this.label, "skipped");
+    }
+    /** Stop the spinner without printing a status line. */
+    stop() {
+        this.clearTimer();
+        if (this.color) {
+            this.stream.write(CLEAR_LINE);
+        }
+    }
+    render() {
+        const frame = amber(BRAILLE_FRAMES[this.frameIdx % BRAILLE_FRAMES.length], this.color);
+        this.stream.write(`${CLEAR_LINE}  ${frame} ${this.label}`);
+    }
+    finish(label, status) {
+        this.clearTimer();
+        if (this.color) {
+            this.stream.write(CLEAR_LINE);
+            const icon = statusIcon(status, true);
+            this.stream.write(`  ${icon} ${label}\n`);
+        }
+        else {
+            const icon = statusIcon(status, false);
+            this.stream.write(`${icon} ${label}\n`);
+        }
+    }
+    clearTimer() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = 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]";
+    }
+}
+// ── Human labels for install step kinds ──────────────────────────────────────
+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",
+};
+/** Return a human-friendly label for an install step kind. */
+export function humanLabel(kind) {
+    return STEP_LABELS[kind];
+}

package/node_modules/@litcodex/lit-loop/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@litcodex/lit-loop",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "LitCodex Lit-Loop runtime: durable repo-native multi-goal orchestration with embedded success criteria and observable evidence audit.",
 	"type": "module",
 	"bin": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "litcodex-ai",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Codex loop harness installer. Run `npx litcodex-ai install` to set up the LitCodex Codex platform: the bare `lit` hook and the durable lit-loop runtime.",
 	"keywords": ["codex", "litcodex", "lit-loop", "ai-agents", "orchestration"],
 	"author": "LitCodex Authors",
@@ -14,13 +14,14 @@
 	},
 	"files": ["bin", "dist", "model-catalog.json", "README.md", "LICENSE"],
 	"dependencies": {
-		"@litcodex/lit-loop": "0.3.0"
+		"@litcodex/lit-loop": "0.3.2"
 	},
 	"bundledDependencies": ["@litcodex/lit-loop"],
 	"scripts": {
 		"build": "tsc -p tsconfig.build.json",
 		"typecheck": "tsc --noEmit",
 		"test": "vitest --run",
+		"postinstall": "node dist/postinstall.js",
 		"prepack": "node ../../scripts/prepack-bundle-component.mjs",
 		"postpack": "node ../../scripts/postpack-clean-component.mjs"
 	},