@litfamily/litcodex 1.0.0

package/node_modules/@litcodex/lit-loop/dist/lit-mark.js

@@ -0,0 +1,138 @@
+// Approved Ignition B geometry. The independently pinned fixture preserves every cell.
+// Runtime data is product-owned; no external brand path is read when rendering.
+export const standard = [
+    "          ▄▖  ▄█▄     ",
+    "▗▄▄▖    ▄██▌  ▜█▛     ",
+    "▐██▌  ▄████████████▜▛ ",
+    "▐██▌ ▐█▀▀▀▀▀▀▀▀▀▀▀▀▘  ",
+    "▐██▌   ▄█▌█████████▌  ",
+    "▐██▌ ▄██▛▘  ▗▄▄  ▗    ",
+    "▐██▌▐█▛▘    ▐██  ▝▀   ",
+    "▐██▌▝       ▐██       ",
+    "▐██████▘    ▐██       ",
+    "▝▀▀▀▀▀      ▝▀▀       ",
+];
+const standardColors = [
+    "          II  LLL     ",
+    "OOOO    IIII  LLL     ",
+    "OOOO  IIIIOOOOOOOOOOO ",
+    "OOOO IIIOOOOOOOOOOOO  ",
+    "OOOO   IIILLLIIIIIII  ",
+    "OOOO IIIII  III  I    ",
+    "OOOOIIII    III  II   ",
+    "OOOOI       III       ",
+    "OOOOOOOO    III       ",
+    "OOOOOO      III       ",
+];
+export const banner = [
+    "                             ▄▄▄▄           ",
+    "                   ▗███▌   ▗██████▖         ",
+    " ▗▄▄▄▄▄          ▗▟████▌   ▝██████▘         ",
+    " ▐█████        ▗▟██████▌    ▝▀▜█▀▘          ",
+    " ▐█████      ▗▟███████▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄  ",
+    " ▐█████    ▗▟█████████████████████████ ▐█▀  ",
+    " ▐█████    ████████████████████████████▀    ",
+    " ▐█████    ██▛▘   ▄ ▄▄▄▄▖▄▄▄▄▄▄▄▄▄▄▄▄▄▖     ",
+    " ▐█████    ▀    ▄██ ████▌█████████████▌     ",
+    " ▐█████       ▄████ ████▌█████████████▌     ",
+    " ▐█████     ▄█████▛                         ",
+    " ▐█████  ▗▟█████▀▘       ▄▄▄▄▄     ▗▖       ",
+    " ▐█████ ▐█████▀          █████     ▐▛▀      ",
+    " ▐█████ ▐███▀            █████              ",
+    " ▐█████ ▐█▀              █████              ",
+    " ▐█████ ▝                █████              ",
+    " ▐█████▄▄▄▄▄▄▄▖          █████              ",
+    " ▐███████████▛           █████              ",
+    " ▐██████████▀            █████              ",
+    "                                            ",
+];
+const bannerColors = [
+    "                             LLLL           ",
+    "                   IIIII   LLLLLLLL         ",
+    " OOOOOO          IIIIIII   LLLLLLLL         ",
+    " OOOOOO        IIIIIIIII    LLLLLL          ",
+    " OOOOOO      IIIIIIIIIOOOOOOOOOOOOOOOOOOOO  ",
+    " OOOOOO    IIIIIIIIOOOOOOOOOOOOOOOOOOO OOO  ",
+    " OOOOOO    IIIIIIOOOOOOOOOOOOOOOOOOOOOOO    ",
+    " OOOOOO    IIII   I LLLLLIIIIIIIIIIIIII     ",
+    " OOOOOO    I    III LLLLLIIIIIIIIIIIIII     ",
+    " OOOOOO       IIIII LLLLLIIIIIIIIIIIIII     ",
+    " OOOOOO     IIIIIII                         ",
+    " OOOOOO  IIIIIIIII       IIIII     II       ",
+    " OOOOOO IIIIIII          IIIII     III      ",
+    " OOOOOO IIIII            IIIII              ",
+    " OOOOOO III              IIIII              ",
+    " OOOOOO I                IIIII              ",
+    " OOOOOOOOOOOOOO          IIIII              ",
+    " OOOOOOOOOOOOO           IIIII              ",
+    " OOOOOOOOOOOO            IIIII              ",
+    "                                            ",
+];
+export const micro = [
+    "▗▖  ▄▄ █▌       ",
+    "▐▌▗█▀▀▀▀▀▀▘     ",
+    "▐▌ ▄▌▀▝▀▀▘      ",
+    "▐▌▛▘  ▐▌        ",
+    "▝▀▀▘  ▝▘        ",
+];
+const microColors = [
+    "OO  II LL       ",
+    "OOIIIOOOOOO     ",
+    "OO IILIIII      ",
+    "OOII  II        ",
+    "OOOO  II        ",
+];
+/** The standard mark in a 28-column field, with an arbitrary product label alongside. */
+export function lockup(productName) {
+    return standard.map((row, index) => `${row.padEnd(28)}${index === 5 ? `  ${productName}` : ""}`);
+}
+export function supportsBlocks(env) {
+    const locale = env["LC_ALL"] || env["LC_CTYPE"] || env["LANG"];
+    return env["TERM"] !== "dumb" && (!locale || /utf-?8/i.test(locale));
+}
+export function colorMode(opts) {
+    const { env } = opts;
+    if (!opts.isTty || opts.json || env["NO_COLOR"] !== undefined || env["CI"] !== undefined || !supportsBlocks(env)) {
+        return "none";
+    }
+    return /truecolor|24bit/i.test(env["COLORTERM"] ?? "") ? "truecolor" : "256";
+}
+const GLYPH = /^[█▓▀▄▌▐▖▗▘▝▙▛▜▟▚▞]$/u;
+const PALETTE = {
+    O: { rgb: "255;99;55", ansi256: 203 },
+    L: { rgb: "215;247;91", ansi256: 191 },
+    I: { rgb: "242;239;223", ansi256: 230 },
+};
+const VARIANTS = [
+    { rows: standard, colors: standardColors },
+    { rows: banner, colors: bannerColors },
+    { rows: micro, colors: microColors },
+];
+/** Flat Ignition cell colors preserve glyphs and leave appended lockup labels unpainted. */
+export function colorize(rows, opts) {
+    if (opts.mode === "none")
+        return [...rows];
+    if (opts.shadow !== undefined && !/^#[a-f\d]{6}$/i.test(opts.shadow)) {
+        throw new Error("shadow must be a six-digit hex colour");
+    }
+    // Keep the former shadow option source-compatible; the current mark has no shadow plane.
+    const variant = VARIANTS.find((candidate) => rows.length === candidate.rows.length &&
+        rows.every((row, index) => row.startsWith(candidate.rows[index] ?? "")));
+    return rows.map((row, index) => [...row]
+        .map((glyph, column) => {
+        if (!GLYPH.test(glyph))
+            return glyph;
+        const key = variant ? variant.colors[index]?.[column] : "O";
+        const color = key ? PALETTE[key] : undefined;
+        if (!color)
+            return glyph;
+        const code = opts.mode === "256" ? `38;5;${color.ansi256}` : `38;2;${color.rgb}`;
+        return `\x1b[${code}m${glyph}\x1b[0m`;
+    })
+        .join(""));
+}
+/** Codex statusMessage is one header span, so use the permitted one-line session lockup. */
+export const sessionLockup = "LIT · codex";
+export function microLine(discipline) {
+    return `${micro[2]}  litcodex · ${discipline}`;
+}

package/node_modules/@litcodex/lit-loop/dist/loop-cli.d.ts

@@ -0,0 +1,19 @@
+export { exitCodeForLoop, LitLoopError, type LoopErrorCode } from "./loop-errors.js";
+export type { LoopClock } from "./loop-handlers.js";
+export { LOOP_CREATE_STDOUT } from "./loop-stdout.js";
+/** The 7 MVP subcommands, help-order, including `help` (A3 D2). M09 is the single source. */
+export declare const LOOP_SUBCOMMANDS: readonly ["help", "create", "status", "run", "checkpoint", "record-evidence", "doctor"];
+export type LoopSubcommand = (typeof LOOP_SUBCOMMANDS)[number];
+export declare function isLoopSubcommand(value: string): value is LoopSubcommand;
+export interface LoopIo {
+    readonly stdout: NodeJS.WritableStream;
+    readonly stderr: NodeJS.WritableStream;
+    readonly stdin: NodeJS.ReadableStream;
+    /** Test seam: override the repo root (default process.cwd()) without process.chdir. */
+    readonly cwd: string;
+}
+/**
+ * Entry point. `argv` is already sliced past `loop`. NEVER throws and NEVER calls process.exit —
+ * resolves exactly one exit code. The M03 router owns process.exit.
+ */
+export declare function loopCommand(argv: readonly string[], io?: Partial<LoopIo>, clock?: () => string): Promise<number>;

package/node_modules/@litcodex/lit-loop/dist/loop-cli.js

@@ -0,0 +1,109 @@
+// src/loop-cli.ts — M09/T14 loop command surface dispatcher (A3 C5/C6/C7/C9/C14, S09 §5).
+//
+// The thin `litcodex loop <sub>` dispatcher. PURE of process.exit and uncaught throws: loopCommand
+// always RESOLVES one exit code (the M03 router owns process.exit). Arg parsing + the five handlers
+// live in loop-handlers.ts; the error model + LOOP_CREATE_STDOUT are re-exported from
+// loop-errors.ts / loop-stdout.ts so this module's public surface is unchanged. All fs I/O is
+// delegated to the M08 store via flat `./state-store.js` (NEVER `../state/...`, A3 C9); M09 never
+// touches node:fs. Error model branches on `err.code` via exitCodeForLoop (A3 C7 — NOT instanceof):
+// store PLAN_MISSING→3, PLAN_CORRUPT→4, WRITE_FAILED→5; unknown subcommand/usage→1; bad args→2;
+// not-found→3. The `doctor` route delegates to the canonical M11 6-check doctor (A3 C5) and ALWAYS
+// resolves exit 0 (a diagnostic, never a gate).
+import { hookRegisteredInstalled, renderDoctorJson, renderDoctorText, runLoopDoctor } from "./loop-doctor.js";
+import { exitCodeForLoop, LitLoopError } from "./loop-errors.js";
+import { handleCheckpoint, handleCreate, handleRecordEvidence, handleRun, handleStatus, hasFlag, } from "./loop-handlers.js";
+import { resolveLoopScope } from "./state-store.js";
+// Re-export the error model + stdout contract so callers (M03 router, M20, tests) keep importing
+// them from `./loop-cli.js` as the M09 public surface.
+export { exitCodeForLoop, LitLoopError } from "./loop-errors.js";
+export { LOOP_CREATE_STDOUT } from "./loop-stdout.js";
+// ── Public contract ──────────────────────────────────────────────────────────
+/** The 7 MVP subcommands, help-order, including `help` (A3 D2). M09 is the single source. */
+export const LOOP_SUBCOMMANDS = ["help", "create", "status", "run", "checkpoint", "record-evidence", "doctor"];
+export function isLoopSubcommand(value) {
+    return LOOP_SUBCOMMANDS.includes(value);
+}
+const HELP_TEXT = `litcodex loop <subcommand>
+
+Subcommands:
+  help              Show this help.
+  create            Derive goals from a brief and seed success criteria.
+  status            Print the plan summary (use --json for a machine envelope).
+  run               Schedule the next runnable goal and print a handoff.
+  checkpoint        Set a goal terminal status (gated on all-criteria-pass for complete).
+  record-evidence   Capture per-criterion evidence.
+  doctor            Diagnose loop state (read-only health report; use --json for an envelope).
+`;
+/**
+ * Entry point. `argv` is already sliced past `loop`. NEVER throws and NEVER calls process.exit —
+ * resolves exactly one exit code. The M03 router owns process.exit.
+ */
+export async function loopCommand(argv, io, clock) {
+    const stdout = io?.stdout ?? process.stdout;
+    const stderr = io?.stderr ?? process.stderr;
+    const now = clock ?? (() => new Date().toISOString());
+    const repoRoot = io?.cwd ?? process.cwd();
+    let head = argv[0] ?? "help";
+    if (head === "--help" || head === "-h") {
+        head = "help";
+    }
+    const rest = argv.slice(1);
+    const json = hasFlag(argv, "--json");
+    if (head === "help") {
+        stdout.write(HELP_TEXT);
+        return 0;
+    }
+    if (!isLoopSubcommand(head)) {
+        return renderError(new LitLoopError(`unknown subcommand: ${head}`, "LIT_LOOP_SUBCOMMAND_UNKNOWN", { subcommand: head }), json, stdout, stderr);
+    }
+    const scope = resolveLoopScope({ argv: rest, env: process.env });
+    if (head === "doctor") {
+        // A3 C5: delegate to the canonical M11 6-check doctor; ALWAYS exit 0 (diagnostic, not gate).
+        // Use the INSTALL-AWARE hook probe: a real `litcodex loop doctor` runs from an arbitrary cwd
+        // (no dev-tree manifest), so the pure repoRoot-only probe falsely warns "hook not registered".
+        // hookRegisteredInstalled also checks where the installed plugin actually lives (Codex cache).
+        const report = await runLoopDoctor({ repoRoot, scope }, { hookRegistered: (r) => hookRegisteredInstalled(r) });
+        stdout.write(json ? renderDoctorJson(report) : renderDoctorText(report));
+        return 0;
+    }
+    try {
+        const result = await dispatch(head, rest, { repoRoot, scope, now });
+        stdout.write(json ? `${JSON.stringify(result.json)}\n` : result.text);
+        return result.exitCode;
+    }
+    catch (err) {
+        return renderError(err, json, stdout, stderr);
+    }
+}
+async function dispatch(sub, argv, ctx) {
+    switch (sub) {
+        case "create":
+            return handleCreate(argv, ctx);
+        case "status":
+            return handleStatus(ctx);
+        case "run":
+            return handleRun(argv, ctx);
+        case "checkpoint":
+            return handleCheckpoint(argv, ctx);
+        case "record-evidence":
+            return handleRecordEvidence(argv, ctx);
+        default:
+            throw new LitLoopError(`unknown subcommand: ${sub}`, "LIT_LOOP_SUBCOMMAND_UNKNOWN", { subcommand: sub });
+    }
+}
+function renderError(err, json, stdout, stderr) {
+    const code = typeof err === "object" && err !== null && "code" in err
+        ? String(err.code)
+        : "LIT_LOOP_INTERNAL";
+    const message = err instanceof Error ? err.message : String(err);
+    const details = err instanceof LitLoopError && err.details !== undefined ? err.details : undefined;
+    if (json) {
+        const error = { code, message };
+        if (details !== undefined) {
+            error["details"] = details;
+        }
+        stdout.write(`${JSON.stringify({ ok: false, error })}\n`);
+    }
+    stderr.write(`[lit-loop] ${message}\n`);
+    return exitCodeForLoop(err);
+}

package/node_modules/@litcodex/lit-loop/dist/loop-doctor-render.d.ts

@@ -0,0 +1,7 @@
+import type { LoopDoctorReport } from "./loop-doctor-types.js";
+/** Render the --json envelope: one line + trailing `\n`. */
+export declare function renderDoctorJson(report: LoopDoctorReport): string;
+/** Render the human (text-mode) report. */
+export declare function renderDoctorText(report: LoopDoctorReport): string;
+/** Strip control chars (incl. newlines) and cap to 80 chars so an id can never forge a render line. */
+export declare function sanitizeId(value: string): string;

package/node_modules/@litcodex/lit-loop/dist/loop-doctor-render.js

@@ -0,0 +1,39 @@
+// src/loop-doctor-render.ts — M11/T16 pure doctor renderers (split from loop-doctor.ts for the
+// 250-LOC ceiling). Deterministic, no env reads, no untrusted-text interpolation: only ids,
+// statuses, integer counts, repo-relative paths, and ISO timestamps appear. `sanitizeId` strips
+// control chars and caps length so a crafted goalId can never forge a render line.
+const SYMBOL = { ok: "ok", warn: "!!", fail: "XX" };
+/** Render the --json envelope: one line + trailing `\n`. */
+export function renderDoctorJson(report) {
+    return `${JSON.stringify({ ok: report.healthy, report })}\n`;
+}
+/** Render the human (text-mode) report. */
+export function renderDoctorText(report) {
+    const failCount = report.checks.filter((c) => c.status === "fail").length;
+    const verdict = report.healthy ? "lit-loop doctor: HEALTHY" : `lit-loop doctor: UNHEALTHY (${failCount} issue(s))`;
+    const lines = [verdict, `state dir: ${report.stateDir}`];
+    for (const c of report.checks) {
+        lines.push(`  [${SYMBOL[c.status]}] ${c.name}: ${c.detail}`);
+    }
+    if (report.latestCheckpoint) {
+        const cp = report.latestCheckpoint;
+        lines.push(`latest checkpoint: ${sanitizeId(cp.goalId)} -> ${cp.status} @ ${sanitizeId(cp.at)}`);
+    }
+    if (report.counts) {
+        const s = report.counts;
+        lines.push(`goals: ${s.total} (${s.pending} pending, ${s.in_progress} in progress, ${s.complete} complete, ${s.failed} failed, ${s.blocked} blocked)`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Strip control chars (incl. newlines) and cap to 80 chars so an id can never forge a render line. */
+export function sanitizeId(value) {
+    let out = "";
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        // Drop C0 controls (incl. \n \r \t), DEL, and C1 controls; keep printable text.
+        if (code >= 0x20 && code !== 0x7f && !(code >= 0x80 && code <= 0x9f)) {
+            out += ch;
+        }
+    }
+    return out.slice(0, 80);
+}

package/node_modules/@litcodex/lit-loop/dist/loop-doctor-types.d.ts

@@ -0,0 +1,52 @@
+import type { LoopGoalStatus, PlanSummary } from "./loop-types.js";
+import type { LitLoopScope } from "./state-paths.js";
+/** The six diagnostic surfaces, in stable render order. */
+export type LoopDoctorCheckName = "state-dir" | "plan-schema" | "ledger" | "evidence-dir" | "hook" | "checkpoint";
+/** ok = healthy; warn = absent-but-recoverable (NOT a failure); fail = corrupt/unusable. */
+export type LoopDoctorCheckStatus = "ok" | "warn" | "fail";
+export interface LoopDoctorCheck {
+    readonly name: LoopDoctorCheckName;
+    readonly status: LoopDoctorCheckStatus;
+    /** One sanitized line. NO absolute paths beyond repo-relative artifacts; NO raw prompt/evidence text. */
+    readonly detail: string;
+    /** Optional machine-readable extras (e.g. backup path, ledger counts). JSON-serializable scalars only. */
+    readonly data?: Readonly<Record<string, string | number | boolean | null>>;
+}
+/** A pointer to the most-recent terminal goal event seen in the ledger tail. */
+export interface LoopCheckpointRef {
+    readonly goalId: string;
+    readonly status: LoopGoalStatus;
+    readonly at: string;
+}
+export interface LoopDoctorReport {
+    /** false iff ANY check.status === "fail". A `warn` alone keeps healthy = true. */
+    readonly healthy: boolean;
+    /** Repo-relative resolved state dir, e.g. ".litcodex/lit-loop" or ".litcodex/lit-loop/<sid>". */
+    readonly stateDir: string;
+    /** Always present, always length 6, always in LoopDoctorCheckName order. */
+    readonly checks: ReadonlyArray<LoopDoctorCheck>;
+    /** Most recent terminal checkpoint, or null when none / ledger unreadable. */
+    readonly latestCheckpoint: LoopCheckpointRef | null;
+    /** Goal/criterion counts when the plan is readable; null when missing/corrupt. */
+    readonly counts: PlanSummary | null;
+}
+export interface RunLoopDoctorOptions {
+    /** Absolute project root. MUST be absolute (the doctor never infers it from import.meta.url). */
+    readonly repoRoot: string;
+    /** Session scope to inspect; undefined ⇒ unscoped root dir. */
+    readonly scope?: LitLoopScope | undefined;
+}
+/**
+ * Injectable seams for deterministic, side-effect-free testing. ALL default to the real M08
+ * store + the real aggregate-hooks-manifest probe. Tests override individually for fault injection.
+ */
+export interface RunLoopDoctorDeps {
+    readonly readPlan: (repoRoot: string, scope?: LitLoopScope) => Promise<unknown>;
+    readonly readLedger: (repoRoot: string, scope?: LitLoopScope) => Promise<{
+        entries: ReadonlyArray<Record<string, unknown>>;
+        skipped: number;
+    }>;
+    readonly statExists: (absPath: string) => Promise<boolean>;
+    /** Resolves true iff a UserPromptSubmit command is wired in the aggregate plugins/litcodex/hooks/hooks.json. */
+    readonly hookRegistered: (repoRoot: string) => Promise<boolean>;
+}

package/node_modules/@litcodex/lit-loop/dist/loop-doctor-types.js

@@ -0,0 +1,7 @@
+// src/loop-doctor-types.ts — M11/T16 doctor-owned shapes (A3 C5/C9, S11 §Public-contract).
+//
+// Types only; ZERO I/O. The canonical LoopDoctorReport (6 checks incl. `checkpoint`, a per-check
+// `data` field, `healthy` flips ONLY on a `fail`) lives here, NOT in M09 (A3 C5 — M11 is the
+// single doctor owner). Imports `PlanSummary`/`LoopGoalStatus` from M09's `loop-types.js` barrel
+// and `LitLoopScope` from M08's `state-paths.js` — flat siblings, NEVER `../state/...` (A3 C9).
+export {};

package/node_modules/@litcodex/lit-loop/dist/loop-doctor.d.ts

@@ -0,0 +1,34 @@
+import type { LoopCheckpointRef, LoopDoctorReport, RunLoopDoctorDeps, RunLoopDoctorOptions } from "./loop-doctor-types.js";
+export { renderDoctorJson, renderDoctorText } from "./loop-doctor-render.js";
+/** The ONLY ledger kinds the checkpoint scan treats as terminal. Each is in BOTH producer enums. */
+export declare const TERMINAL_LEDGER_KINDS: {
+    readonly goal_completed: "complete";
+    readonly goal_failed: "failed";
+    readonly goal_blocked: "blocked";
+};
+/**
+ * Resolves true iff the AGGREGATE hooks.json registers UserPromptSubmit with the canonical command
+ * (all three HOOK_COMMAND_FRAGMENTS). ENOENT ⇒ false; any read/parse error rethrows to checkHook's
+ * catch (→ warn). Never executes any command from the manifest.
+ */
+export declare function hookRegistered(repoRoot: string): Promise<boolean>;
+/**
+ * Install-aware hook probe (production default the global CLI injects). The dev-tree manifest
+ * `<repoRoot>/plugins/litcodex/hooks/hooks.json` ONLY exists when run from the repo; a real install
+ * (`litcodex loop doctor` from any cwd) has no such file, so the pure `hookRegistered` falsely warns
+ * "not registered". This trusts the repoRoot manifest when present (dev/test), and otherwise looks
+ * where the INSTALLED plugin actually lives: the Codex plugin cache
+ * `<CODEX_HOME>/plugins/cache/.../hooks/hooks.json` (the global CLI runs the bundled lit-loop, so the
+ * plugin's aggregate manifest only exists in that cache). Pure-read, never executes a command;
+ * `opts.codexHome` is injectable so tests stay hermetic.
+ */
+export declare function hookRegisteredInstalled(repoRoot: string, opts?: {
+    codexHome?: string;
+}): Promise<boolean>;
+/** Scan the ledger tail backward for the last terminal entry; null when none usable. */
+export declare function latestCheckpointFromLedger(entries: ReadonlyArray<Record<string, unknown>>): LoopCheckpointRef | null;
+/**
+ * Produce a LoopDoctorReport. NEVER throws, NEVER mutates state, NEVER calls process.exit. Every
+ * sub-check is independently fail-soft. Deterministic given the same on-disk state + injected deps.
+ */
+export declare function runLoopDoctor(options: RunLoopDoctorOptions, deps?: Partial<RunLoopDoctorDeps>): Promise<LoopDoctorReport>;