@codyswann/lisa 2.316.2 → 2.317.0

package/plugins/src/base/skills/lisa-setup-remote-env/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: lisa-setup-remote-env
+description: "Provision and verify a remote execution environment for a host project — Codex Cloud today, other remote surfaces as they are added. Generates a repository-owned setup script that installs the declared toolchain, materializes secrets through lisa-secrets-access, and runs the project's own hook. Provisions by API where one exists, by driving the vendor console where one does not, and by emitting exact config otherwise — then proves the result with the same read-back regardless of which tier did the work. Use before dispatching any work with executionEnv."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill"]
+---
+
+# Setup Remote Environment: $ARGUMENTS
+
+Prepare a remote surface so a host project can execute there. Today that means **Codex Cloud**; the shape is deliberately surface-agnostic so Claude Code web, Cursor remote, and others slot in without redesign.
+
+## What lives where
+
+The remote environment's own configuration fields stay **two one-line calls into the repository**. Nothing is pasted into a vendor UI.
+
+```text
+setup:       bash scripts/lisa-remote-env/setup.sh
+maintenance: bash scripts/lisa-remote-env/setup.sh
+```
+
+They are the same script. A container may be built fresh or resumed from cache; every step 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.
+
+The complete logic is repository-owned so it is reviewed, versioned, tested, and reusable. A large inline installer in a settings field is none of those things.
+
+## The three phases
+
+1. **Toolchain** — assert what must already be present, install what is not.
+2. **Secrets** — materialize through `lisa-secrets-access`. This skill never reimplements any part of that contract; the single chokepoint is what makes the one-store rule enforceable.
+3. **Project hook** — an optional `setup.local.sh` the project owns.
+
+Order matters. The toolchain comes first because the secrets step needs the provider CLI it installs. The hook comes last because it is the only part that may assume everything else is ready.
+
+## Toolchain manifest — two entry kinds
+
+```json
+{
+  "remoteEnv": {
+    "tools": {
+      "require": [
+        { "name": "python3" },
+        { "name": "node", "minVersion": "20" },
+        { "name": "curl" },
+        { "name": "unzip" }
+      ],
+      "install": [
+        {
+          "name": "bws",
+          "version": "2.1.0",
+          "install": "release-zip",
+          "url": "https://<vendor>/releases/download/bws-v2.1.0/bws-<platform>-2.1.0.zip",
+          "sha256": "<sha256 published with that exact release>"
+        },
+        {
+          "name": "codex",
+          "version": "0.144.6",
+          "install": "npm-global",
+          "package": "@openai/codex"
+        }
+      ]
+    },
+    "hook": "scripts/lisa-remote-env/setup.local.sh",
+    "surfaces": {
+      "codex-cloud": {
+        "environmentId": "<id>",
+        "repository": "<org>/<repo>",
+        "branch": "main"
+      }
+    }
+  }
+}
+```
+
+**`require`** — assert present, optionally at a minimum version. For everything the base image already provides.
+
+**`install`** — provision it, pinned and checksummed. Only for what genuinely is not there.
+
+Expected shape for most projects: a short `require` list, an empty or near-empty `install` list, and the provider CLI as the only thing always provisioned.
+
+### Rules
+
+- **The base image is not a contract.** A vendor can change it. A project quietly depending on a preinstalled `jq` should break loudly at setup when that happens, not mysteriously mid-task weeks later. `require` is what converts an implicit assumption into an explicit check.
+- **Detect first, install second.** Check the installed version, skip when it matches the pin, reinstall only when the pin changed. This is what makes setup and maintenance the same script, and it is the cheap path on cache resume.
+- **Version-assert, not just presence.** A base-image bump that moves off a supported Node or Python must be caught. Presence alone is not enough when a project depends on a specific version.
+- **Prefer what is there.** A second Node beside the image's creates PATH ambiguity and wastes container time.
+- **Pin and checksum together, in one reviewed commit.** A version bump that does not move the checksum fails before installation, not after. An archive is verified *before* it is unpacked, so unexpected contents never reach a directory on PATH.
+
+## Tooling is never derived from secret notes
+
+Deliberately rejected:
+
+- Most tooling has **no credential** — `jq`, ripgrep, browsers, a linter — so notes could only ever cover a subset, and a second mechanism would be needed anyway.
+- Most credentials **imply no tool**: a webhook is curl'd, a REST key needs no CLI.
+- The mapping is **guesswork** — which CLI, what version, pinned how — and is exactly the inference the secrets contract already forbids from authorising anything.
+- It makes **prose load-bearing**: a note lives provider-side, is editable outside review, and is unfixable by a read-only account.
+- It is a **supply-chain path** — provider write access would become arbitrary install access.
+
+**Notes are an assertion target instead.** At verify time, a tool that declares a credential which is not materialized is an **error**; a credential materialized with no declared consumer is a **warning**. The arrow points the safe way: the repository declares intent, and the provider is checked against it.
+
+## Provisioning tiers
+
+Preference order, falling back:
+
+1. **API** — provision programmatically.
+2. **Console** — drive the vendor's web console.
+3. **Emit** — generate exact config for a human to paste.
+
+**For Codex Cloud today, start at tier 2 or 3.** Verified on 2026-08-01: `codex cloud` exposes only `exec | status | list | apply | diff`. There is no environment-provisioning subcommand, so there is nothing to call. Do not claim tier 1 for this surface until the CLI grows one.
+
+When emitting, produce exactly:
+
+```text
+Environment name:  <project> remote executor
+Repository:        <org>/<repo>        (must be the default checkout)
+Setup script:      bash scripts/lisa-remote-env/setup.sh
+Maintenance:       bash scripts/lisa-remote-env/setup.sh
+Environment vars:  LISA_SECRETS_SURFACE=codex-cloud
+                   BWS_ACCESS_TOKEN=<from the provider; an environment
+                   variable, not a task secret — setup and cache-resume
+                   maintenance both run before task secrets exist>
+```
+
+## Verification is tier-independent
+
+**Whatever tier provisioned it, the same read-back proves it.** Trust comes from the verify, not the mechanism — which is what makes emit-tier as trustworthy as API-tier.
+
+```sh
+scripts/verify-remote-env.mjs [SECRETS_DIR]
+```
+
+Asserts, without printing a value: each declared tool at its pinned or minimum version, the detected surface, the secrets directory at mode `0700`, both files at mode `0600`, and a clean checkout.
+
+**Never verify against vendor UI state.** On 2026-08-01 a Codex environments table reported zero tasks for an environment that had demonstrably completed one, because the task records carried a null environment identifier and the `--env` filter was correspondingly unreliable. Reconcile through durable identifiers only.
+
+## Preconditions
+
+Checked when setup runs, not at 3am:
+
+- the environment exists and is bound to **this** repository as its default checkout;
+- the bootstrap credential resolves;
+- Lisa has been applied to the repository, so its skills are present in that checkout.
+
+Fail with a message naming what is missing. Never provision-and-hope.
+
+## Bootstrap credential placement
+
+On Codex Cloud the bootstrap must be an **environment variable, not a task secret**: setup runs on a new container and maintenance runs on cache resume, both before task secrets exist. The tradeoff is that the variable remains visible during the task, so compensate by keeping the machine account narrowly scoped and instructing the task never to inspect or use it.
+
+## Related
+
+- `lisa-secrets-access` — owns every part of the secrets contract this skill composes with.
+- `lisa-remote-dispatch` — dispatches work to an environment this skill prepared.

package/plugins/src/base/skills/lisa-setup-remote-env/assets/setup.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# Remote environment entrypoint. Installed by /lisa:setup:remote-env; the remote
+# environment's setup AND maintenance fields both call this exact path.
+#
+# They are the same script on purpose. A container may be built fresh or resumed
+# from cache, and everything below 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.
+#
+# This file is deliberately thin. It resolves an interpreter and hands off; the
+# reviewed, tested, versioned logic lives in the Lisa skill rather than here,
+# and emphatically not in a vendor settings field.
+set -euo pipefail
+
+# Node is the one thing that cannot be installed by the installer, since the
+# installer is written in it. Fail with an actionable message rather than a
+# "command not found" forty lines deep.
+if ! command -v node >/dev/null 2>&1; then
+  echo "node is required to prepare this environment but is not present." >&2
+  echo "It cannot be installed by the toolchain step, because that step runs" >&2
+  echo "on node. Pin a base image that provides it." >&2
+  exit 1
+fi
+
+# The skill ships under whichever agent directory this project uses. Search
+# rather than hardcode, so one entrypoint serves every supported harness.
+runner=""
+for candidate in \
+  ".claude/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs" \
+  ".agents/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs" \
+  ".codex/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs"; do
+  if [ -f "$candidate" ]; then
+    runner="$candidate"
+    break
+  fi
+done
+
+if [ -z "$runner" ]; then
+  echo "Cannot find the lisa-setup-remote-env skill in this checkout." >&2
+  echo "Run 'lisa apply' so the skills are present, then re-run setup." >&2
+  exit 1
+fi
+
+exec node "$runner" "$@"

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

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * Prepare a remote environment: toolchain, then secrets, then the project hook.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * Usage:
+ *   setup-remote-env.mjs [--dry-run]
+ * @module setup-remote-env
+ */
+
+import { execFileSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assertPinned, extractVersion, planToolchain } from "./toolchain.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Locate a sibling skill's script.
+ *
+ * Secrets belong to `lisa-secrets-access`, and this script must not reimplement
+ * any part of that contract — the single chokepoint is what makes the one-store
+ * rule enforceable. Resolving relative to this file works in every install
+ * layout, because skills are always siblings under one `skills/` directory.
+ * @param {string} skill Sibling skill slug.
+ * @param {string} script Script filename.
+ * @returns {string} Absolute path.
+ */
+function siblingScript(skill, script) {
+  const path = resolve(HERE, "..", "..", skill, "scripts", script);
+  if (!existsSync(path)) {
+    throw new Error(
+      `cannot find ${skill}/scripts/${script} beside this skill.\n` +
+        `Remote setup composes with that skill rather than reimplementing it.`
+    );
+  }
+  return path;
+}
+
+/**
+ * Read the `remoteEnv` block from `.lisa.config.json`.
+ * @param {string} [cwd] Directory to look in.
+ * @returns {{tools: object, hook: string|null, surfaces: object}} Configuration.
+ */
+export function readRemoteEnvConfig(cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  const defaults = {
+    tools: { require: [], install: [] },
+    hook: null,
+    surfaces: {},
+  };
+  if (!existsSync(path)) return defaults;
+  const cfg = JSON.parse(readFileSync(path, "utf8")).remoteEnv;
+  if (!cfg) return defaults;
+  return {
+    tools: { require: [], install: [], ...(cfg.tools ?? {}) },
+    hook: cfg.hook ?? null,
+    surfaces: cfg.surfaces ?? {},
+  };
+}
+
+/**
+ * Probe what a tool reports for its version, treating absence as not present.
+ * @param {string} name Executable name.
+ * @returns {{version: string|null, present: boolean}} Probe result.
+ */
+function probe(name) {
+  try {
+    const out = execFileSync(name, ["--version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return { present: true, version: extractVersion(out) };
+  } catch {
+    return { present: false, version: null };
+  }
+}
+
+/**
+ * Install a pinned archive, refusing anything whose checksum does not match.
+ * @param {object} tool Manifest entry.
+ * @param {string} binDir Directory to install into.
+ */
+function installReleaseZip(tool, binDir) {
+  const temporary = join(binDir, `.${tool.name}-download`);
+  mkdirSync(temporary, { recursive: true });
+  try {
+    const archive = join(temporary, "download.zip");
+    execFileSync("curl", ["-fsSL", tool.url, "-o", archive], {
+      stdio: "inherit",
+    });
+    // Verify before unpacking, not after. An unexpected archive must fail
+    // before any of its contents reach a directory that is on PATH.
+    execFileSync("sha256sum", ["-c", "-"], {
+      input: `${tool.sha256}  ${archive}\n`,
+      stdio: ["pipe", "ignore", "inherit"],
+    });
+    execFileSync("unzip", ["-q", "-o", archive, "-d", temporary], {
+      stdio: "inherit",
+    });
+    const binary = join(temporary, tool.binary ?? tool.name);
+    execFileSync("install", ["-m", "0755", binary, join(binDir, tool.name)], {
+      stdio: "inherit",
+    });
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Install a pinned global npm package.
+ * @param {object} tool Manifest entry.
+ */
+function installNpmGlobal(tool) {
+  execFileSync(
+    "npm",
+    ["install", "--global", `${tool.package}@${tool.version}`],
+    {
+      stdio: "inherit",
+    }
+  );
+}
+
+/**
+ * Execute one install decision.
+ * @param {object} tool Manifest entry.
+ * @param {string} binDir Directory for downloaded binaries.
+ */
+function installTool(tool, binDir) {
+  assertPinned(tool);
+  if (tool.install === "release-zip") installReleaseZip(tool, binDir);
+  else installNpmGlobal(tool);
+}
+
+/**
+ * Apply the toolchain plan, reporting every decision.
+ * @param {object} tools Manifest.
+ * @param {boolean} dryRun Whether to plan only.
+ * @returns {Array<object>} The plan that was applied.
+ */
+function applyToolchain(tools, dryRun) {
+  const plan = planToolchain(tools, probe);
+  const blocked = plan.filter(
+    p => p.action === "missing" || p.action === "invalid"
+  );
+  if (blocked.length) {
+    throw new Error(blocked.map(p => p.reason).join("\n\n"));
+  }
+
+  const binDir = join(process.env.HOME ?? "", ".local", "bin");
+  mkdirSync(binDir, { recursive: true, mode: 0o755 });
+  const byName = new Map((tools.install ?? []).map(t => [t.name, t]));
+
+  for (const step of plan) {
+    console.log(`  ${step.action.padEnd(8)} ${step.reason}`);
+    if (step.action === "install" && !dryRun)
+      installTool(byName.get(step.name), binDir);
+  }
+  return plan;
+}
+
+/**
+ * Run the project's own setup hook when it has one.
+ *
+ * A declarative manifest will never cover everything, and without an escape
+ * hatch a project's only option is to fork Lisa's script — at which point it
+ * stops receiving any of the fixes.
+ * @param {string|null} hook Repository-relative path.
+ * @param {boolean} dryRun Whether to plan only.
+ */
+function runHook(hook, dryRun) {
+  if (!hook) return;
+  const path = resolve(process.cwd(), hook);
+  if (!existsSync(path)) {
+    throw new Error(`remoteEnv.hook points at ${hook}, which does not exist`);
+  }
+  console.log(`\nProject hook: ${hook}`);
+  if (dryRun) return;
+  chmodSync(path, 0o755);
+  execFileSync("bash", [path], { stdio: "inherit" });
+}
+
+function main() {
+  const dryRun = process.argv.includes("--dry-run");
+  const cfg = readRemoteEnvConfig();
+
+  console.log("Toolchain:");
+  applyToolchain(cfg.tools, dryRun);
+
+  console.log("\nSecrets:");
+  const materialize = siblingScript(
+    "lisa-secrets-access",
+    "materialize-secrets.mjs"
+  );
+  execFileSync("node", dryRun ? [materialize, "--dry-run"] : [materialize], {
+    stdio: "inherit",
+  });
+
+  runHook(cfg.hook, dryRun);
+  console.log(`\nRemote environment ${dryRun ? "plan complete" : "ready"}.`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

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

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Decide what a remote environment already has and what it still needs.
+ *
+ * Remote environments arrive with a base image that already provides much of
+ * what a project needs, so the manifest has two entry kinds rather than one:
+ *
+ *   require — assert present, fail setup with a clear message if missing
+ *   install — provision it, pinned and checksummed
+ *
+ * The distinction is not bookkeeping. A base image is **not a contract**: the
+ * vendor can change it. A project quietly depending on a preinstalled tool
+ * should break loudly at setup when that happens, rather than mysteriously
+ * mid-task weeks later. `require` is what converts an implicit assumption into
+ * an explicit check.
+ *
+ * Planning is separated from execution so the whole decision table is testable
+ * without a container, a network, or a real binary anywhere.
+ * @module toolchain
+ */
+
+/**
+ * Compare dotted version strings numerically.
+ *
+ * String comparison gets this wrong in the case that matters: "10" sorts before
+ * "9", so a base-image bump to a newer major would read as a downgrade and pass
+ * a minimum-version check it should fail.
+ * @param {string} a Left version.
+ * @param {string} b Right version.
+ * @returns {number} Negative, zero, or positive.
+ */
+export function compareVersions(a, b) {
+  const left = String(a).split(".").map(Number);
+  const right = String(b).split(".").map(Number);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Pull a dotted version out of whatever a tool prints for `--version`.
+ *
+ * Tools are wildly inconsistent here ("bws 2.1.0", "v20.11.0", "Python 3.12.1"),
+ * and normalising with a regex is more honest than maintaining a per-tool parser
+ * table that silently rots.
+ * @param {string} output Raw `--version` output.
+ * @returns {string|null} The version, or null when none is recognisable.
+ */
+export function extractVersion(output) {
+  const match = /(\d+(?:\.\d+)*)/.exec(String(output ?? ""));
+  return match ? match[1] : null;
+}
+
+/**
+ * Classify one required tool against what the environment actually provides.
+ * @param {object} tool Manifest entry.
+ * @param {{version: string|null, present: boolean}} found Probe result.
+ * @returns {{name: string, action: string, reason: string}} The decision.
+ */
+function planRequired(tool, found) {
+  if (!found.present) {
+    return {
+      name: tool.name,
+      action: "missing",
+      reason:
+        `${tool.name} is required but not present. The base image is not a ` +
+        `contract — if it used to provide this, the vendor has changed it. ` +
+        `Either add an install entry or pin a different image.`,
+    };
+  }
+  if (
+    tool.minVersion &&
+    compareVersions(found.version ?? "0", tool.minVersion) < 0
+  ) {
+    return {
+      name: tool.name,
+      action: "missing",
+      reason:
+        `${tool.name} ${found.version ?? "(unknown)"} is older than the ` +
+        `required ${tool.minVersion}. Presence alone is not enough when a ` +
+        `project depends on a specific version.`,
+    };
+  }
+  return {
+    name: tool.name,
+    action: "present",
+    reason: `${tool.name} ${found.version ?? ""}`.trim(),
+  };
+}
+
+/**
+ * Classify one installable tool against what is already on disk.
+ *
+ * Detect first, install second. Skipping a matching version is what makes setup
+ * and maintenance the same script, and it is the cheap path when a container
+ * resumes from cache rather than being built fresh.
+ * @param {object} tool Manifest entry.
+ * @param {{version: string|null, present: boolean}} found Probe result.
+ * @returns {{name: string, action: string, reason: string}} The decision.
+ */
+function planInstallable(tool, found) {
+  if (!tool.version) {
+    return {
+      name: tool.name,
+      action: "invalid",
+      reason: `${tool.name} has no pinned version. An unpinned install is not reproducible.`,
+    };
+  }
+  if (found.present && found.version === tool.version) {
+    return {
+      name: tool.name,
+      action: "skip",
+      reason: `${tool.name} ${tool.version} already installed`,
+    };
+  }
+  return {
+    name: tool.name,
+    action: "install",
+    reason: found.present
+      ? `${tool.name} ${found.version ?? "(unknown)"} does not match pin ${tool.version}`
+      : `${tool.name} ${tool.version} not installed`,
+  };
+}
+
+/**
+ * Produce the complete plan for a toolchain manifest.
+ * @param {{require?: object[], install?: object[]}} tools Manifest.
+ * @param {(name: string) => {version: string|null, present: boolean}} probe Version probe.
+ * @returns {Array<{name: string, action: string, reason: string}>} Ordered decisions.
+ */
+export function planToolchain(tools, probe) {
+  const plan = [];
+  for (const tool of tools.require ?? [])
+    plan.push(planRequired(tool, probe(tool.name)));
+  for (const tool of tools.install ?? [])
+    plan.push(planInstallable(tool, probe(tool.name)));
+  return plan;
+}
+
+/**
+ * Reject a manifest entry that could install something unverifiable.
+ *
+ * A pinned version with no checksum still trusts whatever the URL serves today.
+ * Requiring both, changed together in one reviewed commit, is what makes an
+ * unexpected archive fail before installation rather than after.
+ * @param {object} tool Manifest entry.
+ */
+export function assertPinned(tool) {
+  if (tool.install === "release-zip") {
+    if (!tool.url || !tool.sha256) {
+      throw new Error(
+        `${tool.name}: a release-zip install needs both url and sha256.\n` +
+          `A version bump must move the checksum in the same reviewed commit.`
+      );
+    }
+    return;
+  }
+  if (tool.install === "npm-global") {
+    if (!tool.package)
+      throw new Error(`${tool.name}: npm-global install needs a package`);
+    return;
+  }
+  throw new Error(
+    `${tool.name}: unknown install method "${tool.install}".\n` +
+      `Supported: release-zip, npm-global.`
+  );
+}