wizz-method 1.18.2 → 1.19.0

package/src/skills-lib/wizz-router/references/routing-table-flat.md

@@ -59,8 +59,7 @@ Use esta tabela pra mapear skills/CLIs/MCPs direto **fora de projeto Wizz** (sem
 | Intenção / palavras-chave | Skills a oferecer | Prioridade |
 |---|---|---|
 | Ideias de marketing, estratégia de marketing, posicionamento | `marketing-ideas` + `marketing-psychology` + `product-marketing-context` | 1 |
-| Paid ads, anúncios, Google Ads, Meta Ads, TikTok Ads, mídia paga | `paid-ads` + `ad-creative` + `analytics-tracking` + **MCP meta-ads** | 1 |
-| Gestão de campanha Meta/Facebook/Instagram via API real | **MCP meta-ads** (`mcp-meta-ads`) direto | 1 |
+| Paid ads, anúncios, Google Ads, Meta Ads, TikTok Ads, mídia paga | `paid-ads` + `ad-creative` + `analytics-tracking` | 1 |
 | Pixel/UTM/atribuição erradas, "a venda não bate com o gerenciador", "onde está furando o funil", tráfego orgânico inflado, conferir tracking antes de subir campanha | `tracking-audit` (+ `analytics-tracking` se for SaaS/produto) | 1 |
 | Lançamento de feature, lançamento de produto, go-to-market | `launch-strategy` + `social-content` + `email-sequence` | 1 |
 | Site pronto pra subir, pré-lançamento de SITE, "revisa antes do deploy", checklist de go-live, ou item pontual pré-lançamento (og:image/prévia de link, FAQ com schema, robots.txt, LGPD, alt text) | `site-launch-kit` | 1 |
@@ -97,6 +96,4 @@ Quando nenhuma skill/MCP instalado cobrir o pedido, **classifique o que falta**
 
 **Falta um MCP:** informe → `claude mcp list` → consulte `skills-registry.yaml` (`mcps:`/`mcp_utility:`, com `server` pronto) → proponha `claude mcp add <id> [-e VAR=$VAR] -- <command> [args]`. Secrets sempre via env/placeholder, nunca token real.
 
-MCPs comuns: context7 (docs de libs), supabase (Postgres), meta-ads (Meta), exa (pesquisa). Browser/E2E é sempre via CLI `agent-browser`, nunca via MCP Playwright.
-
-Para paid ads Meta, o MCP `mcp-meta-ads` dá acesso real à API Meta Marketing (campanhas, ad sets, ads, métricas, criativos). Combine com `paid-ads` + `ad-creative` + `analytics-tracking`. O `META_ACCESS_TOKEN` vem de env local: nunca exponha em logs ou código commitado.
+MCPs comuns: context7 (docs de libs), supabase (Postgres), exa (pesquisa). Browser/E2E é sempre via CLI `agent-browser`, nunca via MCP Playwright.

package/tools/installer/core/installer.js

@@ -4,7 +4,7 @@ const { Manifest } = require('./manifest');
 const { OfficialModules } = require('../modules/official-modules');
 const { installSkillsLib } = require('../modules/skills-lib');
 const { writeMcpConfig, renderAddCommand, prepareMcps, partitionAlreadyConfigured } = require('../modules/mcp-config');
-const { promptMissingEnvVars } = require('../modules/env-vars');
+const { promptMissingEnvVars, mcpsWithMissingRequiredEnv } = require('../modules/env-vars');
 const { installClis, renderInstallCommand } = require('../modules/cli-config');
 const { writeDepsCache, readPreviousMcpPins } = require('../modules/deps-cache');
 const { IdeManager } = require('../ide/manager');
@@ -423,7 +423,7 @@ class Installer {
               // is still cheap for an already-installed binary: prepareMcp is
               // detect-first, so only a genuinely missing binary pays for the
               // network-heavy install/post_install steps.
-              const { ready: mcpsReady, failed: mcpsFailed } = await prepareMcps({ mcps: toWrite });
+              let { ready: mcpsReady, failed: mcpsFailed } = await prepareMcps({ mcps: toWrite });
               for (const f of mcpsFailed) {
                 await prompts.log.warn(
                   `MCP ${f.id} não pôde ser preparado (${f.error}). Config NÃO escrita para evitar ENOENT — instale manualmente e adicione depois com \`claude mcp add\`.`,
@@ -451,10 +451,27 @@ class Installer {
                   mcps: mcpsReady,
                 });
                 const envInteractive = !config.skipPrompts && !!process.stdin.isTTY;
-                await promptMissingEnvVars(mcpsForEnvVars, {
+                const envResult = await promptMissingEnvVars(mcpsForEnvVars, {
                   projectDir: paths.projectRoot,
                   interactive: envInteractive,
                 });
+
+                // A required (no-default) var that stayed unresolved means
+                // the server would be written with a permanently-broken
+                // literal `${VAR}` — never write it (E1: never fail the
+                // install, just drop that server and tell the user how to
+                // retry).
+                const missingEnv = mcpsWithMissingRequiredEnv(mcpsReady, envResult.skipped);
+                if (missingEnv.length > 0) {
+                  const missingIds = new Set(missingEnv.map((m) => m.id));
+                  mcpsReady = mcpsReady.filter((m) => !missingIds.has(m.id));
+                  for (const m of missingEnv) {
+                    await prompts.log.warn(
+                      `MCP ${m.id} não gravado: faltou ${m.missing.join(', ')}. Rode o installer de novo quando tiver a chave, ou adicione com \`claude mcp add\`.`,
+                    );
+                  }
+                  addResult('MCP servers', 'warn', `não gravados por falta de env var: ${missingEnv.map((m) => m.id).join(', ')}`);
+                }
               } catch (error) {
                 await prompts.log.warn(`Falha ao configurar env vars dos MCPs: ${error.message}`);
                 addResult('MCP env vars', 'warn', error.message);

package/tools/installer/modules/env-vars.js

@@ -589,9 +589,50 @@ async function promptMissingEnvVars(mcps, opts = {}) {
   };
 }
 
+/**
+ * Find which of `mcps` have at least one REQUIRED (`hasDefault: false`) env
+ * placeholder that stayed unresolved, per the `skipped` list returned by
+ * `promptMissingEnvVars`/`resolveEnvVars`. A var WITH a default
+ * (`hasDefault: true`) is fine even when skipped — the Claude Code runtime
+ * resolves `${VAR:-default}` itself — so only `hasDefault: false` entries
+ * count here.
+ *
+ * Writing a server whose required placeholder never resolved to anywhere
+ * (not `process.env`, not `.env`, not the global store, not typed
+ * interactively) would embed a literal, permanently-broken `${VAR}` into
+ * `.mcp.json`: the server sits in the config but can never actually start.
+ * Callers use this to drop such a server from the write instead. Pure: no
+ * I/O.
+ *
+ * @param {Array<{id: string}>} mcps - Resolved MCP entries to check
+ * @param {Array<{name: string, mcpIds: string[], hasDefault: boolean}>} [skipped]
+ *   - The `skipped` array from `promptMissingEnvVars`/`resolveEnvVars`
+ * @returns {Array<{id: string, missing: string[]}>} One entry per affected
+ *   MCP id, with the names of its unresolved required vars (in encounter order)
+ */
+function mcpsWithMissingRequiredEnv(mcps, skipped) {
+  const missingByMcpId = new Map();
+  for (const entry of skipped || []) {
+    if (!entry || entry.hasDefault) continue;
+    for (const id of entry.mcpIds || []) {
+      if (!missingByMcpId.has(id)) missingByMcpId.set(id, []);
+      missingByMcpId.get(id).push(entry.name);
+    }
+  }
+
+  const result = [];
+  for (const mcp of mcps || []) {
+    if (mcp && mcp.id && missingByMcpId.has(mcp.id)) {
+      result.push({ id: mcp.id, missing: missingByMcpId.get(mcp.id) });
+    }
+  }
+  return result;
+}
+
 module.exports = {
   extractEnvPlaceholders,
   resolveEnvVars,
+  mcpsWithMissingRequiredEnv,
   persistEnvValues,
   persistProjectEnv,
   persistGlobalEnv,

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

@@ -326,25 +326,101 @@ async function partitionAlreadyConfigured({ projectDir, mcps }) {
   return { toPrepare, alreadyConfigured };
 }
 
+/**
+ * Resolve the set of MCP ids covered by an installed Claude Code plugin
+ * (`~/.claude/plugins/installed_plugins.json`). A plugin key in that file's
+ * `plugins` map is `<name>@<marketplace>` (e.g.
+ * `supabase@claude-plugins-official`); the plugin covers catalog MCP id
+ * `<name>`. If the plugin ships its own `.mcp.json`
+ * (`<installPath>/.mcp.json`, `installPath` from the plugin's install
+ * record) with an `mcpServers` block, every key in that block is ALSO
+ * covered (e.g. the `vercel` plugin ships a server named `vercel`).
+ *
+ * Read failures at the top level (missing/malformed
+ * `installed_plugins.json`) fall back to "nothing covered", same spirit as
+ * the `~/.claude.json` handling in `partitionGloballyConfigured`. A failure
+ * reading ONE plugin's own `.mcp.json` (missing `installPath`, missing
+ * file, malformed JSON) only skips that plugin's extra ids — the plugin's
+ * own name stays covered, since that didn't require reading anything past
+ * the already-parsed top-level file.
+ *
+ * @param {string} [installedPluginsPath] - Override of
+ *   `~/.claude/plugins/installed_plugins.json` (tests)
+ * @returns {Promise<Set<string>>}
+ */
+async function resolvePluginCoveredIds(installedPluginsPath) {
+  const file = installedPluginsPath || path.join(os.homedir(), '.claude', 'plugins', 'installed_plugins.json');
+  const ids = new Set();
+
+  if (!(await fs.pathExists(file))) return ids;
+
+  let data;
+  try {
+    data = JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch {
+    return ids;
+  }
+
+  const plugins = data && typeof data === 'object' && data.plugins && typeof data.plugins === 'object' ? data.plugins : null;
+  if (!plugins) return ids;
+
+  for (const [key, entries] of Object.entries(plugins)) {
+    const name = String(key).split('@')[0];
+    if (name) ids.add(name);
+
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      const installPath = entry && entry.installPath;
+      if (!installPath || typeof installPath !== 'string') continue;
+
+      const mcpJsonPath = path.join(installPath, '.mcp.json');
+      try {
+        if (!(await fs.pathExists(mcpJsonPath))) continue;
+        const mcpConfig = JSON.parse(await fs.readFile(mcpJsonPath, 'utf8'));
+        const servers =
+          mcpConfig && typeof mcpConfig === 'object' && mcpConfig.mcpServers && !Array.isArray(mcpConfig.mcpServers)
+            ? mcpConfig.mcpServers
+            : null;
+        if (servers) {
+          for (const serverKey of Object.keys(servers)) ids.add(serverKey);
+        }
+      } catch {
+        // Malformed/unreadable plugin .mcp.json: skip its extra ids, the
+        // plugin's own name (added above) stays covered.
+      }
+    }
+  }
+
+  return ids;
+}
+
 /**
  * Split resolved MCP entries into those still worth offering/installing in
- * the project and those the user already configured GLOBALLY (user scope, the
- * `mcpServers` key of `~/.claude.json`). A server configured there is live in
- * every project already — usually with the real key embedded — so writing the
- * registry's `${VAR}`-placeholder copy into the project `.mcp.json` would at
- * best duplicate it and at worst shadow a working global config with a broken
- * placeholder one, then prompt the user for a key they already provided.
+ * the project and those the user already has covered elsewhere: configured
+ * GLOBALLY (user scope, the `mcpServers` key of `~/.claude.json`), or
+ * covered by an installed Claude Code PLUGIN
+ * (`~/.claude/plugins/installed_plugins.json`, see
+ * `resolvePluginCoveredIds`). Either way, the server is already live —
+ * usually with the real key embedded — so writing the registry's
+ * `${VAR}`-placeholder copy into the project `.mcp.json` would at best
+ * duplicate it and at worst shadow a working config with a broken
+ * placeholder one, then prompt the user for a key they already have.
  *
- * Read failures (missing/malformed `~/.claude.json`) fall back to "nothing is
- * global", the safe default: worst case the user sees the old behavior.
+ * Read failures (missing/malformed `~/.claude.json` or
+ * `installed_plugins.json`) fall back to "nothing is global"/"nothing is
+ * plugin-covered", the safe default: worst case the user sees the old
+ * behavior. An id present in BOTH sources is reported once, in
+ * `globallyConfigured` only (never duplicated into `pluginCovered`).
  *
  * @param {Object} args
  * @param {Array<{id: string}>} args.mcps - Resolved MCP entries to partition
  * @param {string} [args.claudeJsonPath] - Override of `~/.claude.json` (tests)
- * @returns {Promise<{toInstall: Array<Object>, globallyConfigured: string[]}>}
+ * @param {string} [args.installedPluginsPath] - Override of
+ *   `~/.claude/plugins/installed_plugins.json` (tests)
+ * @returns {Promise<{toInstall: Array<Object>, globallyConfigured: string[], pluginCovered: string[]}>}
  */
-async function partitionGloballyConfigured({ mcps, claudeJsonPath }) {
-  if (!mcps || mcps.length === 0) return { toInstall: [], globallyConfigured: [] };
+async function partitionGloballyConfigured({ mcps, claudeJsonPath, installedPluginsPath }) {
+  if (!mcps || mcps.length === 0) return { toInstall: [], globallyConfigured: [], pluginCovered: [] };
 
   const file = claudeJsonPath || path.join(os.homedir(), '.claude.json');
   let globalIds = new Set();
@@ -359,13 +435,21 @@ async function partitionGloballyConfigured({ mcps, claudeJsonPath }) {
     }
   }
 
+  const pluginIds = await resolvePluginCoveredIds(installedPluginsPath);
+
   const toInstall = [];
   const globallyConfigured = [];
+  const pluginCovered = [];
   for (const mcp of mcps) {
-    if (mcp && mcp.id && globalIds.has(mcp.id)) globallyConfigured.push(mcp.id);
-    else toInstall.push(mcp);
+    if (mcp && mcp.id && globalIds.has(mcp.id)) {
+      globallyConfigured.push(mcp.id);
+    } else if (mcp && mcp.id && pluginIds.has(mcp.id)) {
+      pluginCovered.push(mcp.id);
+    } else {
+      toInstall.push(mcp);
+    }
   }
-  return { toInstall, globallyConfigured };
+  return { toInstall, globallyConfigured, pluginCovered };
 }
 
 /**

package/tools/installer/ui.js

@@ -629,9 +629,14 @@ class UI {
     // duplicate config and re-prompt for a key that already works. Filter it
     // out of every path below (multiselect, --mcps, --yes) with an info line
     // so nothing disappears silently.
-    const { toInstall, globallyConfigured } = await partitionGloballyConfigured({ mcps: resolved });
+    const { toInstall, globallyConfigured, pluginCovered } = await partitionGloballyConfigured({ mcps: resolved });
     if (globallyConfigured.length > 0) {
       await prompts.log.info(`MCPs já configurados no seu Claude global (~/.claude.json), pulados: ${globallyConfigured.join(', ')}`);
+    }
+    if (pluginCovered.length > 0) {
+      await prompts.log.info(`MCPs já cobertos por plugin do Claude Code (user scope), pulados: ${pluginCovered.join(', ')}`);
+    }
+    if (globallyConfigured.length > 0 || pluginCovered.length > 0) {
       resolved = toInstall;
       if (resolved.length === 0) return { toWrite: [], toRecommend: [] };
     }