wizz-method 2.0.0 → 2.1.0

package/tools/installer/modules/custom-module-manager.js

@@ -1,14 +1,49 @@
 const fs = require('../fs-native');
 const os = require('node:os');
 const path = require('node:path');
-const { execSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
 const prompts = require('../prompts');
+// Timeout constants + timeout-aware helpers (ACH-01/EXT-01, auditoria
+// 2026-09-11) agora vivem em git-cache-utils.js (item 20, etapa 1) — uma
+// fonte única compartilhada com external-manager.js, que ainda re-exporta os
+// mesmos símbolos para callers/testes antigos.
+const {
+  GIT_NETWORK_TIMEOUT_MS,
+  GIT_LOCAL_TIMEOUT_MS,
+  NPM_INSTALL_TIMEOUT_MS,
+  describeGitTimeout,
+  validateGitRef: validateCustomRef,
+} = require('./git-cache-utils');
+// Item 8c (auditoria 2026-09-11): TAG@SHA pins for custom modules. The parse
+// lives in pin-spec.js, shared with external-manager.js and surfaced at the
+// CLI gate by channel-plan.js, so all three paths agree on format + errors.
+const { parsePinTagAndSha, resolvePinOverride, buildPinMismatchError } = require('./pin-spec');
+
+// validateCustomRef (forma defensiva de ref) agora é validateGitRef em
+// git-cache-utils.js, importado acima com o rótulo antigo preservado.
+
+// RFC-1123 hostname: labels of letters/digits/hyphen (no leading/trailing
+// hyphen), joined by dots.
+const SSH_HOST_RE = /^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*$/;
+// Owner/repo path segments: letters, digits, dot, underscore, hyphen only.
+const SSH_PATH_SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
 
-function quoteCustomRef(ref) {
-  if (typeof ref !== 'string' || !/^[\w.\-+/]+$/.test(ref)) {
-    throw new Error(`Unsafe ref name: ${JSON.stringify(ref)}`);
-  }
-  return `"${ref}"`;
+/**
+ * Validate the host/owner/repo captured from a `git@host:owner/repo` SSH URL
+ * match. The regex that captures these groups is intentionally permissive
+ * (it must accept any self-hosted Git host), so this is the layer that
+ * rejects shell metacharacters (quotes, backticks, `$()`, `;`, spaces, etc.)
+ * before the value is ever handed to `git`.
+ * @param {string} host
+ * @param {string} owner - May contain `/` for nested groups (GitLab subgroups).
+ * @param {string} repo
+ * @returns {boolean}
+ */
+function isValidSshRepoParts(host, owner, repo) {
+  if (!SSH_HOST_RE.test(host)) return false;
+  if (!repo || !SSH_PATH_SEGMENT_RE.test(repo)) return false;
+  const ownerSegments = owner.split('/');
+  return ownerSegments.length > 0 && ownerSegments.every((segment) => SSH_PATH_SEGMENT_RE.test(segment));
 }
 
 /**
@@ -118,6 +153,13 @@ class CustomModuleManager {
     const sshMatch = trimmed.match(/^git@([^:]+):(.+?)\/([^/.]+?)(?:\.git)?$/);
     if (sshMatch) {
       const [, host, owner, repo] = sshMatch;
+      if (!isValidSshRepoParts(host, owner, repo)) {
+        throw new Error(
+          `URL SSH inválida: "${trimmedRaw}". O host, o owner e o nome do repositório só podem conter letras, ` +
+            'números, ponto, hífen, underscore e barra (para subgrupos). Verifique se não há aspas, crase, `$()`, ' +
+            '`;` ou espaços na URL.',
+        );
+      }
       return {
         type: 'url',
         cloneUrl: trimmed,
@@ -376,12 +418,19 @@ class CustomModuleManager {
     const silent = options.silent || false;
     const displayName = parsed.displayName;
 
-    // Pin override: --pin CODE=TAG resolved at module-selection time overrides
-    // any @version suffix present in the URL.
-    const effectiveVersion = options.pinOverride || parsed.version || null;
+    // Pin override (bug 8: keyed by displayName — see resolvePinOverride's JSDoc in pin-spec.js) beats any @version suffix in the URL. May be TAG@40-hex-sha — split below; verified against HEAD further down.
+    let effectiveVersion = resolvePinOverride(options, parsed.displayName) || parsed.version || null;
+    let expectedPinSha = null;
+    if (effectiveVersion && effectiveVersion.includes('@')) {
+      const parsedPin = parsePinTagAndSha(effectiveVersion);
+      effectiveVersion = parsedPin.tag;
+      expectedPinSha = parsedPin.expectedSha;
+    }
 
     await fs.ensureDir(path.dirname(repoCacheDir));
 
+    let fetchFailed = false; // Bug 4: set on fetch failure below; read by buildPinMismatchError further down.
+
     const createSpinner = async () => {
       if (silent) {
         return { start() {}, stop() {}, error() {} };
@@ -393,12 +442,30 @@ class CustomModuleManager {
     // Tracked via .wizz-source.json's recorded version.
     if (await fs.pathExists(repoCacheDir)) {
       let cachedVersion = null;
+      let cachedSha = null;
+      let cachedExpectedSha = null;
       try {
         const existing = await fs.readJson(path.join(repoCacheDir, '.wizz-source.json'));
         cachedVersion = existing?.version || null;
+        cachedSha = existing?.sha || null;
+        cachedExpectedSha = existing?.expectedSha || null;
       } catch {
         // no metadata; treat as mismatched to be safe if a version was requested
       }
+      // Item 8c: a TAG@SHA pin whose cache was already verified at this exact
+      // commit needs no refresh — fetching would only risk pulling a remotely
+      // moved tag over a known-good checkout. Same tag under a different
+      // expectedSha falls through to the fetch + post-clone check below.
+      if (
+        expectedPinSha &&
+        (cachedVersion || null) === (effectiveVersion || null) &&
+        cachedSha &&
+        cachedExpectedSha &&
+        cachedSha.toLowerCase() === cachedExpectedSha &&
+        cachedExpectedSha === expectedPinSha
+      ) {
+        return repoCacheDir;
+      }
       if ((effectiveVersion || null) !== (cachedVersion || null)) {
         await fs.remove(repoCacheDir);
       }
@@ -409,23 +476,30 @@ class CustomModuleManager {
       const fetchSpinner = await createSpinner();
       fetchSpinner.start(`Updating ${displayName}...`);
       try {
-        execSync('git fetch origin --depth 1', {
+        execFileSync('git', ['fetch', 'origin', '--depth', '1'], {
           cwd: repoCacheDir,
           stdio: ['ignore', 'pipe', 'pipe'],
           env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          timeout: GIT_NETWORK_TIMEOUT_MS,
+          killSignal: 'SIGKILL',
         });
         if (effectiveVersion) {
           // Fetch the ref as either a tag or a branch — `origin <ref>` works
           // for both, whereas `origin tag <ref>` fails for branch refs parsed
           // out of /tree/<branch>/... URLs.
-          execSync(`git fetch --depth 1 origin ${quoteCustomRef(effectiveVersion)} --no-tags`, {
+          validateCustomRef(effectiveVersion);
+          execFileSync('git', ['fetch', '--depth', '1', 'origin', effectiveVersion, '--no-tags'], {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            timeout: GIT_NETWORK_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
-          execSync(`git checkout --quiet FETCH_HEAD`, {
+          execFileSync('git', ['checkout', '--quiet', 'FETCH_HEAD'], {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: GIT_LOCAL_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
         } else {
           // Resolve the default branch (origin/HEAD) and fetch it explicitly.
@@ -433,9 +507,11 @@ class CustomModuleManager {
           // origin/HEAD` never picks up new commits on the default branch.
           let defaultBranch = 'main';
           try {
-            defaultBranch = execSync('git symbolic-ref refs/remotes/origin/HEAD --short', {
+            defaultBranch = execFileSync('git', ['symbolic-ref', 'refs/remotes/origin/HEAD', '--short'], {
               cwd: repoCacheDir,
               stdio: 'pipe',
+              timeout: GIT_LOCAL_TIMEOUT_MS,
+              killSignal: 'SIGKILL',
             })
               .toString()
               .trim()
@@ -443,24 +519,33 @@ class CustomModuleManager {
           } catch {
             // Fallback if origin/HEAD is not set
           }
-          execSync(`git fetch --depth 1 origin ${quoteCustomRef(defaultBranch)}`, {
+          validateCustomRef(defaultBranch);
+          execFileSync('git', ['fetch', '--depth', '1', 'origin', defaultBranch], {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            timeout: GIT_NETWORK_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
-          execSync(`git reset --hard origin/${quoteCustomRef(defaultBranch)}`, {
+          execFileSync('git', ['reset', '--hard', `origin/${defaultBranch}`], {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: GIT_LOCAL_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
         }
         fetchSpinner.stop(`Updated ${displayName}`);
-      } catch {
+      } catch (error_) {
         // Fetch failed against an existing cache — most often the remote is
-        // unreachable (network down, repo deleted/moved, auth revoked).
-        // Preserve the previous clone so re-deploy still works from cached
-        // content; surface a warning so the user knows the cache is stale.
+        // unreachable (network down, repo deleted/moved, auth revoked), or our
+        // own `timeout` killed a hung git process (ACH-01/EXT-01). Preserve
+        // the previous clone so re-deploy still works from cached content;
+        // surface a warning so the user knows the cache is stale.
+        fetchFailed = true;
         fetchSpinner.error(`Could not refresh ${displayName} — keeping cached copy`);
-        await prompts.log.warn(`Custom module ${displayName} was not refreshed (remote unreachable). Using cached copy.`);
+        await prompts.log.warn(
+          `Custom module ${displayName} was not refreshed (remote unreachable). Using cached copy.${describeGitTimeout(error_)}`,
+        );
       }
     }
 
@@ -469,39 +554,74 @@ class CustomModuleManager {
       fetchSpinner.start(`Cloning ${displayName}${effectiveVersion ? ` @ ${effectiveVersion}` : ''}...`);
       try {
         if (effectiveVersion) {
-          execSync(`git clone --depth 1 --branch ${quoteCustomRef(effectiveVersion)} "${parsed.cloneUrl}" "${repoCacheDir}"`, {
+          validateCustomRef(effectiveVersion);
+          execFileSync('git', ['clone', '--depth', '1', '--branch', effectiveVersion, parsed.cloneUrl, repoCacheDir], {
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            timeout: GIT_NETWORK_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
         } else {
-          execSync(`git clone --depth 1 "${parsed.cloneUrl}" "${repoCacheDir}"`, {
+          execFileSync('git', ['clone', '--depth', '1', parsed.cloneUrl, repoCacheDir], {
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            timeout: GIT_NETWORK_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
         }
         fetchSpinner.stop(`Cloned ${displayName}`);
       } catch (error_) {
         fetchSpinner.error(`Failed to clone ${displayName}`);
         const refSuffix = effectiveVersion ? `@${effectiveVersion}` : '';
-        throw new Error(`Failed to clone ${parsed.cloneUrl}${refSuffix}: ${error_.message}`);
+        throw new Error(`Failed to clone ${parsed.cloneUrl}${refSuffix}: ${error_.message}${describeGitTimeout(error_)}`);
       }
     }
 
     // Record the resolved SHA for the manifest writer.
     let resolvedSha = null;
     try {
-      resolvedSha = execSync('git rev-parse HEAD', { cwd: repoCacheDir, stdio: 'pipe' }).toString().trim();
+      resolvedSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+        cwd: repoCacheDir,
+        stdio: 'pipe',
+        timeout: GIT_LOCAL_TIMEOUT_MS,
+        killSignal: 'SIGKILL',
+      })
+        .toString()
+        .trim();
     } catch {
       // swallow — a non-git repo (local path) wouldn't reach here anyway
     }
+    // Item 8c (auditoria 2026-09-11): with a TAG@SHA pin, verify the commit
+    // we actually checked out matches what was requested. A git tag is a
+    // mutable ref — nothing stops the remote from force-moving it between
+    // installs — so this is a trust check, not a network hiccup: it must run
+    // before any metadata/marker/resolution a later run would trust is
+    // written, and it must never be retried as transient. On mismatch we
+    // remove the whole cache dir rather than leave a "cloned fine but at the
+    // wrong commit" checkout indistinguishable from a good one — same
+    // posture and error text as external-manager.js (item 8 fase 2). Strict equality per bug 3; buildPinMismatchError (pin-spec.js) picks fetch-failed vs. real-mismatch wording per bug 4.
+    if (expectedPinSha && (!resolvedSha || resolvedSha.toLowerCase() !== expectedPinSha)) {
+      await fs.remove(repoCacheDir);
+      const pinDisplay = `${parsed.displayName}=${effectiveVersion}@${expectedPinSha}`;
+      throw buildPinMismatchError({
+        displayName,
+        tag: effectiveVersion,
+        resolvedSha,
+        expectedSha: expectedPinSha,
+        pinDisplay,
+        fetchFailed,
+      });
+    }
     // Best-effort: capture the remote default branch name so channel marker
     // metadata for "next" reflects the actual tracked ref (not always "main").
     let defaultRef = 'main';
     if (!effectiveVersion) {
       try {
-        const symbolic = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
+        const symbolic = execFileSync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], {
           cwd: repoCacheDir,
           stdio: 'pipe',
+          timeout: GIT_LOCAL_TIMEOUT_MS,
+          killSignal: 'SIGKILL',
         })
           .toString()
           .trim();
@@ -530,6 +650,10 @@ class CustomModuleManager {
       version: effectiveVersion || null,
       rawInput: parsed.rawInput || sourceInput,
       sha: resolvedSha,
+      // Item 8c: recorded so a later cloneRepo with the same TAG@SHA pin can
+      // early-return without re-fetching (a fetch could pull a moved tag over
+      // a verified checkout).
+      expectedSha: expectedPinSha || null,
       clonedAt: new Date().toISOString(),
     });
     // Keep a channel marker in custom cache too so update paths that rely on
@@ -539,6 +663,7 @@ class CustomModuleManager {
       channel: effectiveVersion ? 'pinned' : 'next',
       version: effectiveVersion || defaultRef,
       sha: resolvedSha,
+      expectedSha: expectedPinSha || null,
       writtenAt: new Date().toISOString(),
     });
 
@@ -548,10 +673,13 @@ class CustomModuleManager {
       const installSpinner = await createSpinner();
       installSpinner.start(`Installing dependencies for ${displayName}...`);
       try {
-        execSync('npm install --omit=dev --no-audit --no-fund --no-progress --legacy-peer-deps', {
+        execFileSync('npm', ['install', '--omit=dev', '--no-audit', '--no-fund', '--no-progress', '--legacy-peer-deps'], {
+          // npm é npm.cmd no Windows e só roda via shell; os args acima são constantes, sem input do usuário.
+          shell: process.platform === 'win32',
           cwd: repoCacheDir,
           stdio: ['ignore', 'pipe', 'pipe'],
-          timeout: 120_000,
+          timeout: NPM_INSTALL_TIMEOUT_MS,
+          killSignal: 'SIGKILL',
         });
         installSpinner.stop(`Installed dependencies for ${displayName}`);
       } catch (error_) {
@@ -781,7 +909,12 @@ class CustomModuleManager {
       try {
         await this.cloneRepo(metadata.rawInput, {
           silent: true,
-          pinOverride: metadata.version || undefined,
+          // Round-trip both halves of a TAG@SHA pin (item 8c): re-passing only
+          // metadata.version (the plain tag) would drop the expected-SHA trust
+          // check on refresh. metadata.expectedSha is only ever set when the
+          // pin carried it, so plain-version caches are unaffected.
+          pinOverride:
+            metadata.version && metadata.expectedSha ? `${metadata.version}@${metadata.expectedSha}` : metadata.version || undefined,
         });
         CustomModuleManager._refreshedRepoPaths.add(repoPath);
       } catch (error_) {

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

@@ -48,6 +48,113 @@ const os = require('node:os');
 const fs = require('../fs-native');
 const prompts = require('../prompts');
 
+/**
+ * Check if a gitignore line/pattern covers `.claude/settings.local.json`.
+ * Patterns that match:
+ *   - `.claude/settings.local.json` (literal)
+ *   - `settings.local.json` (basename only)
+ *   - `*.local.json` (extension pattern)
+ *   - `.claude/*.local.json` (dir + extension)
+ *   - `.claude/` (entire directory)
+ *   - `.claude` (directory without trailing /)
+ *
+ * @param {string} pattern - A line from .gitignore
+ * @returns {boolean}
+ */
+function patternCoversSettingsLocal(pattern) {
+  if (!pattern || typeof pattern !== 'string') return false;
+  const trimmed = pattern.trim();
+  if (trimmed.startsWith('#') || trimmed === '') return false;
+
+  // Normalize: remove leading/trailing whitespace
+  const normalized = trimmed.trim();
+
+  // Exact literal match
+  if (normalized === '.claude/settings.local.json' || normalized === '.claude/settings.local.json/') {
+    return true;
+  }
+
+  // Basename only
+  if (normalized === 'settings.local.json' || normalized === 'settings.local.json/') {
+    return true;
+  }
+
+  // Extension pattern
+  if (normalized === '*.local.json') {
+    return true;
+  }
+
+  // Directory-scoped extension pattern
+  if (normalized === '.claude/*.local.json') {
+    return true;
+  }
+
+  // Entire .claude directory
+  if (normalized === '.claude/' || normalized === '.claude') {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Verify that `.claude/settings.local.json` is covered by a pattern in
+ * `.gitignore`. If not covered and `.git` exists (repo root), add the line.
+ * Pure function (testable without real filesystem, but performs I/O here for simplicity).
+ *
+ * @param {string} projectRoot - Project root (where `_wizz/`, `.git`, `.gitignore` live)
+ * @returns {Promise<{added: boolean, reason: string}>}
+ *   - `{ added: true, reason: "..." }` if the line was added to .gitignore
+ *   - `{ added: false, reason: "..." }` if already covered, not a git repo, or error
+ */
+async function ensureSettingsLocalIgnored(projectRoot) {
+  if (!projectRoot) {
+    return { added: false, reason: 'projectRoot não fornecido' };
+  }
+
+  const gitDir = path.join(projectRoot, '.git');
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  // Check if this is a git repository
+  const isGitRepo = await fs.pathExists(gitDir);
+  if (!isGitRepo) {
+    return { added: false, reason: 'não é um repositório git' };
+  }
+
+  // Read .gitignore if it exists
+  let content = '';
+  if (await fs.pathExists(gitignorePath)) {
+    try {
+      content = await fs.readFile(gitignorePath, 'utf8');
+    } catch {
+      return { added: false, reason: 'não foi possível ler .gitignore' };
+    }
+  }
+
+  // Check if any line already covers .claude/settings.local.json
+  const lines = content.split('\n');
+  for (const line of lines) {
+    if (patternCoversSettingsLocal(line)) {
+      return { added: false, reason: '.claude/settings.local.json já está no .gitignore' };
+    }
+  }
+
+  // Not covered: add the line (only if .git exists, which we already checked above)
+  try {
+    // Ensure content ends with newline, then append the new line
+    let newContent = content;
+    if (newContent && !newContent.endsWith('\n')) {
+      newContent += '\n';
+    }
+    newContent += '.claude/settings.local.json\n';
+
+    await fs.writeFile(gitignorePath, newContent, 'utf8');
+    return { added: true, reason: 'linha adicionada ao .gitignore' };
+  } catch {
+    return { added: false, reason: 'falha ao escrever em .gitignore' };
+  }
+}
+
 // Global key store, read by the INSTALLER only (never by the Claude Code
 // runtime — C7 still holds). A value found here is copied into the project's
 // `.claude/settings.local.json` at install time, which IS what reaches the
@@ -363,6 +470,16 @@ async function persistProjectEnv(projectDir, envRecord) {
   const file = path.join(claudeDir, 'settings.local.json');
   await fs.ensureDir(claudeDir);
 
+  // Ensure .claude/settings.local.json is in .gitignore before writing secrets
+  const gitignoreCheck = await ensureSettingsLocalIgnored(projectDir);
+  if (gitignoreCheck.added) {
+    await prompts.log.info('.claude/settings.local.json foi adicionado ao .gitignore do projeto (guarda API keys, não deve ir pro git).');
+  } else if (gitignoreCheck.reason === 'não é um repositório git') {
+    await prompts.log.warn(
+      'Este diretório não é um repositório git: garanta que .claude/settings.local.json (API keys) nunca seja versionado.',
+    );
+  }
+
   let settings = {};
   if (await fs.pathExists(file)) {
     try {
@@ -642,4 +759,6 @@ module.exports = {
   createGlobalStoreProvider,
   defaultGlobalEnvPath,
   formatSummary,
+  ensureSettingsLocalIgnored,
+  patternCoversSettingsLocal,
 };