@codyswann/lisa 2.328.5 → 2.330.0

package/plugins/src/base/skills/lisa-setup-workstation/scripts/catalogue.mjs

@@ -0,0 +1,262 @@
+/**
+ * What a workstation can hold, and how each piece is installed.
+ *
+ * This is the layer beneath `remoteEnv.tools`: it describes a MACHINE, not a
+ * project, so nothing here is read from a checkout and no repository needs to
+ * exist. The project-scoped manifest still owns project-scoped tools.
+ *
+ * ## Install method is a per-tool property, not a global policy
+ *
+ * The obvious design — put every binary in `~/.local/bin` so one code path
+ * serves a laptop and a container alike — is wrong, and the agents show why:
+ *
+ *     claude       -> ~/.local/share/claude/versions/2.1.221
+ *     cursor-agent -> ~/.local/share/cursor-agent/versions/2026.07.16-899851b
+ *     codex        -> ~/.codex/packages/standalone/current/bin/codex
+ *
+ * Each vendor manages its own version directory and `~/.local/bin` holds only a
+ * SYMLINK. Writing a raw binary there breaks the vendor's self-updater, which
+ * expects to swap a link target and would instead find a real file in its way.
+ *
+ * So each entry declares its own method, and the honest cost is recorded with
+ * it: a `vendor-script` entry is NOT pinned and NOT checksummed. That is a real
+ * weakening of the guarantee `assertPinned` exists to provide, so the kind is
+ * visible in the catalogue and in the report rather than blended in with
+ * checksummed entries. A reader can see which tools are trusted to a vendor.
+ * @module catalogue
+ */
+
+/** Lisa's supported coding agents. Kept in sync with the harness list. */
+export const AGENTS = [
+  {
+    name: "claude",
+    label: "Claude Code",
+    kind: "vendor-script",
+    // The vendor script installs into ~/.local/share/claude/versions/<v> and
+    // links ~/.local/bin/claude at it, which is why we must not write there.
+    script: "https://claude.ai/install.sh",
+    selfUpdates: true,
+  },
+  {
+    name: "codex",
+    label: "Codex",
+    kind: "npm-global",
+    package: "@openai/codex",
+    selfUpdates: true,
+  },
+  {
+    name: "cursor-agent",
+    label: "Cursor",
+    kind: "vendor-script",
+    script: "https://cursor.com/install",
+    selfUpdates: true,
+  },
+  {
+    name: "opencode",
+    label: "OpenCode",
+    kind: "vendor-script",
+    script: "https://opencode.ai/install",
+    // Installs to its own directory and appends a PATH line to the user's
+    // shell rc — which a non-interactive container never sources. Declared
+    // here so the run puts it on PATH itself rather than reporting a binary
+    // that is on disk as missing.
+    binDir: "~/.opencode/bin",
+    selfUpdates: true,
+  },
+  {
+    name: "agy",
+    label: "Antigravity",
+    kind: "manual",
+    // No headless installer published. Reported as absent with a pointer
+    // rather than silently skipped, because "not installed" and "cannot be
+    // installed by this tool" are different answers to the operator.
+    note: "no headless installer published; install from the vendor",
+  },
+  {
+    name: "copilot",
+    label: "GitHub Copilot CLI",
+    kind: "npm-global",
+    package: "@github/copilot",
+    selfUpdates: false,
+  },
+];
+
+/**
+ * Credential managers, one of which a workstation may use.
+ *
+ * A CHOICE, not a fixed tool. `lisa-secrets-access` already treats the provider
+ * as an axis — bitwarden, 1password, doppler, vault, aws, or plain `env` — and
+ * a bootstrap that installed `bws` unconditionally would contradict that,
+ * pushing every workstation onto one vendor and quietly making the others
+ * second-class.
+ *
+ * `none` is a first-class answer. A machine using plain environment variables
+ * is a supported configuration, not a degraded one, so it must be selectable
+ * rather than merely what happens when a question is skipped.
+ *
+ * Only the SELECTED provider is installed. Installing all of them would put
+ * four unused credential CLIs on a machine, each an extra thing to keep patched
+ * for no benefit.
+ */
+export const PROVIDERS = [
+  {
+    name: "bitwarden",
+    binary: "bws",
+    label: "Bitwarden Secrets Manager",
+    // The one genuinely pinned credential CLI: Bitwarden publishes per-platform
+    // archives that can carry a checksum, and a credential bootstrap is exactly
+    // where an unverified download matters most.
+    kind: "release-zip",
+    version: "2.1.0",
+    platforms: {
+      "linux-x64": {
+        url: "https://github.com/bitwarden/sdk-sm/releases/download/bws-v2.1.0/bws-x86_64-unknown-linux-gnu-2.1.0.zip",
+        sha256:
+          "ba8233c3a4aee5d43e3c73bbd04d99e9bc5aba13bbbfd06d89b073abe732b860",
+      },
+      "linux-arm64": {
+        url: "https://github.com/bitwarden/sdk-sm/releases/download/bws-v2.1.0/bws-aarch64-unknown-linux-gnu-2.1.0.zip",
+        sha256:
+          "18253757286e119d450133a87eb463bf8c1ce418ce24c834f4f250d60cba6f9e",
+      },
+    },
+  },
+  {
+    name: "1password",
+    binary: "op",
+    label: "1Password CLI",
+    kind: "vendor-script",
+    note: "install from 1password.com/downloads/command-line",
+  },
+  {
+    name: "doppler",
+    binary: "doppler",
+    label: "Doppler CLI",
+    kind: "vendor-script",
+    script: "https://cli.doppler.com/install.sh",
+  },
+  {
+    name: "vault",
+    binary: "vault",
+    label: "HashiCorp Vault CLI",
+    kind: "vendor-script",
+    note: "install from developer.hashicorp.com/vault/install",
+  },
+  {
+    name: "aws",
+    binary: "aws",
+    label: "AWS Secrets Manager (via AWS CLI)",
+    kind: "vendor-script",
+    // Deliberately the same entry as the general AWS CLI below: a provider of
+    // `aws` needs exactly that binary and nothing extra.
+    note: "uses the AWS CLI, which is also a general tool",
+  },
+  {
+    name: "none",
+    binary: null,
+    label: "No credential manager (plain environment variables)",
+    kind: "none",
+    note: "supported configuration; nothing is installed",
+  },
+];
+
+/**
+ * Tools every workstation needs regardless of project or provider.
+ */
+export const TOOLS = [
+  {
+    name: "git",
+    label: "git",
+    kind: "required",
+    note: "expected from the OS or base image",
+  },
+  {
+    name: "node",
+    label: "Node.js",
+    kind: "required",
+    minVersion: "22",
+    note: "expected from the OS or base image; the installers run on it",
+  },
+  {
+    name: "gh",
+    label: "GitHub CLI",
+    kind: "release-tar",
+    version: "2.83.0",
+    platforms: {
+      "linux-x64": {
+        url: "https://github.com/cli/cli/releases/download/v2.83.0/gh_2.83.0_linux_amd64.tar.gz",
+        sha256:
+          "a5cf6cdb40fc67751adf561126b3314044779cea81ba4f254fbe8e9a69f1676f",
+        binary: "gh_2.83.0_linux_amd64/bin/gh",
+      },
+      "linux-arm64": {
+        url: "https://github.com/cli/cli/releases/download/v2.83.0/gh_2.83.0_linux_arm64.tar.gz",
+        sha256:
+          "12311e320d4cfdb54d7fa2d58cd1e3a2ccb4c12e1c3abb32b0a2e48bd0f991bf",
+        binary: "gh_2.83.0_linux_arm64/bin/gh",
+      },
+      "darwin-arm64": {
+        url: "https://github.com/cli/cli/releases/download/v2.83.0/gh_2.83.0_macOS_arm64.zip",
+        sha256:
+          "fecba907bc361d5e33620dbf1145f11432c39fb2b388a839463cfbb89a84820b",
+        binary: "gh_2.83.0_macOS_arm64/bin/gh",
+      },
+    },
+  },
+  {
+    name: "aws",
+    label: "AWS CLI v2",
+    kind: "aws-cli",
+    // Not expressible as release-zip: the artifact is a ~73 MB archive
+    // containing an installer, not a single binary on PATH. It gets its own
+    // kind rather than a vendor-script URL because the steps in between —
+    // unzip, then `./aws/install` with an explicit prefix — are the whole job.
+    note: "archive wraps an installer rather than a binary",
+    selfUpdates: false,
+  },
+  {
+    name: "sonar",
+    label: "SonarQube CLI",
+    kind: "vendor-script",
+    // The vendor's real installer. The plausible-looking `sonarsource.com/install`
+    // that was here first 404s, and because a 404 piped to a shell exits 0, it
+    // was reported as installed on a machine that had no `sonar` at all.
+    script:
+      "https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh",
+    // Same shell-rc assumption as OpenCode.
+    binDir: "~/.local/share/sonarqube-cli/bin",
+    selfUpdates: true,
+  },
+];
+
+/** Install kinds this tool can actually perform, versus report only. */
+export const INSTALLABLE = new Set([
+  "release-zip",
+  "release-tar",
+  "npm-global",
+  "vendor-script",
+  "aws-cli",
+]);
+
+/** Kinds whose artifact is verified against a published checksum. */
+export const CHECKSUMMED = new Set(["release-zip", "release-tar"]);
+
+/**
+ * Every directory a workstation must have on PATH.
+ *
+ * Vendors that manage their own version directory append a PATH line to the
+ * user's shell rc, which a non-interactive run — a container build, a cron, an
+ * agent — never sources. Collecting them here means one place decides what PATH
+ * must contain, used identically by the runtime and by the emitted Dockerfile.
+ * @param {string} home The home directory to expand `~` against.
+ * @returns {string[]} Absolute directories, most specific last.
+ */
+export function pathDirs(home) {
+  const declared = [...AGENTS, ...PROVIDERS, ...TOOLS]
+    .map(entry => entry.binDir)
+    .filter(Boolean)
+    .map(dir => dir.replace(/^~/, home));
+  // ~/.local/bin first: it is where the pinned, checksummed binaries land, and
+  // those must win over whatever an image happens to ship under the same name.
+  return [`${home}/.local/bin`, ...declared];
+}

package/plugins/src/base/skills/lisa-setup-workstation/scripts/cli.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+/**
+ * Command-line entry for the workstation bootstrap.
+ *
+ * Kept separate from `workstation.mjs` so the planning logic stays importable
+ * and testable without a process boundary — a test should be able to ask "what
+ * would this do" without any risk of it doing it.
+ *
+ * Usage:
+ *   cli.mjs                                report present vs missing
+ *   cli.mjs --install                      provision what is missing
+ *   cli.mjs --install --agents=claude,codex   only these agents
+ *   cli.mjs --provider=bitwarden           credential manager (asked if a TTY)
+ *   cli.mjs --json                         machine-readable plan
+ *   cli.mjs --print-dockerfile             an image that runs this same script
+ * @module cli
+ */
+
+import { closeSync, existsSync, openSync, readSync, writeSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { AGENTS, PROVIDERS, TOOLS, pathDirs } from "./catalogue.mjs";
+import { installEntry, planWorkstation, renderPlan } from "./workstation.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** Where pinned binaries land, and what must therefore be on PATH. */
+export const BIN_DIR = `${process.env.HOME}/.local/bin`;
+
+/**
+ * Borrow the pinned, checksummed installer the remote-env skill owns.
+ *
+ * Composed rather than reimplemented: the pins and checksums must be the same
+ * ones the remote surfaces use, or the two drift and only one gets fixed.
+ * Returns null when the sibling is absent, so a machine can still install the
+ * unpinned entries instead of failing wholesale — the report says which ones
+ * were skipped rather than passing them off as done.
+ * @returns {Promise<Function|null>} An installer, or null.
+ */
+export async function loadPinnedInstaller() {
+  const sibling = name =>
+    resolve(HERE, "..", "..", "lisa-setup-remote-env", "scripts", name);
+  const setup = sibling("setup-remote-env.mjs");
+  const toolchain = sibling("toolchain.mjs");
+  if (!existsSync(setup) || !existsSync(toolchain)) return null;
+
+  const { installTool, ensureBinDir } = await import(pathToFileURL(setup).href);
+  const { resolvePlatform } = await import(pathToFileURL(toolchain).href);
+  if (typeof installTool !== "function") return null;
+
+  return entry => {
+    // resolvePlatform must run first: installTool calls assertPinned, which
+    // refuses an entry that still carries a `platforms` map. Skipping it failed
+    // bws and gh with "platform-specific entry was not resolved before install"
+    // — the guard doing exactly its job.
+    const resolved = resolvePlatform(toManifestEntry(entry));
+    installTool(resolved, ensureBinDir ? ensureBinDir() : BIN_DIR);
+  };
+}
+
+/**
+ * Translate a catalogue entry into the manifest shape the installer expects.
+ *
+ * The two vocabularies differ — the catalogue describes a machine, the manifest
+ * describes a project — so the seam is made explicit here rather than by giving
+ * the catalogue a shape it does not otherwise need. `kind` becomes `install`;
+ * everything else the manifest reads is already named the same.
+ * @param {object} entry Catalogue entry.
+ * @returns {object} A `remoteEnv.tools` style entry.
+ */
+export function toManifestEntry(entry) {
+  const { kind, label, binDir, note, selfUpdates, ...rest } = entry;
+  return { ...rest, install: kind };
+}
+
+/**
+ * Decide which credential manager to provision.
+ *
+ * Asked, never assumed. Defaulting to Bitwarden because that is what this repo
+ * happens to use would install a vendor CLI on a machine whose project resolves
+ * secrets some other way — and would make `none`, a supported configuration,
+ * reachable only by accident.
+ *
+ * Headless is the primary mode, so a missing answer without a TTY is `none`
+ * rather than a prompt that would hang a container build forever.
+ * @param {string|null} requested Value of --provider, if given.
+ * @param {object} io Injected ask/tty, for tests.
+ * @returns {string} A provider name from the catalogue.
+ */
+export function chooseProvider(requested, io = {}) {
+  if (requested) return requested;
+
+  const ask = io.ask ?? null;
+  const interactive = io.interactive ?? Boolean(process.stdin.isTTY);
+  if (!ask || !interactive) return "none";
+
+  const names = PROVIDERS.map(p => p.name);
+  const menu = PROVIDERS.map((p, i) => `  ${i + 1}) ${p.label}`).join("\n");
+  const answer = String(
+    ask(`Which credential manager does this machine use?\n${menu}\nChoice: `) ??
+      ""
+  ).trim();
+
+  // Accept either the menu number or the name, because an operator reading the
+  // list will reach for whichever is in front of them.
+  const index = Number.parseInt(answer, 10);
+  if (Number.isInteger(index) && index >= 1 && index <= names.length) {
+    return names[index - 1];
+  }
+  return names.includes(answer) ? answer : "none";
+}
+
+/**
+ * A Dockerfile that runs this same script, for a throwaway environment.
+ *
+ * Emitted rather than committed so it cannot drift from the catalogue it
+ * provisions. There is no Docker-specific code path anywhere in this skill —
+ * the image simply gives the script a `$HOME` that dies with the container.
+ *
+ * Deliberately bakes in NO repository. Clone inside the container, then run
+ * lisa-detect-tooling and lisa-setup-local-env for that project's own tools.
+ * @param {string[]} agents Agent names to install.
+ * @param {string} [provider] Credential manager to provision.
+ * @returns {string} Dockerfile text.
+ */
+export function renderDockerfile(agents, provider = "none") {
+  const list = agents.length ? agents.join(",") : "claude,codex";
+  const clean = "apt-get clean";
+  return [
+    "# Ephemeral coding environment. Build, use, discard.",
+    "#   docker build -t lisa-workstation .",
+    "#   docker run --rm -it lisa-workstation",
+    "FROM ubuntu:24.04",
+    "ENV DEBIAN_FRONTEND=noninteractive",
+    "RUN apt-get update -qq \\",
+    "  && apt-get install -y -qq curl git unzip ca-certificates python3 \\",
+    "  && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \\",
+    `  && apt-get install -y -qq nodejs && ${clean}`,
+    // The whole skills/ tree, not just this skill: the checksummed installs are
+    // borrowed from lisa-setup-remote-env, and copying only this directory left
+    // bws and gh silently unprovisioned.
+    "COPY skills/ /opt/lisa/skills/",
+    // Set BEFORE the install, not after. Installers write into ~/.local/bin and
+    // the post-install check looks for the binary by bare name, so a PATH set
+    // afterwards would fail every verification in the image while passing on a
+    // laptop that already exports the directory.
+    `ENV PATH="${pathDirs("/root").join(":")}:\${PATH}"`,
+    // --provider is passed explicitly: the build has no TTY, so an omitted flag
+    // would resolve to `none` and produce an image with no way to reach secrets.
+    `RUN node /opt/lisa/skills/lisa-setup-workstation/scripts/cli.mjs \\`,
+    `  --install --agents=${list} --provider=${provider}`,
+    'CMD ["bash"]',
+  ].join("\n");
+}
+
+/**
+ * Run the CLI.
+ * @param {string[]} argv Arguments after the script name.
+ * @param {object} [io] Injected output sinks, for tests.
+ * @returns {number} Process exit code.
+ */
+export async function run(argv, io = {}) {
+  const out = io.log ?? console.log;
+  const err = io.error ?? console.error;
+  const flag = name => argv.includes(`--${name}`);
+  const value = name => {
+    const hit = argv.find(a => a.startsWith(`--${name}=`));
+    return hit ? hit.slice(name.length + 3) : null;
+  };
+
+  const selected = value("agents");
+  const agents = selected
+    ? selected
+        .split(",")
+        .map(s => s.trim())
+        .filter(Boolean)
+    : null;
+
+  const provider = chooseProvider(value("provider"), io);
+
+  if (flag("print-dockerfile")) {
+    out(renderDockerfile(agents ?? [], provider));
+    return 0;
+  }
+
+  let plan;
+  try {
+    plan = planWorkstation({ agents, provider, ...(io.probes ?? {}) });
+  } catch (error) {
+    // A misspelled provider stops here rather than silently provisioning the
+    // wrong credential manager.
+    err(String(error.message));
+    return 1;
+  }
+
+  if (flag("json")) {
+    out(JSON.stringify({ plan }, null, 2));
+    return 0;
+  }
+
+  out(renderPlan(plan));
+
+  const blocked = plan.filter(r => r.action === "blocked");
+  if (blocked.length) {
+    err(
+      `\n${blocked.length} required tool(s) absent. These come from the OS or ` +
+        `base image and cannot be installed here.`
+    );
+    return 1;
+  }
+
+  const pending = plan.filter(r => r.action === "install");
+  if (!pending.length) {
+    // Idempotence made visible. A second run states it rather than going quiet,
+    // because silence reads as "did nothing because it broke".
+    out("\nNothing to install — this workstation is already prepared.");
+    return 0;
+  }
+
+  if (!flag("install")) {
+    out(
+      `\n${pending.length} missing. Re-run with --install to provision them. ` +
+        `Nothing has been installed or written.`
+    );
+    return 0;
+  }
+
+  out("");
+  // Provider entries are keyed by vendor name but planned under their BINARY
+  // name (`bitwarden` -> `bws`), so they are re-keyed here or the lookup below
+  // silently finds nothing and the install is skipped without a word.
+  const catalogue = [
+    ...AGENTS,
+    ...TOOLS,
+    ...PROVIDERS.filter(p => p.binary).map(p => ({ ...p, name: p.binary })),
+  ];
+  const probes = io.probes ?? {};
+  const installPinned =
+    probes.installPinned ?? (await loadPinnedInstaller()) ?? undefined;
+
+  const results = [];
+  for (const row of pending) {
+    results.push(
+      installEntry(
+        catalogue.find(e => e.name === row.name),
+        row,
+        { ...probes, installPinned }
+      )
+    );
+  }
+  for (const result of results) {
+    out(`  ${result.action.padEnd(10)} ${result.label}  ${result.reason}`);
+  }
+
+  const failed = results.filter(r => r.action === "failed");
+  if (failed.length) {
+    err(
+      `\n${failed.length} install(s) failed: ${failed
+        .map(r => r.name)
+        .join(", ")}. Nothing above was reported as installed unless the ` +
+        `binary was found on PATH afterwards.`
+    );
+  }
+  return failed.length ? 1 : 0;
+}
+
+/**
+ * Prompt on the terminal, synchronously.
+ *
+ * Reads `/dev/tty` rather than stdin so the question still works when the
+ * script is being piped — the ordinary way a bootstrap gets run.
+ * @param {string} prompt Text to display.
+ * @returns {string|null} The answer, or null if no terminal is attached.
+ */
+export function askTty(prompt) {
+  let fd;
+  try {
+    fd = openSync("/dev/tty", "r+");
+  } catch {
+    return null;
+  }
+  try {
+    writeSync(fd, prompt);
+    const buffer = Buffer.alloc(256);
+    const read = readSync(fd, buffer, 0, buffer.length, null);
+    return buffer.toString("utf8", 0, read).trim();
+  } catch {
+    return null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Put the install directory on PATH before anything probes it.
+ *
+ * Installers write into `~/.local/bin`, and the post-install check then looks
+ * for the binary by bare name. That directory is on PATH by default on a
+ * developer workstation and is NOT on a minimal container, so without this
+ * every install in a container would report "exited 0 but still not on PATH"
+ * while every laptop run passed — the environment doing the verifying hiding
+ * the bug. Prepended, and compared entry-by-entry rather than by substring.
+ * @param {string} dir Directory to ensure is present.
+ * @param {object} [env] Environment to mutate.
+ */
+export function ensureOnPath(dir, env = process.env) {
+  const entries = (env.PATH ?? "").split(":").filter(Boolean);
+  if (!entries.includes(dir)) env.PATH = [dir, ...entries].join(":");
+}
+
+if (process.argv[1] && process.argv[1].endsWith("cli.mjs")) {
+  for (const dir of pathDirs(process.env.HOME ?? "")) ensureOnPath(dir);
+  process.exitCode = await run(process.argv.slice(2), { ask: askTty });
+}