@codyswann/lisa 2.328.4 → 2.329.0

package/plugins/lisa/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.

package/plugins/lisa/skills/lisa-setup-workstation/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Setup Workstation"
+short_description: "Prepare a machine — a fresh laptop or a throwaway container — to run coding agents, before any repository exists"
+default_prompt:
+  - "Use $lisa-setup-workstation: Prepare a machine — a fresh laptop or a throwaway container — to run coding agents, before any repository exists."

package/plugins/lisa/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];
+}