wizz-method 1.2.2 → 1.3.1

package/tools/installer/modules/deps-cache.js

@@ -0,0 +1,140 @@
+// Writes a project-local cache manifest of the skill dependencies (CLIs + MCPs)
+// resolved at install-time for the chosen areas.
+//
+// Behavior B of the "Doutrina de Instalação" (skills-registry.yaml, rule 2):
+// when the installed skills declare NPX/CLI/MCP dependencies, detect them and
+// cache the result in the project so future runs and the maestro can see —
+// without re-resolving the registry or re-probing PATH — exactly which deps
+// belong to this project's skills and what state they were left in:
+//   - clis.installed / clis.recommended / clis.alreadyPresent
+//   - mcps.written (merged into .mcp.json) / mcps.recommended
+//
+// This is a passive manifest (a cache, not an installer): it records the plan
+// the install already executed. It never runs commands, never writes secrets
+// (MCP env stays as the registry `${VAR}` placeholders), and is a no-op when
+// there is nothing to record. Written into `_wizz/_config/` next to the
+// installed skills-registry.yaml so the routing source and the dep cache stay
+// co-located.
+
+const path = require('node:path');
+const fs = require('../fs-native');
+
+const CACHE_BASENAME = 'skill-deps-cache.json';
+
+/**
+ * Shape a resolved CLI entry for the cache: identity + the copy-pasteable
+ * install command, dropping the transient `installed` probe flag (its bucket
+ * already encodes that). Returns a new object; never mutates the input.
+ * @param {{id: string, when?: string, install?: string, areas?: string[]}} cli
+ * @returns {{id: string, when: string, install: string, areas: string[]}}
+ */
+function shapeCli(cli) {
+  return {
+    id: cli.id,
+    when: cli.when || '',
+    install: cli.install || '',
+    areas: Array.isArray(cli.areas) ? [...cli.areas] : [],
+  };
+}
+
+/**
+ * Shape a resolved MCP entry for the cache: identity + the server block as it
+ * came from the registry (env values remain `${VAR}` placeholders — no real
+ * token is ever cached). Returns a new object; never mutates the input.
+ * @param {{id: string, when?: string, server?: Object, areas?: string[]}} mcp
+ * @returns {{id: string, when: string, server: Object, areas: string[]}}
+ */
+function shapeMcp(mcp) {
+  return {
+    id: mcp.id,
+    when: mcp.when || '',
+    server: mcp.server ? { ...mcp.server } : {},
+    areas: Array.isArray(mcp.areas) ? [...mcp.areas] : [],
+  };
+}
+
+/**
+ * Build the cache object from the install-time cli/mcp plans. Pure: no I/O,
+ * no mutation of the inputs. Exposed for tests and for the caller to inspect.
+ * @param {Object} args
+ * @param {string[]} [args.selectedAreas] - Chosen area keys ([] => all areas)
+ * @param {{toInstall?: Object[], toRecommend?: Object[], alreadyInstalled?: Object[]}} [args.cliPlan]
+ * @param {{toWrite?: Object[], toRecommend?: Object[]}} [args.mcpPlan]
+ * @returns {Object} The manifest to be written.
+ */
+function buildDepsCache({ selectedAreas, cliPlan = {}, mcpPlan = {} }) {
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    selectedAreas: Array.isArray(selectedAreas) ? [...selectedAreas] : [],
+    clis: {
+      installed: (cliPlan.toInstall || []).map(shapeCli),
+      recommended: (cliPlan.toRecommend || []).map(shapeCli),
+      alreadyPresent: (cliPlan.alreadyInstalled || []).map(shapeCli),
+    },
+    mcps: {
+      written: (mcpPlan.toWrite || []).map(shapeMcp),
+      recommended: (mcpPlan.toRecommend || []).map(shapeMcp),
+    },
+  };
+}
+
+/**
+ * True when a built cache has no dependency entries at all — nothing worth
+ * persisting (e.g. no `bmm` module, or the chosen areas declare no deps).
+ * @param {Object} cache - Output of buildDepsCache
+ * @returns {boolean}
+ */
+function isEmptyDepsCache(cache) {
+  const c = cache.clis || {};
+  const m = cache.mcps || {};
+  return (
+    (c.installed || []).length === 0 &&
+    (c.recommended || []).length === 0 &&
+    (c.alreadyPresent || []).length === 0 &&
+    (m.written || []).length === 0 &&
+    (m.recommended || []).length === 0
+  );
+}
+
+/**
+ * Build and write the deps cache into `<wizzDir>/_config/skill-deps-cache.json`.
+ * No-op (writes nothing, returns wrote:false) when there are no deps to record,
+ * so it is always safe to call. Never throws for lack of deps; a real fs error
+ * propagates to the caller, which already wraps this step in a warn-not-abort.
+ *
+ * @param {Object} args
+ * @param {string} args.wizzDir - Installed `_wizz` directory
+ * @param {string[]} [args.selectedAreas] - Chosen area keys ([] => all)
+ * @param {Object} [args.cliPlan] - The install-time CLI plan (from ui.selectClis)
+ * @param {Object} [args.mcpPlan] - The install-time MCP plan (from ui.selectMcps)
+ * @param {(absPath: string) => void} [args.trackFile] - Record the written file
+ * @returns {Promise<{wrote: boolean, file: string|null, counts: Object}>}
+ */
+async function writeDepsCache({ wizzDir, selectedAreas, cliPlan, mcpPlan, trackFile = () => {} }) {
+  const cache = buildDepsCache({ selectedAreas, cliPlan, mcpPlan });
+  const counts = {
+    clisInstalled: cache.clis.installed.length,
+    clisRecommended: cache.clis.recommended.length,
+    clisAlreadyPresent: cache.clis.alreadyPresent.length,
+    mcpsWritten: cache.mcps.written.length,
+    mcpsRecommended: cache.mcps.recommended.length,
+  };
+
+  if (isEmptyDepsCache(cache)) return { wrote: false, file: null, counts };
+
+  const file = path.join(wizzDir, '_config', CACHE_BASENAME);
+  await fs.ensureDir(path.dirname(file));
+  await fs.writeJson(file, cache, { spaces: 2 });
+  trackFile(file);
+  return { wrote: true, file, counts };
+}
+
+module.exports = {
+  buildDepsCache,
+  isEmptyDepsCache,
+  writeDepsCache,
+  shapeCli,
+  shapeMcp,
+  CACHE_BASENAME,
+};

package/tools/installer/modules/mcp-config.js

@@ -20,6 +20,7 @@
 
 const path = require('node:path');
 const fs = require('../fs-native');
+const { defaultExec } = require('./cli-config');
 
 /**
  * Resolve the recommended MCP entries for the chosen areas, deduped by id.
@@ -48,6 +49,12 @@ function resolveMcps(registry, selectedAreas) {
       id: mcp.id,
       when: mcp.when || '',
       server: mcp.server,
+      // `setup` (optional) declares how to make a `command:`-relative server
+      // actually usable before it is written: install the backing package,
+      // download runtime assets, resolve the binary to an absolute path, and
+      // verify it boots. Carried here so prepareMcps() can act on it; dropped
+      // from what toServerConfig() writes (it never belongs in .mcp.json).
+      setup: mcp.setup || null,
       areas: areaKey ? [areaKey] : [],
     });
   };
@@ -74,6 +81,157 @@ function toServerConfig(server) {
   return out;
 }
 
+/**
+ * POSIX-quote a path so it survives interpolation into a shell command even
+ * when it contains spaces or shell metacharacters. Single-quote wrapped, with
+ * embedded single quotes escaped the classic `'\''` way.
+ * @param {string} value
+ * @returns {string}
+ */
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+
+/**
+ * Substitute the `{bin}` placeholder in a setup command with the shell-quoted
+ * absolute path of the resolved binary. Lets the registry write portable setup
+ * commands (`{bin} install`, `{bin} --version`) that bind to the real path at
+ * run time instead of relying on PATH.
+ * @param {string} command - Command template possibly containing `{bin}`
+ * @param {string} binPath - Absolute path to substitute
+ * @returns {string}
+ */
+function substituteBin(command, binPath) {
+  return String(command).replaceAll('{bin}', shellQuote(binPath));
+}
+
+/**
+ * Resolve the absolute path of a binary an MCP server shells out to. A bare
+ * `command: "scrapling"` is fragile: the MCP subprocess spawned by the client
+ * does not always inherit the user's ~/.local/bin on PATH, so a relative name
+ * fails with ENOENT even when the tool is installed. We resolve and write the
+ * absolute path instead. Tries `command -v` first (honors the current PATH),
+ * then the conventional user-local bin dir where `uv tool` / `pipx` / `pip
+ * --user` land executables. Returns null when the binary is nowhere to be found.
+ *
+ * @param {string} bin - Binary name to locate
+ * @param {Function} [exec] - Injected runner (command, opts) => {ok, stdout,...}
+ * @returns {Promise<string|null>} Absolute path, or null if not found.
+ */
+async function resolveBinPath(bin, exec = defaultExec) {
+  if (!bin) return null;
+  const viaWhich = await exec(`command -v ${bin}`, { timeoutMs: 5000 });
+  if (viaWhich.ok) {
+    const found = (viaWhich.stdout || '').trim().split('\n')[0].trim();
+    if (found) return found;
+  }
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  if (home) {
+    const candidate = path.join(home, '.local', 'bin', bin);
+    if (await fs.pathExists(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Run an MCP entry's `setup` block so the server is genuinely usable BEFORE it
+ * lands in .mcp.json. This closes the ENOENT gap where the installer wrote a
+ * server config but never installed the backing tool. Contract (detect-first,
+ * mirroring cli-config's install philosophy):
+ *
+ *   1. DETECT  — resolve the binary; if already present we skip installation.
+ *   2. INSTALL — on a miss, run `setup.install` (package + its MCP extra), then
+ *      re-resolve. `setup.post_install` (e.g. downloading browsers) runs after,
+ *      only on a fresh install, with `{bin}` bound to the resolved path.
+ *   3. RESOLVE — rewrite `server.command` to the ABSOLUTE path so the client's
+ *      MCP subprocess never depends on PATH inheriting ~/.local/bin.
+ *   4. VERIFY  — run `setup.verify` ({bin} bound). A failure means writing the
+ *      config would point at a broken/missing binary, so we DO NOT write it —
+ *      the entry is reported failed and the caller drops it with a clear message.
+ *
+ * Immutable: returns a new entry with a patched `server.command`; the input is
+ * never mutated. Entries without a `setup` block pass through untouched.
+ *
+ * @param {Object} args
+ * @param {Object} args.mcp - Resolved MCP entry (id, server, setup?)
+ * @param {Function} [args.exec] - Injected runner (command, opts) => {ok,...}
+ * @returns {Promise<{mcp: Object, ok: boolean, ran: boolean, error: string|null}>}
+ */
+async function prepareMcp({ mcp, exec = defaultExec }) {
+  const setup = mcp && mcp.setup;
+  if (!setup) return { mcp, ok: true, ran: false, error: null };
+
+  const bin = setup.bin || (mcp.server && mcp.server.command);
+  if (!bin) {
+    return { mcp, ok: false, ran: false, error: 'setup declarado sem `bin` nem `server.command` para resolver' };
+  }
+
+  // 1. DETECT — install only when the binary is not already resolvable.
+  let binPath = await resolveBinPath(bin, exec);
+  const freshInstall = !binPath;
+
+  if (freshInstall) {
+    if (!setup.install) {
+      return { mcp, ok: false, ran: false, error: `binário '${bin}' ausente e setup não tem comando \`install\`` };
+    }
+    const installed = await exec(setup.install, { timeoutMs: 900_000 });
+    if (!installed.ok) {
+      return { mcp, ok: false, ran: true, error: `instalação falhou: ${(installed.stderr || 'erro desconhecido').trim()}` };
+    }
+    binPath = await resolveBinPath(bin, exec);
+    if (!binPath) {
+      return {
+        mcp,
+        ok: false,
+        ran: true,
+        error: `'${bin}' não encontrado no PATH nem em ~/.local/bin após a instalação`,
+      };
+    }
+    // 2. POST-INSTALL (e.g. browser download) — fresh installs only, idempotent.
+    if (setup.post_install) {
+      const post = await exec(substituteBin(setup.post_install, binPath), { timeoutMs: 900_000 });
+      if (!post.ok) {
+        return { mcp, ok: false, ran: true, error: `pós-instalação falhou: ${(post.stderr || 'erro desconhecido').trim()}` };
+      }
+    }
+  }
+
+  // 4. VERIFY — never write a config pointing at a binary that cannot boot.
+  if (setup.verify) {
+    const verified = await exec(substituteBin(setup.verify, binPath), { timeoutMs: 60_000 });
+    if (!verified.ok) {
+      return { mcp, ok: false, ran: freshInstall, error: `verificação falhou: ${(verified.stderr || 'erro desconhecido').trim()}` };
+    }
+  }
+
+  // 3. RESOLVE — patch the absolute path; leave args/env/everything else intact.
+  const patched = { ...mcp, server: { ...mcp.server, command: binPath } };
+  return { mcp: patched, ok: true, ran: freshInstall, error: null };
+}
+
+/**
+ * Prepare every MCP entry (see prepareMcp), splitting the set into `ready`
+ * (safe to write, with any `server.command` patched to an absolute path) and
+ * `failed` (setup did not complete — the caller must NOT write these and should
+ * surface the error so the user can fix it manually). Never throws: each entry
+ * is isolated so one broken tool never blocks the others or the wider install.
+ *
+ * @param {Object} args
+ * @param {Array<Object>} args.mcps - Resolved MCP entries to prepare
+ * @param {Function} [args.exec] - Injected runner (command, opts) => {ok,...}
+ * @returns {Promise<{ready: Array<Object>, failed: Array<{id: string, error: string}>}>}
+ */
+async function prepareMcps({ mcps, exec = defaultExec }) {
+  const ready = [];
+  const failed = [];
+  for (const mcp of mcps || []) {
+    const res = await prepareMcp({ mcp, exec });
+    if (res.ok) ready.push(res.mcp);
+    else failed.push({ id: mcp.id, error: res.error || 'falha desconhecida' });
+  }
+  return { ready, failed };
+}
+
 /**
  * Render the `claude mcp add` command for an MCP entry — used to recommend
  * servers the user chose NOT to write (nothing is lost; they can add later).
@@ -134,4 +292,14 @@ async function writeMcpConfig({ projectDir, mcps, trackFile = () => {} }) {
   return { added, skipped, file };
 }
 
-module.exports = { resolveMcps, toServerConfig, renderAddCommand, writeMcpConfig };
+module.exports = {
+  resolveMcps,
+  toServerConfig,
+  renderAddCommand,
+  writeMcpConfig,
+  prepareMcp,
+  prepareMcps,
+  resolveBinPath,
+  shellQuote,
+  substituteBin,
+};