@codyswann/lisa 3.16.0 → 3.17.0

package/plugins/src/base/skills/lisa-secrets-access/scripts/preflight-secrets.mjs

@@ -0,0 +1,324 @@
+/**
+ * Prove, before an agent starts work, that the credentials it needs resolve.
+ *
+ * The contract has always claimed this. `secrets.require` is documented as an
+ * assertion — "a listed name that does not resolve is a startup error, not a
+ * late surprise" — and that sentence is the literal text of an error message in
+ * `doctor-secrets.mjs`. But nothing ran it at startup. The only caller of
+ * either presence check was a bash line inside `lisa-doctor`'s SKILL.md, which
+ * an agent had to read and choose to execute. The guarantee was prose; the
+ * plumbing to deliver it did not exist.
+ *
+ * This module is the missing caller, and it answers the question the gate
+ * actually asks. `AGENTS.md` requires intake to establish that the factory has
+ * the tooling "*and provable access to that tooling*" before accepting work. A
+ * credential that resolves nowhere is precisely a failure of provable access,
+ * and discovering it forty minutes into a build — after a ticket is claimed and
+ * a branch is cut — converts a clean refusal into abandoned half-work.
+ *
+ * **Three verdicts, and the third is the point.** `ok` and `missing` are
+ * obvious. `unreachable` is what happens when the provider itself cannot be
+ * asked: no CLI installed, no bootstrap token, an API that errored. That state
+ * must never collapse into either neighbour. Folded into `ok` it is a vacuous
+ * green — the check reports clean precisely when it learned nothing, which is
+ * the failure mode that lets a suppressed error read as a measured zero. Folded
+ * into `missing` it blames the vault for a fault in the caller's access, and
+ * sends whoever reads it to grant a credential that was never absent.
+ *
+ * Both non-ok verdicts fail. They are distinguished in the *message*, not the
+ * exit code, because the remediation differs completely: `missing` means extend
+ * the grant in the vault, `unreachable` means fix this machine's access to it.
+ * @module preflight-secrets
+ */
+
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { fetchAll } from "./providers.mjs";
+import { readConfig } from "./surfaces.mjs";
+import { readMaterialized } from "./resolve-secret.mjs";
+import {
+  routingFloorReasons,
+  SUBSTITUTE_SUBSTRATES,
+} from "./routing-floor.mjs";
+
+/** Verdicts this check can reach, worst last. */
+export const VERDICTS = ["ok", "missing", "unreachable"];
+
+/**
+ * The names that must resolve on this surface, and why each is required.
+ *
+ * The floor is *unioned* with `require` rather than checked against it. A
+ * project should not have to restate `GH_TOKEN` to be protected by a rule its
+ * own `tracker: "github"` already implies, and a required set that depends on
+ * someone having typed it is exactly the hand-maintained list this replaces.
+ *
+ * `require` keeps its second job untouched. It still narrows resolution — a
+ * name outside it cannot be fetched — and the floor deliberately does not feed
+ * that. Unioning the floor into `cfg.require` would switch narrowing *on* for
+ * every project that never opted into it, and every credential they resolve
+ * today that is not in the floor would start throwing.
+ * @param {object} cfg Resolved configuration.
+ * @returns {Array<{name: string, reasons: string[]}>} Required names, sorted.
+ */
+export function requiredNames(cfg) {
+  const reasons = routingFloorReasons(cfg.routing ?? {});
+  const declared = cfg.require ?? [];
+  const names = [...new Set([...(cfg.requiredFloor ?? []), ...declared])];
+  return names
+    .sort((left, right) => left.localeCompare(right))
+    .map(name => ({ name, reasons: whyRequired(name, reasons, declared) }));
+}
+
+/**
+ * Why one name is required, never empty.
+ *
+ * `report` renders this as "NAME — required because <reasons>", so an empty
+ * list prints a sentence that stops mid-clause and tells the operator nothing
+ * about which line of config to change. A name can reach the required set
+ * through the floor without a routing reason — anything that hands `preflight`
+ * a `requiredFloor` it did not derive from `routing` does exactly that — so the
+ * renderer needs a cause it can always print.
+ * @param {string} name The credential name.
+ * @param {Record<string, string[]>} reasons Routing-derived causes.
+ * @param {string[]} declared Names listed in `secrets.require`.
+ * @returns {string[]} At least one reason.
+ */
+function whyRequired(name, reasons, declared) {
+  const routingReasons = Object.hasOwn(reasons, name) ? reasons[name] : [];
+  const causes = [
+    ...(routingReasons ?? []),
+    ...(declared.includes(name) ? ["declared in secrets.require"] : []),
+  ];
+  return causes.length
+    ? causes
+    : ["it is in this project's resolved secrets floor"];
+}
+
+/**
+ * Check every required credential against the resolution ladder.
+ *
+ * Values are never returned, printed, or written anywhere by this function. It
+ * reports names and whether each resolved, which is all a readiness check needs
+ * and the only shape safe to surface into an agent's context.
+ * @param {object} [cfg] Resolved configuration.
+ * @param {Function} [fetch] Provider view factory, injected for tests.
+ * @param {Function} [materialized] Materialized view factory, for tests.
+ * @param {Record<string, string|undefined>} [env] Environment to inspect.
+ * @param {Function} [probe] Substrate probe runner, injected for tests.
+ * @returns {{verdict: string, required: Array<{name: string, reasons: string[]}>, missing: Array<{name: string, reasons: string[]}>, reason: string|null}}
+ */
+export function preflight(
+  cfg = readConfig(),
+  fetch = fetchAll,
+  materialized = readMaterialized,
+  env = process.env,
+  probe = runProbe
+) {
+  const required = requiredNames(cfg);
+  if (!required.length) {
+    return { verdict: "ok", required, missing: [], reason: null };
+  }
+
+  const file = safely(() => materialized(cfg)) ?? new Map();
+
+  // Env and the materialized file are consulted before the provider, and a
+  // required name satisfied by either needs no provider call at all. A session
+  // whose credentials are already exported is the common case on CI, and paying
+  // a network round-trip to confirm what is already in the environment would
+  // make the cheapest surface the slowest.
+  const unresolvedLocally = required.filter(
+    ({ name }) =>
+      !present(env[name]) && !file.get(name) && !substrateSatisfies(name, probe)
+  );
+  if (!unresolvedLocally.length) {
+    return { verdict: "ok", required, missing: [], reason: null };
+  }
+
+  let provider;
+  try {
+    provider = fetch(cfg);
+  } catch (err) {
+    return {
+      verdict: "unreachable",
+      required,
+      missing: unresolvedLocally,
+      reason: err.message,
+    };
+  }
+
+  const missing = unresolvedLocally.filter(
+    ({ name }) => !present(provider.get(name)?.value)
+  );
+  return {
+    verdict: missing.length ? "missing" : "ok",
+    required,
+    missing,
+    reason: null,
+  };
+}
+
+/**
+ * Render a verdict for whoever has to act on it.
+ *
+ * Written for a non-technical operator standing at the gate, per `AGENTS.md`:
+ * everything crossing a gate outward must be readable by the person being asked
+ * to decide. So each line names the credential, why it is required, and which
+ * of the two remedies applies.
+ * @param {object} result A {@link preflight} result.
+ * @param {object} cfg Resolved configuration.
+ * @returns {string} Operator-readable report, empty when nothing needs saying.
+ */
+export function report(result, cfg) {
+  if (result.verdict === "ok") return "";
+
+  const lines = [];
+  if (result.verdict === "unreachable") {
+    lines.push(
+      `Secrets preflight could NOT be completed on surface "${cfg.surface}".`,
+      `The "${cfg.provider}" provider could not be reached, so nothing is`,
+      `known about any credential — this is not a report that they are fine.`,
+      ``,
+      `  reason: ${result.reason}`,
+      ``,
+      `Fix this machine's access to the provider (bootstrap token, CLI`,
+      `install, network), then start a new session. Do not treat the`,
+      `credentials below as verified:`
+    );
+  } else {
+    lines.push(
+      `Secrets preflight FAILED on surface "${cfg.surface}".`,
+      `These credentials are required and resolve nowhere — not in the`,
+      `environment, not materialized, not in the "${cfg.provider}" grant.`,
+      `Extend the grant in the vault (or correct the routing that requires`,
+      `them), then start a new session:`
+    );
+  }
+  lines.push(``);
+  for (const { name, reasons } of result.missing) {
+    lines.push(`  ${name} — required because ${reasons.join("; ")}`);
+  }
+  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");
+}
+
+/**
+ * Whether an alternative substrate already provides this capability.
+ * @param {string} name Required credential name.
+ * @param {Function} probe Probe runner, injected for tests.
+ * @returns {boolean} True when the substrate answered successfully.
+ */
+function substrateSatisfies(name, probe) {
+  const substrate = SUBSTITUTE_SUBSTRATES[name];
+  return substrate ? probe(substrate) : false;
+}
+
+/**
+ * How long a substrate probe may take before it counts as no answer.
+ *
+ * `gh auth status` contacts GitHub, and this runs on the session-start path.
+ * Unbounded, a hung connection holds the session open for as long as the child
+ * lives — the `catch` cannot help, because it is only reached once the call
+ * returns. Five seconds is far beyond a healthy round trip and far below the
+ * point where a person concludes the agent is broken.
+ */
+const PROBE_TIMEOUT_MS = 5000;
+
+/**
+ * Run a substrate probe, treating any failure as "did not satisfy".
+ *
+ * Output is discarded rather than captured. The probe's job is to answer a
+ * yes/no question with its exit status, and a command that can print a
+ * credential is one whose stdout should never enter this process.
+ *
+ * A timeout throws, which the catch maps to false — the fail-closed answer. The
+ * credential is then checked against the environment, the materialized file and
+ * the provider as if no substrate existed, so a slow network costs a stricter
+ * check rather than a wrong verdict.
+ *
+ * Exported so the bound itself can be proved against a real slow command. A
+ * timeout that only exists as an option object is a claim; one that has been
+ * watched cut a hanging child off is a control.
+ * @param {{command: string, args: string[]}} substrate Probe definition.
+ * @returns {boolean} True when the command exited zero.
+ */
+export function runProbe(substrate) {
+  try {
+    execFileSync(substrate.command, substrate.args, {
+      stdio: "ignore",
+      timeout: PROBE_TIMEOUT_MS,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether a resolved value counts as present.
+ * @param {unknown} value Candidate value.
+ * @returns {boolean} True when it is a non-blank string.
+ */
+function present(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Run a thunk, treating any throw as "no view available".
+ *
+ * The materialized file is optional on every surface and absent on most, so a
+ * failure to read it is not a preflight failure — the provider is still
+ * authoritative. Only the provider's own unavailability is a verdict.
+ * @param {Function} thunk Work to attempt.
+ * @returns {*} The result, or undefined when it threw.
+ */
+function safely(thunk) {
+  try {
+    return thunk();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * CLI entry point. Prints the report and exits non-zero on any failure.
+ */
+function main() {
+  const cfg = readConfig();
+  const result = preflight(cfg);
+  const text = report(result, cfg);
+  if (text) console.error(text);
+  if (result.verdict !== "ok") 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();
+}

package/plugins/src/base/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/src/base/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;
 }