@codyswann/lisa 2.328.4 → 2.329.0

package/plugins/lisa/.codex-plugin/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/commands/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/skills/lisa-detect-tooling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lisa-detect-tooling
-description: "Find the command-line tools a project needs but never declares, and propose pinned manifest entries for them. Reads npm scripts, MCP servers, credential usage notes and quality configuration, subtracts whatever remoteEnv.tools already covers, and prints proposals with evidence. Writes nothing and installs nothing — a tool reaches a machine only when a human has reviewed a pinned, checksummed entry. Invoked by lisa-setup-remote-env before provisioning, and runnable on its own."
+description: "Find the command-line tools a project needs but never declares, and propose pinned manifest entries for them. Reads git hooks and npm scripts for what the project actually RUNS — discovering tools no list mentions — plus MCP servers, credential usage notes and quality configuration. Subtracts whatever remoteEnv.tools, node_modules and the workstation layer already cover, and prints proposals with evidence. Writes nothing and installs nothing — a tool reaches a machine only when a human has reviewed a pinned, checksummed entry. Invoked by lisa-setup-remote-env before provisioning, and runnable on its own."
 allowed-tools: ["Bash", "Read", "AskUserQuestion"]
 ---
 
@@ -20,15 +20,45 @@ Nothing populates that last row. So a project can ship scripts that invoke `maes
 
 That is the same failure this repository has now paid for twice: `gh` was declared nowhere and a cloud session could not commit; `tar` was needed by an install method and asserted by nothing.
 
+## Discovery, not recognition
+
+The first version of this could only find tools it had been told about: it matched script bodies against a fixed `KNOWN_TOOLS` list. That makes the detector useful for exactly the set that needs it least — the tools someone already thought of.
+
+An Expo project invoking `eas` from **eight** npm scripts and six CI steps produced no proposal, because `eas` was not on the list. `gitleaks`, which runs on every commit in every one of these repositories, produced no proposal either.
+
+So the question asked of executable sources is now the open one — *what does this project actually run* — and everything already provided is subtracted afterwards:
+
+- what `remoteEnv.tools` declares
+- what `node_modules/.bin` provides (a dependency's binary never needs to be on PATH)
+- what `lisa-setup-workstation` owns (coding agents belong to the machine, not the checkout)
+
+The curated list stays, because a vetted `why` is worth more than an observed one — proposals say which they are, `[curated]` or `[discovered]`.
+
 ## What it does
 
-Reads four signals, subtracts what `remoteEnv.tools` already declares, and prints what is left with the evidence for each:
+Reads six signals, subtracts what is already covered, and prints what is left with the evidence for each:
+
+- **git hooks** (`.husky/*`, `.git/hooks/*`) that invoke a binary. The **strongest** signal available, stronger than an npm script: a hook runs on every commit and push whether anyone asked or not, so a machine without the tool cannot commit at all.
 
-- **npm scripts** that invoke a binary. The strongest signal there is — a script running `maestro test` is the project stating a dependency in executable form. Matched on the script *body*, not its name, because the name is a label.
+  A `command -v` guard counts as evidence rather than as "optional", because the guarded shape is the worse one. Lisa's pre-commit hook wraps its secret scan in `command -v gitleaks`, so on a machine without gitleaks the scan is **skipped silently** — the hook passes, the commit succeeds, and nothing was scanned. A guard makes the absence invisible precisely where it matters.
+
+- **npm scripts** that invoke a binary — a script running `maestro test` is the project stating a dependency in executable form. Read from the script *body*, not its name, because the name is a label.
 - **MCP servers with a CLI equivalent.** An MCP server is not a substitute for the binary: several authenticate by browser OAuth, which a container cannot do, so a project relying on one remotely has *no* integration rather than a degraded one. Do not infer a CLI for access layers that already define their own headless substrate; Linear is handled by `lisa-linear-access` through `LINEAR_API_KEY` + GraphQL when MCP OAuth is unavailable.
 - **Credential usage notes.** A note explaining what a token is for usually names the program that consumes it. `lisa-secrets-access` already exposes these without touching a value, which makes them a first-class input rather than a trick.
 - **Quality configuration**, where a threshold implies the tool that produces it.
 
+## Reading shell is the hard part
+
+Discovery only works if "what does this run" can be answered from shell text without inventing commands. Three things had to be right, each found by running it against real repositories:
+
+**Only the first word of a command position counts.** Word-scanning this repo's own hooks proposed `ltrimstr`, `map` and `select` (jq filter internals), `console.log` and `process.exit` (embedded JavaScript), and `load_audit_cves` (a function the hook defines three lines up). Reading only where a command can actually start removes all of them without a denylist entry for any.
+
+**Quoting and commenting nest, so neither can be stripped independently.** The comment on line 9 of `pre-push.local` ends `...the script's exit code)`. That lone apostrophe pairs with the next real quote 28 lines later, blanks everything between, and leaks a `node -e` payload's JavaScript into the results. Stripping comments first does not fix it, because a `#` inside a quoted string is not a comment. One character scanner tracking both is the only correct shape.
+
+**`$( )` restarts the quoting context.** In `"$(printf '%s' "$JSON" | node -e '…')"`, quotes inside the substitution pair among themselves. A flat scanner falls out of phase on the first one and starts reporting the payload's own string literals.
+
+Against Lisa and the three TunnlAI repositories, what survives is `gitleaks`, `jq`, `gtimeout` and `eas` — every one a real, undeclared invocation, with no false positives.
+
 ## What it will not do
 
 **It writes nothing and installs nothing.** Output is a proposal with `<pin>`, `<release url>` and `<sha256>` left for a human.