pantheon-opencode 1.5.0-beta.4 → 1.5.0-beta.5

package/scripts/doctor.mjs

@@ -22,7 +22,8 @@
  */
 
 import { spawn as spawnAsync, spawnSync } from 'node:child_process'
-import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -389,7 +390,7 @@ function checkMcpConfig(args) {
     // ENOENT-on-spawn failure class (dead hardcoded path, ambiguous relative
     // path) before opencode tries to spawn the server.
     for (const [name, mcpEntry] of Object.entries(mcp)) {
-      if (!mcpEntry || mcpEntry.type !== 'local') continue
+      if (mcpEntry?.type !== 'local') continue
       const cmd = mcpEntry.command
       if (!Array.isArray(cmd) || cmd.length === 0) {
         warn(`${cfg.label}: MCP "${name}" has no command array`)
@@ -530,7 +531,7 @@ async function checkMcpRuntimeSmoke(args) {
   const local = []
   for (const cfg of collectMcpConfigs(args)) {
     for (const [name, entry] of Object.entries(cfg.data.mcp ?? {})) {
-      if (!entry || entry.type !== 'local') continue
+      if (entry?.type !== 'local') continue
       if (!Array.isArray(entry.command) || entry.command.length === 0) continue
       const cwd = resolveMcpCwd(entry, cfg.path)
       const command = entry.command.map((part, index) =>
@@ -966,12 +967,20 @@ function checkVenvLayer(args) {
  */
 export function checkCodeModeDir(args) {
   section('F.2 Code-Mode Scripts')
-  const target = resolve(args.target)
-  const isProject = existsSync(join(target, '.opencode'))
-  const runtimeRoot = isProject ? target : resolveOpenCodeConfigDir(args.env ?? process.env)
-  const codeModeDir = isProject
-    ? join(runtimeRoot, '.opencode', '.pantheon', 'code-mode')
-    : join(runtimeRoot, '.pantheon', 'code-mode')
+  const env = args.env ?? process.env
+  const target = resolve(env.PANTHEON_PROJECT ?? args.target)
+  const projectCandidates = [
+    join(target, '.opencode', '.pantheon', 'code-mode'),
+    join(target, '.pantheon', 'code-mode'),
+  ]
+  // Seeding semantics: an existing project candidate wins; a project
+  // install (.opencode present) gets its runtime dir created when missing.
+  // Only targets with no project layout fall back to the global config dir.
+  const codeModeDir =
+    projectCandidates.find((candidate) => existsSync(candidate)) ??
+    (existsSync(join(target, '.opencode'))
+      ? projectCandidates[0]
+      : join(resolveOpenCodeConfigDir(env), '.pantheon', 'code-mode'))
   if (existsSync(codeModeDir)) {
     pass(`Code-mode scripts directory exists: ${codeModeDir}`)
     return codeModeDir
@@ -986,6 +995,83 @@ export function checkCodeModeDir(args) {
   return codeModeDir
 }
 
+/** Resolve code-mode using the same project-first rule as the MCP server. */
+export function resolveCodeModeDir(args) {
+  const env = args.env ?? process.env
+  const target = resolve(env.PANTHEON_PROJECT ?? args.target)
+  const projectCandidates = [
+    join(target, '.opencode', '.pantheon', 'code-mode'),
+    join(target, '.pantheon', 'code-mode'),
+  ]
+  const projectDir = projectCandidates.find((candidate) => existsSync(candidate))
+  if (projectDir) return projectDir
+  return join(resolveOpenCodeConfigDir(env), '.pantheon', 'code-mode')
+}
+
+/** Validate a code-mode manifest without modifying it. */
+export function validateCodeModeManifest(codeModeDir) {
+  const manifestPath = join(codeModeDir, 'manifest.json')
+  if (!existsSync(manifestPath)) {
+    return { ok: false, message: `Code-mode manifest missing: ${manifestPath}` }
+  }
+
+  let data
+  try {
+    data = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch {
+    return { ok: false, message: `Code-mode manifest malformed: ${manifestPath}` }
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return { ok: false, message: 'Code-mode manifest malformed: root must be an object' }
+  }
+  if (data.version !== 1) {
+    return { ok: false, message: 'Code-mode manifest malformed: version must be 1' }
+  }
+  if (!data.scripts || typeof data.scripts !== 'object' || Array.isArray(data.scripts)) {
+    return { ok: false, message: 'Code-mode manifest malformed: scripts must be an object' }
+  }
+
+  const listed = Object.keys(data.scripts)
+  const invalid = listed.filter(
+    (name) => typeof data.scripts[name] !== 'string' || !/^[a-f0-9]{64}$/i.test(data.scripts[name]),
+  )
+  if (invalid.length) {
+    return { ok: false, message: `Code-mode manifest invalid digest: ${invalid.join(', ')}` }
+  }
+
+  const actualScripts = readdirSync(codeModeDir).filter(
+    (name) =>
+      (name.endsWith('.py') || name.endsWith('.sh')) && statSync(join(codeModeDir, name)).isFile(),
+  )
+  const missing = listed.filter((name) => !existsSync(join(codeModeDir, name)))
+  const extra = actualScripts.filter((name) => !Object.hasOwn(data.scripts, name))
+  const differing = listed.filter((name) => {
+    const path = join(codeModeDir, name)
+    if (!existsSync(path)) return false
+    const digest = createHash('sha256').update(readFileSync(path)).digest('hex')
+    return digest !== data.scripts[name].toLowerCase()
+  })
+  if (missing.length || extra.length || differing.length) {
+    const names = [...new Set([...missing, ...extra, ...differing])]
+    return {
+      ok: false,
+      message: `Code-mode manifest mismatch: ${differing.length + missing.length + extra.length}/${listed.length} scripts differ — ${names.join(', ')}`,
+    }
+  }
+  return { ok: true, count: listed.length, total: actualScripts.length }
+}
+
+/** Run the diagnostic manifest check after directory validation. */
+export function checkCodeModeManifest(args) {
+  const codeModeDir = resolveCodeModeDir(args)
+  const result = validateCodeModeManifest(codeModeDir)
+  if (!result.ok) {
+    error(result.message)
+    return
+  }
+  pass(`✅ Code-mode manifest valid: ${result.count}/${result.total} scripts verified`)
+}
+
 /** Resolve the venv created by init for either a project or global install. */
 export function resolveRuntimePython(args) {
   const target = resolve(args.target)
@@ -1018,6 +1104,87 @@ export function resolveMcpCwd(entry, configPath = '') {
   return dirname(configPath)
 }
 
+// ---------------------------------------------------------------------------
+// Check H2: installed-version drift (beta.5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Prerelease-aware comparison for pantheon versions (X.Y.Z or X.Y.Z-beta.N).
+ * A stable release outranks any beta of the same core version. Returns
+ * <0, 0, >0 (a - b). The shared compareVersions/parseVersion above ignores
+ * the `-beta.N` suffix (it only reads 4 numeric groups), which would make
+ * every beta pair compare equal.
+ */
+function comparePantheonVersions(a, b) {
+  const parse = (v) => {
+    const m = String(v)
+      .trim()
+      .match(/^(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/)
+    if (!m) return null
+    return {
+      core: [+m[1], +m[2], +m[3]],
+      beta: m[4] === undefined ? Number.POSITIVE_INFINITY : +m[4],
+    }
+  }
+  const pa = parse(a)
+  const pb = parse(b)
+  if (!pa || !pb) return 0
+  for (let i = 0; i < 3; i++) {
+    if (pa.core[i] !== pb.core[i]) return pa.core[i] - pb.core[i]
+  }
+  return pa.beta - pb.beta
+}
+
+/**
+ * Compare the version recorded in the installation marker
+ * (<config>/.pantheon/install-state.json, written by the postinstall sync)
+ * against this package's version. When the package is newer, the config
+ * merge/venv/MCP wiring may be stale — point the user at `update`.
+ * Advisory only: a missing marker (pre-beta.5 install) is not an error.
+ */
+export function checkInstallVersionDrift(args) {
+  section('H2 Installed Version')
+  const env = args.env ?? process.env
+  let pkgVersion = null
+  try {
+    pkgVersion = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version
+  } catch {
+    return 'no-marker'
+  }
+  if (!pkgVersion) return 'no-marker'
+
+  const statePath = join(resolveOpenCodeConfigDir(env), '.pantheon', 'install-state.json')
+  let installed = null
+  if (existsSync(statePath)) {
+    try {
+      installed = JSON.parse(readFileSync(statePath, 'utf8')).pantheon_version ?? null
+    } catch {
+      installed = null
+    }
+  }
+  if (!installed) {
+    info('No installation version marker found (pre-beta.5 install) — skipping drift check')
+    return 'no-marker'
+  }
+  const drift = comparePantheonVersions(pkgVersion, installed)
+  if (drift > 0) {
+    warn(
+      `Package v${pkgVersion} is newer than the last-synced installation (v${installed}) — ` +
+        'run `npx pantheon-opencode update` (or re-run init) to refresh config, venv and MCP entries',
+    )
+    return 'package-newer'
+  }
+  if (drift < 0) {
+    warn(
+      `Installation marker (v${installed}) is newer than this package (v${pkgVersion}) — ` +
+        'the doctor is running from a different install than the last sync',
+    )
+    return 'install-newer'
+  }
+  pass(`Installation in sync with package v${pkgVersion}`)
+  return 'sync'
+}
+
 // ---------------------------------------------------------------------------
 // Check G: AGENTS.md freshness
 // ---------------------------------------------------------------------------
@@ -1314,6 +1481,8 @@ async function main() {
   checkMcpConfig(args)
   checkVenvLayer(args)
   checkCodeModeDir(args)
+  checkCodeModeManifest(args)
+  checkInstallVersionDrift(args)
   await checkMcpRuntimeSmoke(args)
   checkPermissionMismatches(args)
   checkSyncStatus(args)

package/scripts/install/cli-ui.mjs

@@ -1,3 +1,5 @@
+import { strings } from './strings.mjs'
+
 export const icons = {
   success: '\u2705',
   warning: '\u26a0\ufe0f ',
@@ -8,9 +10,9 @@ export const icons = {
   arrow: '\u2192',
   bullet: '\u2022',
   star: '\u2b50',
-  wrench: '\U0001f527',
-  rocket: '\U0001f680',
-  package: '\U0001f4e6',
+  wrench: '\u{1F527}',
+  rocket: '\u{1F680}',
+  package: '\u{1F4E6}',
   gear: '\u2699\ufe0f',
 }
 
@@ -160,28 +162,32 @@ export function spinner(message) {
 export function printSummary(target, platforms, stats) {
   if (_quiet) return
 
+  const S = strings()
   const line = '\u2500'.repeat(Math.min(process.stdout.columns || 60, 60))
   const hasErrors = stats && stats.errors > 0
   console.log(
     tag(
       hasErrors
-        ? `${icons.warning} Instalação concluída com erros em ${target}`
-        : `${icons.rocket} OpenCode instalado em ${target}`,
+        ? `${icons.warning} ${S.summaryWithErrors(target)}`
+        : `${icons.rocket} ${S.summaryInstalled(target)}`,
     ),
   )
   console.log(tag(line))
   console.log('')
 
   if (stats) {
-    console.log(tag(`  Componentes:\t${stats.created} instalados, ${stats.skipped} pulados`))
+    console.log(tag(S.summaryComponents(stats.created, stats.skipped)))
     if (stats.errors > 0) {
-      console.warn(tag(`  ${icons.warning}${stats.errors} erro(s) encontrados`))
+      console.warn(tag(S.summaryErrors(stats.errors)))
+    }
+    if (stats.warnings > 0) {
+      console.warn(tag(S.summaryWarnings(stats.warnings)))
     }
     console.log('')
   }
 
-  console.log(tag(`  ${icons.star} Próximos passos:`))
-  console.log(tag(`    ${icons.bullet} Configure seus agentes em opencode.json`))
-  console.log(tag(`    ${icons.bullet} Adicione MCP servers em mcp.json`))
-  console.log(tag(`    ${icons.bullet} Rode 'opencode doctor' para verificar a instalação`))
+  console.log(tag(`  ${icons.star} ${S.summaryNext.trim()}`))
+  console.log(tag(S.summaryNextAgents))
+  console.log(tag(S.summaryNextMcp))
+  console.log(tag(S.summaryNextDoctor))
 }

package/scripts/install/config-migration.mjs

@@ -73,7 +73,7 @@ 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])
+    Object.entries(V1_PERMISSION_TO_ACTION).map(([k, v]) => [v, k]),
   )
 
   for (const { action, resource, effect } of permArray) {
@@ -104,7 +104,7 @@ const PROVIDER_RENAME = {
 
 /** Reverse: V2 → V1 */
 const PROVIDER_RENAME_REVERSE = Object.fromEntries(
-  Object.entries(PROVIDER_RENAME).map(([k, v]) => [v, k])
+  Object.entries(PROVIDER_RENAME).map(([k, v]) => [v, k]),
 )
 
 /**
@@ -176,9 +176,7 @@ function convertProviderV2toV1(name, config) {
 
   // package → npm (strip aisdk: prefix)
   if (result.package !== undefined) {
-    result.npm = result.package.startsWith('aisdk:')
-      ? result.package.slice(6)
-      : result.package
+    result.npm = result.package.startsWith('aisdk:') ? result.package.slice(6) : result.package
     delete result.package
   }
 
@@ -303,7 +301,7 @@ const V1_TO_V2_RENAMES = {
 
 /** Build reverse map */
 const V2_TO_V1_RENAMES = Object.fromEntries(
-  Object.entries(V1_TO_V2_RENAMES).map(([k, v]) => [v, k])
+  Object.entries(V1_TO_V2_RENAMES).map(([k, v]) => [v, k]),
 )
 
 // ---------------------------------------------------------------------------

package/scripts/install/opencode.mjs

@@ -35,6 +35,7 @@ import { detectVersion, runMigrations } from './migrate.mjs'
 import { resolveOpenCodeVersion } from './opencode-version.mjs'
 import { copyPluginFiles, installPlugin, registerPlugin, unregisterPlugin } from './plugin.mjs'
 import {
+  checkRuntimePrerequisites,
   collectSkillNames,
   copyFiles,
   installSkills,
@@ -43,8 +44,10 @@ import {
   sourceDirValid,
   summary,
   syncDir,
+  writeConfigWithBackup,
   writeIfChanged,
 } from './shared.mjs'
+import { strings } from './strings.mjs'
 
 import { setupVenv, venvPythonPath } from './venv.mjs'
 
@@ -372,6 +375,45 @@ export function syncTuiRegistration(target, { isGlobal = false, dryRun = false }
   return registerPlugin(targetTuiConfigPath, tuiCopyDir, { dryRun })
 }
 
+/**
+ * beta.5: set up the Python venv + run the health check. Never throws —
+ * failures are reported as warnings and return false so the caller omits
+ * MCP entries from the config (entries pointing at a missing venv would
+ * make every MCP fail to launch). `deps` is injectable for tests.
+ */
+export function setupRuntimePhase(target, { dryRun, clean, isGlobal }, stats, deps = {}) {
+  const S = strings()
+  const setup = deps.setupVenv ?? setupVenv
+  const check = deps.healthCheck ?? healthCheck
+  try {
+    const venvSpinner = spinner(S.settingUpRuntime)
+    setup(target, { dryRun, force: clean })
+    venvSpinner(true)
+    const runtimeTarget = isGlobal ? target : join(target, '.opencode')
+    const health = check(runtimeTarget, { dryRun, pythonTarget: target })
+
+    section(`\uD83D\uDD0D ${S.healthSection}`)
+    const healthStep = step(S.runningHealthChecks)
+    for (const p of health.passed) success(`${p.check}: ${p.detail}`)
+    for (const w of health.warnings) warning(`${w.check}: ${w.detail}`)
+    for (const f of health.failed) error(`${f.check}: ${f.detail}`)
+
+    if (health.failed.length > 0) {
+      healthStep(false)
+      warning(`${health.failed.length} check(s) failed — review above`)
+      stats.warnings += health.failed.length
+      return false
+    }
+    healthStep(true)
+    return true
+  } catch (err) {
+    error(S.runtimeFailed(err.message))
+    warning(S.runtimeSkippedMcp)
+    stats.warnings += 1
+    return false
+  }
+}
+
 export async function installOpenCode(
   target,
   dryRun = false,
@@ -386,6 +428,7 @@ export async function installOpenCode(
 
   const componentSet = new Set(components)
   const stats = summary.opencode
+  const S = strings()
 
   // V1/V2 dual-version awareness (Phase 3): the installer builds a unified
   // config, then applies V2-native migration (migrateV1toV2) when
@@ -434,6 +477,17 @@ export async function installOpenCode(
   const config = readJsonConfig(targetConfigPath)
   const pantheonConfig = readJsonConfig(pantheonConfigPath)
 
+  // beta.5 preflight: fail BEFORE any files are written when the runtime
+  // component needs toolchain pieces that are missing. Nothing has been
+  // copied yet at this point, so the failure is clean.
+  if (componentSet.has('runtime') && !dryRun) {
+    const missing = checkRuntimePrerequisites()
+    if (missing.length > 0) {
+      for (const problem of missing) error(problem)
+      throw new Error(S.prereqMissing)
+    }
+  }
+
   // Determine layout based on install scope.
   // Global config dir (~/.opencode or ~/.config/opencode) uses a flat layout:
   //   agents/   skills/   commands/   plugins/
@@ -446,7 +500,7 @@ export async function installOpenCode(
   configure({ dryRun })
 
   if (isGlobal) {
-    info('Global config directory detected — using flat layout (agents/, skills/, commands/)')
+    info(S.globalLayout)
   }
 
   // -----------------------------------------------------------------------
@@ -459,7 +513,7 @@ export async function installOpenCode(
       warning(`Agent source directory not found: ${srcDir}`)
       stats.errors++
     } else {
-      const agentStep = step('Installing agents')
+      const agentStep = step(S.installingAgents)
       const dstDir = isGlobal ? join(target, 'agents') : join(target, '.opencode', 'agents')
       if (!dryRun) mkdirSync(dstDir, { recursive: true })
       if (clean && existsSync(dstDir) && !dryRun) {
@@ -712,6 +766,17 @@ export async function installOpenCode(
     }
   }
 
+  // -----------------------------------------------------------------------
+  // 2.11 Setup virtual environment + health check (--components runtime)
+  // beta.5: runs BEFORE the config write and is no longer fatal — on failure
+  // the install completes without MCP entries (which would point at a venv
+  // that does not exist) instead of aborting a half-done installation.
+  // -----------------------------------------------------------------------
+  let runtimeHealthy = !componentSet.has('runtime')
+  if (componentSet.has('runtime')) {
+    runtimeHealthy = setupRuntimePhase(target, { dryRun, clean, isGlobal }, stats)
+  }
+
   // -----------------------------------------------------------------------
   // 3. Create/update opencode.json (always runs)
   //    Reads TARGET's existing config first, then merges Pantheon settings
@@ -1053,8 +1118,10 @@ export async function installOpenCode(
 
   // --------------------------------------------------------------------
   // F.5 MCP server entries (for runtime-deployed scripts)
+  // beta.5: skipped when the Python runtime setup failed — entries pointing
+  // at a venv that does not exist would make every MCP fail to launch.
   // --------------------------------------------------------------------
-  if (componentSet.has('runtime')) {
+  if (componentSet.has('runtime') && runtimeHealthy) {
     config.mcp = config.mcp || {}
     // MCP stays a flat named-server map for BOTH V1 and V2: OpenCode 1.18.x
     // has no `mcp.servers` wrapper and rejects one with
@@ -1138,12 +1205,12 @@ export async function installOpenCode(
   // before writing. V1 path is untouched (zero regression).
   let configToWrite = config
   if (version === 'v2') {
-    info('Migrating config to V2 native format...')
+    info(S.v2Migrating)
     configToWrite = migrateV1toV2(config)
   }
 
   const configContent = `${JSON.stringify(configToWrite, null, 2)}\n`
-  const status = writeIfChanged(targetConfigPath, configContent, dryRun)
+  const status = writeConfigWithBackup(targetConfigPath, configContent, dryRun)
   if (status === 'created') stats.created++
   else stats.skipped++
 
@@ -1164,40 +1231,15 @@ export async function installOpenCode(
   }
 
   // -----------------------------------------------------------------------
-  // 4. Setup virtual environment + health check (--components runtime)
+  // 4. (runtime setup moved to 2.11 — before the config write — so MCP
+  //    entries are only added when the Python runtime is actually healthy)
   // -----------------------------------------------------------------------
-  if (componentSet.has('runtime')) {
-    try {
-      const venvSpinner = spinner('Setting up Python virtual environment')
-      setupVenv(target, { dryRun, force: clean })
-      venvSpinner(true)
-      const runtimeTarget = isGlobal ? target : join(target, '.opencode')
-      const health = healthCheck(runtimeTarget, { dryRun, pythonTarget: target })
-
-      // Print health summary
-      section('\uD83D\uDD0D Health Check')
-      const healthStep = step('Running health checks')
-      for (const p of health.passed) success(`${p.check}: ${p.detail}`)
-      for (const w of health.warnings) warning(`${w.check}: ${w.detail}`)
-      for (const f of health.failed) error(`${f.check}: ${f.detail}`)
-
-      if (health.failed.length > 0) {
-        healthStep(false)
-        warning(`${health.failed.length} check(s) failed — review above`)
-        stats.errors += health.failed.length
-      } else {
-        healthStep(true)
-      }
-    } catch (err) {
-      error(`Setup failed: ${err.message}`)
-      throw err // Fatal — abort installation
-    }
-  }
 
   if (interactive && !dryRun) {
     const created = stats.created
     const skipped = stats.skipped
     const errors = stats.errors
+    const warnings = stats.warnings ?? 0
 
     process.stdout.write('\n')
     process.stdout.write(
@@ -1215,11 +1257,14 @@ export async function installOpenCode(
       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 (warnings > 0)
+      process.stdout.write(
+        `  ${colors.yellow('\u26a0')} ${warnings} warning(s) — run 'pantheon-opencode doctor' for details\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 'pantheon-opencode doctor' to verify\n`)
     process.stdout.write(
       `  ${colors.dim('\u2022')} Run 'opencode' to start using Pantheon agents\n`,
     )

package/scripts/install/shared.mjs

@@ -2,12 +2,15 @@
  * shared.mjs — Shared utilities for the OpenCode installer
  */
 
+import { spawnSync } from 'node:child_process'
 import {
+  copyFileSync,
   cpSync,
   existsSync,
   mkdirSync,
   readdirSync,
   readFileSync,
+  renameSync,
   rmSync,
   statSync,
   writeFileSync,
@@ -41,7 +44,7 @@ export function getAgentNames() {
 // Cached constant for backward compatibility
 export const AGENT_NAMES = getAgentNames()
 
-export const summary = { opencode: { created: 0, skipped: 0, errors: 0 } }
+export const summary = { opencode: { created: 0, skipped: 0, errors: 0, warnings: 0 } }
 
 export function showHelp() {
   console.log(`
@@ -260,11 +263,49 @@ export function writeIfChanged(filePath, content, dryRun) {
     return 'skipped'
   }
   if (!dryRun) {
-    writeFileSync(filePath, content, 'utf8')
+    // Atomic write: write a temp sibling and rename over the target so a
+    // crash mid-write can never leave a truncated file behind (rename is
+    // atomic within the same directory).
+    const tmpPath = `${filePath}.tmp-${process.pid}`
+    writeFileSync(tmpPath, content, 'utf8')
+    renameSync(tmpPath, filePath)
   }
   return 'created'
 }
 
+/**
+ * beta.5: write the user's opencode.json with a same-directory backup of the
+ * previous content. The installer rewrites the whole config; a `.bak` gives
+ * the user a one-step recovery if a merge ever goes wrong.
+ */
+export function writeConfigWithBackup(filePath, content, dryRun) {
+  if (!dryRun && existsSync(filePath)) {
+    copyFileSync(filePath, `${filePath}.bak`)
+  }
+  return writeIfChanged(filePath, content, dryRun)
+}
+
+/**
+ * beta.5 preflight: verify the toolchain pieces the runtime component needs
+ * BEFORE any files are written, so a missing python3/npm fails in seconds
+ * with a clear message instead of aborting a half-done install.
+ * Returns a list of human-readable problems (empty = all good).
+ */
+export function checkRuntimePrerequisites(env = process.env) {
+  const problems = []
+  const checks = [
+    { cmd: 'python3', hint: 'install Python 3.10+ (https://www.python.org/downloads/)' },
+    { cmd: 'npm', hint: 'install Node.js 22+ (https://nodejs.org) — npm ships with it' },
+  ]
+  for (const { cmd, hint } of checks) {
+    const probe = spawnSync(cmd, ['--version'], { encoding: 'utf8', timeout: 10_000, env })
+    if (probe.error || probe.status !== 0) {
+      problems.push(`${cmd} not found or not runnable — ${hint}`)
+    }
+  }
+  return problems
+}
+
 export function collectSkillNames() {
   const skillsDir = join(ROOT, 'src', 'skills')
   if (!existsSync(skillsDir)) return []