wizz-method 2.0.0 → 2.1.0

package/tools/installer/modules/external-manager.js

@@ -1,7 +1,7 @@
 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 yaml = require('yaml');
 const prompts = require('../prompts');
 const { resolveChannel, tagExists, parseGitHubRepo } = require('./channel-resolver');
@@ -10,37 +10,20 @@ const { getProjectRoot } = require('../project-root');
 
 const VALID_CHANNELS = new Set(['stable', 'next', 'pinned']);
 
-// Retry pontual (1 re-tentativa, backoff curto) para `git clone`/`git fetch`.
-// Para comandos de shell não temos código de erro estruturado como em
-// requisições HTTP; classificamos como transitório por padrões conhecidos na
-// mensagem/stderr do git. Erro lógico (repo/tag inexistente, permissão
-// negada etc.) não bate nesses padrões e propaga direto, sem retry.
-const GIT_RETRY_DELAY_MS = 300;
-const TRANSIENT_GIT_ERROR_PATTERNS = [/could not resolve host/i, /timed out/i, /early eof/i, /connection reset/i];
-
-function isTransientGitError(error) {
-  const message = `${error?.message || ''}\n${error?.stderr?.toString?.() || ''}`;
-  return TRANSIENT_GIT_ERROR_PATTERNS.some((pattern) => pattern.test(message));
-}
-
-// Sleep síncrono curto (execSync é bloqueante; não há await aqui). Usa
-// Atomics.wait sobre um buffer compartilhado, sem depender de `sleep` de shell.
-function blockingDelay(ms) {
-  const sharedBuffer = new Int32Array(new SharedArrayBuffer(4));
-  Atomics.wait(sharedBuffer, 0, 0, ms);
-}
-
-// Wrapper de execSync com 1 re-tentativa em falha transitória de rede
-// (ver isTransientGitError). Erro não-transitório propaga direto.
-function execSyncWithRetry(command, options) {
-  try {
-    return execSync(command, options);
-  } catch (error) {
-    if (!isTransientGitError(error)) throw error;
-    blockingDelay(GIT_RETRY_DELAY_MS);
-    return execSync(command, options);
-  }
-}
+// Timeouts, retry e classificação transitória (ACH-01/EXT-01) moram em
+// git-cache-utils.js (item 20, etapa 1 da auditoria de 2026-09-11) — uma
+// fonte única compartilhada com custom-module-manager.js. Re-exportados daqui
+// para callers/testes que já importavam de external-manager.
+const {
+  GIT_NETWORK_TIMEOUT_MS,
+  GIT_LOCAL_TIMEOUT_MS,
+  NPM_INSTALL_TIMEOUT_MS,
+  isTimeoutKillError,
+  describeGitTimeout,
+  isTransientGitError,
+  execSyncWithRetry,
+  validateGitRef: validateShellRef,
+} = require('./git-cache-utils');
 
 function normalizeChannelName(raw) {
   if (typeof raw !== 'string') return null;
@@ -48,17 +31,11 @@ function normalizeChannelName(raw) {
   return VALID_CHANNELS.has(lower) ? lower : null;
 }
 
-/**
- * Conservative quoting for tag names passed to git commands. Tags are
- * user-typed (--pin) or come from the GitHub API. Only allow the semver
- * character class we use to tag Wizz releases; anything else throws.
- */
-function quoteShell(ref) {
-  if (typeof ref !== 'string' || !/^[\w.\-+/]+$/.test(ref)) {
-    throw new Error(`Unsafe ref name: ${JSON.stringify(ref)}`);
-  }
-  return `"${ref}"`;
-}
+// Item 8b (auditoria 2026-09-11): the TAG@SHA split + validation lives in
+// pin-spec.js, shared with custom-module-manager.js (item 8c) and surfaced at
+// the CLI gate by channel-plan.js — one format, one error message, three
+// consumers. Re-exported here for existing callers/tests.
+const { parsePinTagAndSha } = require('./pin-spec');
 
 async function readChannelMarker(markerPath) {
   try {
@@ -303,6 +280,18 @@ class ExternalModuleManager {
       registryDefault: moduleInfo.defaultChannel,
     });
 
+    // Item 8 fase 2 (auditoria 2026-09-11, EXT-02 / IM-ACH-06): --pin
+    // CODE=TAG@SHA. channel-plan.js only knows CODE=<opaque value>, so the
+    // TAG@SHA split (and its validation) happens here, before anything else
+    // in this function reads `planEntry.pin` as a git ref. From this point
+    // on `planEntry.pin` is always a plain tag name.
+    let expectedPinSha = null;
+    if (planEntry.channel === 'pinned' && planEntry.pin) {
+      const parsedPin = parsePinTagAndSha(planEntry.pin);
+      planEntry.pin = parsedPin.tag;
+      expectedPinSha = parsedPin.expectedSha;
+    }
+
     // Same-plan short-circuit: a single install calls cloneExternalModule
     // several times (config collection, directory setup, help-catalog rebuild)
     // with the same channelOptions. The first call resolves + clones; later
@@ -311,7 +300,8 @@ class ExternalModuleManager {
     // on flaky networks even though the tagCache dedupes the GitHub API hit).
     if (existingResolution && haveUsableCache && existingResolution.channel === planEntry.channel) {
       const samePin = planEntry.channel !== 'pinned' || existingResolution.version === planEntry.pin;
-      if (samePin) return moduleCacheDir;
+      const sameExpectedSha = planEntry.channel !== 'pinned' || (existingResolution.expectedSha || null) === expectedPinSha;
+      if (samePin && sameExpectedSha) return moduleCacheDir;
     }
 
     let resolved;
@@ -399,33 +389,56 @@ class ExternalModuleManager {
       const fetchSpinner = await createSpinner();
       fetchSpinner.start(`Fetching ${moduleInfo.name}...`);
       try {
-        const currentSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+        const currentSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+          cwd: moduleCacheDir,
+          stdio: 'pipe',
+          timeout: GIT_LOCAL_TIMEOUT_MS,
+          killSignal: 'SIGKILL',
+        })
+          .toString()
+          .trim();
 
         if (resolved.channel === 'next') {
-          execSyncWithRetry('git fetch origin --depth 1', {
+          execSyncWithRetry('git', ['fetch', 'origin', '--depth', '1'], {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            timeout: GIT_NETWORK_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
-          execSync('git reset --hard origin/HEAD', {
+          execFileSync('git', ['reset', '--hard', 'origin/HEAD'], {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            timeout: GIT_LOCAL_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
         } else {
           // stable or pinned — fetch the specific tag and check it out.
-          execSyncWithRetry(`git fetch --depth 1 origin tag ${quoteShell(resolved.ref)} --no-tags`, {
+          validateShellRef(resolved.ref);
+          execSyncWithRetry('git', ['fetch', '--depth', '1', 'origin', 'tag', resolved.ref, '--no-tags'], {
             cwd: moduleCacheDir,
             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: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: GIT_LOCAL_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
         }
 
-        const newSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+        const newSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+          cwd: moduleCacheDir,
+          stdio: 'pipe',
+          timeout: GIT_LOCAL_TIMEOUT_MS,
+          killSignal: 'SIGKILL',
+        })
+          .toString()
+          .trim();
         fetchSpinner.stop(`Fetched ${moduleInfo.name}`);
         if (currentSha !== newSha) needsDependencyInstall = true;
       } catch {
@@ -442,35 +455,79 @@ class ExternalModuleManager {
       fetchSpinner.start(`Fetching ${moduleInfo.name}...`);
       try {
         if (resolved.channel === 'next') {
-          execSyncWithRetry(`git clone --depth 1 "${moduleInfo.url}" "${moduleCacheDir}"`, {
+          execSyncWithRetry('git', ['clone', '--depth', '1', moduleInfo.url, moduleCacheDir], {
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            timeout: GIT_NETWORK_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
         } else {
-          execSyncWithRetry(`git clone --depth 1 --branch ${quoteShell(resolved.ref)} "${moduleInfo.url}" "${moduleCacheDir}"`, {
+          validateShellRef(resolved.ref);
+          execSyncWithRetry('git', ['clone', '--depth', '1', '--branch', resolved.ref, moduleInfo.url, moduleCacheDir], {
             stdio: ['ignore', 'pipe', 'pipe'],
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            timeout: GIT_NETWORK_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
         }
         fetchSpinner.stop(`Fetched ${moduleInfo.name}`);
       } catch (error) {
         fetchSpinner.error(`Failed to fetch ${moduleInfo.name}`);
-        throw new Error(`Failed to clone external module '${moduleCode}' at ${resolved.version}: ${error.message}`);
+        throw new Error(
+          `Failed to clone external module '${moduleCode}' at ${resolved.version}: ${error.message}${describeGitTimeout(error)}`,
+        );
       }
     }
 
     // Record resolution (channel + tag + SHA) for the manifest writer to pick up.
-    const sha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+    const sha = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: moduleCacheDir,
+      stdio: 'pipe',
+      timeout: GIT_LOCAL_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
+    })
+      .toString()
+      .trim();
+
+    // Item 8 fase 2 (auditoria 2026-09-11, EXT-02 / IM-ACH-06): with --pin
+    // CODE=TAG@SHA, 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 we record any resolution/marker
+    // a later run would trust, and it must never be retried as transient
+    // (compare isTransientGitError / isTimeoutKillError above, neither of
+    // which this error matches). On mismatch we remove the whole cache dir
+    // rather than leave a "cloned fine but at the wrong commit" checkout
+    // sitting there indistinguishable from a good one on the next run — the
+    // simplest safe option, and the same posture as the corrupted-cache
+    // cleanup earlier in this function (fetch-failed / EXT-03 branch above).
+    //
+    // Bug 3 (review da fase 3, 2026-09-11): strict equality, not a prefix
+    // compare — expectedSha is always the full 40-hex SHA (parsePinTagAndSha
+    // rejects anything shorter) and `sha` here is always a full 40-hex SHA.
+    if (expectedPinSha && sha.toLowerCase() !== expectedPinSha) {
+      await fs.remove(moduleCacheDir);
+      throw new Error(
+        `Tag '${planEntry.pin}' aponta para o SHA ${sha}, esperado ${expectedPinSha} (--pin ${moduleCode}=${planEntry.pin}@${expectedPinSha}); a tag pode ter sido movida no repositório remoto.`,
+      );
+    }
+
     ExternalModuleManager._resolutions.set(moduleCode, {
       channel: resolved.channel,
       version: resolved.version,
       ref: resolved.ref,
       sha,
+      expectedSha: expectedPinSha,
       repoUrl: moduleInfo.url,
       resolvedFallback: !!resolved.resolvedFallback,
       planSource: planEntry.source,
     });
-    await writeChannelMarker(markerPath, { channel: resolved.channel, version: resolved.version, sha });
+    await writeChannelMarker(markerPath, {
+      channel: resolved.channel,
+      version: resolved.version,
+      sha,
+      expectedSha: expectedPinSha,
+    });
 
     // Install dependencies if package.json exists
     const packageJsonPath = path.join(moduleCacheDir, 'package.json');
@@ -484,10 +541,13 @@ class ExternalModuleManager {
         const installSpinner = await createSpinner();
         installSpinner.start(`Installing dependencies for ${moduleInfo.name}...`);
         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: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            timeout: 120_000, // 2 minute timeout
+            timeout: NPM_INSTALL_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
           });
           installSpinner.stop(`Installed dependencies for ${moduleInfo.name}`);
         } catch (error) {
@@ -510,10 +570,13 @@ class ExternalModuleManager {
           const installSpinner = await createSpinner();
           installSpinner.start(`Installing dependencies for ${moduleInfo.name}...`);
           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: moduleCacheDir,
               stdio: ['ignore', 'pipe', 'pipe'],
-              timeout: 120_000, // 2 minute timeout
+              timeout: NPM_INSTALL_TIMEOUT_MS,
+              killSignal: 'SIGKILL',
             });
             installSpinner.stop(`Installed dependencies for ${moduleInfo.name}`);
           } catch (error) {
@@ -696,4 +759,14 @@ class ExternalModuleManager {
   cachedModules = null;
 }
 
-module.exports = { ExternalModuleManager, isTransientGitError, execSyncWithRetry };
+module.exports = {
+  ExternalModuleManager,
+  isTransientGitError,
+  execSyncWithRetry,
+  isTimeoutKillError,
+  describeGitTimeout,
+  GIT_NETWORK_TIMEOUT_MS,
+  GIT_LOCAL_TIMEOUT_MS,
+  NPM_INSTALL_TIMEOUT_MS,
+  parsePinTagAndSha,
+};

package/tools/installer/modules/git-cache-utils.js

@@ -0,0 +1,125 @@
+/**
+ * Shared primitives for the two git downloaders (external-manager.js and
+ * custom-module-manager.js) — item 20, etapa 1 (auditoria 2026-09-11).
+ *
+ * This module owns:
+ *   - the ACH-01/EXT-01 timeout constants and the WIZZ_GIT_TIMEOUT_MS override
+ *   - transient-error classification + `execSyncWithRetry` (1 re-tentativa)
+ *   - the defensive ref-shape check (was duplicated as `validateShellRef` in
+ *     external-manager.js and `validateCustomRef` in custom-module-manager.js)
+ *
+ * Policy-level decisions (channels, pins, cache layout, marker files) stay in
+ * each manager — this file deliberately knows nothing about them.
+ *
+ * `execFileSync` blocks Node's main thread with no built-in ceiling: a host
+ * that accepts the TCP connection and never responds (no RST — a network
+ * black hole) hangs the installer forever, with no message and no way out
+ * short of the user killing the process. Every git/npm `execFileSync` call in
+ * both managers must pass an explicit `timeout` (+ `killSignal: 'SIGKILL'`,
+ * since git can ignore SIGTERM while blocked on a syscall). `WIZZ_GIT_TIMEOUT_MS`
+ * lets a user on a slow/high-latency network raise the git timeouts without
+ * touching source; npm install's timeout is fixed — dependency install time
+ * is bounded by package.json, not by the network path to a single git remote,
+ * so it isn't part of the same override.
+ */
+
+const { execFileSync } = require('node:child_process');
+
+function parseGitTimeoutOverride() {
+  const raw = process.env.WIZZ_GIT_TIMEOUT_MS;
+  if (raw === undefined || raw === '') return null;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+const GIT_TIMEOUT_OVERRIDE_MS = parseGitTimeoutOverride();
+// Network git ops: clone / fetch.
+const GIT_NETWORK_TIMEOUT_MS = GIT_TIMEOUT_OVERRIDE_MS ?? 120_000;
+// Local git ops: rev-parse, symbolic-ref, checkout, reset. No network
+// round-trip, but still shelled out via execFileSync, so still needs a
+// ceiling (a corrupted/locked local repo can hang git indefinitely too).
+const GIT_LOCAL_TIMEOUT_MS = GIT_TIMEOUT_OVERRIDE_MS ?? 30_000;
+// npm install for a module's own dependencies. Not affected by WIZZ_GIT_TIMEOUT_MS.
+const NPM_INSTALL_TIMEOUT_MS = 300_000;
+
+/**
+ * True when an execFileSync error is our own timeout kill: Node reports this
+ * via `error.killed`/`error.signal`, not through stdout/stderr text, so the
+ * message-pattern checks below never see it.
+ */
+function isTimeoutKillError(error) {
+  return !!(error && (error.killed === true || error.signal));
+}
+
+/**
+ * PT-BR hint appended to a final thrown/logged error when a git call timed
+ * out, pointing the user at the override env var.
+ */
+function describeGitTimeout(error) {
+  if (!isTimeoutKillError(error)) return '';
+  return ` O comando git estourou o tempo limite (${error.signal || 'timeout'}). Se sua rede é lenta, ajuste com a variável de ambiente WIZZ_GIT_TIMEOUT_MS (em milissegundos).`;
+}
+
+// Retry pontual (1 re-tentativa, backoff curto) para `git clone`/`git fetch`.
+// Para comandos de shell não temos código de erro estruturado como em
+// requisições HTTP; classificamos como transitório por padrões conhecidos na
+// mensagem/stderr do git, OU por ter sido morto pelo nosso próprio `timeout`
+// (error.killed/error.signal — ver isTimeoutKillError). Erro lógico (repo/tag
+// inexistente, permissão negada etc.) não bate em nenhum dos dois e propaga
+// direto, sem retry.
+const GIT_RETRY_DELAY_MS = 300;
+const TRANSIENT_GIT_ERROR_PATTERNS = [/could not resolve host/i, /timed out/i, /early eof/i, /connection reset/i];
+
+function isTransientGitError(error) {
+  if (isTimeoutKillError(error)) return true;
+  const message = `${error?.message || ''}\n${error?.stderr?.toString?.() || ''}`;
+  return TRANSIENT_GIT_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+}
+
+// Sleep síncrono curto (execSync é bloqueante; não há await aqui). Usa
+// Atomics.wait sobre um buffer compartilhado, sem depender de `sleep` de shell.
+function blockingDelay(ms) {
+  const sharedBuffer = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(sharedBuffer, 0, 0, ms);
+}
+
+// Wrapper de execFileSync com 1 re-tentativa em falha transitória de rede
+// (ver isTransientGitError). Erro não-transitório propaga direto.
+// Assinatura (file, args, options) — array de argumentos, nunca uma string
+// de shell — para que nenhum call site precise (nem consiga) interpolar URL
+// ou ref não sanitizada dentro de um comando de shell (ver EXT-09).
+function execSyncWithRetry(file, args, options) {
+  try {
+    return execFileSync(file, args, options);
+  } catch (error) {
+    if (!isTransientGitError(error)) throw error;
+    blockingDelay(GIT_RETRY_DELAY_MS);
+    return execFileSync(file, args, options);
+  }
+}
+
+/**
+ * Conservative validation for tag/branch names passed to git commands. Refs
+ * are user-typed (--pin, --next, version from a /tree/ URL) or come from the
+ * GitHub API. Refs reach `execFileSync('git', [...])` as a single argv
+ * element (no shell), so this isn't shell-quoting anymore — it's a defensive
+ * shape check so a malformed ref fails loudly instead of confusing `git`.
+ */
+function validateGitRef(ref) {
+  // Ref que começa com '-' viraria opção do git (ex.: --upload-pack): rejeitar.
+  if (typeof ref !== 'string' || ref.startsWith('-') || !/^[\w.\-+/]+$/.test(ref)) {
+    throw new Error(`Unsafe ref name: ${JSON.stringify(ref)}`);
+  }
+  return ref;
+}
+
+module.exports = {
+  GIT_NETWORK_TIMEOUT_MS,
+  GIT_LOCAL_TIMEOUT_MS,
+  NPM_INSTALL_TIMEOUT_MS,
+  isTimeoutKillError,
+  describeGitTimeout,
+  isTransientGitError,
+  execSyncWithRetry,
+  validateGitRef,
+};