@codyswann/lisa 4.74.9 → 4.75.0

package/plugins/lisa-devin/skills/lisa-setup-workstation/scripts/bounded-child.mjs

@@ -0,0 +1,168 @@
+/**
+ * bounded-child — the plugin payload's child-start deadline.
+ *
+ * @remarks
+ * ## Why this exists separately from `scripts/lib/bounded-spawn.mjs`
+ *
+ * Same property, different reach. A plugin payload cannot import from
+ * `scripts/lib/`: the built plugin is a self-contained copy of
+ * `plugins/src/<name>/`, and nothing outside that tree exists at runtime. So the
+ * rule is written out here rather than pointed at — the accommodation
+ * `threshold-ratchet.mjs` and `preflight-secrets.mjs` already make for their
+ * entry guards.
+ *
+ * It is a MODULE rather than 28 inline copies because the fanout preserves
+ * relative imports. Measured in the built output, not assumed:
+ * `plugins/lisa/skills/lisa-setup-workstation/scripts/catalogue.mjs` exists and
+ * is imported as `../../lisa-setup-workstation/scripts/catalogue.mjs` from a
+ * sibling skill. The build copies the plugin tree wholesale, so a path that
+ * resolves in `plugins/src/base/` resolves in all five copies.
+ *
+ * That distinction matters because the accommodation above is narrower than its
+ * wording suggests. `threshold-ratchet.mjs` cannot import a sibling because it
+ * is **materialized into other lanes** — `typescript/`, `rails/` — where the
+ * sibling does not exist at the destination. A file that lives only in this
+ * plugin has no such problem.
+ *
+ * ## The one thing a deadline alone does not fix
+ *
+ * `spawnSync` does not throw when it kills a child. It returns:
+ *
+ * | outcome | `.code` | `.status` | `.signal` | streams |
+ * | --- | --- | --- | --- | --- |
+ * | killed at deadline | `"ETIMEDOUT"` | `null` | `"SIGKILL"` | **empty** |
+ * | ran, exited non-zero | *(absent)* | `3` | `null` | real |
+ * | binary not found | `"ENOENT"` | `null` | `null` | empty |
+ *
+ * So the shape that appears all over this tree —
+ *
+ * ```js
+ * return result.status === 0 ? result.stdout : null;
+ * ```
+ *
+ * — takes the benign branch for a killed child exactly as it does for a program
+ * that ran and said no. **Adding `timeout:` gives such a call site a deadline
+ * and changes nothing about its verdict.** There is no `catch` to fix, because
+ * the fail-open is in the conditional.
+ *
+ * That is why `boundedChild` THROWS rather than returning a flag: a caller that
+ * does nothing inherits fail-closed behaviour, and only one that deliberately
+ * catches can proceed.
+ * ## Why it lives in THIS skill's directory
+ *
+ * It is not about workstation setup, and it is here anyway, for a measured
+ * reason. The built Codex artifact — `plugins/lisa/.codex-plugin/` — copies
+ * `skills/` and nothing else: no `scripts/`, `agents/`, `commands/` or
+ * `rules/`. So a skill script importing `../../../scripts/lib/…` resolves to a
+ * path that does not exist in that copy, while `../../<skill>/scripts/…`
+ * resolves everywhere, which is exactly why `catalogue.mjs` beside this file is
+ * already imported that way from a sibling skill.
+ *
+ * A directory of its own under `skills/` was the tidier home and was rejected
+ * on evidence: every `skills/` subdirectory in this tree is a real skill with a
+ * `SKILL.md`, the generators parse that file to build their artifacts, and a
+ * directory without one is a shape nothing here has ever produced. Choosing an
+ * unproven layout is what put the import in the wrong place to begin with.
+ *
+ * **Do not delete this as unused from its host skill.** Its importers are in
+ * other skills and in `../../../scripts/`; `lisa-setup-workstation` hosts it,
+ * it does not own it.
+ * @module bounded-child
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+
+/**
+ * Deadline a child gets when the caller states none, in milliseconds.
+ *
+ * A hang detector, not a performance budget. `git` resolved through `PATH` on
+ * macOS goes via Apple's `xcrun` shim, measured at over 20 seconds under load
+ * against 11ms for a real binary (CodySwannGT/lisa#2887) — so a tighter
+ * deadline would make this module's own timeout the dominant failure mode, and
+ * the tool would start manufacturing the failures it exists to detect.
+ */
+export const CHILD_BUDGET_MS = 30_000;
+
+/**
+ * Deadline for setup operations that legitimately include downloads, package
+ * installation, secret-provider calls, or a project-declared hook.
+ *
+ * Kept separate from {@link CHILD_BUDGET_MS}: probes should still fail quickly,
+ * while a cold network install must not be killed by the probe budget.
+ */
+export const SETUP_OPERATION_BUDGET_MS = 10 * 60_000;
+
+/**
+ * Whether this value is a child that was killed at its deadline.
+ *
+ * Reads `code` rather than an error class, because `ETIMEDOUT` is set by Node
+ * itself on all three call forms — it is a platform fact, not a convention this
+ * module invented, so the same test is correct anywhere including inline.
+ *
+ * Defensive about the shape: a `catch` binding is `unknown` and a thrown
+ * non-object is legal JavaScript, so this must answer `false` rather than crash
+ * the guard that was being careful.
+ * @param {unknown} error A caught value, or `result.error` from `spawnSync`.
+ * @returns {boolean} True when the child was killed at its deadline.
+ */
+export function isChildTimeout(error) {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    /** @type {{ code?: unknown }} */ (error).code === "ETIMEDOUT"
+  );
+}
+
+/**
+ * Re-raise a caught value when it is a killed child, otherwise do nothing.
+ *
+ * The correct spelling is `throw error` — not wrapping — because a wrapped
+ * error loses the `code` the next frame up needs to make the same decision.
+ * @param {unknown} error The caught value.
+ * @returns {void}
+ * @throws {unknown} The original value, when it is a killed child.
+ */
+export function rethrowIfChildTimeout(error) {
+  if (isChildTimeout(error)) throw error;
+}
+
+/**
+ * `spawnSync` with a deadline, refusing to return a killed child's result.
+ * @param {string} command The executable.
+ * @param {readonly string[]} args Arguments.
+ * @param {object} [options] `spawnSync` options; `timeout` overrides the default.
+ * @returns {import("node:child_process").SpawnSyncReturns<string>} The result.
+ * @throws {Error} When the child was killed at its deadline.
+ */
+export function boundedChild(command, args = [], options = {}) {
+  const result = spawnSync(command, [...args], {
+    ...options,
+    // `SIGKILL` rather than the default `SIGTERM`: the hang this exists for is
+    // a process not servicing signals, and a `SIGTERM` a child ignores turns
+    // the deadline into a suggestion.
+    killSignal: "SIGKILL",
+    timeout: options.timeout ?? CHILD_BUDGET_MS,
+  });
+  if (isChildTimeout(result.error)) throw result.error;
+  return result;
+}
+
+/**
+ * `execFileSync` with a deadline.
+ *
+ * `execFileSync` already throws on a timeout, so this changes the FAILURE MODE
+ * rather than adding one: without a `timeout` there is no deadline to reach and
+ * the call blocks for as long as the child lives.
+ * @param {string} command The executable.
+ * @param {readonly string[]} args Arguments.
+ * @param {object} [options] `execFileSync` options; `timeout` overrides the default.
+ * @returns {string|Buffer} Whatever the child wrote to stdout.
+ * @throws {Error} When the child was killed, or exited non-zero.
+ */
+export function boundedChildOutput(command, args = [], options = {}) {
+  return execFileSync(command, [...args], {
+    ...options,
+    killSignal: "SIGKILL",
+    timeout: options.timeout ?? CHILD_BUDGET_MS,
+  });
+}

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

@@ -0,0 +1,293 @@
+/**
+ * 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: "vendor-script",
+    // Google does publish a headless bootstrapper; this entry previously said
+    // otherwise and reported the agent as uninstallable. Confirmed live —
+    // `content-type: application/x-sh`, and the payload is a bash script that
+    // downloads and verifies the flat native build.
+    script: "https://antigravity.google/cli/install.sh",
+    selfUpdates: true,
+  },
+  {
+    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",
+      },
+      // Bitwarden publishes macOS archives for the same tag, and omitting them
+      // made the one genuinely pinned credential CLI the one a macOS operator
+      // had to install by hand — the unverified path, for the tool where an
+      // unverified download matters most.
+      "darwin-arm64": {
+        url: "https://github.com/bitwarden/sdk-sm/releases/download/bws-v2.1.0/bws-aarch64-apple-darwin-2.1.0.zip",
+        sha256:
+          "9cb1c1c6e6164d83b2e339883ba02b4cbb37188ce9a484b1ce8249443163e066",
+      },
+      "darwin-x64": {
+        url: "https://github.com/bitwarden/sdk-sm/releases/download/bws-v2.1.0/bws-x86_64-apple-darwin-2.1.0.zip",
+        sha256:
+          "6f626b3971368902af1b9847c02791a1b4666969d7561e2047681cded7997537",
+      },
+    },
+  },
+  {
+    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",
+      },
+      // `install` is per-block for gh and only for gh: the vendor ships a
+      // .tar.gz for Linux and a .zip for macOS, so the entry-level `release-tar`
+      // is wrong for exactly these two. Without the override the resolved entry
+      // keeps `release-tar` and the installer runs `tar -xzf` over a ZIP, which
+      // fails during extraction — a macOS pin that resolves and cannot install.
+      "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",
+        install: "release-zip",
+      },
+      // Intel Macs are still in service, and an Apple Silicon-only macOS block
+      // reads as "macOS is covered" while leaving half of it uncovered.
+      "darwin-x64": {
+        url: "https://github.com/cli/cli/releases/download/v2.83.0/gh_2.83.0_macOS_amd64.zip",
+        sha256:
+          "0c0de650752bb92d7283e386cafd03d9ac5f47028c648c4ab821ef08a75c0716",
+        binary: "gh_2.83.0_macOS_amd64/bin/gh",
+        install: "release-zip",
+      },
+    },
+  },
+  {
+    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];
+}