@codyswann/lisa 3.16.0 → 3.17.0

package/plugins/lisa/skills/lisa-secrets-access/scripts/routing-floor.mjs

@@ -0,0 +1,153 @@
+/**
+ * Derive the credentials a project's vendor routing already implies.
+ *
+ * `.lisa.config.json` declares `tracker` and `source` — which tracker receives
+ * ticket writes, which system hosts PRDs. Those two lines already determine a
+ * set of credentials without which nothing works: `tracker: "github"` cannot
+ * write an issue without `GH_TOKEN`, `source: "notion"` cannot read a PRD
+ * without `NOTION_API_TOKEN`.
+ *
+ * Until now that mapping lived only in prose, in `config-resolution.md`'s
+ * invariants, with nothing connecting it to `secrets.require`. So the two could
+ * drift silently and adding a vendor never added its credential to the asserted
+ * set — the list was hand-maintained when most of it was deducible.
+ *
+ * This module is that deduction, as code. The floor is *unioned* into the
+ * required set at resolution time rather than checked against a hand-written
+ * list, because correctness should not depend on someone having remembered to
+ * type `GH_TOKEN` into a file. A project still declares its extras — an
+ * `ATTIO_API_KEY` no routing can imply — in `secrets.require`.
+ *
+ * Deliberately not exhaustive about *optional* integrations. A credential
+ * appears here only when the routing that implies it makes the project
+ * non-functional without it. Sonar, Sentry and PostHog are configured
+ * separately and a project runs fine with none of them, so they are extras a
+ * project declares, not a floor anything derives.
+ * @module routing-floor
+ */
+
+/**
+ * The credential each destination tracker cannot operate without.
+ *
+ * Confluence and JIRA share `ATLASSIAN_API_TOKEN` because they are one vendor
+ * behind one token — the same reason `lisa-atlassian-access` serves both.
+ */
+const TRACKER_CREDENTIALS = {
+  jira: ["ATLASSIAN_API_TOKEN"],
+  github: ["GH_TOKEN"],
+  linear: ["LINEAR_API_KEY"],
+};
+
+/** The credential each PRD source cannot be read without. */
+const SOURCE_CREDENTIALS = {
+  notion: ["NOTION_API_TOKEN"],
+  confluence: ["ATLASSIAN_API_TOKEN"],
+  jira: ["ATLASSIAN_API_TOKEN"],
+  github: ["GH_TOKEN"],
+  linear: ["LINEAR_API_KEY"],
+};
+
+/**
+ * The credentials a project's routing makes mandatory.
+ *
+ * An unknown or absent vendor contributes nothing rather than throwing. This
+ * function answers "what does routing imply", and a `tracker` Lisa does not
+ * recognise is a *routing* error that `config-resolution`'s dispatch already
+ * reports with a better message than a credential check could. Failing here
+ * too would report the same defect twice, in the wrong vocabulary, and would
+ * make a preflight the place a typo in `tracker` first surfaces.
+ * @param {{tracker?: string, source?: string}} [routing] Vendor routing.
+ * @returns {readonly string[]} Sorted, de-duplicated credential names.
+ */
+export function routingFloor(routing = {}) {
+  const tracker = normalize(routing.tracker);
+  const source = normalize(routing.source);
+  const names = [
+    ...credentialsFor(TRACKER_CREDENTIALS, tracker),
+    ...credentialsFor(SOURCE_CREDENTIALS, source),
+  ];
+  return [...new Set(names)].sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * Explain which routing key implied each credential.
+ *
+ * The preflight reports a missing credential to whoever has to fix it, and
+ * "GH_TOKEN is required" is a much weaker sentence than "GH_TOKEN is required
+ * because tracker is github". The second names the line of config to change if
+ * the requirement itself is wrong, which is the other valid remedy.
+ * @param {{tracker?: string, source?: string}} [routing] Vendor routing.
+ * @returns {Record<string, string[]>} Credential name to the reasons for it.
+ */
+export function routingFloorReasons(routing = {}) {
+  const tracker = normalize(routing.tracker);
+  const source = normalize(routing.source);
+  const reasons = {};
+  for (const name of credentialsFor(TRACKER_CREDENTIALS, tracker)) {
+    reasons[name] = [`tracker is "${tracker}"`];
+  }
+  for (const name of credentialsFor(SOURCE_CREDENTIALS, source)) {
+    reasons[name] = [...(reasons[name] ?? []), `source is "${source}"`];
+  }
+  return reasons;
+}
+
+/**
+ * Look a vendor up without consulting anything it inherited.
+ *
+ * A routing value reaches these maps as an arbitrary string from a config file,
+ * and plain indexing answers `constructor` and `__proto__` with inherited
+ * members rather than with undefined — so `?? []` never fires and spreading the
+ * result throws `not iterable`. `routingFloor` runs inside `readConfig`, which
+ * means a typo in `tracker` would abort configuration loading with an
+ * iterability error, in place of the documented behavior: an unrecognised
+ * vendor contributes nothing, and routing dispatch reports the typo in its own
+ * vocabulary.
+ * @param {Record<string, string[]>} map Credential map to read.
+ * @param {string} key Normalized vendor name.
+ * @returns {string[]} Declared credentials, empty for anything not declared.
+ */
+function credentialsFor(map, key) {
+  return Object.hasOwn(map, key) ? map[key] : [];
+}
+
+/**
+ * Substrates that satisfy a credential without the variable being set.
+ *
+ * A required name is a proxy for a capability, not an end in itself, and some
+ * capabilities have a second legitimate route. `gh` authenticates from its own
+ * keyring after `gh auth login`, so a laptop can drive every GitHub operation
+ * Lisa performs with `GH_TOKEN` unset — which is the normal state of a
+ * developer machine, not a misconfiguration.
+ *
+ * Without this the floor fails a local session over a credential that surface
+ * demonstrably does not need. That is worse than not checking: a control that
+ * fires when nothing is wrong is one people learn to skip, and it would have
+ * fired on every session in Lisa's own repository.
+ *
+ * This mirrors the credential-substrate-precedence contract the access skills
+ * already follow — a capability is proven by whichever substrate can serve it,
+ * not by one hardcoded variable.
+ *
+ * Kept deliberately small. An entry belongs here only when the alternative is
+ * genuinely equivalent for everything Lisa does with that credential and can be
+ * proven by a cheap local command. `ATLASSIAN_API_TOKEN` is not listed even
+ * though `acli` exists, because the contract ranks the token first and acli
+ * covers only part of the surface.
+ */
+export const SUBSTITUTE_SUBSTRATES = {
+  GH_TOKEN: {
+    command: "gh",
+    args: ["auth", "status"],
+    describes: "the gh CLI is authenticated (gh auth login)",
+  },
+};
+
+/**
+ * Lower-case a routing value, treating blank and absent as the same.
+ * @param {unknown} value Raw routing value.
+ * @returns {string} A comparable key, empty when nothing was declared.
+ */
+function normalize(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}

package/plugins/lisa/skills/lisa-secrets-access/scripts/surfaces.mjs

@@ -18,6 +18,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { bootstrapKeyFor } from "./providers.mjs";
+import { routingFloor } from "./routing-floor.mjs";
 
 /**
  * Capabilities, per surface.
@@ -188,7 +189,7 @@ export function materializedPaths(namespace, env = process.env) {
  * provider means the environment *is* the provider. A credentials manager is
  * the preferred path, never a required one.
  * @param {string} [cwd] Directory to look in.
- * @returns {object} Resolved configuration with defaults applied.
+ * @returns {{provider: string, bootstrap: {sources: string[], key: string|null}, require: string[]|null, requiredFloor: readonly string[], rotating: string[], namespace: string, narrow: object, surface: string, routing: {tracker?: string, source?: string}, capabilities: object}} Resolved configuration with defaults applied.
  */
 export function readConfig(cwd = process.cwd(), env = process.env) {
   const path = join(cwd, ".lisa.config.json");
@@ -203,13 +204,19 @@ export function readConfig(cwd = process.cwd(), env = process.env) {
   // so they can come from the environment instead. Everything else keeps its
   // default, and an environment that sets neither still gets the old behaviour.
   if (!existsSync(path)) return withSurface(fromEnvironment(env));
-  let cfg;
+  let root;
   try {
-    cfg = JSON.parse(readFileSync(path, "utf8")).secrets;
+    root = JSON.parse(readFileSync(path, "utf8"));
   } catch (err) {
     throw new Error(`.lisa.config.json is not readable: ${err.message}`);
   }
-  if (!cfg) return withSurface(DEFAULTS);
+  const cfg = root.secrets;
+  // Read outside the `secrets` block on purpose. The routing that implies a
+  // credential is declared once, at the top level, and restating it under
+  // `secrets` would be a second copy free to disagree with the one every other
+  // skill dispatches on.
+  const routing = { tracker: root.tracker, source: root.source };
+  if (!cfg) return withSurface({ ...DEFAULTS, routing });
   const provider = cfg.provider ?? DEFAULTS.provider;
   const namespace = assertNamespace(cfg.namespace ?? DEFAULTS.namespace);
   return withSurface({
@@ -221,6 +228,7 @@ export function readConfig(cwd = process.cwd(), env = process.env) {
     namespace,
     narrow: { ...DEFAULTS.narrow, ...(cfg.narrow ?? {}) },
     surface: cfg.surface ?? null,
+    routing,
   });
 }
 
@@ -339,11 +347,51 @@ function fromEnvironment(env) {
 }
 
 /**
- * Attach the resolved surface and its capabilities to a configuration.
+ * Attach the resolved surface, its capabilities, and the required sets.
+ *
+ * `require` is flattened here rather than at each caller because this is the
+ * one place that knows the surface, and a surface-scoped list cannot be read
+ * without it.
  * @param {object} cfg Configuration without surface resolution.
- * @returns {object} The same configuration plus `surface` and `capabilities`.
+ * @returns {object} The same configuration plus surface-derived fields.
  */
 function withSurface(cfg) {
   const surface = detectSurface(cfg.surface);
-  return { ...cfg, surface, capabilities: SURFACES[surface] };
+  return {
+    ...cfg,
+    surface,
+    capabilities: SURFACES[surface],
+    require: resolveRequire(cfg.require, surface),
+    requiredFloor: routingFloor(cfg.routing ?? {}),
+  };
+}
+
+/**
+ * Flatten a `require` declaration for one surface.
+ *
+ * Two shapes are accepted. An array is every surface — the original meaning,
+ * and still correct for the many projects whose credentials do not vary. An
+ * object opts into scoping: `all` applies everywhere and a key matching the
+ * surface adds to it.
+ *
+ * Scoping exists because the required set genuinely differs by where the agent
+ * runs. `CLAUDE_ROUTINE_TOKEN` is mandatory on `claude-web` and meaningless on
+ * a laptop; asserting one flat list everywhere would fail a developer's session
+ * over a credential only a cloud surface uses, and the reliable response to a
+ * check that fails for the wrong reason is to stop believing it.
+ *
+ * Returns `null` — not `[]` — when nothing is declared, because the two mean
+ * different things downstream: `null` leaves resolution un-narrowed, while an
+ * empty array would declare that the project needs no secrets and make
+ * `assertDeclared` reject every name.
+ * @param {string[]|Record<string, string[]>|null|undefined} raw Declaration.
+ * @param {string} surface Resolved surface key.
+ * @returns {string[]|null} Names required on this surface, or null.
+ */
+function resolveRequire(raw, surface) {
+  if (!raw) return null;
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw !== "object") return null;
+  const names = [...(raw.all ?? []), ...(raw[surface] ?? [])];
+  return names.length ? [...new Set(names)] : null;
 }

package/plugins/lisa/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -206,22 +206,11 @@ export function validateSecrets(secrets) {
     );
   }
 
-  for (const field of ["require", "rotating"]) {
-    const value = secrets[field];
-    if (value === undefined || value === null) continue;
-    if (!Array.isArray(value)) {
-      problems.push(`secrets.${field} must be an array of exact key names`);
-      continue;
-    }
-    for (const name of value) {
-      if (typeof name !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(name)) {
-        problems.push(
-          `secrets.${field} entry ${JSON.stringify(name)} is not an exact ` +
-            `UPPER_SNAKE_CASE environment-variable name. Lookup is never fuzzy.`
-        );
-      }
-    }
-  }
+  // `rotating` is a flat list on every surface. `require` also accepts a
+  // surface-scoped object, because the required set genuinely differs by where
+  // the agent runs — see `resolveRequire` in surfaces.mjs.
+  validateKeyList("rotating", secrets.rotating, problems);
+  validateRequire(secrets.require, problems);
 
   problems.push(...validatePropagating(secrets.propagating));
 
@@ -263,6 +252,73 @@ export function validateSecrets(secrets) {
  * @param {object} entry The entry or platform block.
  * @param {string[]} problems Accumulator.
  */
+/**
+ * Whether a value parses as a dotted version the comparator can order.
+ * @param {unknown} value Candidate version.
+ * @returns {boolean} True for "20", "1.2", "1.2.3" and similar.
+ */
+function isVersionish(value) {
+  return typeof value === "string" && /^\d+(\.\d+)*$/.test(value.trim());
+}
+
+/**
+ * Validate a flat list of exact environment-variable names.
+ * @param {string} field Config field name, for messages.
+ * @param {unknown} value The declared value.
+ * @param {string[]} problems Collector.
+ */
+function validateKeyList(field, value, problems) {
+  if (value === undefined || value === null) return;
+  if (!Array.isArray(value)) {
+    problems.push(`secrets.${field} must be an array of exact key names`);
+    return;
+  }
+  for (const name of value) {
+    if (typeof name !== "string" || !/^[A-Z][A-Z0-9_]*$/.test(name)) {
+      problems.push(
+        `secrets.${field} entry ${JSON.stringify(name)} is not an exact ` +
+          `UPPER_SNAKE_CASE environment-variable name. Lookup is never fuzzy.`
+      );
+    }
+  }
+}
+
+/**
+ * Validate `require` in either of its two shapes.
+ *
+ * An array means every surface. An object scopes per surface, with `all`
+ * applying everywhere. Unknown keys are rejected rather than ignored: a typo
+ * like `github_actions` for `github-actions` would otherwise resolve to an
+ * empty list and silently assert nothing on the one surface it was written
+ * for — a declaration that reads as protection and delivers none.
+ * @param {unknown} value The declared value.
+ * @param {string[]} problems Collector.
+ */
+function validateRequire(value, problems) {
+  if (value === undefined || value === null) return;
+  if (Array.isArray(value)) {
+    validateKeyList("require", value, problems);
+    return;
+  }
+  if (typeof value !== "object") {
+    problems.push(
+      `secrets.require must be an array of key names, or an object keyed by ` +
+        `surface with an optional "all" entry`
+    );
+    return;
+  }
+  for (const [key, names] of Object.entries(value)) {
+    if (key !== "all" && !SURFACES.has(key)) {
+      problems.push(
+        `secrets.require key "${key}" is not a known surface. ` +
+          `Known: all, ${[...SURFACES].join(", ")}.`
+      );
+      continue;
+    }
+    validateKeyList(`require.${key}`, names, problems);
+  }
+}
+
 function validateInstallArtifact(label, entry, problems) {
   if (!INSTALL_METHODS.has(entry.install)) {
     problems.push(
@@ -308,7 +364,23 @@ export function validateRemoteEnv(remoteEnv) {
   const problems = [];
 
   for (const tool of remoteEnv.tools?.require ?? []) {
-    if (!tool.name) problems.push("remoteEnv.tools.require entry has no name");
+    if (!tool.name) {
+      problems.push("remoteEnv.tools.require entry has no name");
+      continue;
+    }
+    // `minVersion` was accepted unvalidated while `install` entries had their
+    // shape checked in full. The asymmetry mattered: the value is fed to a
+    // version comparison, so `minVersion: "twenty"` sorted below every real
+    // version and the requirement silently passed for any installed release —
+    // a declared constraint that enforced nothing.
+    if (tool.minVersion !== undefined && !isVersionish(tool.minVersion)) {
+      problems.push(
+        `remoteEnv require "${tool.name}" has minVersion ` +
+          `${JSON.stringify(tool.minVersion)}, which is not a dotted version ` +
+          `like "20" or "1.2.3". It is compared numerically, so a value that ` +
+          `does not parse would accept every installed version.`
+      );
+    }
   }
   for (const tool of remoteEnv.tools?.install ?? []) {
     if (!tool.name) {

package/plugins/lisa/skills/lisa-setup-remote-env/scripts/preflight-tools.mjs

@@ -0,0 +1,242 @@
+/**
+ * Prove, before an agent starts work, that the CLIs it needs are on PATH.
+ *
+ * The symmetric half of `preflight-secrets.mjs`, and it exists for the same
+ * reason: the logic to answer the question was already good, and nothing asked
+ * it at the moment the answer mattered. `planToolchain` decides presence,
+ * minimum version, and installability correctly — but its only callers were
+ * `/lisa:setup:local-env`, which a human runs deliberately, and container
+ * provisioning. An agent on a laptop could claim a ticket, cut a branch, and
+ * discover `maestro` was never installed forty minutes later.
+ *
+ * **This is a caller, not a checker.** Every decision comes from
+ * `planToolchain`. Writing a second implementation is exactly the defect this
+ * change also fixes elsewhere — `verify-remote-env.mjs` grew its own toolchain
+ * check that forgot `minVersion`, so a container verified clean against a node
+ * older than the manifest demanded. One function, one verdict, no drift.
+ *
+ * **Two verdicts, not three.** `preflight-secrets` needs `unreachable` because
+ * a vault can fail to be asked. Probing a local binary cannot: it is present or
+ * it is not. The analogous trap — a tool whose version cannot be parsed — is
+ * already handled correctly upstream, because `planRequired` compares
+ * `found.version ?? "0"` and an unknown version loses every `minVersion`
+ * comparison. It fails closed without needing a verdict of its own.
+ *
+ * **The one thing tools have that credentials do not** is a self-service
+ * remedy. An `install` entry is pinned and checksummed, so "missing" splits
+ * into "Lisa can place this for you" and "you must act". A credential can never
+ * be self-provisioned, which is why that distinction has no secrets equivalent.
+ * @module preflight-tools
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { probe, readRemoteEnvConfig } from "./setup-remote-env.mjs";
+import { currentPlatform, planToolchain } from "./toolchain.mjs";
+import { toolFloor } from "./tool-floor.mjs";
+
+/** Plan actions that mean the agent cannot use the tool right now. */
+const BLOCKING = new Set(["missing", "invalid"]);
+
+/**
+ * Read the whole config, for the derivations that live outside `remoteEnv`.
+ *
+ * The floor is implied by `tracker`, `secrets.provider` and `quality`, none of
+ * which sit under `remoteEnv` — so this reads the root rather than reusing
+ * `readRemoteEnvConfig`, which deliberately returns only its own block.
+ *
+ * **Absent and damaged are not the same answer.** A project with no
+ * `.lisa.config.json` declares no tools, and `{}` states that correctly. A file
+ * that exists and does not parse states nothing — and returning `{}` for it
+ * derives an empty floor, which reports `ok` precisely when the declaration
+ * this check exists to enforce could not be read. That is the vacuous green
+ * `preflight-secrets` refuses in its own header, so this throws instead, the
+ * same way `readConfig` in `surfaces.mjs` does.
+ * @param {string} [cwd] Directory to look in.
+ * @returns {object} Parsed config root, empty only when the file is absent.
+ * @throws {Error} When the file exists but cannot be read or parsed.
+ */
+export function readConfigRoot(cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `${path} is not readable, so the tools it requires could not be ` +
+        `derived and nothing was checked: ${err.message}`
+    );
+  }
+}
+
+/**
+ * Merge the derived floor into a declared manifest.
+ *
+ * A derived tool that the project already declares is dropped rather than
+ * duplicated, and the declaration wins: a project that pinned `minVersion` for
+ * `gh` has said something more specific than the derivation knows, and
+ * overriding it would discard the more informed statement.
+ * @param {{require?: object[], install?: object[]}} tools Declared manifest.
+ * @param {Array<{name: string, reason: string}>} floor Derived tools.
+ * @returns {{tools: {require: object[], install?: object[]}, reasons: Record<string, string>}} Merged manifest.
+ */
+export function mergeFloor(tools, floor) {
+  const declared = new Set([
+    ...(tools.require ?? []).map(tool => tool.name),
+    ...(tools.install ?? []).map(tool => tool.name),
+  ]);
+  const added = floor.filter(entry => !declared.has(entry.name));
+  const reasons = Object.fromEntries(
+    floor.map(entry => [entry.name, entry.reason])
+  );
+  return {
+    tools: {
+      ...tools,
+      require: [
+        ...(tools.require ?? []),
+        ...added.map(entry => ({ name: entry.name })),
+      ],
+    },
+    reasons,
+  };
+}
+
+/**
+ * Check every required tool against this machine.
+ * @param {object} [config] Parsed config root.
+ * @param {object} [remoteEnv] Parsed `remoteEnv` block.
+ * @param {Function} [versionProbe] Version probe, injected for tests.
+ * @param {string} [platform] Platform key, injected for tests.
+ * @returns {{verdict: string, blocked: Array<{name: string, action: string, reason: string}>, installable: Array<{name: string, action: string, reason: string}>, reasons: Record<string, string>}}
+ */
+export function preflightTools(
+  config = readConfigRoot(),
+  remoteEnv = readRemoteEnvConfig(),
+  versionProbe = probe,
+  platform = currentPlatform()
+) {
+  const { tools, reasons } = mergeFloor(
+    remoteEnv.tools ?? {},
+    toolFloor(config)
+  );
+  if (!(tools.require ?? []).length && !(tools.install ?? []).length) {
+    return { verdict: "ok", blocked: [], installable: [], reasons };
+  }
+
+  // "local" because this runs where the agent is, and it is the surface word
+  // `appliesToSurface` already understands — a tool narrowed to ["remote"] is
+  // correctly ignored on a laptop rather than reported as missing there.
+  const plan = planToolchain(tools, versionProbe, "local", platform);
+  const blocked = plan.filter(step => BLOCKING.has(step.action));
+  const installable = plan.filter(step => step.action === "install");
+  return {
+    verdict: blocked.length || installable.length ? "missing" : "ok",
+    blocked,
+    installable,
+    reasons,
+  };
+}
+
+/**
+ * Render a verdict for whoever has to act on it.
+ * @param {object} result A {@link preflightTools} result.
+ * @returns {string} Operator-readable report, empty when nothing needs saying.
+ */
+export function reportTools(result) {
+  if (result.verdict === "ok") return "";
+
+  // The header tracks the exit code. Only a blocked tool is a failure — one
+  // Lisa can install is an action with a command attached, and calling that
+  // "FAILED" while exiting zero teaches readers that the word means nothing.
+  const lines = [
+    result.blocked.length
+      ? "Tooling preflight FAILED."
+      : "Tooling preflight — action available.",
+  ];
+  if (result.installable.length) {
+    lines.push(
+      ``,
+      `Lisa can install these itself — they are pinned and checksummed.`,
+      `Run /lisa:setup:local-env to place them:`,
+      ``
+    );
+    for (const step of result.installable) {
+      lines.push(`  ${step.name} — ${step.reason}`);
+    }
+  }
+  if (result.blocked.length) {
+    lines.push(
+      ``,
+      `These need you. Lisa has no pinned artifact it can place:`,
+      ``
+    );
+    for (const step of result.blocked) {
+      const why = result.reasons[step.name];
+      lines.push(`  ${step.name} — ${step.reason}`);
+      if (why) lines.push(`      required because ${why}`);
+    }
+    lines.push(
+      ``,
+      `Work needing one of these cannot be completed. Route the item to`,
+      `blocked with this reason rather than claiming it and stopping partway.`
+    );
+  }
+  return lines.join("\n");
+}
+
+/**
+ * CLI entry point. Prints the report and exits non-zero when anything blocks.
+ */
+function main() {
+  let result;
+  try {
+    result = preflightTools();
+  } catch (err) {
+    // A config that cannot be read is its own outcome, and it is not "ok". Said
+    // in the operator's vocabulary rather than as a stack trace, because this
+    // text is what the session-start hook injects for someone to act on.
+    console.error(
+      [
+        `Tooling preflight could NOT be completed.`,
+        ``,
+        `  reason: ${err.message}`,
+        ``,
+        `Nothing was checked, so this is not a report that the toolchain is`,
+        `fine. Repair the configuration, then start a new session.`,
+      ].join("\n")
+    );
+    process.exit(1);
+  }
+  const text = reportTools(result);
+  if (text) console.error(text);
+  if (result.blocked.length) process.exit(1);
+}
+
+/**
+ * Whether this module is the entry point node was asked to run.
+ *
+ * Both sides are realpath'd rather than compared as text: `import.meta.url` is
+ * the resolved path while `process.argv[1]` is whatever the caller typed, so a
+ * symlinked path — every git worktree, and every `/tmp` path on macOS — makes a
+ * raw comparison false. The module then loads, runs nothing, and exits 0, which
+ * is a readiness check reporting clean because it never ran. Same rule and same
+ * reasoning as `scripts/lib/invoked-as-script.mjs`, written out here because a
+ * plugin payload has no `./lib/` to import from.
+ * @param {string} moduleUrl This module's own `import.meta.url`.
+ * @param {string} [argv1] Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the CLI body should run.
+ */
+function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  main();
+}