@finch.app/minitools 0.1.6 → 0.1.8

package/bin/minitools.mjs

@@ -2,12 +2,12 @@
 /**
  * @finch.app/minitools — install Finch extensions to the correct location.
  *
- * Zero npm dependencies. npm sources are fetched with `npm install --ignore-scripts`
- * so third-party install scripts never run during CLI install.
+ * Zero npm dependencies. npm sources are installed by downloading the registry
+ * dist.tarball (.tgz) directly, so third-party install scripts never run.
  */
 import {
   existsSync, mkdirSync, readdirSync, cpSync, rmSync,
-  readFileSync, writeFileSync, statSync,
+  readFileSync, writeFileSync,
 } from 'node:fs';
 import { join, resolve, basename } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
@@ -147,63 +147,8 @@ function installExtensionDir(srcDir, destRoot, lockSource) {
   return info.id;
 }
 
-/**
- * Look for an executable on PATH (via `which`/`where`), falling back to a
- * handful of common install locations that don't always make it onto the
- * PATH inherited by a GUI-launched app (Homebrew, nvm, Volta, Windows
- * installer). Returns the resolved path, or null if not found anywhere.
- */
-function findExecutable(name) {
-  const finder = process.platform === 'win32' ? 'where' : 'which';
-  const found = spawnSync(finder, [name], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf-8' });
-  if (found.status === 0) {
-    const first = found.stdout.split(/\r?\n/).map((s) => s.trim()).find(Boolean);
-    if (first) return first;
-  }
-
-  const candidateDirs = process.platform === 'win32'
-    ? [
-        join(process.env.ProgramFiles ?? 'C:\\Program Files', 'nodejs'),
-        join(process.env.APPDATA ?? '', 'npm'),
-      ]
-    : (() => {
-        const dirs = ['/opt/homebrew/bin', '/usr/local/bin', join(homedir(), '.volta', 'bin')];
-        const nvmRoot = join(homedir(), '.nvm', 'versions', 'node');
-        try {
-          for (const version of readdirSync(nvmRoot)) dirs.push(join(nvmRoot, version, 'bin'));
-        } catch { /* nvm not installed */ }
-        return dirs;
-      })();
-  const exeName = process.platform === 'win32' ? `${name}.cmd` : name;
-  for (const dir of candidateDirs) {
-    const candidate = join(dir, exeName);
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-
-const NODEJS_INSTALL_HINT = 'Install Node.js (which bundles npm) from https://nodejs.org, then try again.';
-
-function npmInstallToTemp(spec, tmp) {
-  const npmPath = findExecutable('npm');
-  if (!npmPath) {
-    throw new Error(`This extension is an npm package, but no "npm" executable was found on this machine.\n${NODEJS_INSTALL_HINT}`);
-  }
-  mkdirSync(tmp, { recursive: true });
-  const r = spawnSync(npmPath, ['install', '--ignore-scripts', '--omit=dev', '--prefix', tmp, spec], {
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf-8',
-  });
-  if (r.error) {
-    throw new Error(`Failed to run npm (${npmPath}): ${r.error.message}\n${NODEJS_INSTALL_HINT}`);
-  }
-  if (r.status !== 0) {
-    throw new Error(`npm install failed:\n${r.stderr || r.stdout || `exit code ${r.status}`}`);
-  }
-}
-
 function isLocalSource(src) {
-  return src.startsWith('./') || src.startsWith('../') || src.startsWith('/') || src.startsWith('~');
+  return src.startsWith('./') || src.startsWith('../') || src.startsWith('/') || src.startsWith('~') || /^[a-zA-Z]:[\\/]/.test(src);
 }
 function isZipUrl(src) {
   return /^https?:\/\/.+\.zip(\?.*)?$/i.test(src);
@@ -211,6 +156,13 @@ function isZipUrl(src) {
 function isZipFile(src) {
   return src.toLowerCase().endsWith('.zip');
 }
+function isTgzUrl(src) {
+  return /^https?:\/\/.+\.(?:tgz|tar\.gz)(\?.*)?$/i.test(src);
+}
+function isTgzFile(src) {
+  const lower = src.toLowerCase();
+  return lower.endsWith('.tgz') || lower.endsWith('.tar.gz');
+}
 function expandHome(path) {
   return path.replace(/^~(?=\/|$)/, homedir());
 }
@@ -219,16 +171,32 @@ function expandHome(path) {
  * Download a URL to a local file path using Node's built-in fetch (Node 18+).
  * Falls back to curl/wget if fetch is unavailable.
  */
+function downloadWithSystemTool(url, destPath, fetchError) {
+  const curlExe = process.platform === 'win32' ? 'curl.exe' : 'curl';
+  const curl = spawnSync(curlExe, ['-fL', '--retry', '2', '--connect-timeout', '20', '-o', destPath, url], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+  });
+  if (curl.status === 0 && !curl.error) return;
+  if (process.platform === 'win32') {
+    const ps = spawnSync('powershell.exe', ['-NoProfile', '-Command', 'Invoke-WebRequest -Uri $args[0] -OutFile $args[1]', url, destPath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+    });
+    if (ps.status === 0 && !ps.error) return;
+    throw new Error(`Download failed: ${fetchError?.message ?? fetchError}\n${curl.stderr || curl.stdout || curl.error?.message || 'curl failed'}\n${ps.stderr || ps.stdout || ps.error?.message || 'powershell failed'}`);
+  }
+  throw new Error(`Download failed: ${fetchError?.message ?? fetchError}\n${curl.stderr || curl.stdout || curl.error?.message || 'curl failed'}`);
+}
+
 async function downloadFile(url, destPath) {
-  if (typeof fetch === 'function') {
+  try {
     const res = await fetch(url, { redirect: 'follow' });
-    if (!res.ok) throw new Error(`Download failed: ${res.status} ${res.statusText} — ${url}`);
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
     const buf = Buffer.from(await res.arrayBuffer());
     writeFileSync(destPath, buf);
-  } else {
-    // Fallback: curl (macOS / Linux always has it)
-    const r = spawnSync('curl', ['-fsSL', '-o', destPath, url], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
-    if (r.status !== 0) throw new Error(`curl failed:\n${r.stderr || r.stdout}`);
+  } catch (err) {
+    downloadWithSystemTool(url, destPath, err);
   }
 }
 
@@ -237,6 +205,21 @@ async function downloadFile(url, destPath) {
  */
 function extractZip(zipPath, destDir) {
   mkdirSync(destDir, { recursive: true });
+  if (process.platform === 'win32') {
+    const r = spawnSync('powershell.exe', ['-NoProfile', '-Command', 'Expand-Archive -LiteralPath $args[0] -DestinationPath $args[1] -Force', zipPath, destDir], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+    });
+    if (r.status === 0 && !r.error) return;
+    const tar = spawnSync('tar.exe', ['-xf', zipPath, '-C', destDir], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf-8',
+    });
+    if (tar.status !== 0 || tar.error) {
+      throw new Error(`zip extract failed:\n${r.stderr || tar.stderr || r.stdout || tar.stdout || tar.error?.message || 'unknown error'}`);
+    }
+    return;
+  }
   const r = spawnSync('unzip', ['-q', '-o', zipPath, '-d', destDir], {
     stdio: ['ignore', 'pipe', 'pipe'],
     encoding: 'utf-8',
@@ -247,6 +230,75 @@ function extractZip(zipPath, destDir) {
   if (r.status !== 0) throw new Error(`unzip failed:\n${r.stderr || r.stdout || `exit code ${r.status}`}`);
 }
 
+/**
+ * Extract a .tgz/.tar.gz archive using the system tar command. macOS/Linux ship
+ * it by default; modern Windows includes bsdtar as tar.exe.
+ */
+function extractTgz(tgzPath, destDir) {
+  mkdirSync(destDir, { recursive: true });
+  const tarExe = process.platform === 'win32' ? 'tar.exe' : 'tar';
+  const r = spawnSync(tarExe, ['-xzf', tgzPath, '-C', destDir], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+  });
+  if (r.error) {
+    throw new Error(`No "tar" command found on this machine: ${r.error.message}`);
+  }
+  if (r.status !== 0) throw new Error(`tar extract failed:\n${r.stderr || r.stdout || `exit code ${r.status}`}`);
+}
+
+function parseNpmSpec(spec) {
+  const trimmed = String(spec ?? '').trim();
+  if (!trimmed) throw new Error('missing npm package name');
+  if (trimmed.startsWith('@')) {
+    const versionSep = trimmed.indexOf('@', 1);
+    return versionSep > 0
+      ? { name: trimmed.slice(0, versionSep), version: trimmed.slice(versionSep + 1) || 'latest' }
+      : { name: trimmed, version: 'latest' };
+  }
+  const versionSep = trimmed.lastIndexOf('@');
+  return versionSep > 0
+    ? { name: trimmed.slice(0, versionSep), version: trimmed.slice(versionSep + 1) || 'latest' }
+    : { name: trimmed, version: 'latest' };
+}
+
+let registryOverride = null;
+
+function configuredRegistryUrl() {
+  return (registryOverride || process.env.npm_config_registry || 'https://registry.npmjs.org').replace(/\/+$/, '');
+}
+
+function npmMetadataUrl(packageName, version) {
+  return `${configuredRegistryUrl()}/${encodeURIComponent(packageName)}/${encodeURIComponent(version || 'latest')}`;
+}
+
+function officialMiniToolDownloadUrl(packageName, version) {
+  return `https://community.finchwork.app/download/minitool/${packageName}/${encodeURIComponent(version)}`;
+}
+
+async function resolveNpmTarball(spec) {
+  const { name, version } = parseNpmSpec(spec);
+  const url = npmMetadataUrl(name, version);
+  let meta;
+  try {
+    const res = await fetch(url, { redirect: 'follow' });
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    meta = await res.json();
+  } catch (err) {
+    throw new Error(`npm metadata fetch failed: ${err instanceof Error ? err.message : String(err)} — ${url}`);
+  }
+  const resolvedVersion = String(meta.version ?? version);
+  const tarball = meta?.dist?.tarball;
+  if (typeof tarball !== 'string' || !tarball) {
+    throw new Error(`No dist.tarball found for ${name}@${version}`);
+  }
+  return {
+    package: name,
+    version: resolvedVersion,
+    tarball: officialMiniToolDownloadUrl(name, resolvedVersion),
+  };
+}
+
 /**
  * Install extensions from a zip file (local path or remote URL).
  * The zip may contain one or more extensions at any nesting level.
@@ -279,25 +331,60 @@ async function installFromZip(src, dest, isUrl) {
   }
 }
 
+async function installFromTgz(src, dest, { isUrl, lockSource }) {
+  const tmp = join(tmpdir(), `finch-ext-${randomUUID()}`);
+  const tgzPath = join(tmp, 'extension.tgz');
+  const extractDir = join(tmp, 'extracted');
+  mkdirSync(tmp, { recursive: true });
+  try {
+    if (isUrl) {
+      console.log(`  Downloading ${src} …`);
+      await downloadFile(src, tgzPath);
+    } else {
+      const abs = resolve(expandHome(src));
+      if (!existsSync(abs)) throw new Error(`file not found: ${abs}`);
+      cpSync(abs, tgzPath);
+    }
+    console.log('  Extracting …');
+    extractTgz(tgzPath, extractDir);
+    const found = findPluginDirs(extractDir, 5);
+    if (found.length === 0) throw new Error('No Finch extension found inside the tgz archive.');
+    const source = lockSource ?? (isUrl
+      ? { type: 'tgz', url: src }
+      : { type: 'tgz', localPath: resolve(expandHome(src)) });
+    for (const dir of found) installExtensionDir(dir, dest, source);
+  } finally {
+    try { rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+}
+
 async function cmdAdd(src, opts) {
   const dest = targetDir(opts);
 
-  // --- zip URL (e.g. https://github.com/.../archive/main.zip) ---
+  // --- archive URL (e.g. https://github.com/.../archive/main.zip or npm tarball .tgz) ---
   if (isZipUrl(src)) {
     await installFromZip(src, dest, true);
     return;
   }
+  if (isTgzUrl(src)) {
+    await installFromTgz(src, dest, { isUrl: true });
+    return;
+  }
 
   // --- local path ---
   if (isLocalSource(src)) {
     const abs = resolve(expandHome(src));
     if (!existsSync(abs)) throw new Error(`path not found: ${abs}`);
 
-    // Local zip file
+    // Local archive file
     if (isZipFile(src)) {
       await installFromZip(src, dest, false);
       return;
     }
+    if (isTgzFile(src)) {
+      await installFromTgz(src, dest, { isUrl: false });
+      return;
+    }
 
     // Local directory
     const direct = pluginInfo(abs);
@@ -311,18 +398,12 @@ async function cmdAdd(src, opts) {
     return;
   }
 
-  // --- npm package ---
-  const tmp = join(tmpdir(), `finch-ext-${randomUUID()}`);
-  try {
-    npmInstallToTemp(src, tmp);
-    const found = findPluginDirs(join(tmp, 'node_modules'), 5);
-    if (found.length === 0) throw new Error('No package with package.json#finch found in the npm package.');
-    // Prefer the top-level package matching the requested spec when possible.
-    const first = found[0];
-    installExtensionDir(first, dest, { type: 'npm', package: src });
-  } finally {
-    try { rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
-  }
+  // --- npm package: fetch registry metadata, download dist.tarball, then extract locally. ---
+  const resolved = await resolveNpmTarball(src);
+  await installFromTgz(resolved.tarball, dest, {
+    isUrl: true,
+    lockSource: { type: 'npm', package: resolved.package, version: resolved.version },
+  });
 }
 
 function listInstalled(dir) {
@@ -517,7 +598,7 @@ async function cmdUpdate(id, opts) {
     return;
   }
 
-  // zip source: re-download / re-extract from the recorded URL or local path.
+  // zip/tgz source: re-download / re-extract from the recorded URL or local path.
   if (source.type === 'zip') {
     if (source.url) {
       await installFromZip(source.url, dir, true);
@@ -528,34 +609,39 @@ async function cmdUpdate(id, opts) {
     }
     return;
   }
-
-  // npm source: reinstall the latest published version.
-  const spec = source.package ?? id;
-  const tmp = join(tmpdir(), `finch-ext-${randomUUID()}`);
-  try {
-    npmInstallToTemp(spec, tmp);
-    const found = findPluginDirs(join(tmp, 'node_modules'), 5).filter((d) => pluginInfo(d)?.id === id);
-    const fresh = found[0] ?? findPluginDirs(join(tmp, 'node_modules'), 5)[0];
-    if (!fresh) throw new Error('No matching Finch extension found in npm package.');
-    const info = pluginInfo(fresh);
-    rmSync(target, { recursive: true, force: true });
-    cpSync(fresh, target, { recursive: true, force: true, dereference: false });
-    recordInstall(dir, id, source);
-    console.log(`✓ Updated "${info.displayName}" (${id}) → v${info.version}`);
-  } finally {
-    try { rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }
+  if (source.type === 'tgz') {
+    if (source.url) {
+      await installFromTgz(source.url, dir, { isUrl: true, lockSource: source });
+    } else if (source.localPath) {
+      await installFromTgz(source.localPath, dir, { isUrl: false, lockSource: source });
+    } else {
+      throw new Error(`tgz install record for "${id}" has no url or localPath; reinstall with \`add\`.`);
+    }
+    return;
   }
+
+  // npm source: reinstall the latest published version by downloading dist.tarball directly.
+  const resolved = await resolveNpmTarball(source.package ?? id);
+  await installFromTgz(resolved.tarball, dir, {
+    isUrl: true,
+    lockSource: { type: 'npm', package: resolved.package, version: resolved.version },
+  });
 }
 
 function parseArgs(argv) {
   const args = [...argv];
   const cmd = args.shift();
-  const opts = { global: false };
+  const opts = { global: false, registry: null };
   const rest = [];
   for (let i = 0; i < args.length; i += 1) {
     const a = args[i];
     if (a === '--global' || a === '-g') opts.global = true;
-    else if (a === '--cwd') {
+    else if (a === '--registry') {
+      const value = args[i + 1];
+      if (!value || value.startsWith('--')) throw new Error('--registry requires a URL');
+      opts.registry = value;
+      i += 1;
+    } else if (a === '--cwd') {
       // Removed: extensions no longer support project/--cwd scope. Consume any
       // following path argument so old invocations fail loudly instead of
       // silently being parsed as the install source.
@@ -566,12 +652,13 @@ function parseArgs(argv) {
 }
 
 function help() {
-  console.log(`npx @finch.app/minitools\n\nUsage:\n  add <npm-package|local-path|url.zip> [--global]\n  update <id> [--global]\n  list [--global]\n  remove <id> [--global]\n  enable <id>\n  disable <id>\n  where\n  doctor [path]\n\nInstall locations:\n  default     workspace.json#finchHomeDir/.finch/extensions/  (personal — default)\n  --global   ~/.finch/extensions/                              (global)\n\nThere is no project/--cwd scope — extensions only install to personal or global.\n`);
+  console.log(`npx @finch.app/minitools\n\nUsage:\n  add <npm-package|local-path|url.zip|url.tgz> [--global] [--registry <url>]\n  update <id> [--global] [--registry <url>]\n  list [--global]\n  remove <id> [--global]\n  enable <id>\n  disable <id>\n  where\n  doctor [path]\n\nInstall locations:\n  default     workspace.json#finchHomeDir/.finch/extensions/  (personal — default)\n  --global   ~/.finch/extensions/                              (global)\n\nRegistry:\n  --registry <url> overrides npm registry for npm package metadata/tarball downloads.\n  If omitted, npm_config_registry is used, then https://registry.npmjs.org.\n\nThere is no project/--cwd scope — extensions only install to personal or global.\n`);
 }
 
 (async () => {
   try {
     const { cmd, rest, opts } = parseArgs(process.argv.slice(2));
+    registryOverride = opts.registry;
     if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') return help();
     if (cmd === 'add') {
       if (!rest[0]) throw new Error('missing source');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finch.app/minitools",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "CLI shim for installing Finch mini tools to the correct location.",
   "type": "module",
   "bin": {