@codyswann/lisa 2.328.4 → 2.328.5

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

@@ -22,9 +22,11 @@
  * @module detect-tooling
  */
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 
+import { commandsIn } from "./commands.mjs";
+
 /** The tool named by the Expo template's scripts and its flows directory. */
 const MAESTRO = "maestro";
 
@@ -109,6 +111,128 @@ export function toolsFromScripts(pkg) {
   return found;
 }
 
+/** Where git hooks live, strongest signal first. */
+const HOOK_DIRECTORIES = [".husky", join(".git", "hooks")];
+
+/**
+ * Coding agents, which a PROJECT manifest must never try to provision.
+ *
+ * A hook that shells out to `claude` is real evidence of a real dependency, but
+ * `remoteEnv.tools` is the wrong place to answer it: agents belong to the
+ * machine, not the checkout, and each is installed by its vendor's own method
+ * into a version directory it manages itself. Pinning one as a release archive
+ * would fight the self-updater that owns that directory.
+ *
+ * That layer is `lisa-setup-workstation`. Named here rather than imported from
+ * it, because a detector that stops working when a sibling skill is absent is
+ * worse than one carrying six strings.
+ *
+ * Deliberately NOT extended to `gh`, `bws`, `aws` or `sonar`: those genuinely
+ * belong in a project manifest, and `gh` going undeclared is the incident this
+ * skill was written after.
+ */
+const WORKSTATION_PROVISIONED = new Set([
+  "claude",
+  "codex",
+  "cursor-agent",
+  "opencode",
+  "agy",
+  "copilot",
+]);
+
+/**
+ * Tools a git hook runs — the strongest signal a project can give.
+ *
+ * Stronger than an npm script, because a hook runs on EVERY commit and push
+ * whether anyone asked or not. A container missing one of these cannot commit at
+ * all; the failure arrives mid-task, unattended, at the moment of use.
+ *
+ * The worst shape is the guarded one. This repository'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 exactly where it matters
+ * most, which is why a probed name counts as evidence rather than being read as
+ * "optional".
+ * @param {string} cwd Project root.
+ * @returns {Map<string, string>} Tool name to the hook that proves it.
+ */
+export function toolsFromGitHooks(cwd) {
+  const found = new Map();
+  for (const directory of HOOK_DIRECTORIES) {
+    const full = join(cwd, directory);
+    let names = [];
+    try {
+      names = readdirSync(full);
+    } catch {
+      continue;
+    }
+    for (const name of names.sort()) {
+      // `.sample` files ship with git and run nothing.
+      if (name.endsWith(".sample")) continue;
+      let body;
+      try {
+        body = readFileSync(join(full, name), "utf8");
+      } catch {
+        continue;
+      }
+      for (const tool of commandsIn(body)) {
+        if (!found.has(tool)) found.set(tool, `git hook ${directory}/${name}`);
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Tools an npm script invokes, discovered rather than matched against a list.
+ *
+ * `toolsFromScripts` answers "which of the tools I already know about appear
+ * here". This answers the open question — what does this project actually RUN —
+ * which is the one that finds a tool nobody thought to add. An Expo project
+ * invoking `eas` from eight scripts produced nothing under the old shape,
+ * because `eas` was not in `KNOWN_TOOLS`.
+ * @param {object|null} pkg Parsed package.json.
+ * @returns {Map<string, string>} Tool name to the script that proves it.
+ */
+export function toolsDiscoveredInScripts(pkg) {
+  const found = new Map();
+  for (const [name, body] of Object.entries(pkg?.scripts ?? {})) {
+    if (typeof body !== "string") continue;
+    for (const tool of commandsIn(body)) {
+      if (found.has(tool)) continue;
+      found.set(tool, `npm script "${name}": ${body.trim().slice(0, 60)}`);
+    }
+  }
+  return found;
+}
+
+/**
+ * Whether the package manager already puts this binary on the local path.
+ *
+ * A dependency's binary lands in `node_modules/.bin`, where npm scripts resolve
+ * it without it ever being on PATH. Proposing a manifest entry for one is noise,
+ * and noise is how a detector teaches people to skim it.
+ *
+ * Only meaningful once dependencies are installed, which is why
+ * `dependenciesInstalled` exists rather than this quietly returning false on a
+ * fresh clone and over-proposing every dev tool in the project.
+ * @param {string} cwd Project root.
+ * @param {string} tool Tool name.
+ * @returns {boolean} Whether npm already provides it.
+ */
+export function providedByNodeModules(cwd, tool) {
+  return existsSync(join(cwd, "node_modules", ".bin", tool));
+}
+
+/**
+ * Whether `node_modules` is populated, so its absence can be reported.
+ * @param {string} cwd Project root.
+ * @returns {boolean} Whether dependencies are installed.
+ */
+export function dependenciesInstalled(cwd) {
+  return existsSync(join(cwd, "node_modules", ".bin"));
+}
+
 /**
  * MCP servers that are access substrates rather than evidence for a CLI.
  *
@@ -330,8 +454,14 @@ export function detectTooling(cwd = process.cwd()) {
   const notes = readJson(join(cwd, ".lisa", "secret-notes.json"));
 
   const declared = declaredTools(config);
+  // Curated signals carry a vetted `why`. Discovered ones carry only the fact
+  // that the project runs the thing — weaker prose, identical standing as
+  // evidence, and the only kind that can find a tool nobody listed.
+  const hooks = toolsFromGitHooks(cwd);
   const signals = [
+    hooks,
     toolsFromScripts(pkg),
+    toolsDiscoveredInScripts(pkg),
     toolsFromMcp(mcp),
     toolsFromSecretNotes(notes),
     toolsFromQuality(config, pkg, cwd),
@@ -343,8 +473,11 @@ export function detectTooling(cwd = process.cwd()) {
       if (declared.has(tool)) continue;
       // Already provided by the package manager, so there is nothing to pin.
       if (satisfiedByNpm(pkg, tool)) continue;
+      if (providedByNodeModules(cwd, tool)) continue;
+      // Real dependency, wrong manifest — the workstation layer owns it.
+      if (WORKSTATION_PROVISIONED.has(tool)) continue;
       const entry = merged.get(tool) ?? { evidence: [] };
-      entry.evidence.push(evidence);
+      if (!entry.evidence.includes(evidence)) entry.evidence.push(evidence);
       merged.set(tool, entry);
     }
   }
@@ -352,12 +485,35 @@ export function detectTooling(cwd = process.cwd()) {
   return [...merged.entries()]
     .map(([name, entry]) => ({
       name,
-      why: KNOWN_TOOLS[name]?.why ?? "",
+      why: KNOWN_TOOLS[name]?.why ?? discoveredWhy(name, hooks.has(name)),
       evidence: entry.evidence,
+      // Says which vocabulary the `why` came from, so a reader can weigh it.
+      // A curated entry has been thought about; a discovered one has only been
+      // observed.
+      source: Object.hasOwn(KNOWN_TOOLS, name) ? "curated" : "discovered",
     }))
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/**
+ * The `why` for a tool nobody wrote prose for.
+ *
+ * Every proposal must carry one — a proposal without a reason is an assertion,
+ * and this program's whole boundary is that it asserts nothing. So a discovered
+ * tool states the observation plainly rather than borrowing confidence it has
+ * not earned.
+ * @param {string} name Tool name.
+ * @param {boolean} fromHook Whether a git hook runs it.
+ * @returns {string} A reason a reader can check.
+ */
+export function discoveredWhy(name, fromHook) {
+  return fromHook
+    ? `A git hook runs \`${name}\` on every commit or push, and nothing ` +
+        `declares it — a machine without it fails at commit time, or skips the ` +
+        `check silently if the hook guards it.`
+    : `An npm script invokes \`${name}\`, and nothing puts it on PATH.`;
+}
+
 /**
  * The manifest entries an operator can paste, with the parts only they supply.
  *
@@ -438,8 +594,18 @@ if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
     console.log(
       `${proposals.length} tool(s) look required but are not declared:\n`
     );
+    if (!dependenciesInstalled(process.cwd())) {
+      // Without node_modules there is no way to tell a tool that needs PATH
+      // from one npm already provides, so every dev dependency looks missing.
+      // Said out loud rather than silently over-proposing.
+      console.log(
+        "note: dependencies are not installed, so binaries npm would provide " +
+          "cannot be\n      excluded. Run the install first for a shorter, " +
+          "more accurate list.\n"
+      );
+    }
     for (const proposal of proposals) {
-      console.log(`  ${proposal.name}`);
+      console.log(`  ${proposal.name}  [${proposal.source}]`);
       console.log(`    why: ${proposal.why}`);
       for (const evidence of proposal.evidence) {
         console.log(`    evidence: ${evidence}`);

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

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

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