@codyswann/lisa 2.327.0 → 2.328.0

package/plugins/lisa-agy/skills/lisa-setup-remote-env/scripts/toolchain.mjs

@@ -100,7 +100,7 @@ function planRequired(tool, found) {
  * @param {{version: string|null, present: boolean}} found Probe result.
  * @returns {{name: string, action: string, reason: string}} The decision.
  */
-function planInstallable(tool, found) {
+function planInstallable(tool, found, pinIsFloor = false) {
   if (!tool.version) {
     return {
       name: tool.name,
@@ -115,6 +115,25 @@ function planInstallable(tool, found) {
       reason: `${tool.name} ${tool.version} already installed`,
     };
   }
+  // On a laptop the pin is a floor, not an equality. A container is disposable
+  // and reproducible by construction, so an exact match is right there. A
+  // developer's machine is shared with every other project they work on, and
+  // installing a pinned binary into ~/.local/bin ahead of a NEWER one already on
+  // PATH is a downgrade this project imposed on all of them — for gh, pinned at
+  // 2.83.0 against a workstation running 2.96.0, that is the likely case rather
+  // than the exotic one.
+  if (
+    pinIsFloor &&
+    found.present &&
+    found.version &&
+    compareVersions(found.version, tool.version) > 0
+  ) {
+    return {
+      name: tool.name,
+      action: "newer",
+      reason: `${tool.name} ${found.version} is newer than the pinned ${tool.version} — leaving it alone`,
+    };
+  }
   return {
     name: tool.name,
     action: "install",
@@ -127,6 +146,72 @@ function planInstallable(tool, found) {
 /** Surfaces a manifest entry may name. */
 const KNOWN_SURFACES = new Set(["local", "remote"]);
 
+/**
+ * The platform key a manifest entry is resolved against.
+ *
+ * `<platform>-<arch>` rather than either alone, because both halves change the
+ * artifact: an Apple Silicon laptop and an Intel one run different builds of the
+ * same release, and so do an arm64 container and an amd64 one.
+ * @param {{platform: string, arch: string}} [runtime] Injectable, for tests.
+ * @returns {string} A key such as "darwin-arm64" or "linux-x64".
+ */
+export function currentPlatform(runtime = process) {
+  return `${runtime.platform}-${runtime.arch}`;
+}
+
+/**
+ * Collapse a manifest entry to the artifact for one platform.
+ *
+ * A download URL is platform-specific and a checksum doubly so, which the
+ * single-URL shape could not express: the only way to stop a laptop being handed
+ * a Linux binary was `surfaces: ["remote"]`, which bought that safety by making
+ * the tool uninstallable on the laptop entirely. So `bws` and `gh` — the two
+ * tools Lisa's own guardrails shell out to — were declared, required, and
+ * unprovisionable on the machine most likely to be missing them.
+ *
+ * A `platforms` map fixes the cause instead of the symptom. `install` lives
+ * inside each block rather than beside it, because the method varies too: gh
+ * publishes a .tar.gz for Linux and a .zip for macOS, so a single install method
+ * would have forced one platform onto an archive kind its vendor does not ship.
+ *
+ * A flat entry is still valid and means "identical everywhere" — true of every
+ * `npm-global` install, which is genuinely platform-independent.
+ * @param {object} tool Manifest entry.
+ * @param {string} [platform] Platform key to resolve for.
+ * @returns {object} The entry with its platform block merged in.
+ */
+export function resolvePlatform(tool, platform = currentPlatform()) {
+  const { platforms } = tool;
+  if (platforms === undefined) return tool;
+  if (
+    typeof platforms !== "object" ||
+    platforms === null ||
+    Array.isArray(platforms)
+  ) {
+    throw new Error(
+      `${tool.name}: platforms must be an object keyed by <platform>-<arch>, ` +
+        `got ${Array.isArray(platforms) ? "an array" : typeof platforms}.\n` +
+        `Omit it when one artifact serves every platform.`
+    );
+  }
+  const block = platforms[platform];
+  if (!block) {
+    const known = Object.keys(platforms).sort().join(", ");
+    throw new Error(
+      `${tool.name}: no pin for ${platform}.\n` +
+        `Declared platforms: ${known || "(none)"}.\n` +
+        `Add a block for ${platform} with its own url and sha256, or drop the ` +
+        `tool from this surface. Guessing an artifact would defeat the ` +
+        `checksum.`
+    );
+  }
+  // The platform block wins over the shared fields, and `platforms` itself is
+  // dropped so a resolved entry is indistinguishable from a flat one — that is
+  // what lets assertPinned and the installers stay unaware of any of this.
+  const { platforms: _discarded, ...shared } = tool;
+  return { ...shared, ...block };
+}
+
 /**
  * Whether a manifest entry applies to the surface being provisioned.
  *
@@ -171,18 +256,48 @@ export function appliesToSurface(tool, surface) {
 
 /**
  * Produce the complete plan for a toolchain manifest.
+ *
+ * Install entries are resolved to the running platform here rather than at
+ * install time, so a tool with no artifact for this machine is reported
+ * alongside every other problem instead of aborting the run at the first one.
+ * An operator fixing a manifest wants the whole list.
+ *
+ * `require` entries are deliberately not resolved: they carry a name and a
+ * minimum version, nothing platform-specific, and inventing a per-platform shape
+ * for them would be ceremony with no artifact behind it.
  * @param {{require?: object[], install?: object[]}} tools Manifest.
  * @param {(name: string) => {version: string|null, present: boolean}} probe Version probe.
- * @returns {Array<{name: string, action: string, reason: string}>} Ordered decisions.
+ * @param {string} [surface] Surface being provisioned.
+ * @param {string} [platform] Platform key to resolve install entries against.
+ * @returns {Array<{name: string, action: string, reason: string, tool?: object}>} Ordered decisions.
  */
-export function planToolchain(tools, probe, surface = "remote") {
+export function planToolchain(
+  tools,
+  probe,
+  surface = "remote",
+  platform = currentPlatform()
+) {
   const plan = [];
   for (const tool of tools.require ?? [])
     if (appliesToSurface(tool, surface))
       plan.push(planRequired(tool, probe(tool.name)));
-  for (const tool of tools.install ?? [])
-    if (appliesToSurface(tool, surface))
-      plan.push(planInstallable(tool, probe(tool.name)));
+  for (const tool of tools.install ?? []) {
+    if (!appliesToSurface(tool, surface)) continue;
+    let resolved;
+    try {
+      resolved = resolvePlatform(tool, platform);
+    } catch (err) {
+      plan.push({ name: tool.name, action: "invalid", reason: err.message });
+      continue;
+    }
+    // The resolved entry travels with the decision so the installer never has to
+    // resolve a second time — two resolutions are two chances to disagree, and
+    // the one that installs would be the one nothing tested.
+    plan.push({
+      ...planInstallable(resolved, probe(tool.name), surface === "local"),
+      tool: resolved,
+    });
+  }
   return plan;
 }
 
@@ -195,6 +310,17 @@ export function planToolchain(tools, probe, surface = "remote") {
  * @param {object} tool Manifest entry.
  */
 export function assertPinned(tool) {
+  // An unresolved entry reaching here means a caller skipped resolvePlatform and
+  // is about to read a url and sha256 that belong to no platform in particular.
+  // Refusing is the point: the failure this whole change exists to prevent is
+  // exactly "downloaded the wrong platform's artifact", and a silent pass here
+  // would reintroduce it one call site at a time.
+  if (tool.platforms !== undefined) {
+    throw new Error(
+      `${tool.name}: platform-specific entry was not resolved before install.\n` +
+        `Call resolvePlatform() first — the shared fields alone do not name an artifact.`
+    );
+  }
   // Both archive kinds carry the same obligation, and differ only in how they
   // are unpacked. gh, for one, publishes no zip for Linux at all — only .deb,
   // .rpm and .tar.gz — so a zip-only installer could not pin the CLI that

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.327.0",
+  "version": "2.328.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.327.0",
+  "version": "2.328.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.327.0",
+  "version": "2.328.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.327.0",
+  "version": "2.328.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.327.0",
+  "version": "2.328.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.327.0",
+  "version": "2.328.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/commands/lisa/setup/local-env.md

@@ -0,0 +1,7 @@
+---
+description: "Bring this machine in line with the toolchain the project declares. Reports every tool in remoteEnv.tools that is missing, outdated, or unpinned for this platform, and installs the missing ones into ~/.local/bin from the same pinned, checksummed entries the remote surfaces use — but only when asked with --install-tools. A newer tool already on PATH is left alone."
+allowed-tools: ["Skill"]
+argument-hint: "[--install-tools] [--json]"
+---
+
+Use the /lisa-setup-local-env skill to report and optionally install the project's declared toolchain on this machine. $ARGUMENTS

package/plugins/lisa-copilot/skills/lisa-detect-tooling/SKILL.md

@@ -46,7 +46,27 @@ What genuinely differs is **consent**, not the list:
 
 Omitting `surfaces` means every surface, because that is true of most tools and the cost of forgetting should be a redundant check rather than a silent absence.
 
-A platform-specific pin is the exception worth knowing: a Linux release archive must be `surfaces: ["remote"]`, with a matching `require` entry for `local`, so a laptop asserts the tool without being offered a binary it cannot run.
+Platform differences are **not** expressed with `surfaces`. A downloaded tool declares a
+`platforms` map keyed `<platform>-<arch>`, each block carrying its own `install` method, `url`,
+and `sha256`:
+
+```json
+"platforms": {
+  "linux-x64":    { "install": "release-tar", "url": "...", "sha256": "..." },
+  "darwin-arm64": { "install": "release-zip", "url": "...", "sha256": "..." }
+}
+```
+
+The method lives inside the block because it varies — gh ships a `.tar.gz` for Linux and a
+`.zip` for macOS. A flat entry means one artifact serves everything, which is true of
+`npm-global` and nothing else.
+
+This replaces an earlier convention worth naming, because its residue may still be in a
+manifest you read: a Linux archive used to be marked `surfaces: ["remote"]` with a bare
+`require` entry for `local`, so a laptop asserted the tool without being offered a binary it
+could not run. That kept the wrong binary off the laptop by making the tool uninstallable
+there — which is how `bws` and `gh`, the two CLIs Lisa's own guardrails shell out to, came to
+be required on developer machines and provisionable only in containers.
 
 ## Usage
 

package/plugins/lisa-copilot/skills/lisa-detect-tooling/scripts/detect-tooling.mjs

@@ -361,9 +361,11 @@ export function detectTooling(cwd = process.cwd()) {
 /**
  * The manifest entries an operator can paste, with the parts only they supply.
  *
- * Returns both lists because a platform-specific archive needs both: an
- * `install` entry for the surface it is built for, and a `require` entry so the
- * other surface still asserts the tool instead of silently ignoring it.
+ * A release archive is proposed as a `platforms` map rather than a single URL
+ * plus `surfaces: ["remote"]`. The old shape could express only one artifact, so
+ * keeping a Linux binary off a laptop meant excluding the tool from laptops
+ * altogether — which is how `bws` and `gh` came to be required on a developer
+ * machine and installable only in a container.
  * @param {{name: string}} proposal One detected tool.
  * @returns {{install: object[], require: object[]}} Manifest skeletons.
  */
@@ -394,23 +396,33 @@ export function proposedEntries(proposal) {
       require: [],
     };
   }
-  // A release archive is built for one platform, so it is proposed as
-  // remote-install plus a local `require`. Proposing only the install entry
-  // produced a manifest that either offered a Linux binary to a laptop or —
-  // once narrowed to remote — stopped checking for the tool locally at all.
-  // Both halves or neither.
+  // A release archive is built for one platform, so every platform the project
+  // is developed or built on needs its own block — with its own install method,
+  // because a vendor may ship a tarball for one and a zip for another, as gh
+  // does. Both containers and laptops are proposed: a tool the manifest can
+  // only install remotely is one every developer installs by hand or does
+  // without.
+  //
+  // The placeholders stay unresolved on purpose. A guessed URL is an artifact
+  // the checksum cannot vouch for, which is the one property that makes a
+  // pinned entry worth reviewing.
+  const archive = platform => ({
+    install: "<release-tar or release-zip, whichever this platform ships>",
+    url: `<release url for this exact version, for ${platform}>`,
+    sha256: `<sha256 published with the ${platform} release>`,
+  });
   return {
     install: [
       {
         name: proposal.name,
         version: "<pin>",
-        install: "release-tar",
-        url: "<release url for this exact version, for the remote platform>",
-        sha256: "<sha256 published with that release>",
-        surfaces: ["remote"],
+        platforms: {
+          "linux-x64": archive("linux-x64"),
+          "darwin-arm64": archive("darwin-arm64"),
+        },
       },
     ],
-    require: [{ name: proposal.name, surfaces: ["local"] }],
+    require: [],
   };
 }
 

package/plugins/lisa-copilot/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -73,8 +73,16 @@ function bindingsFor(surface) {
   return SURFACE_BINDINGS[surface] ?? ["repository"];
 }
 
-/** Install methods the toolchain runner supports. */
-const INSTALL_METHODS = new Set(["release-zip", "npm-global"]);
+/**
+ * Install methods the toolchain runner supports.
+ *
+ * `release-tar` was missing here while the runner had supported it for as long
+ * as gh has been pinned — so this validator would have rejected the project's
+ * own manifest, and the only reason nobody hit it is that nothing ran the two
+ * against each other. Kept in step with `assertPinned` in `toolchain.mjs`,
+ * which is the list that actually decides.
+ */
+const INSTALL_METHODS = new Set(["release-zip", "release-tar", "npm-global"]);
 
 /**
  * Validate the `secrets` block.
@@ -143,6 +151,44 @@ export function validateSecrets(secrets) {
   return problems;
 }
 
+/**
+ * Validate the artifact half of one install entry.
+ *
+ * Split out because the same obligations apply whether the fields sit directly
+ * on the entry or inside a per-platform block: a method must be one Lisa can
+ * execute, an archive must carry a checksum, and an npm install must name a
+ * package. Duplicating those three rules per shape is how one shape ends up
+ * quietly weaker than the other.
+ * @param {string} label How to name this entry in a message.
+ * @param {object} entry The entry or platform block.
+ * @param {string[]} problems Accumulator.
+ */
+function validateInstallArtifact(label, entry, problems) {
+  if (!INSTALL_METHODS.has(entry.install)) {
+    problems.push(
+      `remoteEnv install ${label} has method ${JSON.stringify(entry.install)}. ` +
+        `Supported: ${[...INSTALL_METHODS].join(", ")}.`
+    );
+    return;
+  }
+  // Both archive kinds, not just zip. A tarball pinned without a checksum
+  // trusts whatever the URL serves today exactly as much as a zip does, and
+  // checking only one of them meant the tool Lisa's guardrails shell out to —
+  // gh, which ships a tarball on Linux — was the one going unverified.
+  if (
+    (entry.install === "release-zip" || entry.install === "release-tar") &&
+    !(entry.url && entry.sha256)
+  ) {
+    problems.push(
+      `remoteEnv install ${label} needs both url and sha256. A pinned ` +
+        `version with no checksum still trusts whatever the URL serves today.`
+    );
+  }
+  if (entry.install === "npm-global" && !entry.package) {
+    problems.push(`remoteEnv install ${label} needs a package`);
+  }
+}
+
 /**
  * Validate the `remoteEnv` block.
  * @param {object|undefined} remoteEnv The block, if present.
@@ -163,21 +209,37 @@ export function validateRemoteEnv(remoteEnv) {
     if (!tool.version) {
       problems.push(`remoteEnv install "${tool.name}" has no pinned version`);
     }
-    if (!INSTALL_METHODS.has(tool.install)) {
+    // A flat entry means one artifact serves every platform — true of npm-global
+    // and of nothing else. Anything downloaded is platform-specific, so those
+    // declare a block per platform and each block is validated in full: a
+    // half-filled map is the failure this shape exists to prevent, and it is
+    // invisible until someone runs setup on the platform that was left out.
+    if (tool.platforms === undefined) {
+      validateInstallArtifact(`"${tool.name}"`, tool, problems);
+      continue;
+    }
+    if (
+      typeof tool.platforms !== "object" ||
+      tool.platforms === null ||
+      Array.isArray(tool.platforms)
+    ) {
       problems.push(
-        `remoteEnv install "${tool.name}" has method ${JSON.stringify(tool.install)}. ` +
-          `Supported: ${[...INSTALL_METHODS].join(", ")}.`
+        `remoteEnv install "${tool.name}" has a platforms field that is not an ` +
+          `object keyed by <platform>-<arch>. Omit it when one artifact serves ` +
+          `every platform.`
       );
       continue;
     }
-    if (tool.install === "release-zip" && !(tool.url && tool.sha256)) {
+    const platforms = Object.entries(tool.platforms);
+    if (platforms.length === 0) {
       problems.push(
-        `remoteEnv install "${tool.name}" needs both url and sha256. A pinned ` +
-          `version with no checksum still trusts whatever the URL serves today.`
+        `remoteEnv install "${tool.name}" declares platforms but lists none, so ` +
+          `it can never be installed anywhere.`
       );
+      continue;
     }
-    if (tool.install === "npm-global" && !tool.package) {
-      problems.push(`remoteEnv install "${tool.name}" needs a package`);
+    for (const [platform, block] of platforms) {
+      validateInstallArtifact(`"${tool.name}" (${platform})`, block, problems);
     }
   }
 

package/plugins/lisa-copilot/skills/lisa-setup-local-env/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: lisa-setup-local-env
+description: "Bring a developer's machine in line with the toolchain the project declares. Reports every tool in remoteEnv.tools that is missing, outdated, or unpinned for this platform, and installs the missing ones into ~/.local/bin from the same pinned, checksummed entries the remote surfaces use — but only when asked. Same manifest, same pins, same installers as lisa-setup-remote-env; what differs is consent and that the pin is a floor rather than an equality. Run it on a fresh checkout, after a manifest change, or when a tool fails at the moment of use."
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Setup Local Environment: $ARGUMENTS
+
+Make this machine match what the project says it needs.
+
+## Why this exists separately
+
+`remoteEnv.tools` was always the manifest for **every** surface, and the executor always
+understood `local`. What did not exist was a way to ask for it. The only path ran a file named
+`setup-remote-env.mjs`, out of a directory named `lisa-remote-env`, via a skill named
+`lisa-setup-remote-env` — and it only existed at all once someone had provisioned a *remote*
+environment, because that is what writes it into the repository.
+
+So the machine most likely to be missing a tool was the one with no way to ask about it.
+
+This skill is that surface. It adds no manifest, no pins, and no installer: it imports the
+ones the remote flow owns. A second installer would be a second thing to keep honest, and the
+one people run least is the one that rots.
+
+## Usage
+
+```sh
+node scripts/local-env.mjs                  # report what diverges
+node scripts/local-env.mjs --install-tools  # install what is missing
+node scripts/local-env.mjs --json           # machine-readable plan
+```
+
+Exit status is non-zero when a tool cannot be resolved, so this is usable as a gate.
+
+## What differs from a container
+
+Two things, and both are because a person is here.
+
+**Consent.** A container is disposable and provisions itself silently — that is the whole
+point of it. A laptop belongs to someone, and putting pinned binaries into their
+`~/.local/bin` uninvited is not ours to decide. Nothing installs until `--install-tools`.
+Reporting happens either way, because knowing the machine diverges from what the project
+declares is most of the value.
+
+**The pin is a floor, not an equality.** A container should hold exactly the pinned version;
+it exists to be reproducible. A developer's machine is shared with every other project they
+work on, so installing a pinned binary ahead of a **newer** one already on `PATH` is a
+downgrade this project imposed on all of them. A newer tool is reported as `newer` and left
+alone. Older, or absent, is an install.
+
+## Platform pins
+
+An install entry either serves every platform — true of `npm-global` and nothing else — or
+declares a `platforms` map keyed `<platform>-<arch>`, each block carrying its own `install`
+method, `url`, and `sha256`:
+
+```json
+{
+  "name": "gh",
+  "version": "2.83.0",
+  "platforms": {
+    "linux-x64":    { "install": "release-tar", "url": "...linux_amd64.tar.gz", "sha256": "...", "binary": "gh_2.83.0_linux_amd64/bin/gh" },
+    "darwin-arm64": { "install": "release-zip", "url": "...macOS_arm64.zip",    "sha256": "...", "binary": "gh_2.83.0_macOS_arm64/bin/gh" }
+  }
+}
+```
+
+The method lives **inside** each block because it varies: gh publishes a `.tar.gz` for Linux
+and a `.zip` for macOS, so a single method would have forced one platform onto an archive kind
+its vendor does not ship.
+
+When a tool has no block for the running platform, this skill says so and stops there. It will
+not guess a download URL — a guessed artifact is one the checksum cannot vouch for, and the
+checksum is the only thing standing between a pinned entry and whatever a URL serves today.
+Add the block, or install that one tool however the platform normally would.
+
+## Detect before you install
+
+Run `/lisa:detect-tooling` when the report looks thin. The manifest is the only thing that puts
+a binary on `PATH`, and nothing populates it automatically — so a project ships npm scripts
+invoking `maestro`, wires an MCP server whose CLI it also shells out to, and configures
+Playwright thresholds, while `remoteEnv.tools` stays empty and each of those fails at the
+moment of use instead of at setup.
+
+The detector proposes and a human decides. It writes nothing, so a tool still only ever reaches
+a machine from a reviewed, pinned, checksummed entry.
+
+## What it will not do
+
+- **No unpinned installs.** Every install goes through the same `assertPinned` gate the remote
+  flow uses, and the same in-process checksum verification, which refuses before unpacking.
+- **No package-manager fallback.** Shelling out to Homebrew would give no version pin and no
+  checksum, which is the property this design exists to enforce.
+- **No writes to the manifest.** Proposing entries belongs to `/lisa:detect-tooling`; deciding
+  belongs to a human reviewing a diff.