@finch.app/minitools 0.1.8 → 0.1.9

package/README.md

@@ -15,26 +15,21 @@ npx @finch.app/minitools add ./my-tool
 npx @finch.app/minitools add ./my-tool.zip
 npx @finch.app/minitools add https://github.com/user/repo/archive/refs/heads/main.zip
 
-# Install to the current project
-npx @finch.app/minitools add @finch.app/mcp-client --cwd
-
-# Install to a specific project path
-npx @finch.app/minitools add @finch.app/mcp-client --cwd /path/to/project
-
 # Install globally (~/.finch/extensions/)
+# Default installs go to the personal Finch workspace extension directory.
 npx @finch.app/minitools add @finch.app/mcp-client --global
 
 # List installed mini tools (id, version, enabled/disabled, name, path)
 npx @finch.app/minitools list
 npx @finch.app/minitools list --global
 
-# Remove an mini tool
+# Remove a mini tool
 npx @finch.app/minitools remove mcp-client
 
 # Show install paths
 npx @finch.app/minitools where
 
-# Validate an mini tool package
+# Validate a mini tool package
 npx @finch.app/minitools doctor ./my-tool
 ```
 
@@ -42,12 +37,14 @@ npx @finch.app/minitools doctor ./my-tool
 
 | Flag | Path | Scope |
 |---|---|---|
-| *(default)* | `<workspace.json#finchHomeDir>/.finch/extensions/<id>/` | Current Finch workspace |
-| `--cwd` | `<process.cwd()>/.finch/extensions/<id>/` | Current project |
-| `--cwd path` | `<path>/.finch/extensions/<id>/` | Specific project |
+| *(default)* | `<workspace.json#finchHomeDir>/.finch/extensions/<id>/` | Personal Finch workspace |
 | `--global` | `~/.finch/extensions/<id>/` | All Finch sessions |
 
-The default workspace path is read from `~/.finch/workspace.json#finchHomeDir`.
+The default workspace path is read from `~/.finch/workspace.json#finchHomeDir`. There is no project/`--cwd` scope for mini tools; use the personal default or `--global`.
+
+## Registry and downloads
+
+Pinned npm specs such as `@scope/tool@1.2.3` skip npm registry metadata and download directly from `https://community.finchwork.app/download/minitool/<package>/<version>`. Unpinned specs such as `@scope/tool` or `@scope/tool@latest` still use npm registry metadata to resolve the concrete version first; `--registry <url>` only affects that metadata lookup, not the final package download.
 
 ## Mini tool package
 
@@ -62,11 +59,15 @@ A Finch mini tool is an npm-style package with `package.json#finch`:
   "finch": {
     "manifestVersion": 1,
     "id": "my-tool",
-    "displayName": "My Tool",
+    "name": "My Tool",
     "main": "dist/index.js",
     "activationEvents": ["onStartup"]
   }
 }
 ```
 
+`doctor` reports fatal issues and warnings. `add` / `update` block packages with fatal validation issues such as a missing `package.json#finch`, invalid `id`, unsupported `manifestVersion`, malformed contribution declarations, or a missing entry file.
+
+Downloads served by `https://community.finchwork.app/download/minitool/<package>/<version>` are cached under `~/.finch/cache/minitools/` by package and version, so reinstalling or updating the same version avoids another network download.
+
 `add` installs the mini tool but does not enable or grant permissions. Open Finch → Toolcase → Tools to review permissions and enable it.

package/bin/minitools.mjs

@@ -9,12 +9,15 @@ import {
   existsSync, mkdirSync, readdirSync, cpSync, rmSync,
   readFileSync, writeFileSync,
 } from 'node:fs';
-import { join, resolve, basename } from 'node:path';
+import { isAbsolute, join, resolve, basename } from 'node:path';
 import { homedir, tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 
 const LOCK_FILE = '.plugins-lock.json';
+const SUPPORTED_MANIFEST_VERSION = 1;
+const EXTENSION_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+const KNOWN_EXTENSION_TYPES = new Set(['official', 'community', 'local']);
 const LEGACY_NPM_PACKAGE_RENAMES = new Map([
   ['@finch.app/mcp-bridge', '@finch.app/mcp-client'],
 ]);
@@ -56,6 +59,9 @@ function targetDir(opts) {
 function pluginsStatePath() {
   return join(finchRuntimeHome(), 'extensions.json');
 }
+function miniToolCacheDir() {
+  return join(finchRuntimeHome(), 'cache', 'minitools');
+}
 function lockPath(dir) {
   return join(dir, LOCK_FILE);
 }
@@ -90,30 +96,221 @@ function readPackageJson(dir) {
   try { return JSON.parse(readFileSync(file, 'utf-8')); } catch { return null; }
 }
 
-function pluginInfo(dir) {
+function localizedValue(value, fallback = '') {
+  if (typeof value === 'string') return value;
+  if (value && typeof value === 'object') {
+    return value.default ?? value['en-US'] ?? value['zh-CN'] ?? fallback;
+  }
+  return fallback;
+}
+
+function isLocalizedString(value) {
+  if (value == null) return true;
+  if (typeof value === 'string') return true;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  return Object.entries(value).every(([locale, text]) => (
+    typeof locale === 'string' && typeof text === 'string'
+  ));
+}
+
+function validateStringField(value, field, diagnostics, { required = false, localized = false } = {}) {
+  if (value == null) {
+    if (required) diagnostics.fatal.push(`${field} 缺失`);
+    return;
+  }
+  const ok = localized ? isLocalizedString(value) : typeof value === 'string';
+  if (!ok) diagnostics.fatal.push(`${field} 必须是${localized ? '字符串或本地化字符串对象' : '字符串'}`);
+}
+
+function validateStringArray(value, field, diagnostics) {
+  if (value == null) return;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item.trim())) {
+    diagnostics.warning.push(`${field} 应为非空字符串数组`);
+  }
+}
+
+function validateObject(value, field, diagnostics) {
+  if (value == null) return true;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    diagnostics.warning.push(`${field} 应为对象`);
+    return false;
+  }
+  return true;
+}
+
+function validateContributes(contributes, diagnostics) {
+  if (contributes == null) return;
+  if (!validateObject(contributes, 'finch.contributes', diagnostics)) return;
+
+  if (contributes.tools != null && typeof contributes.tools !== 'boolean') {
+    diagnostics.warning.push('finch.contributes.tools 应为 boolean');
+  }
+  if (contributes.skills != null && typeof contributes.skills !== 'boolean') {
+    diagnostics.warning.push('finch.contributes.skills 应为 boolean');
+  }
+  if (contributes.composerActions != null) {
+    if (!Array.isArray(contributes.composerActions)) {
+      diagnostics.fatal.push('finch.contributes.composerActions 必须是数组');
+    } else {
+      for (const [index, action] of contributes.composerActions.entries()) {
+        const prefix = `finch.contributes.composerActions[${index}]`;
+        if (!action || typeof action !== 'object' || Array.isArray(action)) {
+          diagnostics.fatal.push(`${prefix} 必须是对象`);
+          continue;
+        }
+        if (typeof action.id !== 'string' || !action.id.trim()) {
+          diagnostics.fatal.push(`${prefix}.id 缺失或不是字符串`);
+        }
+        validateStringField(action.icon, `${prefix}.icon`, diagnostics);
+        validateStringField(action.tooltip, `${prefix}.tooltip`, diagnostics, { localized: true });
+      }
+    }
+  }
+  if (contributes.iconPacks != null) {
+    if (!Array.isArray(contributes.iconPacks)) {
+      diagnostics.fatal.push('finch.contributes.iconPacks 必须是数组');
+    } else {
+      for (const [index, pack] of contributes.iconPacks.entries()) {
+        const prefix = `finch.contributes.iconPacks[${index}]`;
+        if (!pack || typeof pack !== 'object' || Array.isArray(pack)) {
+          diagnostics.fatal.push(`${prefix} 必须是对象`);
+          continue;
+        }
+        if (typeof pack.id !== 'string' || !pack.id.trim()) diagnostics.fatal.push(`${prefix}.id 缺失或不是字符串`);
+        validateStringField(pack.label, `${prefix}.label`, diagnostics, { localized: true });
+        validateStringField(pack.description, `${prefix}.description`, diagnostics, { localized: true });
+      }
+    }
+  }
+  if (contributes.icons != null && validateObject(contributes.icons, 'finch.contributes.icons', diagnostics)) {
+    for (const [iconId, icon] of Object.entries(contributes.icons)) {
+      if (!icon || typeof icon !== 'object' || Array.isArray(icon)) {
+        diagnostics.fatal.push(`finch.contributes.icons.${iconId} 必须是对象`);
+        continue;
+      }
+      if (typeof icon.svg !== 'string' || !icon.svg.trim()) diagnostics.fatal.push(`finch.contributes.icons.${iconId}.svg 缺失或不是字符串`);
+    }
+  }
+  if (contributes.mcpServers != null && !Array.isArray(contributes.mcpServers)) {
+    diagnostics.fatal.push('finch.contributes.mcpServers 必须是数组');
+  }
+}
+
+function validatePermissions(permissions, diagnostics) {
+  if (permissions == null) return;
+  if (!validateObject(permissions, 'finch.permissions', diagnostics)) return;
+  if (permissions.filesystem != null && !['none', 'read', 'write'].includes(permissions.filesystem)) {
+    diagnostics.warning.push('finch.permissions.filesystem 建议使用 none/read/write');
+  }
+  if (permissions.network != null && typeof permissions.network !== 'boolean') {
+    diagnostics.warning.push('finch.permissions.network 应为 boolean');
+  }
+  if (permissions.shell != null && typeof permissions.shell !== 'boolean') {
+    diagnostics.warning.push('finch.permissions.shell 应为 boolean');
+  }
+}
+
+function validateCapabilitySpec(spec, field, diagnostics) {
+  if (spec == null) return;
+  if (!validateObject(spec, field, diagnostics)) return;
+  validateStringArray(spec.capabilities, `${field}.capabilities`, diagnostics);
+}
+
+function validateMiniToolPackage(dir, { lintSource = false } = {}) {
+  const diagnostics = { fatal: [], warning: [] };
   const pkg = readPackageJson(dir);
-  const manifest = pkg?.finch;
-  if (!pkg || !manifest || typeof manifest !== 'object') return null;
+  if (!pkg) {
+    diagnostics.fatal.push('缺少 package.json，或 package.json 不是合法 JSON');
+    return { diagnostics, info: null };
+  }
+
+  const manifest = pkg.finch;
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    diagnostics.fatal.push('缺少 package.json#finch，或 finch manifest 不是对象');
+    return { diagnostics, info: null };
+  }
+
   const id = String(manifest.id ?? pkg.name ?? '').trim();
-  if (!id) return { error: 'package.json#finch 缺少 id' };
-  const main = String(manifest.main ?? pkg.main ?? 'dist/index.js');
-  if (!existsSync(join(dir, main))) return { error: `入口文件不存在: ${main}（请先构建插件）`, id };
-  // `name` is the current preferred manifest field; `displayName` is kept only
-  // for backward compatibility with older extensions.
+  if (!id) {
+    diagnostics.fatal.push('package.json#finch 缺少 id');
+  } else if (!EXTENSION_ID_RE.test(id) || id === '.' || id === '..') {
+    diagnostics.fatal.push(`package.json#finch.id 不合法: ${id}（只能使用字母、数字、点、下划线、短横线，且不能包含路径分隔符）`);
+  }
+
+  if (manifest.manifestVersion !== undefined && manifest.manifestVersion !== SUPPORTED_MANIFEST_VERSION) {
+    diagnostics.fatal.push(`不支持的 manifestVersion: ${manifest.manifestVersion}（当前 Finch 支持 ${SUPPORTED_MANIFEST_VERSION}）`);
+  }
+
+  validateStringField(manifest.name, 'finch.name', diagnostics, { localized: true });
+  validateStringField(manifest.displayName, 'finch.displayName', diagnostics, { localized: true });
+  validateStringField(manifest.description, 'finch.description', diagnostics, { localized: true });
+  validateStringField(manifest.systemPrompt, 'finch.systemPrompt', diagnostics, { localized: true });
+  validateStringArray(manifest.categories, 'finch.categories', diagnostics);
+
+  const extensionType = manifest.miniToolType ?? manifest.extensionType;
+  if (extensionType != null && (typeof extensionType !== 'string' || !extensionType.trim())) {
+    diagnostics.warning.push('finch.miniToolType/extensionType 应为字符串');
+  } else if (typeof extensionType === 'string' && !KNOWN_EXTENSION_TYPES.has(extensionType)) {
+    diagnostics.warning.push(`未知 extensionType: ${extensionType}（常见值为 official/community/local）`);
+  }
+
+  if (manifest.install != null && validateObject(manifest.install, 'finch.install', diagnostics)) {
+    const scope = manifest.install.preferredScope;
+    if (scope != null && scope !== 'global' && scope !== 'personal') {
+      diagnostics.warning.push('finch.install.preferredScope 应为 global 或 personal');
+    }
+  }
+
+  validatePermissions(manifest.permissions, diagnostics);
+  validateCapabilitySpec(manifest.provides, 'finch.provides', diagnostics);
+  validateCapabilitySpec(manifest.requires, 'finch.requires', diagnostics);
+  validateContributes(manifest.contributes, diagnostics);
+
+  const mainValue = manifest.main ?? pkg.main ?? 'dist/index.js';
+  if (typeof mainValue !== 'string' || !mainValue.trim()) {
+    diagnostics.fatal.push('入口 main 必须是非空字符串（finch.main 或 package.json#main）');
+  }
+  const main = typeof mainValue === 'string' && mainValue.trim() ? mainValue.trim() : 'dist/index.js';
+  const entry = isAbsolute(main) ? main : join(dir, main);
+  if (!existsSync(entry)) diagnostics.fatal.push(`入口文件不存在: ${main}（请先构建小工具）`);
+
+  const recommended = [];
+  if (manifest.name == null && manifest.displayName == null) recommended.push('name');
+  if (manifest.description == null) recommended.push('description');
+  if (manifest.miniToolType == null && manifest.extensionType == null) recommended.push('miniToolType');
+  if (recommended.length) diagnostics.warning.push(`manifest 建议补充字段: ${recommended.join(', ')}`);
+
+  if (lintSource) diagnostics.warning.push(...lintExtensionSource(dir));
+
   const nameField = manifest.name ?? manifest.displayName;
+  const displayName = localizedValue(nameField, pkg.name ?? id).trim() || id;
   return {
-    id,
-    name: pkg.name ?? id,
-    version: pkg.version ?? '0.0.0',
-    displayName: typeof nameField === 'string'
-      ? nameField
-      : nameField?.default ?? nameField?.['en-US'] ?? nameField?.['zh-CN'] ?? id,
-    main,
+    diagnostics,
+    info: {
+      id,
+      name: pkg.name ?? id,
+      version: pkg.version ?? '0.0.0',
+      displayName,
+      main,
+    },
   };
 }
 
+function pluginInfo(dir) {
+  const result = validateMiniToolPackage(dir);
+  if (!result.info && result.diagnostics.fatal.length > 0) {
+    const pkg = readPackageJson(dir);
+    return pkg && Object.prototype.hasOwnProperty.call(pkg, 'finch')
+      ? { error: result.diagnostics.fatal[0] }
+      : null;
+  }
+  if (result.diagnostics.fatal.length > 0) return { error: result.diagnostics.fatal[0], id: result.info?.id };
+  return result.info;
+}
+
 function findPluginDirs(root, maxDepth = 4) {
   const found = [];
+  const invalid = [];
   const seen = new Set();
   function visit(dir, depth) {
     const key = dir.toLowerCase();
@@ -121,6 +318,7 @@ function findPluginDirs(root, maxDepth = 4) {
     seen.add(key);
     const info = pluginInfo(dir);
     if (info && !info.error) found.push(dir);
+    else if (info?.error) invalid.push({ dir, error: info.error });
     if (depth <= 0) return;
     let entries = [];
     try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
@@ -131,6 +329,7 @@ function findPluginDirs(root, maxDepth = 4) {
     }
   }
   visit(root, maxDepth);
+  found.invalid = invalid;
   return found;
 }
 
@@ -143,7 +342,7 @@ function installExtensionDir(srcDir, destRoot, lockSource) {
   cpSync(srcDir, dest, { recursive: true, force: true, dereference: false });
   recordInstall(destRoot, info.id, lockSource);
   console.log(`✓ Added "${info.displayName}" (${info.id}) → ${dest}`);
-  console.log('  Installed only. Open Finch → Toolcase → Extensions to review permissions and enable.');
+  console.log('  Installed only. Open Finch → Toolcase → Mini Tool to review permissions and enable.');
   return info.id;
 }
 
@@ -200,6 +399,46 @@ async function downloadFile(url, destPath) {
   }
 }
 
+function communityMiniToolFromUrl(url) {
+  let parsed;
+  try { parsed = new URL(url); } catch { return null; }
+  if (parsed.protocol !== 'https:' || parsed.hostname !== 'community.finchwork.app') return null;
+  const parts = parsed.pathname.split('/').filter(Boolean).map((part) => decodeURIComponent(part));
+  if (parts[0] !== 'download' || parts[1] !== 'minitool' || parts.length < 4) return null;
+  const version = parts.at(-1);
+  const packageName = parts.slice(2, -1).join('/');
+  if (!packageName || !version || version === 'latest') return null;
+  return { packageName, version };
+}
+
+function safeCacheSegment(value) {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+function communityMiniToolCachePath(meta) {
+  return join(miniToolCacheDir(), `${safeCacheSegment(meta.packageName)}-${safeCacheSegment(meta.version)}.tgz`);
+}
+
+async function downloadFileWithCache(url, destPath) {
+  const communityMeta = communityMiniToolFromUrl(url);
+  if (!communityMeta) {
+    await downloadFile(url, destPath);
+    return;
+  }
+
+  const cachePath = communityMiniToolCachePath(communityMeta);
+  if (existsSync(cachePath)) {
+    cpSync(cachePath, destPath);
+    console.log(`  Using cached package ${communityMeta.packageName}@${communityMeta.version}`);
+    return;
+  }
+
+  await downloadFile(url, destPath);
+  mkdirSync(miniToolCacheDir(), { recursive: true });
+  cpSync(destPath, cachePath);
+  console.log(`  Cached package ${communityMeta.packageName}@${communityMeta.version}`);
+}
+
 /**
  * Extract a zip archive to destDir using the system `unzip` command (macOS / Linux built-in).
  */
@@ -278,6 +517,14 @@ function officialMiniToolDownloadUrl(packageName, version) {
 
 async function resolveNpmTarball(spec) {
   const { name, version } = parseNpmSpec(spec);
+  if (version && version !== 'latest') {
+    return {
+      package: name,
+      version,
+      tarball: officialMiniToolDownloadUrl(name, version),
+    };
+  }
+
   const url = npmMetadataUrl(name, version);
   let meta;
   try {
@@ -311,17 +558,20 @@ async function installFromZip(src, dest, isUrl) {
   try {
     if (isUrl) {
       console.log(`  Downloading ${src} …`);
-      await downloadFile(src, zipPath);
+      await downloadFileWithCache(src, zipPath);
     } else {
       // Local zip — copy to tmp so we have a consistent path
       const abs = resolve(expandHome(src));
       if (!existsSync(abs)) throw new Error(`file not found: ${abs}`);
       cpSync(abs, zipPath);
     }
-    console.log('  Extracting …');
+    // console.log('  Extracting …');
     extractZip(zipPath, extractDir);
     const found = findPluginDirs(extractDir, 5);
-    if (found.length === 0) throw new Error('No Finch extension found inside the zip archive.');
+    if (found.length === 0) {
+      if (found.invalid?.length) throw new Error(`Invalid Finch extension inside the zip archive: ${found.invalid[0].error}`);
+      throw new Error('No Finch extension found inside the zip archive.');
+    }
     const lockSource = isUrl
       ? { type: 'zip', url: src }
       : { type: 'zip', localPath: resolve(expandHome(src)) };
@@ -339,16 +589,19 @@ async function installFromTgz(src, dest, { isUrl, lockSource }) {
   try {
     if (isUrl) {
       console.log(`  Downloading ${src} …`);
-      await downloadFile(src, tgzPath);
+      await downloadFileWithCache(src, tgzPath);
     } else {
       const abs = resolve(expandHome(src));
       if (!existsSync(abs)) throw new Error(`file not found: ${abs}`);
       cpSync(abs, tgzPath);
     }
-    console.log('  Extracting …');
+    // 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.');
+    if (found.length === 0) {
+      if (found.invalid?.length) throw new Error(`Invalid Finch extension inside the tgz archive: ${found.invalid[0].error}`);
+      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)) });
@@ -393,7 +646,10 @@ async function cmdAdd(src, opts) {
       return;
     }
     const found = findPluginDirs(abs, 3);
-    if (found.length === 0) throw new Error('No Finch extension found in the given directory.');
+    if (found.length === 0) {
+      if (found.invalid?.length) throw new Error(`Invalid Finch extension in the given directory: ${found.invalid[0].error}`);
+      throw new Error('No Finch extension found in the given directory.');
+    }
     for (const dir of found) installExtensionDir(dir, dest, { type: 'local', localPath: dir });
     return;
   }
@@ -532,22 +788,20 @@ function lintExtensionSource(root) {
 
 function cmdDoctor(src = '.') {
   const abs = resolve(expandHome(src));
-  const info = pluginInfo(abs);
-  if (!info) throw new Error('Not a Finch extension package (missing package.json#finch).');
-  if (info.error) throw new Error(info.error);
-  console.log(`✓ Finch extension: ${info.displayName}`);
-  console.log(`  id:      ${info.id}`);
-  console.log(`  version: ${info.version}`);
-  console.log(`  main:    ${info.main}`);
+  const { diagnostics, info } = validateMiniToolPackage(abs, { lintSource: true });
+
+  if (info) {
+    console.log(`Finch mini tool: ${info.displayName}`);
+    console.log(`  id:      ${info.id || '(missing)'}`);
+    console.log(`  version: ${info.version}`);
+    console.log(`  main:    ${info.main}`);
+  } else {
+    console.log(`Finch mini tool: ${abs}`);
+  }
 
   const pkg = readPackageJson(abs);
   const manifest = pkg?.finch ?? {};
-  // Surface recommended manifest metadata that's missing (non-fatal).
-  const recommended = ['name', 'description'];
-  const missing = recommended.filter((k) => manifest[k] == null);
-  if (manifest.miniToolType == null && manifest.extensionType == null) missing.push('miniToolType');
-  if (missing.length) console.log(`  hint: manifest 建议补充字段: ${missing.join(', ')}`);
-  if (manifest.permissions) {
+  if (manifest.permissions && typeof manifest.permissions === 'object') {
     const p = manifest.permissions;
     const decl = [
       p.filesystem && p.filesystem !== 'none' ? `filesystem=${p.filesystem}` : null,
@@ -557,13 +811,20 @@ function cmdDoctor(src = '.') {
     if (decl.length) console.log(`  permissions: ${decl.join(', ')}（启用时会向用户展示）`);
   }
 
-  const warnings = lintExtensionSource(abs);
-  if (warnings.length === 0) {
+  if (diagnostics.fatal.length > 0) {
+    console.log(`\n✖ ${diagnostics.fatal.length} fatal issue(s):`);
+    for (const issue of diagnostics.fatal) console.log(`  - ${issue}`);
+  }
+  if (diagnostics.warning.length > 0) {
+    console.log(`\n⚠ ${diagnostics.warning.length} warning(s):`);
+    for (const issue of diagnostics.warning) console.log(`  - ${issue}`);
+  }
+  if (diagnostics.fatal.length === 0 && diagnostics.warning.length === 0) {
     console.log('✓ No issues found.');
-    return;
   }
-  console.log(`\n⚠ ${warnings.length} warning(s):`);
-  for (const w of warnings) console.log(`  - ${w}`);
+  if (diagnostics.fatal.length > 0) {
+    throw new Error('mini tool package validation failed');
+  }
 }
 
 async function cmdUpdate(id, opts) {

package/package.json

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