@litfamily/litcodex 1.0.0

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

@@ -0,0 +1,336 @@
+// src/loop-doctor.ts — M11/T16 canonical read-only loop doctor (A3 C5/C6/C9, S11 + addendum).
+//
+// The single doctor owner (A3 C5): six checks — state-dir / plan-schema / ledger / evidence-dir /
+// hook / checkpoint — a per-check `data` field, and `healthy` flips to false ONLY on a `fail`
+// (warnings keep healthy true). `runLoopDoctor` NEVER throws, NEVER mutates state, NEVER calls
+// process.exit, and ALWAYS resolves a report (M09 maps it to exit 0 unconditionally). Every
+// sub-check is independently try-wrapped; `checkStateDir`/`checkEvidenceDir` CATCH the `statExists`
+// non-ENOENT THROW (LIT_LOOP_WRITE_FAILED) and downgrade to warn (A3 C6 — statExists re-throws
+// EACCES/ELOOP/EIO; the doctor must not propagate it). The hook probe scans the AGGREGATE manifest
+// plugins/litcodex/hooks/hooks.json (M14/M19 ship it) and degrades to warn when absent.
+//
+// Imports flat siblings `./state-store.js`/`./state-paths.js`/`./loop-model.js`/`./loop-types.js`
+// (A3 C9 — NEVER `../state/...`). No `node:fs` import: existence-probing is M08 `statExists` only.
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { sanitizeId } from "./loop-doctor-render.js";
+import { summarizePlan } from "./loop-model.js";
+import { litLoopDir, litLoopEvidenceDir, repoRelative } from "./state-paths.js";
+import { readLedger, readPlan, statExists } from "./state-store.js";
+// Re-export the pure renderers so the M11 public surface stays single-import from `./loop-doctor.js`
+// (A2 §2.5; loop-cli's doctor route imports both from here). The bodies live in loop-doctor-render.ts.
+export { renderDoctorJson, renderDoctorText } from "./loop-doctor-render.js";
+// ── Hook-probe contract (A3 §G11.2; byte-identical to M14 hookCommandFragments) ──────────────
+/** The aggregate manifest the host actually loads, POSIX-joined onto the absolute repoRoot. */
+const HOOK_MANIFEST_RELPATH = "plugins/litcodex/hooks/hooks.json";
+/** All three MUST appear in a `command` string for a registration to count (no bare-cli.js shortcut). */
+const HOOK_COMMAND_FRAGMENTS = [
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: inert literal the host expands; the doctor scans for it verbatim and MUST NOT interpolate it.
+    "${PLUGIN_ROOT}",
+    "components/lit-loop/dist/cli.js",
+    "hook user-prompt-submit",
+];
+// ── Terminal-kind contract (A3 §G11.3; the M08∩M09 intersection, closed constant) ────────────
+/** The ONLY ledger kinds the checkpoint scan treats as terminal. Each is in BOTH producer enums. */
+export const TERMINAL_LEDGER_KINDS = {
+    goal_completed: "complete",
+    goal_failed: "failed",
+    goal_blocked: "blocked",
+};
+// ── Default hooks-manifest probe (pure-Node: no spawn, no network, never runs the command) ───
+/**
+ * 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 async function hookRegistered(repoRoot) {
+    const manifestAbs = join(repoRoot, ...HOOK_MANIFEST_RELPATH.split("/"));
+    if (!(await statExists(manifestAbs))) {
+        return false;
+    }
+    const raw = await readFile(manifestAbs, "utf8");
+    const parsed = JSON.parse(raw);
+    return scanForCommand(parsed);
+}
+/** Read + scan a manifest at an absolute path; ENOENT/parse-error ⇒ false (never throws). */
+async function scanManifestAt(manifestAbs) {
+    try {
+        if (!(await statExists(manifestAbs)))
+            return false;
+        return scanForCommand(JSON.parse(await readFile(manifestAbs, "utf8")));
+    }
+    catch {
+        return false;
+    }
+}
+/** Walk `<cacheRoot>/<marketplace>/<plugin>/<version>/hooks/hooks.json` (bounded; a few installs). */
+async function scanCodexPluginCache(cacheRoot) {
+    const listDirs = async (dir) => {
+        try {
+            return await readdir(dir);
+        }
+        catch {
+            return [];
+        }
+    };
+    for (const mp of await listDirs(cacheRoot)) {
+        for (const plugin of await listDirs(join(cacheRoot, mp))) {
+            for (const ver of await listDirs(join(cacheRoot, mp, plugin))) {
+                if (await scanManifestAt(join(cacheRoot, mp, plugin, ver, "hooks", "hooks.json")))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * 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 async function hookRegisteredInstalled(repoRoot, opts) {
+    // 1. Dev tree — authoritative when present (preserves dev/test behavior and keeps the real-fs cache
+    //    walk below from ever running inside the repo's own hermetic unit tests).
+    const devManifest = join(repoRoot, ...HOOK_MANIFEST_RELPATH.split("/"));
+    if (await statExists(devManifest)) {
+        return scanManifestAt(devManifest);
+    }
+    // 2. Codex plugin cache — the real install context for a global-CLI `litcodex loop doctor`.
+    const codexHome = opts?.codexHome ?? (process.env["CODEX_HOME"]?.trim() || join(homedir(), ".codex"));
+    return scanCodexPluginCache(join(codexHome, "plugins", "cache"));
+}
+/** Recursively scan every string value under a `command` key for ALL three fragments. */
+function scanForCommand(node) {
+    if (Array.isArray(node)) {
+        return node.some(scanForCommand);
+    }
+    if (node !== null && typeof node === "object") {
+        for (const [key, value] of Object.entries(node)) {
+            if (key === "command" && typeof value === "string" && HOOK_COMMAND_FRAGMENTS.every((f) => value.includes(f))) {
+                return true;
+            }
+            if (scanForCommand(value)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+// ── Per-check helpers (each pure given its injected dep; the orchestrator try-wraps them) ─────
+async function checkStateDir(stateDirAbs, statExistsFn) {
+    try {
+        const exists = await statExistsFn(stateDirAbs);
+        return exists
+            ? { name: "state-dir", status: "ok", detail: "state directory present" }
+            : { name: "state-dir", status: "warn", detail: "not created — run `litcodex loop create`" };
+    }
+    catch {
+        // A3 C6: statExists re-throws non-ENOENT (EACCES/ELOOP) as LIT_LOOP_WRITE_FAILED. Downgrade
+        // to warn — an unreadable/absent state dir is benign for a diagnostic; NEVER `fail`.
+        return {
+            name: "state-dir",
+            status: "warn",
+            detail: "state directory unreadable (permission or I/O)",
+            data: { code: "LIT_LOOP_WRITE_FAILED" },
+        };
+    }
+}
+async function checkPlanSchema(repoRoot, scope, readPlanFn) {
+    try {
+        const plan = (await readPlanFn(repoRoot, scope));
+        const counts = summarizePlan(plan);
+        return {
+            check: {
+                name: "plan-schema",
+                status: "ok",
+                detail: `goals.json valid (version 1, ${plan.goals.length} goal(s))`,
+            },
+            counts,
+        };
+    }
+    catch (err) {
+        const code = errCode(err);
+        if (code === "LIT_LOOP_PLAN_MISSING") {
+            return {
+                check: { name: "plan-schema", status: "warn", detail: "no plan yet — run `litcodex loop create`" },
+                counts: null,
+            };
+        }
+        if (code === "LIT_LOOP_PLAN_CORRUPT") {
+            const backup = errBackup(err);
+            return {
+                check: {
+                    name: "plan-schema",
+                    status: "fail",
+                    detail: "goals.json was corrupt; quarantined to backup",
+                    data: { backup },
+                },
+                counts: null,
+            };
+        }
+        // Any other error (EACCES/EIO on read) — no raw message echoed.
+        return {
+            check: { name: "plan-schema", status: "fail", detail: "could not read goals.json (permission or I/O error)" },
+            counts: null,
+        };
+    }
+}
+async function checkLedger(repoRoot, scope, readLedgerFn) {
+    try {
+        const { entries, skipped } = await readLedgerFn(repoRoot, scope);
+        if (entries.length === 0 && skipped === 0) {
+            return { check: { name: "ledger", status: "warn", detail: "no ledger yet" }, entries: [] };
+        }
+        return {
+            check: {
+                name: "ledger",
+                status: skipped > 0 ? "warn" : "ok",
+                detail: `ledger present (${entries.length} entries, ${skipped} skipped)`,
+                data: { entries: entries.length, skipped },
+            },
+            entries,
+        };
+    }
+    catch {
+        // Defensive — readLedger is fail-open, but the ledger check NEVER fails and NEVER throws.
+        return {
+            check: { name: "ledger", status: "warn", detail: "ledger unreadable (treated as absent)" },
+            entries: [],
+        };
+    }
+}
+async function checkEvidenceDir(repoRoot, scope, statExistsFn) {
+    try {
+        const exists = await statExistsFn(litLoopEvidenceDir(repoRoot, scope));
+        return exists
+            ? { name: "evidence-dir", status: "ok", detail: "evidence/ present" }
+            : { name: "evidence-dir", status: "warn", detail: "evidence/ missing — created lazily on first capture" };
+    }
+    catch {
+        // A3 C6: same downgrade as state-dir; evidence-dir NEVER produces `fail`.
+        return {
+            name: "evidence-dir",
+            status: "warn",
+            detail: "evidence/ unreadable (permission or I/O)",
+            data: { code: "LIT_LOOP_WRITE_FAILED" },
+        };
+    }
+}
+async function checkHook(repoRoot, hookRegisteredFn) {
+    try {
+        const wired = await hookRegisteredFn(repoRoot);
+        return wired
+            ? { name: "hook", status: "ok", detail: "UserPromptSubmit hook registered" }
+            : { name: "hook", status: "warn", detail: "UserPromptSubmit hook not registered — run `litcodex install`" };
+    }
+    catch {
+        // Manifest unreadable / parse error / probe threw ⇒ warn. The hook check NEVER produces `fail`.
+        return { name: "hook", status: "warn", detail: "could not confirm hook registration" };
+    }
+}
+// ── Checkpoint derivation (pure) ──────────────────────────────────────────────────────────────
+/** Scan the ledger tail backward for the last terminal entry; null when none usable. */
+export function latestCheckpointFromLedger(entries) {
+    for (let i = entries.length - 1; i >= 0; i -= 1) {
+        const entry = entries[i];
+        if (entry === undefined) {
+            continue;
+        }
+        const kind = entry["kind"];
+        if (typeof kind !== "string" || !(kind in TERMINAL_LEDGER_KINDS)) {
+            continue;
+        }
+        const goalId = entry["goalId"];
+        const at = entry["at"];
+        if (typeof goalId === "string" && goalId !== "" && typeof at === "string" && at !== "") {
+            return { goalId, status: TERMINAL_LEDGER_KINDS[kind], at };
+        }
+    }
+    return null;
+}
+// ── Orchestrator ──────────────────────────────────────────────────────────────────────────────
+/**
+ * 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 async function runLoopDoctor(options, deps) {
+    const { repoRoot, scope } = options;
+    const d = {
+        readPlan: deps?.readPlan ?? ((r, s) => readPlan(r, s)),
+        readLedger: deps?.readLedger ??
+            (async (r, s) => {
+                const { entries, skipped } = await readLedger(r, s);
+                return { entries: entries, skipped };
+            }),
+        statExists: deps?.statExists ?? statExists,
+        hookRegistered: deps?.hookRegistered ?? hookRegistered,
+    };
+    // Murphy backstop (A3/S11 §9): a non-absolute root is misuse — never throw; report all-warn,
+    // with plan-schema `fail` so `healthy` is false (M09 always passes an absolute cwd).
+    if (typeof repoRoot !== "string" || !isAbsolute(repoRoot)) {
+        const detail = "invalid repoRoot (not absolute)";
+        const names = [
+            "state-dir",
+            "plan-schema",
+            "ledger",
+            "evidence-dir",
+            "hook",
+            "checkpoint",
+        ];
+        const checks = names.map((name) => ({
+            name,
+            status: name === "plan-schema" ? "fail" : "warn",
+            detail,
+        }));
+        return { healthy: false, stateDir: "", checks, latestCheckpoint: null, counts: null };
+    }
+    const stateDirAbs = litLoopDir(repoRoot, scope);
+    const stateDir = repoRelative(stateDirAbs, repoRoot);
+    const stateDirCheck = await checkStateDir(stateDirAbs, d.statExists);
+    const planResult = await checkPlanSchema(repoRoot, scope, d.readPlan);
+    const ledgerResult = await checkLedger(repoRoot, scope, d.readLedger);
+    const evidenceCheck = await checkEvidenceDir(repoRoot, scope, d.statExists);
+    const hookCheck = await checkHook(repoRoot, d.hookRegistered);
+    const latestCheckpoint = latestCheckpointFromLedger(ledgerResult.entries);
+    const checkpointCheck = latestCheckpoint
+        ? {
+            name: "checkpoint",
+            status: "ok",
+            detail: `latest checkpoint ${sanitizeId(latestCheckpoint.goalId)} -> ${latestCheckpoint.status}`,
+        }
+        : { name: "checkpoint", status: "warn", detail: "no checkpoint recorded yet" };
+    const checks = [
+        stateDirCheck,
+        planResult.check,
+        ledgerResult.check,
+        evidenceCheck,
+        hookCheck,
+        checkpointCheck,
+    ];
+    const healthy = checks.every((c) => c.status !== "fail");
+    return { healthy, stateDir, checks, latestCheckpoint, counts: planResult.counts };
+}
+// ── Error helpers ─────────────────────────────────────────────────────────────────────────────
+function errCode(err) {
+    if (typeof err === "object" && err !== null && "code" in err) {
+        const code = err.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    return undefined;
+}
+function errBackup(err) {
+    if (typeof err === "object" && err !== null && "details" in err) {
+        const details = err.details;
+        if (typeof details === "object" && details !== null && "backup" in details) {
+            const backup = details.backup;
+            return typeof backup === "string" ? backup : "";
+        }
+    }
+    return "";
+}

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

@@ -0,0 +1,15 @@
+/** Stable SCREAMING_SNAKE error codes; consumers map them to an exit code via `.code`. */
+export type LoopErrorCode = "LIT_LOOP_SUBCOMMAND_UNKNOWN" | "LIT_LOOP_ARGUMENT_MISSING" | "LIT_LOOP_ARGUMENT_INVALID" | "LIT_LOOP_BRIEF_REQUIRED" | "LIT_LOOP_BRIEF_FILE_UNREADABLE" | "LIT_LOOP_PLAN_EXISTS_COMPLETE" | "LIT_LOOP_PLAN_EXISTS_DIFFERENT_BRIEF" | "LIT_LOOP_EVIDENCE_STATUS_INVALID" | "LIT_LOOP_GOAL_NOT_FOUND" | "LIT_LOOP_CRITERION_NOT_FOUND" | "LIT_LOOP_CRITERIA_NOT_ALL_PASS";
+/** Machine-readable CLI error. `code` is the stable token; the exit code is derived from it. */
+export declare class LitLoopError extends Error {
+    readonly name = "LitLoopError";
+    readonly code: LoopErrorCode;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(message: string, code: LoopErrorCode, details?: Readonly<Record<string, unknown>>);
+}
+/**
+ * Exit code for any thrown error, branching ONLY on `err.code` (A3 C7 — never `instanceof`
+ * PlanMissingError/PlanCorruptError). Store codes (PLAN_MISSING→3, PLAN_CORRUPT→4, WRITE_FAILED→5)
+ * defer to the store-owned {@link exitCodeFor}; the CLI's own codes map here.
+ */
+export declare function exitCodeForLoop(err: unknown): number;

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

@@ -0,0 +1,45 @@
+// src/loop-errors.ts — M09/T14 CLI error model (A3 C7: branch on `err.code`, NOT instanceof).
+//
+// The CLI-owned `LitLoopError` + its stable `LoopErrorCode` union, plus `exitCodeForLoop`, which
+// maps ANY thrown error to an exit code by reading `.code` (never `instanceof`
+// PlanMissingError/PlanCorruptError). The store's own codes (PLAN_MISSING→3, PLAN_CORRUPT→4,
+// WRITE_FAILED→5) defer to the store-owned `exitCodeFor`. Split out of loop-cli for the LOC ceiling
+// and to break the cli↔handlers import cycle (handlers throw these; cli renders + maps them).
+import { exitCodeFor } from "./state-store.js";
+/** Machine-readable CLI error. `code` is the stable token; the exit code is derived from it. */
+export class LitLoopError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.name = "LitLoopError";
+        this.code = code;
+        if (details !== undefined) {
+            this.details = details;
+        }
+    }
+}
+/**
+ * Exit code for any thrown error, branching ONLY on `err.code` (A3 C7 — never `instanceof`
+ * PlanMissingError/PlanCorruptError). Store codes (PLAN_MISSING→3, PLAN_CORRUPT→4, WRITE_FAILED→5)
+ * defer to the store-owned {@link exitCodeFor}; the CLI's own codes map here.
+ */
+export function exitCodeForLoop(err) {
+    const code = typeof err === "object" && err !== null && "code" in err ? err.code : undefined;
+    switch (code) {
+        case "LIT_LOOP_SUBCOMMAND_UNKNOWN":
+            return 1; // unknown subcommand / usage
+        case "LIT_LOOP_ARGUMENT_MISSING":
+        case "LIT_LOOP_ARGUMENT_INVALID":
+        case "LIT_LOOP_BRIEF_REQUIRED":
+        case "LIT_LOOP_BRIEF_FILE_UNREADABLE":
+        case "LIT_LOOP_EVIDENCE_STATUS_INVALID":
+            return 2; // bad args
+        case "LIT_LOOP_GOAL_NOT_FOUND":
+        case "LIT_LOOP_CRITERION_NOT_FOUND":
+        case "LIT_LOOP_CRITERIA_NOT_ALL_PASS":
+        case "LIT_LOOP_PLAN_EXISTS_COMPLETE":
+        case "LIT_LOOP_PLAN_EXISTS_DIFFERENT_BRIEF":
+            return 3; // not found / unresolved
+        default:
+            return exitCodeFor(err); // store codes (3/4/5) + unexpected → 1
+    }
+}

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

@@ -0,0 +1,18 @@
+import { type resolveLoopScope } from "./state-store.js";
+export type LoopClock = () => string;
+export type Ctx = {
+    repoRoot: string;
+    scope: ReturnType<typeof resolveLoopScope>;
+    now: LoopClock;
+};
+export interface HandlerResult {
+    readonly exitCode: number;
+    readonly text: string;
+    readonly json: Record<string, unknown>;
+}
+export declare function hasFlag(argv: readonly string[], flag: string): boolean;
+export declare function handleCreate(argv: readonly string[], ctx: Ctx): Promise<HandlerResult>;
+export declare function handleStatus(ctx: Ctx): Promise<HandlerResult>;
+export declare function handleRun(argv: readonly string[], ctx: Ctx): Promise<HandlerResult>;
+export declare function handleCheckpoint(argv: readonly string[], ctx: Ctx): Promise<HandlerResult>;
+export declare function handleRecordEvidence(argv: readonly string[], ctx: Ctx): Promise<HandlerResult>;