pantheon-opencode 1.1.1 → 1.2.0-beta.9.7bef03e

package/scripts/install/health-check.mjs

@@ -9,7 +9,7 @@
  */
 
 import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 /**
@@ -24,6 +24,7 @@ import { join } from 'node:path'
 export function healthCheck(target, { dryRun = false } = {}) {
   const results = { passed: [], failed: [], warnings: [] }
   const python = findPython(target)
+  const visionServer = resolveVisionServer(target)
 
   // Check 1: Critical runtime scripts exist
   const scripts = ['mcp_persistence_server.py', '_pantheon_paths.py']
@@ -38,9 +39,70 @@ export function healthCheck(target, { dryRun = false } = {}) {
       })
     }
   }
+  if (visionServer) {
+    results.passed.push({
+      check: visionServer.check,
+      detail: visionServer.detail,
+    })
+    const installedVisionServer = join(target, 'scripts', 'pantheon_vision_server.py')
+    const canonicalVisionServer = join(target, 'src', 'mcp', 'pantheon_vision_server.py')
+    if (existsSync(installedVisionServer) && existsSync(canonicalVisionServer)) {
+      try {
+        if (
+          readFileSync(installedVisionServer, 'utf8') !==
+          readFileSync(canonicalVisionServer, 'utf8')
+        ) {
+          results.failed.push({
+            check: 'pantheon-vision source drift',
+            detail: 'installed script differs from src/mcp/pantheon_vision_server.py',
+          })
+        }
+      } catch {
+        results.failed.push({
+          check: 'pantheon-vision source drift',
+          detail: 'could not compare installed script with src/mcp source',
+        })
+      }
+    }
+  } else {
+    results.failed.push({
+      check: 'src/mcp/pantheon_vision_server.py',
+      detail: 'NOT FOUND — canonical vision server source is unavailable',
+    })
+  }
 
   if (dryRun) return results
 
+  // Check 1.5: Vision keeps a small, isolated dependency manifest.
+  const visionRequirements = [
+    join(target, 'src', 'mcp', 'requirements-vision.txt'),
+    join(target, 'requirements-vision.txt'),
+    join(target, '.opencode', 'requirements-vision.txt'),
+  ].find((path) => existsSync(path))
+  if (!visionRequirements) {
+    results.failed.push({
+      check: 'requirements-vision.txt',
+      detail: 'NOT FOUND — vision dependency isolation is incomplete',
+    })
+  } else {
+    const requirements = readFileSync(visionRequirements, 'utf8').toLowerCase()
+    const forbidden = ['pillow', 'paddle', 'gemini', 'torch']
+    const unwanted = forbidden.filter((name) =>
+      new RegExp(`^${name}(?:[<>=!~]|$)`, 'm').test(requirements),
+    )
+    if (unwanted.length > 0) {
+      results.failed.push({
+        check: 'requirements-vision.txt',
+        detail: `forbidden MVP dependencies: ${unwanted.join(', ')}`,
+      })
+    } else {
+      results.passed.push({
+        check: 'requirements-vision.txt',
+        detail: 'isolated and free of heavyweight vision runtimes',
+      })
+    }
+  }
+
   // Check 2: Syntax check on each MCP server script
   const mcpScripts = [
     'mcp_persistence_server.py',
@@ -67,6 +129,22 @@ export function healthCheck(target, { dryRun = false } = {}) {
       }
     }
   }
+  if (visionServer && python) {
+    const result = spawnSync(python, ['-m', 'py_compile', visionServer.path], {
+      stdio: 'pipe',
+    })
+    if (result.status === 0) {
+      results.passed.push({
+        check: 'syntax:pantheon_vision_server.py',
+        detail: 'valid',
+      })
+    } else {
+      results.failed.push({
+        check: 'syntax:pantheon_vision_server.py',
+        detail: result.stderr.toString().trim().split('\n').slice(-1)[0],
+      })
+    }
+  }
 
   // Check 3: _pantheon_paths import works
   if (python) {
@@ -150,6 +228,28 @@ export function healthCheck(target, { dryRun = false } = {}) {
   return results
 }
 
+/**
+ * Resolve the canonical source when checking the repository, or the generated
+ * runtime copy when checking an installed target.
+ * @param {string} target
+ * @returns {{path: string, check: string, detail: string}|null}
+ */
+function resolveVisionServer(target) {
+  const candidates = [
+    {
+      path: join(target, 'src', 'mcp', 'pantheon_vision_server.py'),
+      check: 'src/mcp/pantheon_vision_server.py',
+      detail: 'canonical source exists',
+    },
+    {
+      path: join(target, 'scripts', 'pantheon_vision_server.py'),
+      check: 'scripts/pantheon_vision_server.py',
+      detail: 'installed copy exists (deployed from src/mcp)',
+    },
+  ]
+  return candidates.find(({ path }) => existsSync(path)) ?? null
+}
+
 /**
  * Find the target's venv python, falling back to system python3.
  * @param {string} target

package/scripts/install/model-picker.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * model-picker.mjs — interactive model preset selection + persistence
+ *
+ * Used by the installer (interactive prompt) and the `pantheon-opencode`
+ * CLI. Writes the active preset marker to <presetDir>/.pantheon/active-preset.json
+ * which the plugin (src/plugin.ts) reads on startup via resolveActivePreset().
+ */
+import { copyFileSync, existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline/promises'
+import { loadPresetDefs } from '../../src/pantheon/presets.mjs'
+
+/**
+ * Build the active-preset.json payload (version 1).
+ *
+ * @param {string} presetName
+ * @param {string} [source] 'cli' | 'interactive'
+ * @returns {{version: number, preset: string, source: string, updated_at: string}}
+ */
+export function buildActivePresetFile(presetName, source = 'cli') {
+  return {
+    version: 1,
+    preset: presetName,
+    source,
+    updated_at: new Date().toISOString(),
+  }
+}
+
+/**
+ * Persist the active preset marker, backing up any previous file to .bak.
+ *
+ * @param {string} presetDir install target (project root or global opencode dir)
+ * @param {string} presetName
+ * @param {{dryRun?: boolean, source?: string, logger?: object}} [opts]
+ * @returns {{written: boolean, path: string, backupPath: string|null}}
+ */
+export function writeActivePreset(
+  presetDir,
+  presetName,
+  { dryRun = false, source = 'cli', logger = console } = {},
+) {
+  const dir = join(presetDir, '.pantheon')
+  const filePath = join(dir, 'active-preset.json')
+  const backupPath = join(dir, 'active-preset.json.bak')
+
+  if (dryRun) {
+    logger.log?.(`[dry-run] Would write model preset "${presetName}" to ${filePath}`)
+    return { written: false, path: filePath, backupPath: null }
+  }
+
+  mkdirSync(dir, { recursive: true })
+  let backupMade = false
+  if (existsSync(filePath)) {
+    copyFileSync(filePath, backupPath)
+    backupMade = true
+  }
+  writeFileSync(`${filePath}.tmp-${process.pid}`, `${JSON.stringify(buildActivePresetFile(presetName, source), null, 2)}\n`)
+  renameSync(`${filePath}.tmp-${process.pid}`, filePath)
+  return { written: true, path: filePath, backupPath: backupMade ? backupPath : null }
+}
+
+/**
+ * Interactive model preset picker. Asks the user to choose a preset; persists
+ * the choice unless dryRun. `rl` may be injected for tests; otherwise a
+ * readline/promises interface on stdin/stdout is created and closed.
+ *
+ * @param {{presetDir?: string, presets?: object, dryRun?: boolean, logger?: object, rl?: object}} [opts]
+ * @returns {Promise<string|null>} chosen preset name or null (skipped/unknown)
+ */
+export async function runModelPicker({
+  presetDir,
+  presets,
+  dryRun = false,
+  logger = console,
+  rl,
+} = {}) {
+  const defs = presets ?? loadPresetDefs()
+  const names = Object.keys(defs)
+  if (names.length === 0) {
+    logger.warn?.('Model presets: no presets defined in routing.yml')
+    return null
+  }
+
+  const list = names.map((n, i) => `  ${i + 1}) ${n} — ${defs[n].description ?? ''}`).join('\n')
+  const rli = rl ?? createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const answer = await rli.question(
+      `\nModel presets (number or name; blank to skip):\n${list}\n> `,
+    )
+    const trimmed = (answer ?? '').trim()
+    if (trimmed === '' || trimmed.toLowerCase() === 'none') {
+      logger.log?.('Skipping model preset selection.')
+      return null
+    }
+    let name = null
+    if (names.includes(trimmed)) {
+      name = trimmed
+    } else {
+      const idx = Number(trimmed)
+      if (Number.isInteger(idx) && idx >= 1 && idx <= names.length) {
+        name = names[idx - 1]
+      }
+    }
+    if (!name) {
+      logger.warn?.(`Unknown preset "${trimmed}" — skipping model preset selection.`)
+      return null
+    }
+    if (!dryRun) {
+      writeActivePreset(presetDir, name, { dryRun: false, source: 'interactive', logger })
+    } else {
+      logger.log?.(`[dry-run] Would set model preset "${name}"`)
+    }
+    return name
+  } finally {
+    if (!rl) rli.close()
+  }
+}

package/scripts/install/opencode.mjs

@@ -3,12 +3,33 @@
  * opencode.mjs — OpenCode platform installer
  */
 
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
+import {
+  bullet,
+  colors,
+  configure,
+  error,
+  info,
+  printSummary,
+  section,
+  spinner,
+  step,
+  success,
+  warning,
+} from './cli-ui.mjs'
 import { healthCheck } from './health-check.mjs'
 import { detectVersion, runMigrations } from './migrate.mjs'
-import { colors, configure, section, step, success, warning, error, info, bullet, spinner, printSummary } from './cli-ui.mjs'
+import { installPlugin, registerPlugin, unregisterPlugin } from './plugin.mjs'
 import {
   collectSkillNames,
   copyFiles,
@@ -21,10 +42,16 @@ import {
   writeIfChanged,
 } from './shared.mjs'
 import { setupVenv } from './venv.mjs'
-import { installPlugin, registerPlugin, unregisterPlugin } from './plugin.mjs'
-import { resolveComponents } from './component.mjs'
 
-const COMPONENT_NAMES = ['agents', 'skills', 'instructions', 'prompts', 'commands', 'plugins', 'runtime']
+const COMPONENT_NAMES = [
+  'agents',
+  'skills',
+  'instructions',
+  'prompts',
+  'commands',
+  'plugins',
+  'runtime',
+]
 
 function deepClone(value) {
   return JSON.parse(JSON.stringify(value))
@@ -63,7 +90,7 @@ function mergeMissing(target, source) {
  * Global installs use a flat layout: agents/ skills/ commands/ plugins/
  * Project installs use the .opencode/ sub-directory layout.
  */
-function isGlobalConfigDir(target) {
+export function isGlobalConfigDir(target) {
   // Primary: ~/.opencode (actual OpenCode installation)
   const homeDir = resolve(join(homedir(), '.opencode'))
   if (resolve(target) === homeDir) return true
@@ -261,9 +288,12 @@ export async function installOpenCode(
       try {
         const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'))
         let changed = false
-        if (cfg.subagent_depth === undefined) { cfg.subagent_depth = 2; changed = true }
+        if (cfg.subagent_depth === undefined) {
+          cfg.subagent_depth = 2
+          changed = true
+        }
         if (changed && !dryRun) {
-          writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n')
+          writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`)
           success('subagent_depth: 2 added to opencode.json')
         }
       } catch (e) {
@@ -314,12 +344,16 @@ export async function installOpenCode(
       'scrub-secrets.py',
       '_pantheon_paths.py',
       'mcp_persistence_server.py',
+      'pantheon_vision_server.py',
     ]
     const srcScriptsDir = join(ROOT, 'scripts')
+    const canonicalMcpScripts = {
+      'pantheon_vision_server.py': join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py'),
+    }
     const dstScriptsDir = join(runtimeTarget, 'scripts')
     if (!dryRun) mkdirSync(dstScriptsDir, { recursive: true })
     for (const script of mcpScripts) {
-      const src = join(srcScriptsDir, script)
+      const src = canonicalMcpScripts[script] || join(srcScriptsDir, script)
       if (!existsSync(src)) {
         warning(`Script not found: ${src}`)
         stats.errors++
@@ -341,6 +375,18 @@ export async function installOpenCode(
       } else stats.skipped++
     }
 
+    // Keep Vision's dependency contract available to the installed runtime.
+    const visionRequirements = join(ROOT, 'src', 'mcp', 'requirements-vision.txt')
+    if (existsSync(visionRequirements)) {
+      const destination = join(runtimeTarget, 'requirements-vision.txt')
+      const status = writeIfChanged(destination, readFileSync(visionRequirements, 'utf8'), dryRun)
+      if (status === 'created') stats.created++
+      else stats.skipped++
+    } else {
+      warning(`Requirements file not found: ${visionRequirements}`)
+      stats.errors++
+    }
+
     // ── Code-mode scripts ──
     const srcCodeModeDir = join(ROOT, '.pantheon', 'code-mode')
     const dstCodeModeDir = join(runtimeTarget, '.pantheon', 'code-mode')
@@ -605,9 +651,13 @@ export async function installOpenCode(
   if (componentSet.has('runtime')) {
     config.mcp = config.mcp || {}
     const runtimeTarget = isGlobal ? target : join(target, '.opencode')
-    const pythonPath = process.platform === 'win32' ? 'python' : 'python3'
-    const venvPython = join(runtimeTarget, '.venv', 'bin', 'python3')
-    const memoryPython = existsSync(venvPython) ? venvPython : pythonPath
+    const venvPython =
+      process.platform === 'win32'
+        ? join(runtimeTarget, '.venv', 'Scripts', 'python.exe')
+        : join(runtimeTarget, '.venv', 'bin', 'python3')
+    // Point the config at the venv even on a first install; setupVenv runs
+    // later in this function and creates this path before OpenCode starts.
+    const memoryPython = venvPython
 
     // Only add if not already configured by user
     if (!config.mcp['pantheon-resources']) {
@@ -642,6 +692,14 @@ export async function installOpenCode(
         enabled: true,
       }
     }
+    if (!config.mcp['pantheon-vision']) {
+      config.mcp['pantheon-vision'] = {
+        type: 'local',
+        cwd: runtimeTarget,
+        command: [memoryPython, 'scripts/pantheon_vision_server.py'],
+        enabled: true,
+      }
+    }
 
     // Default MCP permissions
     config.permission = config.permission || {}
@@ -658,6 +716,9 @@ export async function installOpenCode(
     if (!config.permission.mcp['pantheon-persistence']) {
       config.permission.mcp['pantheon-persistence'] = 'allow'
     }
+    if (!config.permission.mcp['pantheon-vision']) {
+      config.permission.mcp['pantheon-vision'] = 'ask'
+    }
   }
 
   const configContent = `${JSON.stringify(config, null, 2)}\n`
@@ -707,7 +768,7 @@ export async function installOpenCode(
       }
     } catch (err) {
       error(`Setup failed: ${err.message}`)
-      throw err  // Fatal — abort installation
+      throw err // Fatal — abort installation
     }
   }
 
@@ -718,18 +779,38 @@ export async function installOpenCode(
 
     process.stdout.write('\n')
     process.stdout.write(`  ${colors.bold(colors.green('Installation complete'))}\n`)
-    process.stdout.write(`  ${colors.dim('\u2500'.repeat(Math.min(process.stdout.columns || 60, 60)))}\n`)
+    process.stdout.write(
+      `  ${colors.dim('\u2500'.repeat(Math.min(process.stdout.columns || 60, 60)))}\n`,
+    )
     process.stdout.write(`  ${colors.green('\u2713')} ${created} component(s) installed\n`)
-    if (skipped > 0) process.stdout.write(`  ${colors.dim('\u2014')} ${skipped} already up-to-date\n`)
-    if (errors > 0) process.stdout.write(`  ${colors.yellow('\u26a0')} ${errors} error(s) encountered\n`)
+    if (skipped > 0)
+      process.stdout.write(`  ${colors.dim('\u2014')} ${skipped} already up-to-date\n`)
+    if (errors > 0)
+      process.stdout.write(`  ${colors.yellow('\u26a0')} ${errors} error(s) encountered\n`)
     process.stdout.write('\n')
     process.stdout.write(`  ${colors.bold('Next steps:')}\n`)
     process.stdout.write(`  ${colors.dim('\u2022')} Configure agents in opencode.json\n`)
     process.stdout.write(`  ${colors.dim('\u2022')} Add MCP servers in mcp.json\n`)
     process.stdout.write(`  ${colors.dim('\u2022')} Run 'opencode doctor' to verify\n`)
-    process.stdout.write(`  ${colors.dim('\u2022')} Run 'opencode' to start using Pantheon agents\n`)
+    process.stdout.write(
+      `  ${colors.dim('\u2022')} Run 'opencode' to start using Pantheon agents\n`,
+    )
     process.stdout.write('\n')
   } else {
     printSummary(target, ['opencode'], stats)
   }
+
+  // -----------------------------------------------------------------------
+  // 5. Model preset selection (--components agents). Interactive picker runs
+  //    unless autoYes (use defaults) or an explicit --preset was given.
+  // -----------------------------------------------------------------------
+  if (interactive && !dryRun && !autoYes && !opts.preset) {
+    const { runModelPicker } = await import('./model-picker.mjs')
+    await runModelPicker({ presetDir: target, logger: console })
+  }
+
+  if (opts.preset && !dryRun) {
+    const { writeActivePreset } = await import('./model-picker.mjs')
+    writeActivePreset(target, opts.preset, { source: 'cli' })
+  }
 }

package/scripts/install-mcp.mjs

@@ -23,7 +23,7 @@
 import { execSync } from 'node:child_process'
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { createInterface } from 'node:readline'
 import { fileURLToPath } from 'node:url'
 
@@ -171,11 +171,31 @@ const MCPS = {
     name: 'Pantheon Resources',
     description: 'Pantheon framework resources — agents, skills, routing, deepwork, memory bank',
     platforms: {
-      opencode: { type: 'local', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/mcp_resources_server.py')] },
-      vscode: { type: 'stdio', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/mcp_resources_server.py')] },
-      cursor: { type: 'local', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/mcp_resources_server.py')] },
-      claude: { type: 'local', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/mcp_resources_server.py')] },
-      windsurf: { type: 'local', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/mcp_resources_server.py')] },
+      opencode: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/mcp_resources_server.py')],
+      },
+      vscode: {
+        type: 'stdio',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/mcp_resources_server.py')],
+      },
+      cursor: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/mcp_resources_server.py')],
+      },
+      claude: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/mcp_resources_server.py')],
+      },
+      windsurf: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/mcp_resources_server.py')],
+      },
     },
     env: [],
     validate: async () => {
@@ -191,11 +211,31 @@ const MCPS = {
     name: 'Pantheon Code Mode',
     description: 'Execute orchestration scripts from .pantheon/code-mode/ directory',
     platforms: {
-      opencode: { type: 'local', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/code_mode_server.py')] },
-      vscode: { type: 'stdio', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/code_mode_server.py')] },
-      cursor: { type: 'local', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/code_mode_server.py')] },
-      claude: { type: 'local', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/code_mode_server.py')] },
-      windsurf: { type: 'local', command: join(ROOT, '.venv/bin/python3'), args: [join(ROOT, 'scripts/code_mode_server.py')] },
+      opencode: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/code_mode_server.py')],
+      },
+      vscode: {
+        type: 'stdio',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/code_mode_server.py')],
+      },
+      cursor: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/code_mode_server.py')],
+      },
+      claude: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/code_mode_server.py')],
+      },
+      windsurf: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'scripts/code_mode_server.py')],
+      },
     },
     env: [],
     validate: async () => {
@@ -278,6 +318,49 @@ const MCPS = {
       return { ok: false, message: 'scripts/mcp_persistence_server.py not found' }
     },
   },
+  'pantheon-vision': {
+    tier: 1,
+    name: 'Pantheon Vision',
+    description:
+      'Image description, OCR, and structured analysis through the OpenCode vision gateway',
+    requirements: join(ROOT, 'src', 'mcp', 'requirements-vision.txt'),
+    platforms: {
+      opencode: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py')],
+      },
+      vscode: {
+        type: 'stdio',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py')],
+      },
+      claude: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py')],
+      },
+      cursor: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py')],
+      },
+      windsurf: {
+        type: 'local',
+        command: join(ROOT, '.venv/bin/python3'),
+        args: [join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py')],
+      },
+    },
+    env: [],
+    validate: async () => {
+      const sourcePath = join(ROOT, 'src', 'mcp', 'pantheon_vision_server.py')
+      const requirementsPath = join(ROOT, 'src', 'mcp', 'requirements-vision.txt')
+      if (existsSync(sourcePath) && existsSync(requirementsPath)) {
+        return { ok: true, message: 'canonical server source and isolated requirements present' }
+      }
+      return { ok: false, message: 'canonical vision source or requirements not found' }
+    },
+  },
   docker: {
     tier: 2,
     name: 'Docker MCP',
@@ -790,7 +873,7 @@ function logValidation(mcpKey, result) {
 // Main
 // ---------------------------------------------------------------------------
 
-async function main() {
+export async function main() {
   const args = parseArgs(process.argv)
 
   if (args.help) {
@@ -918,4 +1001,6 @@ async function main() {
   process.exit(progress.errors.length > 0 ? 1 : 0)
 }
 
-main()
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  main()
+}