@codyswann/lisa 2.328.4 → 2.328.5

package/plugins/src/base/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}`);