@codyswann/lisa 2.328.5 → 2.329.0

package/plugins/lisa-agy/skills/lisa-setup-workstation/scripts/workstation.mjs

@@ -0,0 +1,403 @@
+#!/usr/bin/env node
+/**
+ * Prepare a machine — or a throwaway container — to run coding agents.
+ *
+ * This is the layer beneath `lisa-setup-local-env`, which reads a project's
+ * `remoteEnv.tools` and therefore needs a checkout to exist first. That left
+ * the machine most likely to be missing a tool — a fresh laptop, or an empty
+ * container — with nothing to ask.
+ *
+ * Nothing here reads a repository. The composition is:
+ *
+ *     workstation  ->  git clone  ->  lisa-detect-tooling  ->  lisa-setup-local-env
+ *
+ * ## Ephemerality is not a mode
+ *
+ * There is no Docker branch. A container gets a throwaway `$HOME` and dies with
+ * it; a laptop keeps its own. Same code path, so the rarely-run one cannot rot
+ * — the failure mode a second install path always eventually has.
+ *
+ * ## Already-installed wins, however it got there
+ *
+ * A tool present by ANY means is reported and left alone. That dissolves the
+ * "Homebrew or ~/.local/bin" question: we never contend for ownership of a tool
+ * someone else's package manager installed, and never shadow it with an earlier
+ * PATH entry that would silently win over their upgrades.
+ *
+ * Usage:
+ *   workstation.mjs                     report what is present and missing
+ *   workstation.mjs --install           install everything missing
+ *   workstation.mjs --install --agents=claude,codex   only these agents
+ *   workstation.mjs --json              machine-readable plan
+ *   workstation.mjs --print-dockerfile  an image that runs this same script
+ * @module workstation
+ */
+
+import { execFileSync } from "node:child_process";
+
+import {
+  AGENTS,
+  CHECKSUMMED,
+  INSTALLABLE,
+  PROVIDERS,
+  TOOLS,
+} from "./catalogue.mjs";
+
+/**
+ * Locate a command without running it.
+ *
+ * Presence and version are different questions, and conflating them has bitten
+ * this codebase before: probing with `--version` reported `unzip` missing on
+ * machines that had it, because Info-ZIP exits 10 on an unknown flag. So
+ * presence is `command -v` and nothing else.
+ * @param {string} name Executable name.
+ * @param {Function} [exec] Runner, injectable for tests.
+ * @returns {string|null} Absolute path, or null when absent.
+ */
+export function locate(name, exec = execFileSync) {
+  try {
+    return String(
+      exec("command", ["-v", name], { encoding: "utf8", shell: true })
+    ).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read a tool's version, tolerating tools that dislike `--version`.
+ *
+ * A non-zero exit does NOT mean absent — only a failure to spawn does. 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.
+ * @param {string} name Executable name.
+ * @param {Function} [exec] Runner, injectable for tests.
+ * @returns {string|null} A dotted version, or null.
+ */
+export function version(name, exec = execFileSync) {
+  const read = out => {
+    const match = /(\d+(?:\.\d+)+)/.exec(String(out ?? ""));
+    return match ? match[1] : null;
+  };
+  try {
+    return read(
+      exec(name, ["--version"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+      })
+    );
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    return read(`${error.stdout ?? ""}${error.stderr ?? ""}`);
+  }
+}
+
+/**
+ * Where a tool came from, so the report can say why it is being left alone.
+ * @param {string|null} path Absolute path to the executable.
+ * @returns {string} A short provenance label.
+ */
+export function provenance(path) {
+  if (!path) return "absent";
+  if (path.includes("/homebrew/") || path.startsWith("/usr/local/Cellar"))
+    return "homebrew";
+  if (path.includes("/.local/bin/")) return "~/.local/bin";
+  if (path.includes("/node_modules/")) return "node_modules";
+  if (path.startsWith("/usr/bin") || path.startsWith("/bin")) return "system";
+  return "other";
+}
+
+/**
+ * Decide what to do about one catalogue entry.
+ * @param {object} entry Catalogue entry.
+ * @param {object} [deps] Injected probes, for tests.
+ * @returns {object} A plan row.
+ */
+export function planEntry(entry, deps = {}) {
+  const find = deps.locate ?? locate;
+  const read = deps.version ?? version;
+
+  const path = find(entry.name);
+  const found = path ? read(entry.name) : null;
+  const base = {
+    name: entry.name,
+    label: entry.label,
+    kind: entry.kind,
+    path,
+    version: found,
+    from: provenance(path),
+    checksummed: CHECKSUMMED.has(entry.kind),
+  };
+
+  if (path) {
+    // Present by any means: report and leave alone. Re-installing over a
+    // vendor's own layout is how a self-updater gets broken.
+    return {
+      ...base,
+      action: "present",
+      reason: `already installed (${base.from})`,
+    };
+  }
+  if (entry.kind === "required") {
+    return {
+      ...base,
+      action: "blocked",
+      reason: `${entry.name} is required but absent — ${entry.note}`,
+    };
+  }
+  if (!INSTALLABLE.has(entry.kind)) {
+    return {
+      ...base,
+      action: "manual",
+      reason: entry.note ?? "no headless installer available",
+    };
+  }
+  return { ...base, action: "install", reason: "absent" };
+}
+
+/**
+ * Build the full plan across agents and tools.
+ * @param {object} [options] Selection and injected probes.
+ * @returns {object[]} Plan rows.
+ */
+export function planWorkstation(options = {}) {
+  const wanted = options.agents ?? null;
+  const agents = AGENTS.filter(a => !wanted || wanted.includes(a.name)).map(
+    a => ({
+      ...planEntry(a, options),
+      group: "agent",
+    })
+  );
+  const tools = TOOLS.map(t => ({ ...planEntry(t, options), group: "tool" }));
+
+  // Only the SELECTED provider is planned. Installing every credential CLI
+  // would leave four unused ones on the machine, each needing patching for no
+  // benefit — and would contradict the secrets contract, where the provider is
+  // a per-project axis rather than a fixed vendor.
+  const provider = resolveProvider(options.provider);
+  const credential = provider
+    ? [{ ...planProvider(provider, options), group: "provider" }]
+    : [];
+
+  return [...agents, ...credential, ...tools];
+}
+
+/**
+ * Resolve a requested provider name to its catalogue entry.
+ *
+ * An unknown name is an error rather than a silent fallback to Bitwarden: a
+ * typo that quietly provisions the wrong credential manager is worse than one
+ * that stops.
+ * @param {string|null|undefined} name Requested provider.
+ * @returns {object|null} Entry, or null when none was requested.
+ */
+export function resolveProvider(name) {
+  if (name === null || name === undefined) return null;
+  const entry = PROVIDERS.find(p => p.name === name);
+  if (!entry) {
+    throw new Error(
+      `unknown credential manager "${name}". Supported: ` +
+        `${PROVIDERS.map(p => p.name).join(", ")}`
+    );
+  }
+  return entry;
+}
+
+/**
+ * Plan the selected credential manager.
+ * @param {object} provider Catalogue entry.
+ * @param {object} [deps] Injected probes, for tests.
+ * @returns {object} A plan row.
+ */
+export function planProvider(provider, deps = {}) {
+  if (provider.kind === "none") {
+    // A first-class answer, not an absence. Reported so the operator can see
+    // the machine is deliberately on plain environment variables.
+    return {
+      name: "none",
+      label: provider.label,
+      kind: "none",
+      path: null,
+      version: null,
+      from: "n/a",
+      checksummed: false,
+      action: "present",
+      reason: "no credential manager selected",
+    };
+  }
+  return planEntry({ ...provider, name: provider.binary }, deps);
+}
+
+/**
+ * Render the plan for a human.
+ * @param {object[]} plan Plan rows.
+ * @returns {string} Report text.
+ */
+export function renderPlan(plan) {
+  const lines = [];
+  const heading = {
+    agent: "Coding agents:",
+    provider: "\nCredential manager:",
+    tool: "\nTools:",
+  };
+  for (const group of ["agent", "provider", "tool"]) {
+    const rows = plan.filter(r => r.group === group);
+    if (!rows.length) continue;
+    lines.push(heading[group]);
+    for (const row of rows) {
+      const mark = {
+        present: "  ok     ",
+        install: "  install",
+        manual: "  manual ",
+        blocked: "  BLOCKED",
+      }[row.action];
+      // `none` is present-but-not-a-binary, so it has no version to show; a
+      // bare "?" there reads as a failed probe rather than a chosen answer.
+      const detail =
+        row.action !== "present"
+          ? row.reason
+          : row.path
+            ? `${row.version ?? "unknown version"}  (${row.from})`
+            : row.reason;
+      lines.push(`${mark} ${row.label.padEnd(22)} ${detail}`);
+    }
+  }
+
+  // Say plainly which installs carry a checksum and which trust a vendor.
+  const unverified = plan.filter(r => r.action === "install" && !r.checksummed);
+  if (unverified.length) {
+    lines.push(
+      `\nNot checksummed: ${unverified.map(r => r.name).join(", ")} — these run a` +
+        ` vendor installer, which is weaker than the pinned entries. Installing` +
+        ` them trusts the vendor's script at fetch time.`
+    );
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Install one entry by its own preferred method.
+ *
+ * Each vendor owns its layout; we invoke their installer rather than placing a
+ * binary ourselves. `release-zip`/`release-tar` are the exception and the only
+ * checksummed path — they are reused from the remote-env installer rather than
+ * reimplemented, because a second installer is a second thing to keep honest.
+ * @param {object} entry Catalogue entry.
+ * @param {object} row Plan row for it.
+ * @param {object} [deps] Injected runner, for tests.
+ * @returns {object} Result row.
+ */
+export function installEntry(entry, row, deps = {}) {
+  const run =
+    deps.run ??
+    ((cmd, args, opts) =>
+      execFileSync(cmd, args, { stdio: "inherit", ...opts }));
+  const find = deps.locate ?? locate;
+
+  try {
+    if (entry.kind === "npm-global") {
+      run("npm", ["install", "-g", entry.package]);
+    } else if (entry.kind === "vendor-script") {
+      if (!entry.script) {
+        return {
+          ...row,
+          action: "manual",
+          reason: entry.note ?? "no installer",
+        };
+      }
+      // Piping a fetched script to a shell is exactly the unverified path the
+      // report warns about. It is the vendor's supported route for these
+      // tools, and the alternative — repackaging their binaries ourselves —
+      // would break the self-updaters that own those directories.
+      //
+      // bash, NOT sh. On Ubuntu `/bin/sh` is dash, and every one of these
+      // vendor scripts is a bash script: piping them to sh in a container gave
+      // `Syntax error: "(" unexpected` and `set: Illegal option -o pipefail`
+      // while the same command worked on a Mac, where sh is bash.
+      //
+      // `set -o pipefail` matters as much as the shell does: without it the
+      // exit status is the SHELL's, not curl's, so a 404 feeds an empty script
+      // to bash, bash exits 0, and a tool that was never installed is reported
+      // as installed. That is exactly what `sonarsource.com/install` did.
+      run("bash", [
+        "-o",
+        "pipefail",
+        "-c",
+        `curl -fsSL ${entry.script} | bash`,
+      ]);
+    } else if (entry.kind === "aws-cli") {
+      // macOS ships a .pkg that wants an administrator, which a headless run
+      // has no business prompting for. Reported as manual with the one-line
+      // fix rather than attempted and failed halfway.
+      if ((deps.platform ?? process.platform) === "darwin") {
+        return {
+          ...row,
+          action: "manual",
+          reason:
+            "macOS installs from a .pkg needing admin — `brew install awscli`",
+        };
+      }
+      // Unprivileged by construction: the vendor installer defaults to /usr/local,
+      // which needs root and would put a container and a laptop on different
+      // paths. An explicit prefix under $HOME keeps one code path for both and
+      // survives a throwaway container, which is where $HOME dies anyway.
+      const home = deps.home ?? process.env.HOME;
+      const url = `https://awscli.amazonaws.com/awscli-exe-linux-${
+        process.arch === "arm64" ? "aarch64" : "x86_64"
+      }.zip`;
+      run("bash", [
+        "-o",
+        "pipefail",
+        "-c",
+        [
+          "set -e",
+          'tmp="$(mktemp -d)"',
+          `curl -fsSL "${url}" -o "$tmp/awscli.zip"`,
+          'unzip -q "$tmp/awscli.zip" -d "$tmp"',
+          `"$tmp/aws/install" --install-dir "${home}/.local/aws-cli" ` +
+            `--bin-dir "${home}/.local/bin" --update`,
+          'rm -rf "$tmp"',
+        ].join("\n"),
+      ]);
+    } else if (CHECKSUMMED.has(entry.kind)) {
+      // The pinned, checksummed path belongs to the remote-env installer. It is
+      // borrowed rather than reimplemented so the pins and checksums cannot
+      // drift between the two — a second installer is a second thing to keep
+      // honest, and the one run least often is the one that rots.
+      if (!deps.installPinned) {
+        return {
+          ...row,
+          action: "failed",
+          reason:
+            "pinned installer unavailable — cannot verify a checksum here",
+        };
+      }
+      deps.installPinned(entry);
+    } else {
+      return {
+        ...row,
+        action: "manual",
+        reason: entry.note ?? "no headless installer",
+      };
+    }
+  } catch (error) {
+    return {
+      ...row,
+      action: "failed",
+      reason: String(error.message).slice(0, 160),
+    };
+  }
+
+  // Verify by looking, not by exit status. Every installer above can exit 0
+  // having installed nothing, so a claim of success is only as good as a fresh
+  // probe — reporting a tool as installed when it is absent is worse than
+  // reporting the failure, because it moves the error to the moment of use.
+  if (!find(entry.name)) {
+    return {
+      ...row,
+      action: "failed",
+      reason: `installer exited 0 but ${entry.name} is still not on PATH`,
+    };
+  }
+  return { ...row, action: "installed", reason: "ok" };
+}

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.328.5",
+  "version": "2.329.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.328.5",
+  "version": "2.329.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.328.5",
+  "version": "2.329.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.328.5",
+  "version": "2.329.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.328.5",
+  "version": "2.329.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

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

package/plugins/lisa-copilot/commands/lisa/setup/workstation.md

@@ -0,0 +1,7 @@
+---
+description: "Prepare this machine — or a throwaway container — to run coding agents, before any repository exists. Detects which of Lisa's supported agents are already installed, asks which credential manager the machine uses (or none), and installs only what is missing, each by its vendor's own preferred method. Idempotent and headless; --print-dockerfile emits a spin-up/spin-down environment. Nothing is installed without --install."
+allowed-tools: ["Skill"]
+argument-hint: "[--install] [--agents=claude,codex] [--provider=bitwarden] [--json] [--print-dockerfile]"
+---
+
+Use the /lisa-setup-workstation skill to report and optionally install the coding agents, credential manager, and base tools this machine needs. $ARGUMENTS

package/plugins/lisa-copilot/skills/lisa-setup-workstation/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: lisa-setup-workstation
+description: "Prepare a machine — a fresh laptop or a throwaway container — to run coding agents, before any repository exists. Detects which of Lisa's supported agents (Claude Code, Codex, Cursor, OpenCode, Antigravity, Copilot) are already installed, asks which credential manager the machine uses (Bitwarden, 1Password, Doppler, Vault, AWS, or none), and installs only what is missing, each by its vendor's own preferred method. Idempotent, headless by default, and emits a Dockerfile for a spin-up/spin-down environment. Run it on a new machine, in a container, or before cloning anything."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Setup Workstation: $ARGUMENTS
+
+Get a machine ready to run agents. No checkout required.
+
+## Why this exists separately
+
+`lisa-setup-local-env` reads `remoteEnv.tools` — a **project's** declared toolchain — so it
+needs a checkout to exist before it can answer anything. That leaves a gap at the start:
+a bare laptop or an empty container has no repository yet, and therefore nothing to ask.
+
+This skill fills that gap and stops there. It describes a **machine**, never a project:
+
+```text
+workstation  ->  git clone  ->  lisa-detect-tooling  ->  lisa-setup-local-env
+```
+
+Project-scoped tools stay in `remoteEnv.tools` where they belong. Nothing here reads a
+repository, and nothing here duplicates that manifest.
+
+## Usage
+
+```sh
+node scripts/cli.mjs                              # report what is present and missing
+node scripts/cli.mjs --install                    # install what is missing
+node scripts/cli.mjs --install --agents=claude,codex   # only these agents
+node scripts/cli.mjs --provider=bitwarden         # credential manager (asked if a TTY)
+node scripts/cli.mjs --json                       # machine-readable plan
+node scripts/cli.mjs --print-dockerfile           # an image that runs this same script
+```
+
+Nothing is installed or written without `--install`. Exit status is non-zero when a required
+tool is absent or an install fails, so this is usable as a gate.
+
+## Ephemerality is not a mode
+
+There is no Docker branch anywhere in this skill. A container gets a throwaway `$HOME` and
+dies with it; a laptop keeps its own. Same code path either way — so the rarely-run one
+cannot rot, which is the failure mode a second install path eventually always has.
+
+`--print-dockerfile` emits an image rather than shipping a committed one, so the image cannot
+drift from the catalogue it provisions. It 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.
+
+```sh
+node scripts/cli.mjs --print-dockerfile --agents=claude,codex --provider=bitwarden > Dockerfile
+docker build -t lisa-workstation . && docker run --rm -it lisa-workstation
+```
+
+## Already-installed wins, however it got there
+
+A tool present by **any** means is reported and left alone. That dissolves the "Homebrew or
+`~/.local/bin`" question entirely: we never contend for ownership of a tool someone else's
+package manager installed, and never shadow it with an earlier PATH entry that would silently
+win over their upgrades. The report names where each tool came from so the operator can see
+why it was skipped.
+
+Running twice installs nothing the second time, and says so rather than going quiet — silence
+reads as "did nothing because it broke".
+
+## 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:
+
+```text
+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 catalogue entry declares its own method, and the honest cost is recorded with it:
+
+| kind | pinned | checksummed | notes |
+| --- | --- | --- | --- |
+| `release-zip` / `release-tar` | yes | yes | reuses the remote-env installer |
+| `npm-global` | no | no | vendor registry |
+| `vendor-script` | no | no | pipes a fetched script to a shell |
+| `manual` | n/a | n/a | no headless installer published |
+| `required` | n/a | n/a | expected from the OS or base image |
+
+`vendor-script` is a real weakening of the guarantee `assertPinned` exists to provide, so the
+report **names every unchecksummed install** rather than blending them in. Installing them
+trusts the vendor's script at fetch time. The alternative — repackaging vendor binaries
+ourselves — would break the self-updaters that own those directories.
+
+## The credential manager is asked, never assumed
+
+`lisa-secrets-access` already treats the provider as an axis: Bitwarden, 1Password, Doppler,
+Vault, AWS, or plain environment variables. A bootstrap that installed `bws` unconditionally
+would contradict that — pushing every workstation onto one vendor and quietly making the
+others second-class.
+
+So the provider is a question, `none` is a first-class answer, and only the selected one is
+installed. Installing all of them would leave four unused credential CLIs on the machine,
+each an extra thing to keep patched for no benefit.
+
+Headless is the primary mode, so with no TTY and no `--provider`, the answer is `none` — not
+a prompt that would hang a container build forever. A misspelled provider stops the run
+instead of falling back, because quietly provisioning the wrong credential manager is worse
+than stopping.
+
+## What it will not do
+
+- **Read a repository.** That is the next step, not this one.
+- **Install a credential manager you did not pick.**
+- **Reinstall over a tool that is already there**, whatever installed it.
+- **Install anything without `--install`.**
+- **Install `agy`.** Antigravity publishes no headless installer; it is reported as manual
+  with a pointer, because "not installed" and "cannot be installed by this tool" are
+  different answers to the operator.