litcodex-ai 0.3.0

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

@@ -0,0 +1,14 @@
+// Single source of the lit-family directive markers (A3 C1).
+// Zero-dependency on purpose: guards.ts, directive.ts, and modes.ts import (and
+// re-export) from here so the dedupe markers can never drift between them
+// while preserving the no-cycle invariant (guards never imports directive).
+export const LIT_LOOP_DIRECTIVE_MARKER = "<lit-loop-mode>";
+export const LIT_LOOP_DIRECTIVE_CLOSE = "</lit-loop-mode>";
+// lit-family modes (multi-mode hook router): each mode owns its open/close marker pair so the
+// per-mode idempotency guard (RC1) scans the transcript for the MATCHED mode's marker only.
+export const LITWORK_DIRECTIVE_MARKER = "<litwork-mode>";
+export const LITWORK_DIRECTIVE_CLOSE = "</litwork-mode>";
+export const LIT_PLAN_DIRECTIVE_MARKER = "<lit-plan-mode>";
+export const LIT_PLAN_DIRECTIVE_CLOSE = "</lit-plan-mode>";
+export const LITGOAL_DIRECTIVE_MARKER = "<litgoal-mode>";
+export const LITGOAL_DIRECTIVE_CLOSE = "</litgoal-mode>";

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

@@ -0,0 +1,15 @@
+import type { LitTriggerToken } from "./trigger.js";
+/** The four lit-family modes. Multiple tokens may map to one mode (lit/litcodex/lit-loop → lit-loop). */
+export type LitMode = "lit-loop" | "litwork" | "lit-plan" | "litgoal";
+/** Per-mode routing spec: its marker pair (guard) + resolved directive path (loader). */
+export interface LitModeSpec {
+    readonly mode: LitMode;
+    readonly openMarker: string;
+    readonly closeMarker: string;
+    /** Absolute path to the mode's directive.md, resolved from this module. */
+    readonly directivePath: string;
+}
+/** Token → mode spec. Frozen; the single source the hook router branches on. */
+export declare const MODE_BY_TOKEN: Readonly<Record<LitTriggerToken, LitModeSpec>>;
+/** The mode spec for a matched token. Total over the token union (every token has a spec). */
+export declare function modeForToken(token: LitTriggerToken): LitModeSpec;

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

@@ -0,0 +1,56 @@
+// src/modes.ts — multi-mode hook router table (RC1/RC2).
+//
+// Maps each bounded trigger token (trigger.ts) to its mode spec: the open/close directive markers
+// (for the per-mode idempotency guard, RC1) and the absolute directive path (for the generic loader,
+// RC2). The three lit-loop-family tokens (lit-loop / litcodex / lit) share the single lit-loop mode;
+// litwork / lit-plan / litgoal each own a distinct mode + directive.
+//
+// Layout decision (SDD RC4): lit-loop keeps the authored `directive.md` at the COMPONENT ROOT (zero
+// churn to its lockstep points); the three new directives live under `directives/<mode>.md`. Paths
+// resolve relative to THIS module so they land correctly from both layouts (src/modes.ts →
+// <component>/… in dev/vitest; dist/modes.js → <pkg>/… in the published tarball, where files[] ships
+// `directive.md` and the `directives/` dir beside dist/). Path resolution never reads the file; the
+// loader reads lazily + fail-silent, so a not-yet-authored directive simply degrades to a noop.
+//
+// Imports markers + the trigger token type only (no cycle: hook → modes → {markers, trigger}).
+import { fileURLToPath } from "node:url";
+import { LIT_LOOP_DIRECTIVE_CLOSE, LIT_LOOP_DIRECTIVE_MARKER, LIT_PLAN_DIRECTIVE_CLOSE, LIT_PLAN_DIRECTIVE_MARKER, LITGOAL_DIRECTIVE_CLOSE, LITGOAL_DIRECTIVE_MARKER, LITWORK_DIRECTIVE_CLOSE, LITWORK_DIRECTIVE_MARKER, } from "./markers.js";
+/** Resolve a path relative to this module (percent-decoding, space/#/Hangul-safe). */
+function resolveFromHere(rel) {
+    return fileURLToPath(new URL(rel, import.meta.url));
+}
+// lit-loop keeps the component-root directive.md (A3 G6); shared by lit / litcodex / lit-loop tokens.
+const LIT_LOOP_SPEC = Object.freeze({
+    mode: "lit-loop",
+    openMarker: LIT_LOOP_DIRECTIVE_MARKER,
+    closeMarker: LIT_LOOP_DIRECTIVE_CLOSE,
+    directivePath: resolveFromHere("../directive.md"),
+});
+/** Token → mode spec. Frozen; the single source the hook router branches on. */
+export const MODE_BY_TOKEN = Object.freeze({
+    "lit-loop": LIT_LOOP_SPEC,
+    litcodex: LIT_LOOP_SPEC,
+    lit: LIT_LOOP_SPEC,
+    litwork: Object.freeze({
+        mode: "litwork",
+        openMarker: LITWORK_DIRECTIVE_MARKER,
+        closeMarker: LITWORK_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/litwork.md"),
+    }),
+    "lit-plan": Object.freeze({
+        mode: "lit-plan",
+        openMarker: LIT_PLAN_DIRECTIVE_MARKER,
+        closeMarker: LIT_PLAN_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/lit-plan.md"),
+    }),
+    litgoal: Object.freeze({
+        mode: "litgoal",
+        openMarker: LITGOAL_DIRECTIVE_MARKER,
+        closeMarker: LITGOAL_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/litgoal.md"),
+    }),
+});
+/** The mode spec for a matched token. Total over the token union (every token has a spec). */
+export function modeForToken(token) {
+    return MODE_BY_TOKEN[token];
+}

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

@@ -0,0 +1,41 @@
+export declare const LIT_LOOP_DIR = ".litcodex/lit-loop";
+export declare const LIT_LOOP_BRIEF = "brief.md";
+export declare const LIT_LOOP_GOALS = "goals.json";
+export declare const LIT_LOOP_LEDGER = "ledger.jsonl";
+export declare const LIT_LOOP_EVIDENCE = "evidence";
+/** Optional session partition. Absent / null ⇒ the unscoped root dir. */
+export interface LitLoopScope {
+    readonly sessionId?: string | null;
+}
+/**
+ * Sanitize an arbitrary session id into a single safe path segment, OR null.
+ * Splits on `/` and `\`, drops "", ".", ".." segments, joins survivors with "-", whitelists
+ * `[A-Za-z0-9._-]` (everything else → "-"), collapses repeats, strips leading dots and
+ * leading/trailing `[.-]`. Provably contains no "/", "\", or ".." and is never "."/""/null-unsafe.
+ */
+export declare function normalizeSessionId(sessionId: string | null | undefined): string | null;
+/** Relative dir: `.litcodex/lit-loop` or `.litcodex/lit-loop/<normalizedSessionId>`. */
+export declare function litLoopRelativeDir(scope?: LitLoopScope): string;
+/** Absolute scope dir. repoRoot MUST be absolute. */
+export declare function litLoopDir(repoRoot: string, scope?: LitLoopScope): string;
+export declare function litLoopBriefPath(repoRoot: string, scope?: LitLoopScope): string;
+export declare function litLoopGoalsPath(repoRoot: string, scope?: LitLoopScope): string;
+export declare function litLoopLedgerPath(repoRoot: string, scope?: LitLoopScope): string;
+export declare function litLoopEvidenceDir(repoRoot: string, scope?: LitLoopScope): string;
+/**
+ * Resolve an evidence file path under the scope's evidence/ dir. Rejects an escaping `name`
+ * (contains "/", "\", "..", or is ""/".") with LIT_LOOP_EVIDENCE_NAME_UNSAFE BEFORE any fs op.
+ */
+export declare function evidencePath(repoRoot: string, name: string, scope?: LitLoopScope): string;
+/** repoRoot-relative, forward-slash form of an absolute path (for messages / plan fields). */
+export declare function repoRelative(absolutePath: string, repoRoot: string): string;
+/**
+ * Resolve a LitLoopScope from argv/env. Precedence (first non-blank wins): `--session <id>` /
+ * `--session=<id>` → env `LITCODEX_LOOP_SESSION` → env `LIT_LOOP_SESSION`. The chosen raw id is
+ * normalized; returns `{ sessionId }` when a non-null id results, else `undefined`. Pure aside
+ * from reading the provided `env` object (NEVER `process.env`); zero I/O.
+ */
+export declare function resolveLoopScope(source: {
+    argv?: readonly string[];
+    env?: Record<string, string | undefined>;
+}): LitLoopScope | undefined;

package/node_modules/@litcodex/lit-loop/dist/state-paths.js

@@ -0,0 +1,111 @@
+// src/state-paths.ts — M08/T13 pure path algebra (A3 C9 flat layout, Part D constants).
+//
+// The literal runtime-layout name constants, the LitLoopScope type, the path-traversal-safe
+// session-id normalizer, every absolute/relative path builder, the evidence-name escape guard,
+// the repo-relative formatter, and the CLI/hook scope resolver. ZERO I/O — pure, deterministic.
+// The state root is LITERALLY `.litcodex/lit-loop` and is NEVER the legacy runtime dir, never absolute here.
+import { isAbsolute, join, relative, sep } from "node:path";
+import { LitLoopStateError } from "./state-types.js";
+// ── Name constants (A3 Part D) ───────────────────────────────────────────────
+export const LIT_LOOP_DIR = ".litcodex/lit-loop";
+export const LIT_LOOP_BRIEF = "brief.md";
+export const LIT_LOOP_GOALS = "goals.json";
+export const LIT_LOOP_LEDGER = "ledger.jsonl";
+export const LIT_LOOP_EVIDENCE = "evidence";
+// ── Session-id normalization (path-traversal guard) ──────────────────────────
+/**
+ * Sanitize an arbitrary session id into a single safe path segment, OR null.
+ * Splits on `/` and `\`, drops "", ".", ".." segments, joins survivors with "-", whitelists
+ * `[A-Za-z0-9._-]` (everything else → "-"), collapses repeats, strips leading dots and
+ * leading/trailing `[.-]`. Provably contains no "/", "\", or ".." and is never "."/""/null-unsafe.
+ */
+export function normalizeSessionId(sessionId) {
+    const trimmed = sessionId?.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const survivors = trimmed.split(/[\\/]+/).filter((seg) => seg !== "" && seg !== "." && seg !== "..");
+    const joined = survivors.length > 0 ? survivors.join("-") : trimmed;
+    const cleaned = joined
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^\.+/, "")
+        .replace(/^[.-]+/, "")
+        .replace(/[.-]+$/, "");
+    return cleaned.length > 0 ? cleaned : null;
+}
+// ── repoRoot guard ───────────────────────────────────────────────────────────
+function assertAbsoluteRepoRoot(repoRoot) {
+    if (typeof repoRoot !== "string" || !isAbsolute(repoRoot)) {
+        throw new LitLoopStateError(`repoRoot must be an absolute path (got ${JSON.stringify(repoRoot)})`, "LIT_LOOP_REPO_ROOT_INVALID", { details: { repoRoot } });
+    }
+}
+// ── Path builders (pure) ─────────────────────────────────────────────────────
+/** Relative dir: `.litcodex/lit-loop` or `.litcodex/lit-loop/<normalizedSessionId>`. */
+export function litLoopRelativeDir(scope) {
+    const id = normalizeSessionId(scope?.sessionId);
+    return id === null ? LIT_LOOP_DIR : `${LIT_LOOP_DIR}/${id}`;
+}
+/** Absolute scope dir. repoRoot MUST be absolute. */
+export function litLoopDir(repoRoot, scope) {
+    assertAbsoluteRepoRoot(repoRoot);
+    return join(repoRoot, litLoopRelativeDir(scope));
+}
+export function litLoopBriefPath(repoRoot, scope) {
+    return join(litLoopDir(repoRoot, scope), LIT_LOOP_BRIEF);
+}
+export function litLoopGoalsPath(repoRoot, scope) {
+    return join(litLoopDir(repoRoot, scope), LIT_LOOP_GOALS);
+}
+export function litLoopLedgerPath(repoRoot, scope) {
+    return join(litLoopDir(repoRoot, scope), LIT_LOOP_LEDGER);
+}
+export function litLoopEvidenceDir(repoRoot, scope) {
+    return join(litLoopDir(repoRoot, scope), LIT_LOOP_EVIDENCE);
+}
+/**
+ * Resolve an evidence file path under the scope's evidence/ dir. Rejects an escaping `name`
+ * (contains "/", "\", "..", or is ""/".") with LIT_LOOP_EVIDENCE_NAME_UNSAFE BEFORE any fs op.
+ */
+export function evidencePath(repoRoot, name, scope) {
+    if (typeof name !== "string" ||
+        name === "" ||
+        name === "." ||
+        name.includes("/") ||
+        name.includes("\\") ||
+        name.includes("..")) {
+        throw new LitLoopStateError(`evidence name escapes the evidence dir: ${JSON.stringify(name)}`, "LIT_LOOP_EVIDENCE_NAME_UNSAFE", { details: { name } });
+    }
+    return join(litLoopEvidenceDir(repoRoot, scope), name);
+}
+/** repoRoot-relative, forward-slash form of an absolute path (for messages / plan fields). */
+export function repoRelative(absolutePath, repoRoot) {
+    const rel = relative(repoRoot, absolutePath);
+    return sep === "\\" ? rel.split(sep).join("/") : rel;
+}
+// ── Scope resolver (CLI/hook callers) ────────────────────────────────────────
+function readSessionFlag(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--session") {
+            return argv[i + 1];
+        }
+        if (arg?.startsWith("--session=")) {
+            return arg.slice("--session=".length);
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve a LitLoopScope from argv/env. Precedence (first non-blank wins): `--session <id>` /
+ * `--session=<id>` → env `LITCODEX_LOOP_SESSION` → env `LIT_LOOP_SESSION`. The chosen raw id is
+ * normalized; returns `{ sessionId }` when a non-null id results, else `undefined`. Pure aside
+ * from reading the provided `env` object (NEVER `process.env`); zero I/O.
+ */
+export function resolveLoopScope(source) {
+    const argv = source.argv ?? [];
+    const env = source.env ?? {};
+    const raw = readSessionFlag(argv) ?? env["LITCODEX_LOOP_SESSION"] ?? env["LIT_LOOP_SESSION"];
+    const sessionId = normalizeSessionId(raw);
+    return sessionId === null ? undefined : { sessionId };
+}

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

@@ -0,0 +1,39 @@
+import { type LitLoopScope } from "./state-paths.js";
+import { type LitLoopLedgerEntry, type LitLoopLedgerInput, type LitLoopPlan } from "./state-types.js";
+export { evidencePath, resolveLoopScope } from "./state-paths.js";
+/** Alias of `litLoopDir` under the name M09 (loop model) and M11 (doctor) import. */
+export declare function resolveLoopStateDir(repoRoot: string, scope?: LitLoopScope): string;
+export declare function statExists(absPath: string): Promise<boolean>;
+export declare class BriefFileMissingError extends Error {
+    readonly name = "BriefFileMissingError";
+    readonly path: string;
+    constructor(path: string, cause?: unknown);
+}
+export declare class BriefFileUnreadableError extends Error {
+    readonly name = "BriefFileUnreadableError";
+    readonly path: string;
+    constructor(path: string, cause?: unknown);
+}
+/**
+ * Read `briefFilePath` as INERT UTF-8 text. The path is used AS GIVEN — no normalization, no
+ * re-rooting against `repoRoot`, no rejection (the bytes are data, never re-interpreted as a
+ * path/flag). ENOENT/EISDIR → BriefFileMissingError; EACCES/EIO → BriefFileUnreadableError.
+ */
+export declare function readBriefFile(_repoRoot: string, briefFilePath: string): Promise<string>;
+export declare function withMutationLock<T>(repoRoot: string, scope: LitLoopScope | undefined, body: () => Promise<T>): Promise<T>;
+/** @deprecated Alias of `withMutationLock` (SAME function reference, same lock map). */
+export declare const withStateMutationLock: typeof withMutationLock;
+export declare function writePlan(repoRoot: string, plan: LitLoopPlan, scope?: LitLoopScope): Promise<void>;
+export declare function writeBrief(repoRoot: string, brief: string, scope?: LitLoopScope): Promise<void>;
+export declare function appendLedger(repoRoot: string, entry: LitLoopLedgerInput, scope?: LitLoopScope): Promise<void>;
+export declare function readLedger(repoRoot: string, scope?: LitLoopScope): Promise<{
+    entries: LitLoopLedgerEntry[];
+    skipped: number;
+}>;
+export declare function ensureEvidenceDir(repoRoot: string, scope?: LitLoopScope): Promise<string>;
+export declare function readPlan(repoRoot: string, scope?: LitLoopScope): Promise<LitLoopPlan>;
+export declare function initState(repoRoot: string, args: {
+    brief: string;
+    sessionId?: string | null;
+}): Promise<LitLoopPlan>;
+export declare function exitCodeFor(err: unknown): number;