@codyswann/lisa 2.318.0 → 2.320.0

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

@@ -5,15 +5,26 @@
  * This is the script a remote environment's setup **and** maintenance fields
  * call. They are the same script on purpose. A container may be built fresh or
  * resumed from cache, and every step here is idempotent and version-aware, so
- * running it twice is correct and running it on resume is what picks up a
- * rotated value, an edited note, or a changed version pin.
+ * running it twice is correct.
  *
  * Order matters. The toolchain comes first because the secrets step needs the
  * provider CLI that the toolchain installs. The project hook comes last because
  * it is the only part that may assume everything else is ready.
  *
+ * **Which phases run depends on the surface, and the reason is not cosmetic.**
+ * On a surface that re-runs this script when a container resumes, materializing
+ * here is what picks up a rotated value. On a surface that *skips* it whenever a
+ * filesystem cache exists, materializing here would write the value once and
+ * then never refresh it — a rotated credential would stay stale until the cache
+ * expired. Those surfaces materialize from a session-start hook instead, which
+ * runs every session including resumed ones, and `--phase=secrets` is how that
+ * hook re-enters this file.
+ *
+ * The selection comes from the surface's `materializeAt` capability rather than
+ * from its name, so adding a surface does not mean editing a branch here.
+ *
  * Usage:
- *   setup-remote-env.mjs [--dry-run]
+ *   setup-remote-env.mjs [--dry-run] [--phase=toolchain|secrets|hook]
  * @module setup-remote-env
  */
 
@@ -26,7 +37,7 @@ import {
   rmSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { assertPinned, extractVersion, planToolchain } from "./toolchain.mjs";
 
@@ -197,31 +208,252 @@ function runHook(hook, dryRun) {
   execFileSync("bash", [path], { stdio: "inherit" });
 }
 
-function main() {
+/** Phases this runner can execute, in the order they must happen. */
+const PHASES = ["toolchain", "secrets", "hook"];
+
+/**
+ * The settings block that wires the session-start hook into a repository.
+ *
+ * Emitted rather than written, because `.claude/settings.json` belongs to the
+ * project: it may already carry hooks, and merging someone else's file from
+ * here is how a careless tool destroys a configuration it did not understand.
+ */
+const SESSION_START_BLOCK = `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \\"$CLAUDE_PROJECT_DIR\\"/scripts/lisa-remote-env/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}`;
+
+/**
+ * Produce the configuration a human pastes to provision a Claude cloud surface.
+ *
+ * This surface has no API tier and no console tier to fall back to: a Claude
+ * cloud environment is configured only in the environment dialog, which has no
+ * settings page, no direct URL, and no endpoint. Emit is not a degraded option
+ * here, it is the only one — so the read-back in `verify-remote-env.mjs` is
+ * what makes the result trustworthy, exactly as it would be at any other tier.
+ * @param {{bootstrapKey: string|null, install: string}} options Project details.
+ * @returns {string} Text to show the operator.
+ */
+export function emitClaudeWeb({ bootstrapKey, install }) {
+  const key = bootstrapKey ?? "<secrets.bootstrap.key is not configured>";
+  return [
+    "Provisioning tier: EMIT — and for this surface that is the only tier.",
+    "  A Claude cloud environment is account-scoped configuration edited in the",
+    "  environment selector at claude.ai/code. There is no settings page, no",
+    "  direct URL and no API, so nothing here can provision it for you.",
+    "",
+    "Paste into the environment dialog",
+    "---------------------------------",
+    "  Network access:  Trusted, or Custom plus any host your project needs",
+    "",
+    "  Environment variables:",
+    `    ${key}=<read this from your credential manager>`,
+    "",
+    "    Only the bootstrap belongs in this box. Values here are stored as",
+    "    plain text and are readable by anyone who uses the environment — on an",
+    "    organization-shared environment that is every member of the org. Every",
+    "    other credential is materialized by the session-start hook below, which",
+    "    is why exactly one value needs to live here.",
+    "",
+    "  Setup script:",
+    `    ${install} && bash scripts/lisa-remote-env/setup.sh`,
+    "",
+    "    The install must come first. On a fresh container node_modules is the",
+    "    only copy of the Lisa skills present, because Claude receives them as",
+    "    an installed plugin rather than as part of the clone.",
+    "",
+    "Commit to the repository",
+    "------------------------",
+    "  scripts/lisa-remote-env/session-start.sh   (from this skill's assets)",
+    "",
+    "  .claude/settings.json — merge this into any hooks already there:",
+    SESSION_START_BLOCK.split("\n")
+      .map(line => `    ${line}`)
+      .join("\n"),
+    "",
+    "    The setup script is skipped whenever a cached environment exists, so",
+    "    secrets are materialized from this hook instead. It runs every session,",
+    "    including a resumed one, which is what keeps a rotated value current.",
+    "",
+    "Worth knowing about this base image",
+    "-----------------------------------",
+    "  The GitHub CLI is not pre-installed. If this project's flows shell out to",
+    "  `gh`, add it to remoteEnv.tools.install with a pinned version and",
+    "  checksum, the same as any other tool.",
+    "",
+    "  A credential handled by the GitHub proxy reads as the literal string",
+    '  "proxy-injected" inside the session. Tools that authenticate through the',
+    "  proxy work; a script that reads the variable itself gets the placeholder.",
+    "",
+    "Then prove it",
+    "-------------",
+    "  Start a session and run the read-back. Whatever provisioned an",
+    "  environment, the same verify is what makes it trustworthy:",
+    "    node node_modules/@codyswann/lisa/plugins/lisa/skills/lisa-setup-remote-env/scripts/verify-remote-env.mjs",
+  ].join("\n");
+}
+
+/**
+ * Decide which phases this invocation runs.
+ *
+ * An explicit `--phase` always wins, because that is how a session-start hook
+ * asks for the one phase it owns. Otherwise every phase runs except a secrets
+ * step that belongs to a different moment on this surface — running it here
+ * would produce a copy that the surface never refreshes.
+ * @param {string|undefined} requested Value of `--phase`, when given.
+ * @param {string|null} materializeAt When this surface materializes.
+ * @returns {string[]} Phases to run, in order.
+ */
+export function selectPhases(requested, materializeAt) {
+  if (requested) {
+    if (!PHASES.includes(requested)) {
+      throw new Error(
+        `unknown --phase "${requested}". Known: ${PHASES.join(", ")}.`
+      );
+    }
+    if (requested === "secrets" && materializeAt !== "session-start") {
+      // Not an error: the hook is committed to the repository and runs on every
+      // surface the project is ever checked out on. Refusing loudly would make
+      // a correct local session look broken every time it started.
+      return [];
+    }
+    return [requested];
+  }
+  return PHASES.filter(
+    phase => phase !== "secrets" || materializeAt === "setup"
+  );
+}
+
+/**
+ * Read the surface the resolver detects, without duplicating its rules.
+ *
+ * Imported rather than shelled out to, because the answer is a pure function of
+ * the environment and a subprocess would buy nothing. The path is converted to
+ * a file URL first: a bare absolute path is not a portable module specifier.
+ * @returns {Promise<{surface: string, materializeAt: string|null}>} Detected surface.
+ */
+async function detectSurface() {
+  const script = siblingScript("lisa-secrets-access", "surfaces.mjs");
+  const mod = await import(pathToFileURL(script).href);
+  const surface = mod.detectSurface();
+  return { surface, materializeAt: mod.SURFACES[surface].materializeAt };
+}
+
+/**
+ * Name the project's own install command rather than inventing one.
+ *
+ * The emitted setup line must begin with whatever this project already uses; a
+ * guessed package manager produces a container that fails on its first command.
+ * @param {string} [cwd] Repository root.
+ * @returns {string} The install command to place before the setup script.
+ */
+export function detectInstallCommand(cwd = process.cwd()) {
+  const lockfiles = [
+    ["bun.lockb", "bun install"],
+    ["bun.lock", "bun install"],
+    ["pnpm-lock.yaml", "pnpm install --frozen-lockfile"],
+    ["yarn.lock", "yarn install --immutable"],
+    ["package-lock.json", "npm ci"],
+  ];
+  for (const [file, command] of lockfiles) {
+    if (existsSync(join(cwd, file))) return command;
+  }
+  return "<your install command>";
+}
+
+/**
+ * Read the bootstrap key name, which is the one value the operator must paste.
+ * @param {string} [cwd] Repository root.
+ * @returns {string|null} The configured key name, when there is one.
+ */
+function readBootstrapKey(cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8")).secrets?.bootstrap?.key ?? null;
+}
+
+async function main() {
   const dryRun = process.argv.includes("--dry-run");
+  const emit = process.argv
+    .find(arg => arg.startsWith("--emit="))
+    ?.slice("--emit=".length);
+
+  if (emit) {
+    if (emit !== "claude-web") {
+      throw new Error(
+        `no emit template for surface "${emit}".\n` +
+          `Emitting is implemented for claude-web, which has no other tier.`
+      );
+    }
+    console.log(
+      emitClaudeWeb({
+        bootstrapKey: readBootstrapKey(),
+        install: detectInstallCommand(),
+      })
+    );
+    return;
+  }
+
+  const requested = process.argv
+    .find(arg => arg.startsWith("--phase="))
+    ?.slice("--phase=".length);
   const cfg = readRemoteEnvConfig();
+  const { surface, materializeAt } = await detectSurface();
+  const phases = selectPhases(requested, materializeAt);
 
-  console.log("Toolchain:");
-  applyToolchain(cfg.tools, dryRun);
+  if (!phases.length) {
+    console.log(
+      `Nothing to do: surface "${surface}" does not materialize from a ` +
+        `session-start hook.`
+    );
+    return;
+  }
 
-  console.log("\nSecrets:");
-  const materialize = siblingScript(
-    "lisa-secrets-access",
-    "materialize-secrets.mjs"
-  );
-  execFileSync("node", dryRun ? [materialize, "--dry-run"] : [materialize], {
-    stdio: "inherit",
-  });
+  if (phases.includes("toolchain")) {
+    console.log("Toolchain:");
+    applyToolchain(cfg.tools, dryRun);
+  }
+
+  if (phases.includes("secrets")) {
+    console.log("\nSecrets:");
+    const materialize = siblingScript(
+      "lisa-secrets-access",
+      "materialize-secrets.mjs"
+    );
+    execFileSync("node", dryRun ? [materialize, "--dry-run"] : [materialize], {
+      stdio: "inherit",
+    });
+  } else if (!requested) {
+    console.log(
+      `\nSecrets: materialized from a session-start hook on "${surface}", ` +
+        `not here.\n` +
+        `  This script is skipped whenever a cached environment exists, so a ` +
+        `value written\n  here would go stale the moment it was rotated. The ` +
+        `hook runs every session.`
+    );
+  }
 
-  runHook(cfg.hook, dryRun);
+  if (phases.includes("hook")) runHook(cfg.hook, dryRun);
   console.log(`\nRemote environment ${dryRun ? "plan complete" : "ready"}.`);
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
-  try {
-    main();
-  } catch (err) {
+  // Awaited rather than called bare: main is async, so a synchronous try/catch
+  // would let a rejected promise escape as an unhandled rejection and exit 0 —
+  // reporting a prepared environment that was never prepared.
+  main().catch(err => {
     console.error(err.message);
     process.exit(1);
-  }
+  });
 }

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

@@ -22,7 +22,8 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
 
 import { readRemoteEnvConfig } from "./setup-remote-env.mjs";
 import { extractVersion } from "./toolchain.mjs";
@@ -119,6 +120,43 @@ function verifyToolchain(tools) {
   }
 }
 
+/**
+ * Assert that a declared credential is genuinely readable, not a proxy stand-in.
+ *
+ * A surface may keep a credential outside the sandbox entirely and substitute
+ * the real value at egress. The variable is then present and non-empty, so a
+ * presence check passes — and a script that reads the variable and puts it in a
+ * header sends the placeholder and fails somewhere far from here, with an error
+ * that points at the service rather than at the environment.
+ *
+ * Reported without printing any value: the placeholder is compared, and a real
+ * credential is only ever reported as present.
+ *
+ * Takes its reporter as an argument rather than writing to this module's
+ * results array, so the rule can be exercised against a synthetic environment
+ * without a container and without leaking findings between runs.
+ * @param {string[]} required Declared credential names.
+ * @param {Record<string, string|undefined>} env Environment to inspect.
+ * @param {(ok: boolean, label: string, detail: string) => void} report Collector.
+ */
+export function verifyNotProxied(required, env, report) {
+  for (const name of required) {
+    const value = (env[name] ?? "").trim();
+    if (!value) {
+      report(false, `credential ${name}`, "declared but not present");
+      continue;
+    }
+    report(
+      value !== "proxy-injected",
+      `credential ${name}`,
+      value === "proxy-injected"
+        ? 'reads as "proxy-injected" — substituted at egress, so anything ' +
+            "reading this variable directly receives the placeholder"
+        : "present"
+    );
+  }
+}
+
 /**
  * Assert the working tree is clean.
  *
@@ -142,11 +180,28 @@ function verifyCleanCheckout() {
   }
 }
 
+/**
+ * Read the credential names the project declares it needs.
+ * @param {string} [cwd] Repository root.
+ * @returns {string[]} Declared names, or none when unconfigured.
+ */
+function readRequired(cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) return [];
+  const required = JSON.parse(readFileSync(path, "utf8")).secrets?.require;
+  if (required == null) return [];
+  if (!Array.isArray(required)) {
+    throw new Error("secrets.require must be an array when present");
+  }
+  return required;
+}
+
 function main() {
   const cfg = readRemoteEnvConfig();
   const secretsDir = process.argv[2];
 
   verifyToolchain(cfg.tools);
+  verifyNotProxied(readRequired(), process.env, check);
 
   const surface = node([
     new URL(

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.318.0",
+  "version": "2.320.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/skills/lisa-secrets-access/scripts/doctor-secrets.mjs

@@ -47,6 +47,16 @@ function fingerprint(value) {
   return createHash("sha256").update(value).digest("hex").slice(0, 12);
 }
 
+/**
+ * The value a proxied credential reads as instead of a usable token.
+ *
+ * Some surfaces keep a credential outside the sandbox entirely and substitute
+ * the real value at egress. The variable is then present and non-empty, which
+ * is exactly what makes it dangerous: a presence check passes, and only a
+ * consumer that reads the variable *itself* discovers it holds a placeholder.
+ */
+const PROXY_PLACEHOLDER = "proxy-injected";
+
 /**
  * Assert every declared name actually resolves.
  * @param {object} cfg Resolved configuration.
@@ -56,18 +66,36 @@ function fingerprint(value) {
  */
 export function checkRequired(cfg, provider, file, report) {
   for (const name of cfg.require ?? []) {
-    const resolves =
-      (process.env[name] ?? "").trim() ||
-      file.get(name) ||
-      provider.get(name)?.value;
-    if (resolves) report("ok", name, "resolves");
-    else
+    const fromEnv = (process.env[name] ?? "").trim();
+    const resolves = fromEnv || file.get(name) || provider.get(name)?.value;
+
+    if (!resolves) {
       report(
         "error",
         name,
         "declared in secrets.require but resolves nowhere — a startup error, " +
           "not a late surprise"
       );
+      continue;
+    }
+
+    // Reported separately from "resolves" because the two are not the same
+    // claim. A tool that authenticates through the proxy works; a script that
+    // reads this variable and puts it in an Authorization header sends the
+    // literal placeholder and gets a confusing auth failure far from here.
+    if (fromEnv === PROXY_PLACEHOLDER) {
+      report(
+        "warn",
+        name,
+        `reads as the literal string "${PROXY_PLACEHOLDER}" — the value is ` +
+          `substituted at egress and never enters this environment. Tools that ` +
+          `authenticate through the proxy work; anything reading this variable ` +
+          `directly gets the placeholder, not a credential`
+      );
+      continue;
+    }
+
+    report("ok", name, "resolves");
   }
 }
 

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

@@ -28,11 +28,36 @@ import { join } from "node:path";
  * drift and leak. It is *required* on surfaces whose bootstrap runs before the
  * consuming process exists and which therefore have no other channel; a remote
  * agent container prepares itself during setup, long before any task starts.
+ *
+ * `materializeAt` — *when* the write happens, for surfaces that do one. The two
+ * remote surfaces share the capability but not the timing, and a reader adding a
+ * third should not assume otherwise. `codex-cloud` re-runs its setup script when
+ * a container resumes, so materializing during setup picks up a rotated value.
+ * `claude-web` *skips* its setup script whenever a filesystem cache exists, so
+ * materializing there would strand a rotated value until the cache expired —
+ * it materializes from a session-start hook instead, which runs every session.
+ *
+ * Stated as a capability rather than inferred from the surface name, so the
+ * setup runner selects its phases from the table instead of branching on which
+ * vendor it happens to be talking to.
  */
 export const SURFACES = {
-  local: { materialized: false, mayWriteValues: false },
-  "github-actions": { materialized: false, mayWriteValues: false },
-  "codex-cloud": { materialized: true, mayWriteValues: true },
+  local: { materialized: false, mayWriteValues: false, materializeAt: null },
+  "github-actions": {
+    materialized: false,
+    mayWriteValues: false,
+    materializeAt: null,
+  },
+  "codex-cloud": {
+    materialized: true,
+    mayWriteValues: true,
+    materializeAt: "setup",
+  },
+  "claude-web": {
+    materialized: true,
+    mayWriteValues: true,
+    materializeAt: "session-start",
+  },
 };
 
 /** Config defaults when `.lisa.config.json` carries no `secrets` block. */
@@ -68,6 +93,10 @@ export function detectSurface(configured = null, env = process.env) {
     return explicit;
   }
   if ((env.GITHUB_ACTIONS ?? "") === "true") return "github-actions";
+  // Compared to the exact string rather than tested for presence: the variable
+  // is documented as carrying "true" in a cloud session and never being true
+  // locally, so a presence test would misread a shell that exports it empty.
+  if ((env.CLAUDE_CODE_REMOTE ?? "") === "true") return "claude-web";
   if ((env.CODEX_SANDBOX ?? env.CODEX_HOME ?? "") !== "") return "codex-cloud";
   return "local";
 }

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

@@ -19,14 +19,59 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { SURFACES as SURFACE_CAPABILITIES } from "./surfaces.mjs";
+
 /** Providers with a read implementation today. */
 const IMPLEMENTED_PROVIDERS = new Set(["bitwarden", "doppler", "env"]);
 
 /** Providers named in the dispatch table but not yet implemented. */
 const DECLARED_PROVIDERS = new Set(["1password", "aws", "vault"]);
 
-/** Surfaces the resolver knows. */
-const SURFACES = new Set(["local", "github-actions", "codex-cloud"]);
+/**
+ * Surfaces the resolver knows.
+ *
+ * Derived from the resolver's own table rather than restated here. The two
+ * lists previously drifted apart by construction: adding a surface meant
+ * remembering to edit a second file, and forgetting produced a config that
+ * resolved correctly at runtime while `doctor` called it unknown.
+ */
+const SURFACES = new Set(Object.keys(SURFACE_CAPABILITIES));
+
+/**
+ * What a provisioned surface must record before anything dispatches to it.
+ *
+ * Deliberately not uniform, because these surfaces do not bind the same way. A
+ * Codex Cloud environment is bound to one repository, so naming the repository
+ * is part of proving the environment is the right one. A Claude cloud
+ * environment has no repository at all — it is account-scoped configuration
+ * (network policy, variables, setup script) and the repository arrives per
+ * session — so its durable handle is the routine that dispatch fires.
+ *
+ * Requiring `repository` of every surface, as this file used to, would demand
+ * a field that cannot be true of `claude-web` in any meaningful sense.
+ *
+ * `repository` stays the default so every existing surface keeps its current
+ * contract. This file checks structure only — whether a declaration *could* be
+ * correct — so it deliberately does not restate the fuller preconditions that
+ * `lisa-remote-dispatch` enforces at the moment it actually dispatches.
+ */
+const SURFACE_BINDINGS = {
+  "claude-web": ["routineId", "fireUrl"],
+};
+
+/**
+ * The fields a surface must record, with the default applied.
+ *
+ * Read through one helper rather than at each call site, because the two
+ * callers answer different questions — "could this declaration be correct" and
+ * "may an automation dispatch to it" — and a fallback that drifted between them
+ * would let those answers disagree about the very same config.
+ * @param {string} surface Surface name.
+ * @returns {string[]} Field names that must be present.
+ */
+function bindingsFor(surface) {
+  return SURFACE_BINDINGS[surface] ?? ["repository"];
+}
 
 /** Install methods the toolchain runner supports. */
 const INSTALL_METHODS = new Set(["release-zip", "npm-global"]);
@@ -139,15 +184,30 @@ export function validateRemoteEnv(remoteEnv) {
   for (const [surface, block] of Object.entries(remoteEnv.surfaces ?? {})) {
     if (!SURFACES.has(surface)) {
       problems.push(`remoteEnv.surfaces has unknown surface "${surface}"`);
+      continue;
     }
-    if (!block.repository) {
-      problems.push(`remoteEnv.surfaces["${surface}"] has no repository`);
+    for (const field of bindingsFor(surface)) {
+      if (!block[field]) {
+        problems.push(`remoteEnv.surfaces["${surface}"] has no ${field}`);
+      }
     }
   }
 
   return problems;
 }
 
+/**
+ * Report whether a surface has been provisioned far enough to dispatch to.
+ * @param {object|undefined} remoteEnv The remote-environment block.
+ * @param {string} surface Surface name.
+ * @returns {boolean} Whether every binding field is recorded.
+ */
+export function isProvisioned(remoteEnv, surface) {
+  const block = remoteEnv?.surfaces?.[surface];
+  if (!block) return false;
+  return bindingsFor(surface).every(field => Boolean(block[field]));
+}
+
 /**
  * Validate the `automations` block against declared surfaces.
  * @param {object|undefined} automations The block, if present.
@@ -173,7 +233,7 @@ export function validateAutomations(automations, remoteEnv) {
       );
       continue;
     }
-    if (!remoteEnv?.surfaces?.[loop.executionEnv]?.repository) {
+    if (!isProvisioned(remoteEnv, loop.executionEnv)) {
       problems.push(
         `automations["${name}"] dispatches to "${loop.executionEnv}", which is ` +
           `not provisioned. Run /lisa:setup:remote-env ${loop.executionEnv} first.`