litcodex-ai 0.3.3 → 0.3.6

package/dist/cli.js

@@ -2,10 +2,10 @@
 //
 // This compiles to dist/cli.js and is imported by bin/litcodex.js. It owns the routing table for
 // every litcodex subcommand and is fully self-contained: it NEVER spawns a child process itself and
-// NEVER forwards to a separate package. The ONLY child process the installer ever spawns is `codex`,
-// and that spawn lives behind the install/* modules (dist/install/*.js), never in this file —
-// keeping dist/cli.js free of any spawn/forwarder token. Unknown subcommands exit 1 with a
-// plain-text usage notice (LITCODEX_INSTALL_UNKNOWN_COMMAND).
+// NEVER forwards to a separate package. Child processes live behind dedicated modules, never in this
+// file: the installer spawns `codex` (dist/install/*.js), and the update notifier spawns a detached
+// refresh child (dist/update-check.js). dist/cli.js itself stays free of any spawn/forwarder token.
+// Unknown subcommands exit 1 with a plain-text usage notice (LITCODEX_INSTALL_UNKNOWN_COMMAND).
 //
 // Two surfaces:
 //   - `dispatch` — the PURE synchronous router (help/version/unknown + a pure dry-run install plan).
@@ -21,6 +21,7 @@ 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";
+import { maybeNotifyAndRefresh } from "./update-check.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. */
@@ -140,6 +141,15 @@ export async function runCli(argv) {
     const rest = argv.filter((token) => token !== "--dry-run");
     const isHelp = rest.includes("--help") || rest.includes("-h");
     const isVersion = rest.includes("--version") || rest.includes("-v");
+    // Non-blocking update notifier: reads a cache written by a previous run's background child.
+    // Gated to interactive TTY, no CI, no opt-out envs, no --json. Writes to stderr (stdout clean).
+    maybeNotifyAndRefresh({
+        current: manifest.version,
+        isTty: Boolean(process.stdout.isTTY),
+        env: process.env,
+        stderr: process.stderr,
+        json: argv.includes("--json"),
+    });
     if (!isHelp && !isVersion) {
         const head = rest[0];
         if (head === "config" && rest[1] === "migrate") {

package/dist/install/execute.js

@@ -5,9 +5,10 @@
 // no-op regardless of Codex's own re-add exit codes. `config-update` is in-process: it calls
 // `migrateCodexConfig({ env, cwd: codexHome, mode: "install" })` (A3 C4) and maps every
 // `CodexConfigMigrationError` → `LITCODEX_INSTALL_CONFIG_WRITE_FAILED` (exit 3). `hooks-register`
-// is an in-process verification probe (A4) over the bundled metadata — never a config write.
-// `agents-install` copies bundled litwork agent .toml files into <codexHome>/agents/ with
-// backup-safe + idempotent semantics.
+// is a best-effort DEV-ONLY drift guard over the un-bundled plugin metadata (the real hook is wired
+// by `codex plugin add` from the marketplace), so it passes silently in a published install.
+// `agents-install` copies bundled litwork agent .toml files (resolved relative to THIS package, so
+// npx/global installs work regardless of cwd) into <codexHome>/agents/, backup-safe + idempotent.
 import * as nodeFs from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join } from "node:path";
@@ -59,9 +60,11 @@ async function runStep(step, codexBin, deps) {
 /** Copy bundled litwork agent .toml files into <codexHome>/agents/ (backup-safe, idempotent). */
 function runAgentsInstall(step, deps) {
     const wfs = deps.writeFs ?? nodeFs;
-    // Resolve source dir: injected override or resolve via require from repoRoot.
-    const sourceDir = deps.agentsSourceDir ??
-        join(dirname(createRequire(`${deps.repoRoot}/package.json`).resolve("@litcodex/lit-loop/package.json")), "agents");
+    // Resolve source dir: injected override, else the BUNDLED @litcodex/lit-loop. `@litcodex/lit-loop`
+    // is bundled inside the litcodex-ai package, so it must be resolved relative to THIS module first
+    // (works for npx/global installs where cwd is unrelated to the package); the repoRoot anchor is a
+    // dev/in-repo fallback (workspace symlink under the repo root).
+    const sourceDir = deps.agentsSourceDir ?? join(resolveLitLoopDir(deps.repoRoot), "agents");
     // Validate source dir has .toml files.
     if (!wfs.existsSync(sourceDir)) {
         throw new InstallError("LITCODEX_INSTALL_AGENTS_MISSING", "Bundled litwork agent roles are missing.", {
@@ -146,14 +149,25 @@ function runHooksRegister(step, deps) {
     }
     return { kind: step.kind, status: "skipped", detail: "UserPromptSubmit hook wired (manifest-driven)" };
 }
-/** Default hook verification: load + resolve the M14 metadata over repoRoot (dev/test only). */
+/**
+ * Best-effort, DEV-ONLY hook drift guard. The hook payload (the `@litcodex/plugin` metadata resolver
+ * and `.agents/plugins/marketplace.json`) ships only in the repo/plugin tree — it is NEVER bundled
+ * into the published `litcodex-ai` tarball. In a real install the UserPromptSubmit hook is wired by
+ * `codex plugin add` from the GitHub marketplace, not by reading a local file. So this guard resolves
+ * the dev payload lazily and SILENTLY PASSES when it isn't present (published / npx install). Only a
+ * genuine command-literal drift — a real dev defect — throws.
+ */
 function defaultVerifyHook(repoRoot) {
-    // Resolved lazily so the installer never hard-depends on the un-bundled @litcodex/plugin tree.
-    // (In a published tarball this path is exercised via the injected verifyHook; here it backs the
-    // in-repo run.) The require is wrapped so a missing resolver surfaces as a typed HOOKS_MISSING.
-    const req = createRequireForRepo(repoRoot);
-    const meta = req("@litcodex/plugin/dist/metadata.js");
-    const metadata = meta.loadMarketplaceMetadata(repoRoot);
+    let meta;
+    let metadata;
+    try {
+        meta = createRequireForRepo(repoRoot)("@litcodex/plugin/dist/metadata.js");
+        metadata = meta.loadMarketplaceMetadata(repoRoot);
+    }
+    catch {
+        // No dev payload here → published/npx install. Codex wires the hook from the marketplace.
+        return;
+    }
     const handler = meta.resolveUserPromptSubmitHook(metadata);
     if (!handler.command.includes("hook user-prompt-submit") || !handler.command.includes("cli.js")) {
         throw new Error("hook command literal drift");
@@ -162,6 +176,24 @@ function defaultVerifyHook(repoRoot) {
 function createRequireForRepo(repoRoot) {
     return createRequire(`${repoRoot}/package.json`);
 }
+/**
+ * Resolve the bundled `@litcodex/lit-loop` package directory. Tries THIS module first (so a published
+ * npx/global install finds the copy bundled under litcodex-ai/node_modules regardless of cwd), then
+ * the repoRoot anchor (the dev/in-repo workspace symlink). Throws AGENTS_MISSING when neither resolves.
+ */
+function resolveLitLoopDir(repoRoot) {
+    for (const anchor of [import.meta.url, `${repoRoot}/package.json`]) {
+        try {
+            return dirname(createRequire(anchor).resolve("@litcodex/lit-loop/package.json"));
+        }
+        catch {
+            // Try the next anchor.
+        }
+    }
+    throw new InstallError("LITCODEX_INSTALL_AGENTS_MISSING", "Bundled @litcodex/lit-loop is not resolvable.", {
+        repoRoot,
+    });
+}
 /** In-process config migration via the M13 engine; collapses all M13 codes → CONFIG_WRITE_FAILED. */
 async function runConfigUpdate(step, deps) {
     let res;

package/dist/update-check.d.ts

@@ -0,0 +1,46 @@
+/** Path to the on-disk version-check cache. */
+export declare const CACHE_PATH: string;
+/** Re-check at most once every 24 hours. */
+export declare const STALE_MS: number;
+export interface UpdateCache {
+    checkedAt: number;
+    latest: string;
+}
+/**
+ * Read and parse the cached update-check result. Returns null for missing, corrupt, or
+ * unreadable files. NEVER throws.
+ */
+export declare function readUpdateCache(path?: string): UpdateCache | null;
+/**
+ * True when `latest` is strictly newer than `current` (major.minor.patch numeric compare).
+ * Ignores prerelease tags; returns false for malformed input. NEVER throws.
+ */
+export declare function isNewer(latest: string, current: string): boolean;
+/**
+ * True when the environment permits an update check: interactive TTY, no CI, no opt-out.
+ * Independent of NO_COLOR (color is a separate concern).
+ */
+export declare function shouldCheck(opts: {
+    isTty: boolean;
+    env: NodeJS.ProcessEnv;
+    json?: boolean;
+}): boolean;
+/**
+ * Render a tasteful 2-line update notice. Uses the repo's own ANSI helpers when color is true;
+ * emits no escape codes when color is false.
+ */
+export declare function renderUpdateNotice(current: string, latest: string, color: boolean): string;
+/**
+ * The single entry point cli.ts calls. Non-blocking, non-throwing.
+ *
+ * 1. If not interactive / CI / opt-out → return silently.
+ * 2. Read cache → if latest > current → print notice to stderr.
+ * 3. If cache stale or missing → fire-and-forget a detached child to refresh it.
+ */
+export declare function maybeNotifyAndRefresh(opts: {
+    current: string;
+    isTty: boolean;
+    env: NodeJS.ProcessEnv;
+    stderr: NodeJS.WritableStream;
+    json?: boolean;
+}): void;

package/dist/update-check.js

@@ -0,0 +1,182 @@
+// Non-blocking "update available" notifier for the litcodex CLI (zero deps).
+//
+// Two roles:
+//   1. Library — imported by cli.ts to read a cached version check and maybe print a notice.
+//   2. CLI entrypoint — when invoked with `--refresh <current>`, fetches the latest version from
+//      npm and writes the cache. Runs as a detached child; never blocks the parent CLI.
+//
+// The notice you SEE comes from the PREVIOUS run's background check — never from a blocking
+// network call. Offline-safe, CI-silent, pipe-silent, opt-out via LITCODEX_NO_UPDATE_CHECK.
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { get } from "node:https";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { bold, orange } from "./ui.js";
+// ── Cache ───────────────────────────────────────────────────────────────────
+/** Path to the on-disk version-check cache. */
+export const CACHE_PATH = join(homedir(), ".litcodex", "update-check.json");
+/** Re-check at most once every 24 hours. */
+export const STALE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Read and parse the cached update-check result. Returns null for missing, corrupt, or
+ * unreadable files. NEVER throws.
+ */
+export function readUpdateCache(path) {
+    try {
+        const raw = readFileSync(path ?? CACHE_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            typeof parsed.checkedAt === "number" &&
+            typeof parsed.latest === "string") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Semver compare ──────────────────────────────────────────────────────────
+/**
+ * True when `latest` is strictly newer than `current` (major.minor.patch numeric compare).
+ * Ignores prerelease tags; returns false for malformed input. NEVER throws.
+ */
+export function isNewer(latest, current) {
+    try {
+        const parse = (v) => {
+            const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+            if (!m)
+                return null;
+            return [Number(m[1]), Number(m[2]), Number(m[3])];
+        };
+        const l = parse(latest);
+        const c = parse(current);
+        if (!l || !c)
+            return false;
+        for (let i = 0; i < 3; i++) {
+            if (l[i] > c[i])
+                return true;
+            if (l[i] < c[i])
+                return false;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Gating ──────────────────────────────────────────────────────────────────
+/**
+ * True when the environment permits an update check: interactive TTY, no CI, no opt-out.
+ * Independent of NO_COLOR (color is a separate concern).
+ */
+export function shouldCheck(opts) {
+    if (!opts.isTty)
+        return false;
+    if (opts.env["CI"])
+        return false;
+    if (opts.env["NO_UPDATE_NOTIFIER"])
+        return false;
+    if (opts.env["LITCODEX_NO_UPDATE_CHECK"])
+        return false;
+    if (opts.json)
+        return false;
+    return true;
+}
+// ── Notice rendering ────────────────────────────────────────────────────────
+/**
+ * Render a tasteful 2-line update notice. Uses the repo's own ANSI helpers when color is true;
+ * emits no escape codes when color is false.
+ */
+export function renderUpdateNotice(current, latest, color) {
+    const arrow = "→";
+    const latestStyled = color ? bold(orange(latest, true), true) : latest;
+    const line1 = `\u{1F525} Update available  ${current} ${arrow} ${latestStyled}`;
+    const line2 = `   Run  npm i -g litcodex-ai@latest   (or  npx --yes litcodex-ai@latest …)`;
+    return `\n${line1}\n${line2}\n\n`;
+}
+// ── Orchestrator ────────────────────────────────────────────────────────────
+/**
+ * The single entry point cli.ts calls. Non-blocking, non-throwing.
+ *
+ * 1. If not interactive / CI / opt-out → return silently.
+ * 2. Read cache → if latest > current → print notice to stderr.
+ * 3. If cache stale or missing → fire-and-forget a detached child to refresh it.
+ */
+export function maybeNotifyAndRefresh(opts) {
+    try {
+        if (!shouldCheck({ isTty: opts.isTty, env: opts.env, ...(opts.json ? { json: true } : {}) }))
+            return;
+        const cache = readUpdateCache();
+        if (cache && isNewer(cache.latest, opts.current)) {
+            const color = !opts.env["NO_COLOR"];
+            opts.stderr.write(renderUpdateNotice(opts.current, cache.latest, color));
+        }
+        const stale = !cache || Date.now() - cache.checkedAt > STALE_MS;
+        if (stale) {
+            const scriptPath = fileURLToPath(new URL("./update-check.js", import.meta.url));
+            const child = spawn(process.execPath, [scriptPath, "--refresh", opts.current], {
+                detached: true,
+                stdio: "ignore",
+            });
+            child.unref();
+        }
+    }
+    catch {
+        // Never break the CLI for an update check failure.
+    }
+}
+// ── Background refresh child ────────────────────────────────────────────────
+/**
+ * When invoked as `node dist/update-check.js --refresh <current>`, fetch the latest version
+ * from npm and write the cache. All errors are swallowed; the process always exits 0.
+ */
+function refreshAndExit() {
+    const TIMEOUT_MS = 3000;
+    const url = "https://registry.npmjs.org/litcodex-ai/latest";
+    const req = get(url, { timeout: TIMEOUT_MS }, (res) => {
+        let body = "";
+        res.on("data", (chunk) => {
+            body += chunk.toString();
+        });
+        res.on("end", () => {
+            try {
+                const parsed = JSON.parse(body);
+                if (typeof parsed !== "object" || parsed === null)
+                    return;
+                const version = parsed.version;
+                if (typeof version !== "string")
+                    return;
+                writeCache({ checkedAt: Date.now(), latest: version });
+            }
+            catch {
+                // Parse failure — swallow.
+            }
+        });
+    });
+    req.on("error", () => {
+        // Network error — swallow.
+    });
+    req.on("timeout", () => {
+        req.destroy();
+    });
+}
+function writeCache(data) {
+    try {
+        const dir = dirname(CACHE_PATH);
+        mkdirSync(dir, { recursive: true });
+        const tmp = `${CACHE_PATH}.tmp.${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(data), "utf8");
+        renameSync(tmp, CACHE_PATH);
+    }
+    catch {
+        // fs failure — swallow.
+    }
+}
+// ── CLI entrypoint guard ────────────────────────────────────────────────────
+if (process.argv.includes("--refresh")) {
+    refreshAndExit();
+}

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

@@ -1,6 +1,6 @@
 {
 	"name": "@litcodex/lit-loop",
-	"version": "0.3.3",
+	"version": "0.3.6",
 	"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.3",
+	"version": "0.3.6",
 	"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",
@@ -15,7 +15,7 @@
 	},
 	"files": ["bin", "dist", "model-catalog.json", "README.md", "LICENSE"],
 	"dependencies": {
-		"@litcodex/lit-loop": "0.3.3"
+		"@litcodex/lit-loop": "0.3.6"
 	},
 	"bundledDependencies": ["@litcodex/lit-loop"],
 	"scripts": {