pantheon-opencode 1.4.2 → 1.5.0-beta.1

package/scripts/install/config-migration.mjs

@@ -0,0 +1,401 @@
+/**
+ * config-migration.mjs — Bidirectional V1↔V2 config format migration
+ *
+ * Converts opencode.json between:
+ * - V1 (object-based): `permission`, `agent`, `provider`, `mcp` with flat keys
+ * - V2 (array-based):  `permissions`, `agents`, `providers`; MCP remains the
+ *   named top-level server map because OpenCode 1.18.x validates that shape for
+ *   both the V1 and V2 installer paths.
+ *
+ * Rules:
+ * 1. Deep clone before mutating — never modifies input
+ * 2. Unknown fields pass through untouched
+ * 3. console.warn for ambiguities
+ * 4. Handles nested objects recursively
+ *
+ * @module config-migration
+ */
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Deep clone a JSON-serializable value */
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj))
+}
+
+// ---------------------------------------------------------------------------
+// V1 → V2 helpers
+// ---------------------------------------------------------------------------
+
+/** Action name mapping for permissions (V1 key → V2 action) */
+const V1_PERMISSION_TO_ACTION = {
+  bash: 'shell',
+  skill: 'skill',
+  edit: 'edit',
+  websearch: 'websearch',
+  // passthrough unknowns
+}
+
+/**
+ * Convert V1 permission object to V2 permissions array.
+ *
+ * V1 shape:
+ *   { bash: { "git *": "allow" }, edit: "allow", skill: { "*": "allow" }, websearch: "deny" }
+ *
+ * V2 shape:
+ *   [ { action: "shell", resource: "git *", effect: "allow" }, ... ]
+ */
+function convertPermissionsV1toV2(permObj) {
+  const result = []
+  for (const [key, value] of Object.entries(permObj)) {
+    const action = V1_PERMISSION_TO_ACTION[key] || key
+    if (typeof value === 'string') {
+      // Simple: { edit: "allow" } → [{ action: "edit", resource: "*", effect: "allow" }]
+      result.push({ action, resource: '*', effect: value })
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      // Nested: { bash: { "git *": "allow" } } → [{ action: "shell", resource: "git *", effect: "allow" }]
+      for (const [resource, effect] of Object.entries(value)) {
+        result.push({ action, resource, effect })
+      }
+    } else {
+      console.warn(`[config-migration] Unexpected permission value for "${key}":`, value)
+    }
+  }
+  return result
+}
+
+/**
+ * Convert V2 permissions array back to V1 permission object.
+ */
+function convertPermissionsV2toV1(permArray) {
+  const result = {}
+  // Reverse action mapping: V2 action → V1 key
+  const ACTION_TO_V1 = Object.fromEntries(
+    Object.entries(V1_PERMISSION_TO_ACTION).map(([k, v]) => [v, k])
+  )
+
+  for (const { action, resource, effect } of permArray) {
+    const v1Key = ACTION_TO_V1[action] || action
+    if (resource === '*') {
+      result[v1Key] = effect
+    } else {
+      if (!result[v1Key] || typeof result[v1Key] === 'string') {
+        // Convert scalar to object
+        if (typeof result[v1Key] === 'string') {
+          const prevEffect = result[v1Key]
+          result[v1Key] = { '*': prevEffect }
+        } else {
+          result[v1Key] = {}
+        }
+      }
+      result[v1Key][resource] = effect
+    }
+  }
+  return result
+}
+
+/** Provider name consolidation: V1 → V2 */
+const PROVIDER_RENAME = {
+  'azure-cognitive-services': 'azure',
+  'google-vertex-anthropic': 'google-vertex',
+}
+
+/** Reverse: V2 → V1 */
+const PROVIDER_RENAME_REVERSE = Object.fromEntries(
+  Object.entries(PROVIDER_RENAME).map(([k, v]) => [v, k])
+)
+
+/**
+ * Convert a single V1 provider config to V2.
+ *
+ * V1 shape:
+ *   { npm: "ai-sdk-openai", api: "https://...", options: { apiKey: "..." }, models: { ... } }
+ *
+ * V2 shape:
+ *   { package: "aisdk:ai-sdk-openai", settings: { baseURL: "...", apiKey: "..." }, models: { ... } }
+ */
+function convertProviderV1toV2(name, config) {
+  const result = { ...config }
+
+  // npm → package (with aisdk: prefix)
+  if (result.npm !== undefined) {
+    const pkg = result.npm.startsWith('aisdk:') ? result.npm : `aisdk:${result.npm}`
+    result.package = pkg
+    delete result.npm
+  }
+
+  // api → settings.baseURL
+  if (result.api !== undefined) {
+    if (!result.settings) result.settings = {}
+    result.settings.baseURL = result.api
+    delete result.api
+  }
+
+  // options.apiKey → settings.apiKey
+  if (result.options?.apiKey !== undefined) {
+    if (!result.settings) result.settings = {}
+    result.settings.apiKey = result.options.apiKey
+    const { apiKey, ...restOptions } = result.options
+    if (Object.keys(restOptions).length > 0) {
+      result.options = restOptions
+    } else {
+      delete result.options
+    }
+  }
+
+  // Model variant: { variant: "high" } → key suffix #high
+  // Also rename model-level "attachment" → "media"
+  if (result.models) {
+    const newModels = {}
+    for (const [modelKey, modelConfig] of Object.entries(result.models)) {
+      const { variant, attachment, ...restConfig } = modelConfig || {}
+      const finalConfig = { ...restConfig }
+      if (attachment !== undefined) {
+        finalConfig.media = attachment
+      }
+      if (variant) {
+        const newKey = `${modelKey}#${variant}`
+        newModels[newKey] = finalConfig
+      } else {
+        newModels[modelKey] = finalConfig
+      }
+    }
+    result.models = newModels
+  }
+
+  return result
+}
+
+/**
+ * Convert a single V2 provider config back to V1.
+ */
+function convertProviderV2toV1(name, config) {
+  const result = { ...config }
+
+  // package → npm (strip aisdk: prefix)
+  if (result.package !== undefined) {
+    result.npm = result.package.startsWith('aisdk:')
+      ? result.package.slice(6)
+      : result.package
+    delete result.package
+  }
+
+  // settings.baseURL → api
+  if (result.settings?.baseURL !== undefined) {
+    result.api = result.settings.baseURL
+    const { baseURL, ...restSettings } = result.settings
+    if (Object.keys(restSettings).length > 0) {
+      result.settings = restSettings
+    } else {
+      delete result.settings
+    }
+  }
+
+  // settings.apiKey → options.apiKey
+  if (result.settings?.apiKey !== undefined) {
+    if (!result.options) result.options = {}
+    result.options.apiKey = result.settings.apiKey
+    const { apiKey, ...restSettings } = result.settings || {}
+    if (Object.keys(restSettings).length > 0) {
+      result.settings = restSettings
+    } else {
+      delete result.settings
+    }
+  }
+
+  // Model key with #suffix → variant field
+  // Also rename model-level "media" → "attachment"
+  if (result.models) {
+    const newModels = {}
+    for (const [modelKey, modelConfig] of Object.entries(result.models)) {
+      const { media, ...restConfig } = modelConfig || {}
+      const finalConfig = { ...restConfig }
+      if (media !== undefined) {
+        finalConfig.attachment = media
+      }
+      if (modelKey.includes('#')) {
+        const [baseName, variant] = modelKey.split('#', 2)
+        newModels[baseName] = { ...finalConfig, variant }
+      } else {
+        newModels[modelKey] = finalConfig
+      }
+    }
+    result.models = newModels
+  }
+
+  return result
+}
+
+/**
+ * Convert V1 MCP config to V2.
+ *
+ * V1: { bifrost: { type: "remote", url: "...", enabled: true, timeout: 30000 } }
+ * V2 installer output: { bifrost: { type: "remote", url: "...", enabled: true } }
+ *
+ * OpenCode 1.18.18 does not have an `mcp.servers` wrapper. It interprets
+ * `servers` as the name of an MCP server and then rejects it with
+ * `Missing key mcp.servers.enabled`. Keep MCP in the documented shape and
+ * normalize old generated V2 entries back to it.
+ */
+function convertMcpV1toV2(mcpConfig) {
+  if (!mcpConfig || typeof mcpConfig !== 'object') return mcpConfig
+
+  const servers = {}
+  const source =
+    mcpConfig.servers && typeof mcpConfig.servers === 'object' && !Array.isArray(mcpConfig.servers)
+      ? { ...mcpConfig, ...mcpConfig.servers }
+      : mcpConfig
+
+  for (const [name, serverConfig] of Object.entries(source)) {
+    if (name === 'servers') continue
+    // Installer versions that seeded the legacy wrapper also wrote a boolean
+    // feature toggle (`servers: { enabled: true }`). After unwrapping, that
+    // toggle surfaces as a non-object entry and is not a server; drop it.
+    if (serverConfig === null || typeof serverConfig !== 'object') continue
+    const srv = { ...serverConfig }
+
+    // Normalize legacy V2's disabled flag to OpenCode 1.18.x's enabled flag.
+    if ('disabled' in srv) {
+      srv.enabled = !srv.disabled
+      delete srv.disabled
+    }
+
+    // Normalize legacy V2's split timeout to the V1/V2-compatible number.
+    if (srv.timeout !== undefined && srv.timeout !== null) {
+      if (typeof srv.timeout === 'object') {
+        srv.timeout = srv.timeout.execution || srv.timeout.catalog || 30000
+      }
+    }
+
+    // A shorthand inherited-server override is valid only when named directly.
+    // Runtime MCP entries always have a complete config, so leave other values
+    // untouched and avoid dropping user-owned servers.
+    servers[name] = srv
+  }
+
+  return servers
+}
+
+/**
+ * Convert V2 MCP config back to V1.
+ */
+function convertMcpV2toV1(mcpConfig) {
+  if (!mcpConfig || typeof mcpConfig !== 'object') return mcpConfig
+
+  return convertMcpV1toV2(mcpConfig)
+}
+
+// ---------------------------------------------------------------------------
+// Top-level key mappings
+// ---------------------------------------------------------------------------
+
+const V1_TO_V2_RENAMES = {
+  provider: 'providers',
+  agent: 'agents',
+  command: 'commands',
+  reference: 'references',
+  snapshot: 'snapshots',
+  attachment: 'media',
+  permission: 'permissions',
+}
+
+/** Build reverse map */
+const V2_TO_V1_RENAMES = Object.fromEntries(
+  Object.entries(V1_TO_V2_RENAMES).map(([k, v]) => [v, k])
+)
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Migrate a V1 opencode.json config to V2 format.
+ *
+ * @param {object} config - V1 config object (not mutated)
+ * @returns {object} V2 config object
+ */
+export function migrateV1toV2(config) {
+  const c = deepClone(config)
+  const result = {}
+
+  for (const [key, value] of Object.entries(c)) {
+    const v2Key = V1_TO_V2_RENAMES[key] || key
+
+    if (key === 'permission' && typeof value === 'object' && value !== null) {
+      result.permissions = convertPermissionsV1toV2(value)
+    } else if (key === 'agent' && typeof value === 'object' && value !== null) {
+      const agents = {}
+      for (const [agentName, agentConfig] of Object.entries(value)) {
+        const ac = { ...agentConfig }
+        if (ac.permission && typeof ac.permission === 'object') {
+          ac.permissions = convertPermissionsV1toV2(ac.permission)
+          delete ac.permission
+        }
+        agents[agentName] = ac
+      }
+      result.agents = agents
+    } else if (key === 'provider' && typeof value === 'object' && value !== null) {
+      const providers = {}
+      for (const [provName, provConfig] of Object.entries(value)) {
+        const renamed = PROVIDER_RENAME[provName] || provName
+        providers[renamed] = convertProviderV1toV2(provName, provConfig)
+      }
+      result.providers = providers
+    } else if (key === 'mcp' && typeof value === 'object' && value !== null) {
+      result.mcp = convertMcpV1toV2(value)
+    } else if (v2Key !== key) {
+      result[v2Key] = value
+    } else {
+      result[key] = value
+    }
+  }
+
+  return result
+}
+
+/**
+ * Migrate a V2 opencode.json config back to V1 format.
+ *
+ * @param {object} config - V2 config object (not mutated)
+ * @returns {object} V1 config object
+ */
+export function migrateV2toV1(config) {
+  const c = deepClone(config)
+  const result = {}
+
+  for (const [key, value] of Object.entries(c)) {
+    const v1Key = V2_TO_V1_RENAMES[key] || key
+
+    if (key === 'permissions' && Array.isArray(value)) {
+      result.permission = convertPermissionsV2toV1(value)
+    } else if (key === 'agents' && typeof value === 'object' && value !== null) {
+      const agents = {}
+      for (const [agentName, agentConfig] of Object.entries(value)) {
+        const ac = { ...agentConfig }
+        if (Array.isArray(ac.permissions)) {
+          ac.permission = convertPermissionsV2toV1(ac.permissions)
+          delete ac.permissions
+        }
+        agents[agentName] = ac
+      }
+      result.agent = agents
+    } else if (key === 'providers' && typeof value === 'object' && value !== null) {
+      const providers = {}
+      for (const [provName, provConfig] of Object.entries(value)) {
+        const renamed = PROVIDER_RENAME_REVERSE[provName] || provName
+        providers[renamed] = convertProviderV2toV1(provName, provConfig)
+      }
+      result.provider = providers
+    } else if (key === 'mcp' && typeof value === 'object' && value !== null) {
+      result.mcp = convertMcpV2toV1(value)
+    } else if (v1Key !== key) {
+      result[v1Key] = value
+    } else {
+      result[key] = value
+    }
+  }
+
+  return result
+}

package/scripts/install/health-check.mjs

@@ -18,12 +18,12 @@ import { join } from 'node:path'
  * NON-FATAL — all checks are reported, none throw.
  *
  * @param {string} target - Installation directory
- * @param {{ dryRun?: boolean }} [options]
+ * @param {{ dryRun?: boolean; pythonTarget?: string }} [options]
  * @returns {{ passed: Array<{check: string, detail: string}>, failed: Array<{check: string, detail: string}>, warnings: Array<{check: string, detail: string}> }}
  */
-export function healthCheck(target, { dryRun = false } = {}) {
+export function healthCheck(target, { dryRun = false, pythonTarget = target } = {}) {
   const results = { passed: [], failed: [], warnings: [] }
-  const python = findPython(target)
+  const python = findPython(pythonTarget)
   const visionServer = resolveVisionServer(target)
 
   // Check 1: Critical runtime scripts exist

package/scripts/install/model-picker.mjs

@@ -14,7 +14,14 @@
  * "herdar do chat" (inherit) é o default da Q1: não grava active-preset.json,
  * então os delegates herdam o modelo do chat pai (herança nativa, sem preset).
  */
-import { copyFileSync, existsSync, mkdirSync, renameSync, writeFileSync, readFileSync } from 'node:fs'
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { createInterface } from 'node:readline/promises'
@@ -22,10 +29,22 @@ import { loadPresetDefs } from '../../src/pantheon/presets.mjs'
 
 /** Preset pricing table (2026 verified). */
 export const PRESET_PRICE = {
-  'go-free': { label: 'Gratuito', detail: 'Zen free – sem custo, quota limitada, só modelos -free' },
-  'go-fast': { label: 'Baixo custo', detail: 'Go gateway – baixa latência, kimi-k2.7-code / glm-5.3-flash' },
-  'go-premium': { label: 'Premium', detail: 'Go gateway – melhor qualidade, gpt-5.6-sol / qwen3.8-max / deepseek-v4-pro' },
-  openai: { label: 'Pago (OpenAI)', detail: 'Direto OpenAI – https://api.openai.com/v1, gpt-5.6 family' },
+  'go-free': {
+    label: 'Gratuito',
+    detail: 'Zen free – sem custo, quota limitada, só modelos -free',
+  },
+  'go-fast': {
+    label: 'Baixo custo',
+    detail: 'Go gateway – baixa latência, kimi-k2.7-code / glm-5.3-flash',
+  },
+  'go-premium': {
+    label: 'Premium',
+    detail: 'Go gateway – melhor qualidade, gpt-5.6-sol / qwen3.8-max / deepseek-v4-pro',
+  },
+  openai: {
+    label: 'Pago (OpenAI)',
+    detail: 'Direto OpenAI – https://api.openai.com/v1, gpt-5.6 family',
+  },
 }
 
 /**
@@ -37,7 +56,9 @@ export const PRESET_PRICE = {
 export function requiredKeyEnvForPreset(name, def) {
   if (name === 'openai') return 'OPENAI_API_KEY'
   // all Go presets use PANTHEON_OPENCODE_API_KEY (alias OPENCODE_GO_API_KEY)
-  const providerEnvs = Object.values(def?.providers ?? {}).map((p) => p.apiKeyEnv).filter(Boolean)
+  const providerEnvs = Object.values(def?.providers ?? {})
+    .map((p) => p.apiKeyEnv)
+    .filter(Boolean)
   if (providerEnvs.includes('PANTHEON_OPENCODE_API_KEY')) return 'PANTHEON_OPENCODE_API_KEY'
   if (providerEnvs.includes('OPENAI_API_KEY')) return 'OPENAI_API_KEY'
   return 'PANTHEON_OPENCODE_API_KEY'
@@ -134,8 +155,14 @@ export function buildInitQuestions(presetDefs) {
       header: 'Escopo',
       question: 'Onde salvar o preset ativo?',
       options: [
-        { label: 'project', description: './.pantheon/active-preset.json (escopo do projeto, seguro)' },
-        { label: 'global', description: '~/.config/opencode/.pantheon/active-preset.json (global)' },
+        {
+          label: 'project',
+          description: './.pantheon/active-preset.json (escopo do projeto, seguro)',
+        },
+        {
+          label: 'global',
+          description: '~/.config/opencode/.pantheon/active-preset.json (global)',
+        },
       ],
       multiSelect: false,
     },
@@ -238,7 +265,10 @@ export async function runModelPicker({
   }
 
   const list = names
-    .map((n, i) => `  ${i + 1}) ${n} — ${defs[n].description ?? ''} | ${buildPresetTableRow(n, defs[n])}`)
+    .map(
+      (n, i) =>
+        `  ${i + 1}) ${n} — ${defs[n].description ?? ''} | ${buildPresetTableRow(n, defs[n])}`,
+    )
     .join('\n')
   const rli = rl ?? createInterface({ input: process.stdin, output: process.stdout })
   try {
@@ -319,7 +349,7 @@ export async function runInitWizard({
   } else {
     // Fallback: readline 3-step wizard
     const rli = rl ?? createInterface({ input: process.stdin, output: process.stdout })
-    let closeAfter = !rl
+    const closeAfter = !rl
     try {
       // Q1: perfil (0 = herdar do chat, default)
       const list = [
@@ -353,20 +383,22 @@ export async function runInitWizard({
       // Q2: key masked
       const requiredEnv = requiredKeyEnvForPreset(presetName, defs[presetName])
       const aliasNote =
-        requiredEnv === 'PANTHEON_OPENCODE_API_KEY'
-          ? ' (alias OPENCODE_GO_API_KEY aceito)'
-          : ''
+        requiredEnv === 'PANTHEON_OPENCODE_API_KEY' ? ' (alias OPENCODE_GO_API_KEY aceito)' : ''
       const envConfigured = isKeyConfiguredForPreset(env, presetName, defs[presetName])
       let keyAnswer = ''
       if (envConfigured) {
-        logger.log?.(`Chave ${requiredEnv}${aliasNote} já configurada no ambiente (mascarada: ${maskKey(env[requiredEnv] ?? env.OPENCODE_GO_API_KEY ?? '')}).`)
+        logger.log?.(
+          `Chave ${requiredEnv}${aliasNote} já configurada no ambiente (mascarada: ${maskKey(env[requiredEnv] ?? env.OPENCODE_GO_API_KEY ?? '')}).`,
+        )
       } else {
         // masked collection
         const prompt = `[2/3] Informe ${requiredEnv}${aliasNote} (entrada mascarada, não escreve .env): `
         // Use questionMasked for tests; real TTY would mask
         keyAnswer = (await questionMasked(rli, prompt)).trim()
         if (keyAnswer === '') {
-          logger.warn?.(`Chave vazia para ${requiredEnv} — wizard canceled. Preencha env ${requiredEnv} antes de continuar.`)
+          logger.warn?.(
+            `Chave vazia para ${requiredEnv} — wizard canceled. Preencha env ${requiredEnv} antes de continuar.`,
+          )
           return null
         }
         // validate non-empty already; optionally check length
@@ -374,7 +406,9 @@ export async function runInitWizard({
           // For health-check, set in current env (not .env file) for this session
           // Prefer primary var
           env[requiredEnv] = keyAnswer
-          logger.log?.(`Chave coletada (mascarada: ${maskKey(keyAnswer)}). Defina export ${requiredEnv}='${maskKey(keyAnswer)}' no seu shell para persistir (não escrevemos .env).`)
+          logger.log?.(
+            `Chave coletada (mascarada: ${maskKey(keyAnswer)}). Defina export ${requiredEnv}='${maskKey(keyAnswer)}' no seu shell para persistir (não escrevemos .env).`,
+          )
         }
       }
 
@@ -398,8 +432,14 @@ export async function runInitWizard({
     })()
     const dir = scope === 'global' ? globalDir : projectDir
     if (!dryRun) {
-      const result = writeActivePreset(dir, presetName, { dryRun: false, source: 'interactive', logger })
-      logger.log?.(`Preset ${presetName} salvo em ${scope} (${result.path})${result.backupPath ? ` backup: ${result.backupPath}` : ''}`)
+      const result = writeActivePreset(dir, presetName, {
+        dryRun: false,
+        source: 'interactive',
+        logger,
+      })
+      logger.log?.(
+        `Preset ${presetName} salvo em ${scope} (${result.path})${result.backupPath ? ` backup: ${result.backupPath}` : ''}`,
+      )
       // health-check: verify file
       try {
         const raw = readFileSync(result.path, 'utf8')
@@ -423,15 +463,18 @@ export async function runInitWizard({
     const a2 = answers[2]?.answer ?? answers[2]
     presetName = a0 && typeof a0 === 'object' && 'label' in a0 ? a0.label : a0
     keyAnswer = a1 && typeof a1 === 'object' && 'answer' in a1 ? a1.answer : a1
-    if (keyAnswer && typeof keyAnswer === 'object' && 'label' in keyAnswer) keyAnswer = keyAnswer.label
+    if (keyAnswer && typeof keyAnswer === 'object' && 'label' in keyAnswer)
+      keyAnswer = keyAnswer.label
     scope = a2 && typeof a2 === 'object' && 'label' in a2 ? a2.label : a2
     if (scope && typeof scope === 'object' && 'answer' in scope) scope = scope.answer
   } else if (answers && typeof answers === 'object') {
     presetName = answers.preset ?? answers['0'] ?? answers.q1 ?? answers.presetName
     keyAnswer = answers.key ?? answers['1'] ?? answers.q2
     scope = answers.scope ?? answers['2'] ?? answers.q3
-    if (presetName && typeof presetName === 'object' && 'label' in presetName) presetName = presetName.label
-    if (presetName && typeof presetName === 'object' && 'answer' in presetName) presetName = presetName.answer
+    if (presetName && typeof presetName === 'object' && 'label' in presetName)
+      presetName = presetName.label
+    if (presetName && typeof presetName === 'object' && 'answer' in presetName)
+      presetName = presetName.answer
     if (scope && typeof scope === 'object' && 'label' in scope) scope = scope.label
     if (scope && typeof scope === 'object' && 'answer' in scope) scope = scope.answer
   }
@@ -459,7 +502,9 @@ export async function runInitWizard({
   }
   if (keyAnswer && !dryRun) {
     env[requiredEnv] = keyAnswer
-    logger.log?.(`Chave coletada (mascarada: ${maskKey(String(keyAnswer))}). Não escrevemos .env; export ${requiredEnv} no shell para persistir.`)
+    logger.log?.(
+      `Chave coletada (mascarada: ${maskKey(String(keyAnswer))}). Não escrevemos .env; export ${requiredEnv} no shell para persistir.`,
+    )
   }
   const finalScope = scope === 'global' ? 'global' : 'project'
   const projectDir = presetDir ?? target ?? process.cwd()
@@ -470,7 +515,11 @@ export async function runInitWizard({
   })()
   const dir = finalScope === 'global' ? globalDir : projectDir
   if (!dryRun) {
-    const result = writeActivePreset(dir, presetName, { dryRun: false, source: 'interactive', logger })
+    const result = writeActivePreset(dir, presetName, {
+      dryRun: false,
+      source: 'interactive',
+      logger,
+    })
     logger.log?.(`Preset ${presetName} salvo em ${finalScope} (${result.path})`)
     try {
       const raw = readFileSync(result.path, 'utf8')

package/scripts/install/opencode-version.mjs

@@ -0,0 +1,47 @@
+/** OpenCode major-version selection shared by the CLI and installer. */
+
+const VALID_VERSIONS = new Set(['v1', 'v2', 'auto'])
+
+/** @param {string[]} args @returns {'v1'|'v2'|'auto'|null} */
+export function parseOpenCodeVersion(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg.startsWith('--opencode-version=')) return normalize(arg.split('=', 2)[1])
+    if (arg === '--opencode-version') return normalize(args[index + 1])
+    // --version v1|v2 was supported by 1.4.x. Bare --version remains the
+    // package version command and is deliberately not interpreted here.
+    if (arg.startsWith('--version=')) return normalize(arg.split('=', 2)[1])
+    if (arg === '--version' && args[index + 1]?.startsWith('v')) {
+      // Preserve bare --version/package-version compatibility, while making
+      // unsupported OpenCode selectors (for example v3) fail loudly.
+      return normalize(args[index + 1])
+    }
+  }
+  return null
+}
+
+function normalize(value) {
+  if (!VALID_VERSIONS.has(value)) {
+    throw new Error(`Invalid OpenCode version "${value}" — expected v1, v2, or auto`)
+  }
+  return value
+}
+
+/**
+ * Resolve auto conservatively: only an explicit hint selects V2.
+ * @param {'v1'|'v2'|'auto'|null|undefined} requested
+ * @param {{env?: Record<string, string|undefined>, binary?: string}} [options]
+ * @returns {'v1'|'v2'}
+ */
+export function resolveOpenCodeVersion(requested = 'v1', options = {}) {
+  if (!VALID_VERSIONS.has(requested)) {
+    throw new Error(`Invalid OpenCode version "${requested}" — expected v1, v2, or auto`)
+  }
+  if (requested === 'v1' || requested === 'v2') return requested
+  const env = options.env ?? process.env
+  if (env.OPENCODE_VERSION === 'v1' || env.OPENCODE_VERSION === 'v2') {
+    return env.OPENCODE_VERSION
+  }
+  const binary = options.binary ?? env.OPENCODE_BIN ?? ''
+  return /(?:^|[\\/])opencode2(?:\.exe)?$/i.test(binary) ? 'v2' : 'v1'
+}