pantheon-opencode 1.1.1-beta.3 → 1.1.1-beta.5

package/scripts/install/opencode.mjs

@@ -3,17 +3,16 @@
  * opencode.mjs — OpenCode platform installer
  */
 
-import { execSync } from 'node:child_process'
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 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 {
   collectSkillNames,
   copyFiles,
   installSkills,
-  PLATFORM_DIR,
   parseFrontmatter,
   ROOT,
   sourceDirValid,
@@ -22,6 +21,10 @@ 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']
 
 function deepClone(value) {
   return JSON.parse(JSON.stringify(value))
@@ -71,11 +74,12 @@ function isGlobalConfigDir(target) {
   return resolve(target) === xdgDir
 }
 
-export function installOpenCode(
+export async function installOpenCode(
   target,
   dryRun = false,
   clean = false,
   components = ['agents', 'skills', 'instructions', 'commands', 'plugins', 'runtime'],
+  opts = {},
 ) {
   // Default target if not provided (global ~/.config/opencode)
   if (!target) {
@@ -85,6 +89,35 @@ export function installOpenCode(
   const componentSet = new Set(components)
   const stats = summary.opencode
 
+  // Interactive mode handling
+  const stdinTTY = process.stdin.isTTY && process.stdout.isTTY
+  const forceInteractive = opts.interactive === true
+  const forceHeadless = opts.headless === true
+  const autoYes = opts.yes === true
+  const interactive = forceInteractive || (stdinTTY && !forceHeadless)
+
+  if (interactive && !dryRun) {
+    const { runInteractiveInstall } = await import('./interactive.mjs')
+    const result = await runInteractiveInstall({
+      components,
+      defaultComponents: COMPONENT_NAMES,
+    })
+
+    if (!result.confirmed && !autoYes) {
+      info('Installation canceled.')
+      return stats
+    }
+
+    // Map target selection to actual path
+    const newComponents = [...result.components]
+    componentSet.clear()
+    for (const c of newComponents) componentSet.add(c)
+
+    if (result.target === 'project') {
+      target = process.cwd()
+    }
+  }
+
   // Determine layout based on install scope.
   // Global config dir (~/.opencode or ~/.config/opencode) uses a flat layout:
   //   agents/   skills/   commands/   plugins/
@@ -94,21 +127,23 @@ export function installOpenCode(
   const _subDir = isGlobal ? '' : '.opencode'
   const agentPrefix = isGlobal ? 'agents' : '.opencode/agents'
 
+  configure({ dryRun })
+
   if (isGlobal) {
-    console.log(
-      '  🌐 Global config directory detected — using flat layout (agents/, skills/, commands/)',
-    )
+    info('Global config directory detected — using flat layout (agents/, skills/, commands/)')
   }
 
   // -----------------------------------------------------------------------
   // 1. Install agents (--components agents)
   // -----------------------------------------------------------------------
   if (componentSet.has('agents')) {
+    section('\uD83D\uDCE6 Agents')
     const srcDir = join(ROOT, 'src', 'agents')
     if (!sourceDirValid(srcDir)) {
-      console.warn(`  ⚠️  Agent source directory not found: ${srcDir}`)
+      warning(`Agent source directory not found: ${srcDir}`)
       stats.errors++
     } else {
+      const agentStep = step('Installing agents')
       const dstDir = isGlobal ? join(target, 'agents') : join(target, '.opencode', 'agents')
       if (!dryRun) mkdirSync(dstDir, { recursive: true })
       if (clean && existsSync(dstDir) && !dryRun) {
@@ -120,6 +155,7 @@ export function installOpenCode(
       const { created, skipped } = copyFiles(srcDir, dstDir, dryRun)
       stats.created += created
       stats.skipped += skipped
+      agentStep(true)
     }
   }
 
@@ -139,9 +175,10 @@ export function installOpenCode(
   // 2. Install skills (--components skills)
   // -----------------------------------------------------------------------
   if (componentSet.has('skills')) {
+    section('\uD83D\uDCDA Skills')
     const skillNames = collectSkillNames()
     if (skillNames.length > 0) {
-      console.log(`  📚 Installing ${skillNames.length} skills...`)
+      const skillStep = step(`Installing ${skillNames.length} skills`)
       const dstSkillsDir = isGlobal ? join(target, 'skills') : join(target, '.opencode', 'skills')
       if (clean && existsSync(dstSkillsDir) && !dryRun) {
         const existing = readdirSync(dstSkillsDir)
@@ -158,6 +195,7 @@ export function installOpenCode(
       )
       stats.created += sCreated
       stats.skipped += sSkipped
+      skillStep(true)
     }
   }
 
@@ -165,6 +203,7 @@ export function installOpenCode(
   // 2.5 Install instructions: AGENTS.md + instructions/ (--components instructions)
   // -----------------------------------------------------------------------
   if (componentSet.has('instructions')) {
+    section('\uD83D\uDCCB Instructions')
     // AGENTS.md
     const srcAgentsMd = join(ROOT, 'AGENTS.md')
     const dstAgentsMd = join(target, 'AGENTS.md')
@@ -188,6 +227,7 @@ export function installOpenCode(
   // 2.6 Install prompts (--components prompts)
   // -----------------------------------------------------------------------
   if (componentSet.has('prompts')) {
+    section('\uD83D\uDCAC Prompts')
     const srcPrompts = join(ROOT, 'prompts')
     const dstPrompts = join(target, 'prompts')
     if (existsSync(srcPrompts)) {
@@ -201,6 +241,7 @@ export function installOpenCode(
   // 2.7 Install commands (--components commands)
   // -----------------------------------------------------------------------
   if (componentSet.has('commands')) {
+    section('\u26A1 Commands')
     const srcCmds = join(ROOT, 'commands')
     const dstCmds = isGlobal ? join(target, 'commands') : join(target, '.opencode', 'commands')
     if (existsSync(srcCmds)) {
@@ -223,10 +264,10 @@ export function installOpenCode(
         if (cfg.subagent_depth === undefined) { cfg.subagent_depth = 2; changed = true }
         if (changed && !dryRun) {
           writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n')
-          console.log('    ✅ subagent_depth: 2 added to opencode.json')
+          success('subagent_depth: 2 added to opencode.json')
         }
       } catch (e) {
-        console.warn(`    ⚠️  Could not update opencode.json: ${e.message}`)
+        warning(`Could not update opencode.json: ${e.message}`)
       }
     }
   }
@@ -234,46 +275,15 @@ export function installOpenCode(
   // 2.8 Install TUI plugins (--components plugins)
   // -----------------------------------------------------------------------
   if (componentSet.has('plugins')) {
+    section('\uD83D\uDD0C Plugins')
     const srcPluginDir = join(ROOT, 'src', 'plugins', 'tui')
     const dstPluginDir = isGlobal
       ? join(target, 'plugins', 'pantheon-tui')
       : join(target, '.opencode', 'plugins', 'pantheon-tui')
-    if (!dryRun) mkdirSync(dstPluginDir, { recursive: true })
-    if (clean && existsSync(dstPluginDir) && !dryRun) {
-      rmSync(dstPluginDir, { recursive: true, force: true })
-      mkdirSync(dstPluginDir, { recursive: true })
-    }
-    if (!dryRun) mkdirSync(join(dstPluginDir, "dist"), { recursive: true })
-    // Copy src/index.tsx -> index.tsx
-    const srcIdx = join(srcPluginDir, "src", "index.tsx")
-    if (existsSync(srcIdx)) {
-      writeIfChanged(join(dstPluginDir, "index.tsx"), readFileSync(srcIdx, "utf8"), dryRun)
-      stats.created++
-    }
-    // Copy dist files
-    const distSrc = join(srcPluginDir, "dist")
-    if (existsSync(distSrc)) {
-      for (const f of readdirSync(distSrc)) {
-        const c = readFileSync(join(distSrc, f), "utf8")
-        writeIfChanged(join(dstPluginDir, "dist", f), c, dryRun)
-        stats.created++
-      }
-    }
-    // Copy package.json
-    const pkgSrc = join(srcPluginDir, "package.json")
-    if (existsSync(pkgSrc)) {
-      writeIfChanged(join(dstPluginDir, "package.json"), readFileSync(pkgSrc, "utf8"), dryRun)
-      stats.created++
-    }
-    // Install plugin dependencies (@opentui/core, @opentui/solid, solid-js)
-    if (!dryRun) {
-      try {
-        execSync('npm install --omit=dev --no-audit', { cwd: dstPluginDir, stdio: 'pipe' })
-      } catch (e) {
-        console.warn('    ⚠️  Failed to install TUI plugin dependencies:', e.message)
-      }
-    }
-
+    const pluginStats = installPlugin(srcPluginDir, dstPluginDir, { dryRun, clean })
+    stats.created += pluginStats.created
+    stats.skipped += pluginStats.skipped
+    stats.errors += pluginStats.errors
   }
 
   // -----------------------------------------------------------------------
@@ -282,30 +292,9 @@ export function installOpenCode(
   const targetTuiConfigPath = isGlobal
     ? join(target, 'tui.json')
     : join(target, '.opencode', 'tui.json')
-  let tuiConfig = { plugin: [] }
-  if (existsSync(targetTuiConfigPath)) {
-    try {
-      tuiConfig = JSON.parse(readFileSync(targetTuiConfigPath, 'utf8'))
-    } catch {
-      /* use default */
-    }
-  }
-  if (!Array.isArray(tuiConfig.plugin)) {
-    tuiConfig.plugin = []
-  }
-  // Remove stale plugin refs (old dist/tui.tsx path)
-  const staleRefs = ["plugins/pantheon-tui/dist/tui.tsx", "plugins/pantheon-tui/dist/tui.js"]
-  for (const stale of staleRefs) {
-    const idx = tuiConfig.plugin.indexOf(stale)
-    if (idx !== -1) tuiConfig.plugin.splice(idx, 1)
-  }
-  // Add our plugin if not already present
   const pluginRef = 'plugins/pantheon-tui'
-  if (!tuiConfig.plugin.includes(pluginRef)) {
-    tuiConfig.plugin.push(pluginRef)
-  }
-  const tuiContent = `${JSON.stringify(tuiConfig, null, 2)}\n`
-  const tuiStatus = writeIfChanged(targetTuiConfigPath, tuiContent, dryRun)
+  unregisterPlugin(targetTuiConfigPath, pluginRef, { dryRun })
+  const tuiStatus = registerPlugin(targetTuiConfigPath, pluginRef, { dryRun })
   if (tuiStatus === 'created') stats.created++
   else stats.skipped++
 
@@ -314,6 +303,7 @@ export function installOpenCode(
   //      MCP server scripts, code-mode scripts, tiers.json
   // -----------------------------------------------------------------------
   if (componentSet.has('runtime')) {
+    section('\u2699\uFE0F Runtime')
     const runtimeTarget = isGlobal ? target : join(target, '.opencode')
 
     // ── MCP server scripts ──
@@ -331,7 +321,7 @@ export function installOpenCode(
     for (const script of mcpScripts) {
       const src = join(srcScriptsDir, script)
       if (!existsSync(src)) {
-        console.warn(`  ⚠️  Script not found: ${src}`)
+        warning(`Script not found: ${src}`)
         stats.errors++
         continue
       }
@@ -683,9 +673,9 @@ export function installOpenCode(
     if (currentVersion) {
       const migration = runMigrations(target, currentVersion, { dryRun })
       if (migration.applied > 0) {
-        console.log(`  ✅ Applied ${migration.applied} migration(s)`)
+        success(`Applied ${migration.applied} migration(s)`)
         for (const msg of migration.messages) {
-          console.log(`     • ${msg}`)
+          bullet(msg, 1)
         }
       }
     }
@@ -696,22 +686,50 @@ export function installOpenCode(
   // -----------------------------------------------------------------------
   if (componentSet.has('runtime')) {
     try {
+      const venvSpinner = spinner('Setting up Python virtual environment')
       setupVenv(target, { dryRun, force: clean })
+      venvSpinner(true)
       const health = healthCheck(target, { dryRun })
 
       // Print health summary
-      console.log('\n  📊 Health Check:')
-      for (const p of health.passed) console.log(`    ✅ ${p.check}: ${p.detail}`)
-      for (const w of health.warnings) console.log(`    ⚠️  ${w.check}: ${w.detail}`)
-      for (const f of health.failed) console.log(`    ❌ ${f.check}: ${f.detail}`)
+      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) {
-        console.log(`  ⚠️  ${health.failed.length} check(s) failed — review above`)
+        healthStep(false)
+        warning(`${health.failed.length} check(s) failed — review above`)
         stats.errors += health.failed.length
+      } else {
+        healthStep(true)
       }
     } catch (err) {
-      console.error(`  ❌ Setup failed: ${err.message}`)
+      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
+
+    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.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`)
+    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('\n')
+  } else {
+    printSummary(target, ['opencode'], stats)
+  }
 }

package/scripts/install/plugin.mjs

@@ -0,0 +1,139 @@
+/**
+ * plugin.mjs — Plugin installation utilities for the OpenCode installer
+ */
+
+import { execSync } from 'node:child_process'
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { warning } from './cli-ui.mjs'
+import { writeIfChanged } from './shared.mjs'
+
+/**
+ * Install a plugin from source to destination.
+ * @param {string} srcDir - Source plugin directory (e.g. ROOT/src/plugins/tui)
+ * @param {string} dstDir - Destination plugin directory
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false] - If true, don't write files
+ * @param {boolean} [options.clean=false] - If true, remove existing before install
+ * @returns {{ created: number, skipped: number, errors: number }}
+ */
+export function installPlugin(srcDir, dstDir, { dryRun = false, clean = false } = {}) {
+  const result = { created: 0, skipped: 0, errors: 0 }
+
+  if (!dryRun) mkdirSync(dstDir, { recursive: true })
+  if (clean && existsSync(dstDir) && !dryRun) {
+    rmSync(dstDir, { recursive: true, force: true })
+    mkdirSync(dstDir, { recursive: true })
+  }
+  if (!dryRun) mkdirSync(join(dstDir, 'dist'), { recursive: true })
+
+  // Copy src/index.tsx -> index.tsx
+  const srcIdx = join(srcDir, 'src', 'index.tsx')
+  if (existsSync(srcIdx)) {
+    const idxStatus = writeIfChanged(join(dstDir, 'index.tsx'), readFileSync(srcIdx, 'utf8'), dryRun)
+    if (idxStatus === 'created') result.created++
+    else result.skipped++
+  }
+
+  // Copy dist/* files
+  const distSrc = join(srcDir, 'dist')
+  if (existsSync(distSrc)) {
+    for (const f of readdirSync(distSrc)) {
+      const c = readFileSync(join(distSrc, f), 'utf8')
+      writeIfChanged(join(dstDir, 'dist', f), c, dryRun)
+      result.created++
+    }
+  }
+
+  // Copy package.json
+  const pkgSrc = join(srcDir, 'package.json')
+  if (existsSync(pkgSrc)) {
+    const pkgStatus = writeIfChanged(join(dstDir, 'package.json'), readFileSync(pkgSrc, 'utf8'), dryRun)
+    if (pkgStatus === 'created') result.created++
+    else result.skipped++
+  }
+
+  // Install plugin dependencies (@opentui/core, @opentui/solid, solid-js)
+  if (!dryRun) {
+    try {
+      execSync('npm install --omit=dev --no-audit', { cwd: dstDir, stdio: 'pipe' })
+    } catch (e) {
+      warning('Failed to install TUI plugin dependencies: ' + e.message)
+      result.errors++
+    }
+  }
+
+  return result
+}
+
+/**
+ * Install plugin dependencies via npm.
+ * @param {string} pluginDir - Directory containing package.json
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false] - If true, skip npm install
+ */
+export function installPluginDependencies(pluginDir, { dryRun = false } = {}) {
+  if (dryRun) return
+  try {
+    execSync('npm install --omit=dev --no-audit', { cwd: pluginDir, stdio: 'pipe' })
+  } catch (e) {
+    warning('Failed to install plugin dependencies: ' + e.message)
+  }
+}
+
+/**
+ * Register a plugin in tui.json.
+ * @param {string} tuiJsonPath - Path to tui.json
+ * @param {string} pluginId - Plugin identifier string
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ * @returns {'created'|'skipped'}
+ */
+export function registerPlugin(tuiJsonPath, pluginId, { dryRun = false } = {}) {
+  let tuiConfig = { plugin: [] }
+  if (existsSync(tuiJsonPath)) {
+    try {
+      tuiConfig = JSON.parse(readFileSync(tuiJsonPath, 'utf8'))
+    } catch {
+      /* use default */
+    }
+  }
+  if (!Array.isArray(tuiConfig.plugin)) {
+    tuiConfig.plugin = []
+  }
+  if (!tuiConfig.plugin.includes(pluginId)) {
+    tuiConfig.plugin.push(pluginId)
+  }
+  const tuiContent = `${JSON.stringify(tuiConfig, null, 2)}\n`
+  return writeIfChanged(tuiJsonPath, tuiContent, dryRun)
+}
+
+/**
+ * Unregister stale plugin references from tui.json.
+ * @param {string} tuiJsonPath - Path to tui.json
+ * @param {string} pluginId - Plugin to unregister
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ * @returns {'created'|'skipped'}
+ */
+export function unregisterPlugin(tuiJsonPath, pluginId, { dryRun = false } = {}) {
+  let tuiConfig = { plugin: [] }
+  if (existsSync(tuiJsonPath)) {
+    try {
+      tuiConfig = JSON.parse(readFileSync(tuiJsonPath, 'utf8'))
+    } catch {
+      /* use default */
+    }
+  }
+  if (!Array.isArray(tuiConfig.plugin)) {
+    tuiConfig.plugin = []
+  }
+  // Remove stale plugin refs (old dist/tui.tsx path)
+  const staleRefs = [`${pluginId}/dist/tui.tsx`, `${pluginId}/dist/tui.js`]
+  for (const stale of staleRefs) {
+    const idx = tuiConfig.plugin.indexOf(stale)
+    if (idx !== -1) tuiConfig.plugin.splice(idx, 1)
+  }
+  const tuiContent = `${JSON.stringify(tuiConfig, null, 2)}\n`
+  return writeIfChanged(tuiJsonPath, tuiContent, dryRun)
+}

package/scripts/install/state.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * state.mjs — State manifest for Pantheon installations (schema v2)
+ *
+ * Manages the install-state.json manifest with version tracking,
+ * component state, and applied migration history.
+ *
+ * Schema v2:
+ *   {
+ *     "schema_version": 2,
+ *     "pantheon_version": "1.1.1",
+ *     "previous_version": "1.1.0",
+ *     "updated_at": "2026-07-26T10:30:00Z",
+ *     "migration_checkpoint": null,
+ *     "applied_migrations": [
+ *       { "from": "1.1.0", "to": "1.1.1", "applied_at": "2026-07-26T10:30:00Z", "status": "completed" }
+ *     ],
+ *     "components": {
+ *       "agents": { "version": 1, "status": "installed" },
+ *       "skills": { "version": 1, "status": "installed" },
+ *       "plugins": { "version": 1, "status": "installed" },
+ *       "runtime": { "version": 1, "status": "installed" }
+ *     }
+ *   }
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const STATE_FILE = 'install-state.json'
+const STATE_DIR = '.pantheon'
+
+/**
+ * Create a fresh v2 state object for a new install.
+ * @param {string} version - Pantheon version string
+ * @returns {object} v2 state
+ */
+export function createInitialState(version) {
+  return {
+    schema_version: 2,
+    pantheon_version: version || '0.0.0',
+    previous_version: null,
+    updated_at: new Date().toISOString(),
+    migration_checkpoint: null,
+    applied_migrations: [],
+    components: {
+      agents: { version: 1, status: 'pending' },
+      skills: { version: 1, status: 'pending' },
+      plugins: { version: 1, status: 'pending' },
+      runtime: { version: 1, status: 'pending' },
+    },
+  }
+}
+
+/**
+ * Read install-state.json from a target directory.
+ * Backward-compatible with v1 schema (auto-upgrades on read).
+ * @param {string} target - Installation directory
+ * @returns {object|null} v2 state object, or null if not found
+ */
+export function readState(target) {
+  const stateFile = join(target, STATE_DIR, STATE_FILE)
+  if (!existsSync(stateFile)) return null
+  try {
+    const raw = JSON.parse(readFileSync(stateFile, 'utf8'))
+    return normalizeState(raw)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Detect whether the raw state is v1 format (pre-schema_version).
+ * v1 state has pantheon_version (or version) but no schema_version.
+ * @param {object} state
+ * @returns {boolean}
+ */
+export function isV1State(state) {
+  if (!state || typeof state !== 'object') return false
+  return !state.schema_version && (!!state.pantheon_version || !!state.version)
+}
+
+/**
+ * Upgrade a v1 state to v2 schema.
+ * Preserves all existing fields, adds defaults for new ones.
+ * @param {object} state - v1 state object
+ * @returns {object} v2 state object
+ */
+export function upgradeStateV1toV2(state) {
+  const now = new Date().toISOString()
+  return {
+    schema_version: 2,
+    pantheon_version: state.pantheon_version || state.version || 'unknown',
+    previous_version: state.previous_version || null,
+    updated_at: state.updated_at || now,
+    migration_checkpoint: null,
+    applied_migrations: Array.isArray(state.applied_migrations) ? state.applied_migrations : [],
+    components: state.components && typeof state.components === 'object' ? state.components : {
+      agents: { version: 1, status: 'installed' },
+      skills: { version: 1, status: 'installed' },
+      plugins: { version: 1, status: 'unknown' },
+      runtime: { version: 1, status: 'unknown' },
+    },
+  }
+}
+
+/**
+ * Normalize any state to v2 (handles v1 → v2 upgrade).
+ * @param {object} state
+ * @returns {object|null}
+ */
+function normalizeState(state) {
+  if (!state || typeof state !== 'object') return null
+  if (isV1State(state)) return upgradeStateV1toV2(state)
+  if (!state.schema_version || state.schema_version < 2) return upgradeStateV1toV2(state)
+  return state
+}
+
+/**
+ * Write state to target's install-state.json (always v2 format).
+ * @param {string} target - Installation directory
+ * @param {object} state - v2 state object
+ */
+export function writeState(target, state) {
+  const stateDir = join(target, STATE_DIR)
+  if (!existsSync(stateDir)) {
+    mkdirSync(stateDir, { recursive: true })
+  }
+  const stateFile = join(stateDir, STATE_FILE)
+  state.updated_at = new Date().toISOString()
+  state.schema_version = 2
+  writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
+}
+
+/**
+ * Check whether install-state.json exists in target.
+ * @param {string} target
+ * @returns {boolean}
+ */
+export function hasState(target) {
+  return existsSync(join(target, STATE_DIR, STATE_FILE))
+}
+
+/**
+ * Add a migration record to the applied_migrations array.
+ * @param {object} state
+ * @param {string} fromVersion
+ * @param {string} toVersion
+ * @param {string} [status='completed']
+ */
+export function addMigrationRecord(state, fromVersion, toVersion, status = 'completed') {
+  if (!Array.isArray(state.applied_migrations)) {
+    state.applied_migrations = []
+  }
+  state.applied_migrations.push({
+    from: fromVersion,
+    to: toVersion,
+    applied_at: new Date().toISOString(),
+    status,
+  })
+}
+
+/**
+ * Update the pantheon_version and previous_version.
+ * @param {object} state
+ * @param {string} newVersion
+ */
+export function updateVersion(state, newVersion) {
+  state.previous_version = state.pantheon_version || null
+  state.pantheon_version = newVersion
+}
+
+/**
+ * Get a component's state object.
+ * @param {object} state
+ * @param {string} component - Component name (agents, skills, plugins, runtime)
+ * @returns {{ version: number, status: string }|null}
+ */
+export function getComponentState(state, component) {
+  if (!state.components) return null
+  return state.components[component] || null
+}
+
+/**
+ * Set a component's version and status.
+ * @param {object} state
+ * @param {string} component
+ * @param {number} version
+ * @param {string} status
+ */
+export function setComponentState(state, component, version, status) {
+  if (!state.components) state.components = {}
+  state.components[component] = { version, status }
+}