@codyswann/lisa 2.328.5 → 2.330.0

package/plugins/lisa-copilot/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-cursor/.claude-plugin/plugin.json

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

package/plugins/lisa-cursor/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-cursor/hooks/block-instruction-file-edits.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+# PreToolUse hook: refuse agent writes to the session-instruction files.
+#
+# `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` are the files
+# every agent loads at session start. They are human-authored and curated on
+# purpose — Lisa's own contract says so in two places:
+#   - plugins/src/base/rules/reference/project-learnings.md
+#   - plugins/src/base/skills/lisa-debrief-apply/SKILL.md ("CLAUDE.md is
+#     human-authored ... apply never writes to any of the three")
+#
+# Nothing enforced it, so agents appended their own findings anyway: one fleet
+# repo reached 949 lines of ticket-keyed trap dumps in `AGENTS.md` while its
+# learnings ledger held 22. Every one of those lines is charged to the context
+# of every later session in that project, forever. Prose did not hold; this is
+# the executable control that does.
+#
+# Blocked signatures:
+#   1. Write / Edit / MultiEdit / NotebookEdit whose target basename is one of
+#      the instruction files;
+#   2. Bash output redirection (`>`, `>>`), `tee`, or `sed -i` aimed at one.
+#      Reads (`cat AGENTS.md`, `rg pattern AGENTS.md`) never fire.
+#
+# Exemptions (allowed):
+#   - `LISA_ALLOW_INSTRUCTION_FILE_WRITE` set — the operator's explicit override,
+#     named in the refusal so a human who really wants the edit can take it;
+#   - payloads carrying a `<!-- LISA_` marker: Lisa's own marker-bounded regions
+#     (the agy project-learnings bridge, cross-pollinate's rule section) replace
+#     in place on re-run and cannot grow the file;
+#   - paths under `node_modules/` or `dist/` — vendored copies, not the host's.
+set -euo pipefail
+
+input="$(cat)"
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+# The operator's override. Checked before anything else so it is always the
+# cheapest way out of a refusal a human deliberately wants to overrule.
+if [ -n "${LISA_ALLOW_INSTRUCTION_FILE_WRITE:-}" ]; then
+  exit 0
+fi
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty')"
+[ -n "$tool_name" ] || exit 0
+
+# Lisa's own bounded bridges write marked regions. A payload carrying a marker
+# is replacing a delimited block, not appending prose, so it cannot be the
+# unbounded growth this guard exists to stop.
+if printf '%s' "$input" | grep -q '<!-- LISA_'; then
+  exit 0
+fi
+
+# Basename match, case-insensitively: `agents.md` and `AGENTS.md` are the same
+# file on the macOS checkouts this fleet runs on.
+is_instruction_file() {
+  local candidate="$1"
+  case "$candidate" in
+    */node_modules/* | node_modules/* | */dist/* | dist/*) return 1 ;;
+  esac
+  local base="${candidate##*/}"
+  case "$(printf '%s' "$base" | tr '[:upper:]' '[:lower:]')" in
+    agents.md | claude.md | copilot-instructions.md) return 0 ;;
+  esac
+  return 1
+}
+
+refuse() {
+  local target="$1"
+  cat >&2 <<EOF
+BLOCKED: refusing to write \`$target\`.
+
+WHY: this is a session-instruction file, not a place to record what you just
+learned. Every line in it is loaded into the context of every agent, in every
+future session, in this project, forever. It is human-curated on purpose. An
+agent appending its own findings is how these files grow into hundreds of lines
+of stale, ticket-specific trivia that every later session pays for and half of
+which was only ever true once.
+
+WHERE IT GOES INSTEAD — take the first one that fits:
+
+1. Every agent genuinely needs this in every session, and only in this project.
+   That is a project rule — but do not write it yourself. Capture it with
+   \`/lisa:persist-learning\` so it lands in the learnings ledger with provenance
+   and a confidence score. The gardener (\`/lisa:learnings:audit\`) then proposes
+   promotion into \`.claude/rules/PROJECT_RULES.md\` as a human-gated ticket.
+
+2. It changes how an existing skill should behave. Edit that skill's SKILL.md.
+   Knowledge belongs next to the procedure it modifies, not in a global preamble.
+
+3. It is true beyond this project. Propose it upstream to Lisa via
+   \`/lisa:cross-pollinate\`, or open an issue on CodySwannGT/lisa. A local copy of
+   a general rule silently drifts the moment upstream changes.
+
+4. None of the above — it is background someone may want to look up, not a
+   standing instruction. Write it into the project documentation (\`wiki/\` or
+   \`docs/\`).
+
+If a human explicitly asked for this edit, they can re-run with
+\`LISA_ALLOW_INSTRUCTION_FILE_WRITE=1\` set, which bypasses this guard.
+EOF
+  exit 2
+}
+
+case "$tool_name" in
+  Write | Edit | MultiEdit | NotebookEdit | Update)
+    # `file_path` covers Write/Edit; `edits[].file_path` covers the MultiEdit
+    # shapes that carry a path per edit; `notebook_path` covers NotebookEdit.
+    paths="$(printf '%s' "$input" | jq -r '
+      [ .tool_input.file_path?,
+        .tool_input.path?,
+        .tool_input.notebook_path?,
+        (.tool_input.edits? // [] | .[].file_path?)
+      ] | map(select(. != null and . != "")) | .[]' 2>/dev/null || true)"
+    while IFS= read -r candidate; do
+      [ -n "$candidate" ] || continue
+      if is_instruction_file "$candidate"; then
+        refuse "$candidate"
+      fi
+    done <<EOF
+$paths
+EOF
+    ;;
+  Bash)
+    command_str="$(printf '%s' "$input" | jq -r '.tool_input.command // empty')"
+    [ -n "$command_str" ] || exit 0
+    # Fast path: no instruction filename mentioned means nothing to classify.
+    if ! printf '%s' "$command_str" |
+      grep -Eqi '(agents|claude|copilot-instructions)\.md'; then
+      exit 0
+    fi
+    # Write signatures only. A bare mention (`cat AGENTS.md`, `rg x AGENTS.md`)
+    # is a read and must stay allowed — the filename has to appear as the target
+    # of a redirection, a tee, or an in-place sed.
+    write_target='[^ |;&]*(agents|claude|copilot-instructions)\.md'
+    if printf '%s' "$command_str" |
+      grep -Eqi ">>?[[:space:]]*['\"]?$write_target|tee([[:space:]]+-[a-z]+)*[[:space:]]+['\"]?$write_target|sed[[:space:]]+[^|;&]*-i[^|;&]*$write_target"; then
+      refuse "$(printf '%s' "$command_str" |
+        grep -Eoi "$write_target" | head -1)"
+    fi
+    ;;
+esac
+
+exit 0

package/plugins/lisa-cursor/hooks/hooks.json

@@ -29,6 +29,14 @@
         "command": "${CURSOR_PLUGIN_ROOT}/hooks/block-shell-json-parsing.sh",
         "matcher": "Bash"
       },
+      {
+        "command": "${CURSOR_PLUGIN_ROOT}/hooks/block-instruction-file-edits.sh",
+        "matcher": "Bash"
+      },
+      {
+        "command": "${CURSOR_PLUGIN_ROOT}/hooks/block-instruction-file-edits.sh",
+        "matcher": "Write|Edit|MultiEdit"
+      },
       {
         "command": "${CURSOR_PLUGIN_ROOT}/hooks/enforce-verification-gate.sh"
       }