@codyswann/lisa 4.66.5 → 4.68.0

package/plugins/src/base/hooks/enforcement-vintage-npm.mjs

@@ -0,0 +1,320 @@
+/**
+ * The two rows `enforcement-vintage` could not show before: the Lisa version the
+ * PROJECT installed, and the newest Lisa PUBLISHED (CodySwannGT/lisa#4325).
+ *
+ * Why these two. The session-copy rows answer "is this session running the
+ * newest Lisa on this disk?" — and a whole host can be current by that measure
+ * while sitting many releases behind npm, because nothing on the disk is newer
+ * than the version the project last installed. A host only moves when something
+ * opens an update PR for it. The agent standing in that host is the party most
+ * able to notice and least likely to be told, so the comparison goes where the
+ * agent reads: the injected context.
+ *
+ * NO NETWORK ON THE STARTUP PATH. A session start must never wait on npm. The
+ * row is read from the cache the `lisa` CLI's own update check already writes
+ * (`node_modules/.cache/@codyswann/lisa/update-check.json`, same shape, same
+ * 6-hour freshness), so the two surfaces cannot disagree about "latest". When
+ * that cache is missing or stale, a DETACHED child refreshes it for the next
+ * session and this session reports what it has — a stale reading named as
+ * stale, never a guess.
+ *
+ * FAIL SOFT, ALWAYS. Every function here returns a neutral value on any error.
+ * @module plugins/src/base/hooks/enforcement-vintage-npm
+ */
+import { spawn } from "child_process";
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+/** The package whose versions are compared. */
+export const LISA_PACKAGE = "@codyswann/lisa";
+
+/** Same freshness window as the CLI update check (`src/cli/update-check.ts`). */
+export const NPM_LATEST_TTL_MS = 6 * 60 * 60 * 1000;
+
+/** Budget for the detached refresh; it runs after the session has started. */
+const REFRESH_TIMEOUT_MS = 5000;
+
+/**
+ * Registry endpoint for the latest dist-tag.
+ *
+ * The cached mutable pointer lags a publish by minutes (CodySwannGT/lisa#3685).
+ * That is fine here for the same reason it is fine in the CLI nag: nothing
+ * downstream of this value chooses, publishes or gates — it is advice.
+ */
+const NPM_LATEST_URL = "https://registry.npmjs.org/@codyswann/lisa/latest";
+
+/** A plain `x.y.z` release, optionally with a prerelease or build suffix. */
+const VERSION_SHAPE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$/u;
+
+/**
+ * Compare two prerelease identifier lists by semver precedence.
+ * @param {string[]} a Identifiers of the first prerelease.
+ * @param {string[]} b Identifiers of the second prerelease.
+ * @returns {number} Negative when `a` precedes `b`, positive when it follows.
+ */
+function comparePrerelease(a, b) {
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    if (a[index] === undefined) return -1;
+    if (b[index] === undefined) return 1;
+    if (a[index] === b[index]) continue;
+    const numeric = /^\d+$/u;
+    if (numeric.test(a[index]) && numeric.test(b[index])) {
+      return Number(a[index]) - Number(b[index]);
+    }
+    if (numeric.test(a[index])) return -1;
+    if (numeric.test(b[index])) return 1;
+    return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Whether version `a` has lower semver precedence than `b`.
+ *
+ * Prerelease-aware on purpose: a project pinned to `4.66.5-rc.1` is BEHIND a
+ * published `4.66.5`, and comparing release fields alone would call it current.
+ * Build metadata is ignored, as semver requires.
+ * @param {string} a Candidate older version.
+ * @param {string} b Candidate newer version.
+ * @returns {boolean} True when `a` precedes `b`.
+ */
+export function precedes(a, b) {
+  const split = version => {
+    const [core, pre] = String(version).split("+")[0].split(/-(.*)/su);
+    const fields = core.split(".").map(field => Number(field) || 0);
+    return { fields, pre: pre ? pre.split(".") : [] };
+  };
+  const left = split(a);
+  const right = split(b);
+  for (let index = 0; index < 3; index += 1) {
+    const l = left.fields[index] ?? 0;
+    const r = right.fields[index] ?? 0;
+    if (l !== r) return l < r;
+  }
+  if (left.pre.length === 0) return false;
+  if (right.pre.length === 0) return true;
+  return comparePrerelease(left.pre, right.pre) < 0;
+}
+
+/**
+ * Parse a JSON file, or return null.
+ * @param {string} file Absolute path.
+ * @returns {any} Parsed JSON, or null when unreadable or malformed.
+ */
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The update-check cache path for a project — the CLI's own path.
+ * @param {string} projectDir Project root.
+ * @returns {string} Absolute cache path.
+ */
+export function npmLatestCachePath(projectDir) {
+  return path.join(
+    projectDir,
+    "node_modules",
+    ".cache",
+    "@codyswann",
+    "lisa",
+    "update-check.json"
+  );
+}
+
+/**
+ * The Lisa version this project installed, or null when it has none to show.
+ *
+ * Null inside the Lisa monorepo itself: there `node_modules/@codyswann/lisa` is
+ * a fixture pinned majors behind the repository, and reporting it as the
+ * project's pin would tell every Lisa session its project is stale.
+ * @param {string} projectDir Project root.
+ * @returns {{version: string, source: string} | null} The installed copy.
+ */
+export function projectPin(projectDir) {
+  const own = readJson(path.join(projectDir, "package.json"));
+  if (own?.name === LISA_PACKAGE) return null;
+  const source = path.join(
+    projectDir,
+    "node_modules",
+    "@codyswann",
+    "lisa",
+    "package.json"
+  );
+  const version = readJson(source)?.version;
+  return typeof version === "string" && VERSION_SHAPE.test(version)
+    ? { version, source }
+    : null;
+}
+
+/**
+ * Read the cached npm latest.
+ * @param {string} cachePath Absolute cache path.
+ * @param {number} nowMs Current time in ms.
+ * @param {number} [ttlMs] Freshness window.
+ * @returns {{version: string, fetchedAt: string, fresh: boolean} | null} Cached value.
+ */
+export function cachedNpmLatest(cachePath, nowMs, ttlMs = NPM_LATEST_TTL_MS) {
+  const cache = readJson(cachePath);
+  const version = cache?.latest;
+  const fetchedAt = cache?.fetchedAt;
+  if (typeof version !== "string" || !VERSION_SHAPE.test(version)) return null;
+  if (typeof fetchedAt !== "string") return null;
+  const fetchedMs = Date.parse(fetchedAt);
+  if (!Number.isFinite(fetchedMs)) return null;
+  return { version, fetchedAt, fresh: nowMs - fetchedMs <= ttlMs };
+}
+
+/**
+ * Whether a refresh should be started for this session.
+ * @param {{version: string, fresh: boolean} | null} cached Cached value.
+ * @param {NodeJS.ProcessEnv} env Environment.
+ * @returns {boolean} True when the cache is missing or stale and checks are on.
+ */
+export function needsRefresh(cached, env) {
+  if (env.LISA_SKIP_UPDATE_CHECK === "1") return false;
+  return cached === null || !cached.fresh;
+}
+
+/**
+ * Start a detached refresh of the cache and return immediately.
+ * @param {string} script Absolute path of this module.
+ * @param {string} cachePath Absolute cache path.
+ * @param {typeof spawn} [spawnImpl] Injected for tests.
+ * @returns {boolean} Whether a child was started.
+ */
+export function startDetachedRefresh(script, cachePath, spawnImpl = spawn) {
+  try {
+    const child = spawnImpl(
+      process.execPath,
+      [script, "--refresh-npm-latest", cachePath],
+      { detached: true, stdio: "ignore" }
+    );
+    child.on?.("error", () => {});
+    child.unref?.();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Fetch npm latest and write it to the cache in the CLI's shape.
+ *
+ * probe-direction: neutral — a failed fetch writes nothing, so the next
+ * session reports "npm latest: unknown" (or the older cached value, labelled
+ * stale); no gate reads this value, it only shapes advisory context.
+ * @param {string} cachePath Absolute cache path.
+ * @param {{fetchImpl?: typeof fetch, now?: () => Date}} [deps] Injected for tests.
+ * @returns {Promise<string | null>} The version written, or null.
+ */
+export async function refreshNpmLatest(cachePath, deps = {}) {
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  const now = deps.now ?? (() => new Date());
+  try {
+    const response = await fetchImpl(NPM_LATEST_URL, {
+      signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    const version = body?.version;
+    if (typeof version !== "string" || !VERSION_SHAPE.test(version)) {
+      return null;
+    }
+    mkdirSync(path.dirname(cachePath), { recursive: true });
+    writeFileSync(
+      cachePath,
+      `${JSON.stringify({ latest: version, fetchedAt: now().toISOString() }, null, 2)}\n`,
+      "utf8"
+    );
+    return version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render the project and npm rows, plus the guidance when the project is behind.
+ * @param {{pin: {version: string, source: string} | null, latest: {version: string, fetchedAt: string, fresh: boolean} | null, refreshing: boolean, projectBehind: boolean}} state Resolved rows.
+ * @returns {{rows: string[], guidance: string[]}} Lines to splice into the block.
+ */
+export function renderNpmRows(state) {
+  const rows = [];
+  if (state.pin) {
+    rows.push(`project pin: lisa ${state.pin.version} at ${state.pin.source}`);
+  }
+  if (state.latest) {
+    rows.push(
+      `npm latest: lisa ${state.latest.version} (checked ${state.latest.fetchedAt}${state.latest.fresh ? "" : "; stale"}${state.refreshing ? ", refreshing for the next session" : ""})`
+    );
+  } else if (state.pin) {
+    rows.push(
+      `npm latest: unknown${state.refreshing ? " (checking in the background for the next session)" : ""}`
+    );
+  }
+  const guidance = state.projectBehind
+    ? [
+        `PROJECT BEHIND — this project installs lisa ${state.pin?.version} while lisa ${state.latest?.version} is published.`,
+        "- Do NOT upgrade Lisa inside the current task: a version bump plus its template apply belongs in its own pull request, never mixed into feature work.",
+        "- Check for an open pull request on a `lisa/update-*` branch. If none is open, the project's Lisa Update workflow (`.github/workflows/lisa-update.yml`) opens one on its schedule; say so in your report, and if that workflow is missing, recommend running `lisa apply` once so the project receives it.",
+      ]
+    : [];
+  return { rows, guidance };
+}
+
+/**
+ * Resolve everything the npm rows need, starting a refresh when warranted.
+ * @param {{projectDir: string, script?: string, env: NodeJS.ProcessEnv, nowMs: number, spawnImpl?: typeof spawn}} input Inputs.
+ * @returns {{pin: {version: string, source: string} | null, latest: {version: string, fetchedAt: string, fresh: boolean} | null, refreshing: boolean, projectBehind: boolean}} Resolved rows.
+ */
+export function resolveNpmState(input) {
+  try {
+    const pin = projectPin(input.projectDir);
+    if (pin === null) {
+      return { pin, latest: null, refreshing: false, projectBehind: false };
+    }
+    const cachePath = npmLatestCachePath(input.projectDir);
+    const latest = cachedNpmLatest(cachePath, input.nowMs);
+    const refreshing =
+      needsRefresh(latest, input.env) &&
+      startDetachedRefresh(
+        input.script ?? fileURLToPath(import.meta.url),
+        cachePath,
+        input.spawnImpl
+      );
+    const projectBehind = Boolean(
+      latest && precedes(pin.version, latest.version)
+    );
+    return { pin, latest, refreshing, projectBehind };
+  } catch {
+    return { pin: null, latest: null, refreshing: false, projectBehind: false };
+  }
+}
+
+/**
+ * Whether this module is the process entry point (the detached refresh child).
+ * Realpaths both sides for the reason `enforcement-vintage.mjs` gives.
+ * @param {string} moduleUrl This module's `import.meta.url`.
+ * @param {string | undefined} [argv1] Entry path.
+ * @returns {boolean} True when run directly.
+ */
+function invokedDirectly(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (
+  invokedDirectly(import.meta.url) &&
+  process.argv[2] === "--refresh-npm-latest" &&
+  process.argv[3]
+) {
+  refreshNpmLatest(process.argv[3]).catch(() => {});
+}

package/plugins/src/base/hooks/enforcement-vintage.mjs

@@ -52,6 +52,7 @@ import { readFileSync, existsSync } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import { realpathSync } from "fs";
+import { renderNpmRows, resolveNpmState } from "./enforcement-vintage-npm.mjs";
 
 /** Marker the block is wrapped in, so an agent can cite it by name. */
 const BLOCK_TAG = "lisa-enforcement-vintage";
@@ -336,6 +337,15 @@ export function renderBlock(state) {
       `newest on this disk: lisa ${state.newest.version} at ${state.newest.source}`
     );
   }
+  const npm = renderNpmRows(
+    state.npm ?? {
+      pin: null,
+      latest: null,
+      refreshing: false,
+      projectBehind: false,
+    }
+  );
+  npm.rows.forEach(row => lines.push(row));
   lines.push("");
   if (state.behind || !state.running.version || state.treeBehind) {
     lines.push(
@@ -363,6 +373,10 @@ export function renderBlock(state) {
         "when you report on guard or contract behaviour; it is only current until the next release."
     );
   }
+  if (npm.guidance.length > 0) {
+    lines.push("");
+    npm.guidance.forEach(line => lines.push(line));
+  }
   lines.push(`</${BLOCK_TAG}>`);
   return lines.join("\n");
 }
@@ -405,9 +419,14 @@ export function run(argv, stdin, env = process.env) {
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: eventName(stdin),
-      additionalContext: renderBlock(
-        resolveState({ hooksDir, projectDir, configDir })
-      ),
+      additionalContext: renderBlock({
+        ...resolveState({ hooksDir, projectDir, configDir }),
+        npm: resolveNpmState({
+          projectDir,
+          env,
+          nowMs: Date.now(),
+        }),
+      }),
     },
   });
 }

package/scripts/lisa-self-update.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Lisa's own entry point for the shipped updater (CodySwannGT/lisa#4331).
+ *
+ * `.github/workflows/lisa-update.yml` runs `node scripts/lisa-self-update.mjs`,
+ * and that path is the CALLER's tree: a host gets it from
+ * `all/copy-overwrite/scripts/` on apply, and in this repository it is this
+ * file. A re-export rather than a second copy, so there is one implementation;
+ * here it runs in self mode because this manifest's name is `@codyswann/lisa`.
+ * @module scripts/lisa-self-update
+ */
+import { runCli } from "../all/copy-overwrite/scripts/lisa-self-update.mjs";
+
+runCli();

package/scripts/two-channel-couplings.json

@@ -97,7 +97,7 @@
     "workflows": 23,
     "steps": 784,
     "couplings": 33,
-    "inventory": 90
+    "inventory": 91
   },
   "counts": {
     "package-backed": 10,

package/typescript/copy-overwrite/.prettierignore

@@ -92,6 +92,7 @@ scripts/lisa-postinstall.mjs
 scripts/lisa-reconcile-policy.mjs
 scripts/lisa-run-gates.mjs
 scripts/lisa-schema-validate.mjs
+scripts/lisa-self-update.mjs
 scripts/lisa-test-node.mjs
 scripts/lisa-work-item.mjs
 scripts/lisa-worktree-guard.mjs

package/typescript/copy-overwrite/audit.ignore.config.json

@@ -137,6 +137,12 @@
       "id": "GHSA-j759-j44w-7fr8",
       "package": "@xmldom/xmldom",
       "reason": "XML node injection via unvalidated comment serialization. Transitive via expo > @expo/config-plugins > @expo/plist; only serializes developer-authored plist files at build/prebuild time, no runtime code path serializes attacker-controlled XML."
+    },
+    {
+      "id": "GHSA-vfj7-8cjw-p6xm",
+      "cve": "CVE-2026-93687",
+      "package": "braces",
+      "reason": "Stack-exhaustion DoS (uncaught RangeError) via deeply nested brace patterns; no patched release exists. Keep this exclusion only if no runtime code path passes attacker-supplied glob or brace patterns to braces/micromatch (dev tooling expanding repo-owned globs is unaffected)."
     }
   ]
 }