@codyswann/lisa 2.319.0 → 2.321.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
  */
 
@@ -24,9 +35,10 @@ import {
   mkdirSync,
   readFileSync,
   rmSync,
+  writeFileSync,
 } 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";
 
@@ -78,18 +90,35 @@ export function readRemoteEnvConfig(cwd = process.cwd()) {
 
 /**
  * Probe what a tool reports for its version, treating absence as not present.
+ *
+ * "Not installed" and "dislikes `--version`" are different answers, and only a
+ * failure to *spawn* means the first. Info-ZIP's `unzip` — the build shipped by
+ * both macOS and Ubuntu — parses `--version` one letter at a time, warns that
+ * `-n` and `-o` conflict, and exits 10. Reading that as absence made `require`
+ * fail on a machine that had the tool, which is precisely the false alarm the
+ * check exists to avoid raising.
+ *
+ * Version text is still recovered from a failed invocation where there is any,
+ * because a tool that refuses the flag often prints its banner anyway — which
+ * is how `unzip` still reports 6.00 despite exiting non-zero.
+ *
+ * The runner is injectable so both branches can be exercised without depending
+ * on which quirky binaries happen to exist on the machine running the tests.
  * @param {string} name Executable name.
+ * @param {Function} [exec] Command runner, for tests.
  * @returns {{version: string|null, present: boolean}} Probe result.
  */
-function probe(name) {
+export function probe(name, exec = execFileSync) {
   try {
-    const out = execFileSync(name, ["--version"], {
+    const out = exec(name, ["--version"], {
       encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
+      stdio: ["ignore", "pipe", "pipe"],
     });
     return { present: true, version: extractVersion(out) };
-  } catch {
-    return { present: false, version: null };
+  } catch (err) {
+    if (err.code === "ENOENT") return { present: false, version: null };
+    const output = `${err.stdout ?? ""}${err.stderr ?? ""}`;
+    return { present: true, version: extractVersion(output) };
   }
 }
 
@@ -197,31 +226,353 @@ 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"];
+
+/** Where a host project keeps the scripts its remote environment invokes. */
+export const INSTALL_DIR = join("scripts", "lisa-remote-env");
+
+/** Assets a host project needs on disk before any remote session can start. */
+const INSTALLABLE = ["setup.sh", "session-start.sh"];
+
+/**
+ * Copy this skill's assets into the host project that will run them.
+ *
+ * These live in the skill, but the paths that reference them are *repository*
+ * paths: a vendor's setup field says `bash scripts/lisa-remote-env/setup.sh`,
+ * and a session-start hook is only committed if it is a real file in the repo.
+ * Nothing put them there, so every reference resolved to a path that did not
+ * exist — the environment came up, ran a missing script, exited non-zero, and
+ * the session failed to start with no indication that a setup step was skipped.
+ *
+ * Copied rather than symlinked or generated: the file must survive in a fresh
+ * clone on a container that has never seen the plugin, which is the whole
+ * reason the entrypoint is thin enough to copy in the first place.
+ * @param {string} [cwd] Repository root.
+ * @returns {Array<{name: string, action: string}>} What was written.
+ */
+export function installAssets(cwd = process.cwd()) {
+  const destination = join(cwd, INSTALL_DIR);
+  mkdirSync(destination, { recursive: true, mode: 0o755 });
+  return INSTALLABLE.map(name => {
+    const source = resolve(HERE, "..", "assets", name);
+    if (!existsSync(source)) {
+      throw new Error(`asset ${name} is missing from this skill install`);
+    }
+    const target = join(destination, name);
+    const desired = readFileSync(source, "utf8");
+    const unchanged =
+      existsSync(target) && readFileSync(target, "utf8") === desired;
+    if (!unchanged) writeFileSync(target, desired, { mode: 0o755 });
+    chmodSync(target, 0o755);
+    return { name, action: unchanged ? "current" : "written" };
+  });
+}
+
+/**
+ * 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"
+          }
+        ]
+      }
+    ]
+  }
+}`;
+
+/**
+ * Pin which cloud environment this project's sessions use.
+ *
+ * `/remote-env` writes `remote.defaultEnvironmentId` into *user* settings, which
+ * is one value for the whole machine. That is wrong as soon as a developer has
+ * more than one project, because an environment's contents are project-shaped:
+ * its setup script is a repository-relative path and its bootstrap is scoped to
+ * that project's secrets. Pointing one project's session at another's
+ * environment runs a setup script that may not exist there, and a non-zero setup
+ * script means the session never starts.
+ *
+ * Written to `.claude/settings.local.json` for two reasons. It outranks user
+ * settings, so the per-project choice wins over the machine-wide default; and it
+ * is gitignored, which is correct because an environment belongs to one
+ * developer's account and is meaningless in someone else's checkout.
+ *
+ * Merged rather than replaced — that file commonly holds permission grants a
+ * developer has accumulated, and clobbering them to write one key would be a
+ * poor trade.
+ * @param {string} environmentId Cloud environment identifier.
+ * @param {string} [cwd] Repository root.
+ * @returns {string} The settings path written.
+ */
+export function pinEnvironment(environmentId, cwd = process.cwd()) {
+  const path = join(cwd, ".claude", "settings.local.json");
+  mkdirSync(dirname(path), { recursive: true });
+  const existing = existsSync(path)
+    ? JSON.parse(readFileSync(path, "utf8"))
+    : {};
+  const merged = {
+    ...existing,
+    remote: { ...(existing.remote ?? {}), defaultEnvironmentId: environmentId },
+  };
+  writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`);
+  return path;
+}
+
+/**
+ * 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 (process.argv.includes("--install")) {
+    console.log(`Installing remote-environment scripts into ${INSTALL_DIR}/`);
+    for (const { name, action } of installAssets()) {
+      console.log(`  ${action.padEnd(8)} ${join(INSTALL_DIR, name)}`);
+    }
+
+    const pin = process.argv
+      .find(arg => arg.startsWith("--pin-env="))
+      ?.slice("--pin-env=".length);
+    if (pin) {
+      console.log(`\nPinned this project to environment ${pin}`);
+      console.log(`  written  ${pinEnvironment(pin)}`);
+      console.log(
+        "  That file is gitignored and outranks the machine-wide default, so\n" +
+          "  every project can name its own environment."
+      );
+    }
+    console.log(
+      "\nCommit these. They are repository files by design — a container that " +
+        "has\njust cloned the repo has never seen the plugin they came from."
+    );
+    return;
+  }
+
+  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);
+  }
 
-  runHook(cfg.hook, 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.`
+    );
+  }
+
+  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.319.0",
+  "version": "2.321.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/surfaces.mjs

@@ -29,18 +29,35 @@ import { join } from "node:path";
  * consuming process exists and which therefore have no other channel; a remote
  * agent container prepares itself during setup, long before any task starts.
  *
- * 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 there 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 — its materialize step runs from a session-start hook instead.
+ * `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 },
-  "claude-web": { 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. */