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

package/scripts/install/migrate-config.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * migrate-config.mjs — Standalone migration CLI with checkpoint crash recovery
+ *
+ * Runs configuration migrations with an atomic checkpoint system.
+ * If the process crashes mid-migration, the checkpoint file persists
+ * so that --resume picks up where it left off.
+ *
+ * Usage:
+ *   node scripts/install/migrate-config.mjs --from=1.1.0 --to=1.1.1 --target=~/.config/opencode
+ *   node scripts/install/migrate-config.mjs --resume --target=~/.config/opencode
+ *   node scripts/install/migrate-config.mjs --list --target=~/.config/opencode
+ *   node scripts/install/migrate-config.mjs --dry-run --from=1.1.0 --to=1.1.1
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  readState,
+  writeState,
+  createInitialState,
+  addMigrationRecord,
+  updateVersion,
+} from './state.mjs'
+import {
+  readCheckpoint,
+  writeCheckpoint,
+  advanceCheckpoint,
+  removeCheckpoint,
+  resumePendingMigration,
+  listAppliedMigrations,
+} from './migrate.mjs'
+
+// ---------------------------------------------------------------------------
+// Migration step definitions
+// Each step is an idempotent function(target, state, { dryRun }) => void
+// ---------------------------------------------------------------------------
+
+const MIGRATION_STEPS = {
+  /**
+   * migrate_state_v2: Upgrade install-state.json from schema v1 to v2.
+   * Adds schema_version field, components tracking, and migration history.
+   */
+  migrate_state_v2: (target, state, { dryRun }) => {
+    if (state.schema_version && state.schema_version >= 2) {
+      return
+    }
+    if (!dryRun) {
+      state.schema_version = 2
+      state.components = state.components || {
+        agents: { version: 1, status: 'pending' },
+        skills: { version: 1, status: 'pending' },
+        plugins: { version: 1, status: 'pending' },
+        runtime: { version: 1, status: 'pending' },
+      }
+      state.applied_migrations = state.applied_migrations || []
+      state.migration_checkpoint = null
+    }
+  },
+
+  /**
+   * update_schema: Ensure all v2 schema fields exist with defaults.
+   */
+  update_schema: (target, state, { dryRun }) => {
+    if (!dryRun) {
+      if (!state.components) {
+        state.components = {
+          agents: { version: 1, status: 'pending' },
+          skills: { version: 1, status: 'pending' },
+          plugins: { version: 1, status: 'pending' },
+          runtime: { version: 1, status: 'pending' },
+        }
+      }
+      for (const key of ['agents', 'skills', 'plugins', 'runtime']) {
+        if (!state.components[key]) {
+          state.components[key] = { version: 1, status: 'pending' }
+        }
+      }
+      state.applied_migrations = state.applied_migrations || []
+      if (state.migration_checkpoint === undefined) {
+        state.migration_checkpoint = null
+      }
+    }
+  },
+
+  /**
+   * migrate_plugins: Normalize plugin component tracking.
+   */
+  migrate_plugins: (target, state, { dryRun }) => {
+    if (!dryRun) {
+      if (!state.components) state.components = {}
+      const p = state.components.plugins || { version: 1, status: 'pending' }
+      p.version = Math.max(p.version || 0, 1)
+      state.components.plugins = p
+    }
+  },
+}
+
+// ---------------------------------------------------------------------------
+// Migration step ordering (a step runs ONLY after all predecessors complete)
+// ---------------------------------------------------------------------------
+
+const STEP_ORDER = Object.keys(MIGRATION_STEPS)
+
+/**
+ * Resolve which steps to run based on from/to version comparison.
+ * For now, runs all steps. In the future this can be gated by version.
+ * @param {string} fromVersion
+ * @param {string} toVersion
+ * @returns {string[]} Ordered list of step names
+ */
+function resolveSteps(fromVersion, toVersion) {
+  return [...STEP_ORDER]
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(2)
+  const result = {
+    from: null,
+    to: null,
+    target: process.cwd(),
+    dryRun: false,
+    resume: false,
+    list: false,
+    help: false,
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--dry-run') result.dryRun = true
+    else if (arg === '--resume') result.resume = true
+    else if (arg === '--list') result.list = true
+    else if (arg === '--help' || arg === '-h') result.help = true
+    else if (arg.startsWith('--from=')) result.from = arg.split('=', 2)[1]
+    else if (arg.startsWith('--to=')) result.to = arg.split('=', 2)[1]
+    else if (arg.startsWith('--target=')) result.target = arg.split('=', 2)[1]
+    else if (arg === '--from') result.from = args[++i]
+    else if (arg === '--to') result.to = args[++i]
+    else if (arg === '--target') result.target = args[++i]
+  }
+
+  return result
+}
+
+function showHelp() {
+  console.log(`
+migrate-config.mjs — Pantheon configuration migration CLI
+
+Usage:
+  node scripts/install/migrate-config.mjs --from=1.1.0 --to=1.1.1 --target=~/.config/opencode
+  node scripts/install/migrate-config.mjs --resume --target=~/.config/opencode
+  node scripts/install/migrate-config.mjs --list --target=~/.config/opencode
+  node scripts/install/migrate-config.mjs --dry-run --from=1.1.0 --to=1.1.1
+  node scripts/install/migrate-config.mjs --help
+
+Options:
+  --from=<version>  Source version (required for new migrations)
+  --to=<version>    Target version (required for new migrations)
+  --target=<path>   Installation directory (default: cwd)
+  --dry-run         Preview without writing
+  --resume          Resume from pending checkpoint (crash recovery)
+  --list            Show applied migration history
+  --help            Show this help
+
+Crash Recovery:
+  If the process is interrupted mid-migration, a checkpoint file is left
+  at .pantheon/.migration-checkpoint. Run with --resume to continue.
+`)
+}
+
+function main() {
+  const config = parseArgs()
+
+  if (config.help) {
+    showHelp()
+    return
+  }
+
+  // ── List mode ──
+  if (config.list) {
+    const history = listAppliedMigrations(config.target)
+    if (!history.currentVersion) {
+      console.log('  \u2139\uFE0F  No install state found in: ' + config.target)
+      return
+    }
+    console.log(`  Current version: ${history.currentVersion}`)
+    console.log(`  Previous version: ${history.previousVersion || 'N/A'}`)
+    console.log(`  Applied migrations: ${history.migrations.length}`)
+    for (const m of history.migrations) {
+      const icon =
+        m.status === 'completed'
+          ? '\u2705'
+          : m.status === 'rolled_back'
+            ? '\u{1F504}'
+            : '\u26A0\uFE0F'
+      console.log(`    ${icon} ${m.from} \u2192 ${m.to} [${m.status}] (${m.applied_at})`)
+    }
+    return
+  }
+
+  // ── Resume mode ──
+  if (config.resume) {
+    const cp = resumePendingMigration(config.target)
+    if (!cp) {
+      console.log('  \u23ED\uFE0F  No pending checkpoint found — nothing to resume')
+      return
+    }
+    config.from = cp.from
+    config.to = cp.to
+  } else {
+    if (!config.from || !config.to) {
+      console.error('\u274C --from and --to are required (or use --resume)')
+      showHelp()
+      process.exit(1)
+    }
+  }
+
+  // ── Read state ──
+  let state = readState(config.target)
+  if (!state) {
+    state = createInitialState(config.from)
+    console.log(`  \u{1F4DD} Creating new install state (v${state.schema_version})`)
+    if (!config.dryRun) writeState(config.target, state)
+  } else {
+    console.log(
+      `  \u{1F4CB} Current state: v${state.schema_version}, version ${state.pantheon_version}`,
+    )
+  }
+
+  // ── Resolve checkpoint ──
+  let cp = readCheckpoint(config.target)
+
+  if (!cp) {
+    const steps = resolveSteps(config.from, config.to)
+    cp = writeCheckpoint(config.target, config.from, config.to, steps)
+    console.log(`  \u{1F4DD} Checkpoint written: ${config.from} \u2192 ${config.to}`)
+  } else {
+    console.log(
+      `  \u{1F504} Resuming from checkpoint (${cp.steps_completed.length} steps done, ${cp.steps_pending.length} remaining)`,
+    )
+  }
+
+  // ── Run pending steps ──
+  const stepsToRun = [...cp.steps_pending]
+  let failed = false
+
+  for (const step of stepsToRun) {
+    const stepFn = MIGRATION_STEPS[step]
+    if (!stepFn) {
+      console.warn(`  \u26A0\uFE0F  Unknown migration step: ${step} — skipping`)
+      if (!config.dryRun) {
+        advanceCheckpoint(config.target, step)
+      }
+      continue
+    }
+
+    console.log(`  \u25B6\uFE0F  Running: ${step}`)
+    try {
+      stepFn(config.target, state, { dryRun: config.dryRun })
+
+      if (!config.dryRun) {
+        advanceCheckpoint(config.target, step)
+        writeState(config.target, state)
+        console.log(`  \u2705 ${step} completed`)
+      } else {
+        console.log(`  \u2705 ${step} would complete (dry-run)`)
+      }
+    } catch (err) {
+      console.error(`  \u274C ${step} failed: ${err.message}`)
+      failed = true
+      break
+    }
+  }
+
+  // ── Finalize ──
+  if (failed) {
+    console.error(`\n  \u274C Migration failed at checkpoint.`)
+    console.error(
+      `     Resume with: node scripts/install/migrate-config.mjs --resume --target=${config.target}`,
+    )
+    process.exit(1)
+  }
+
+  if (!config.dryRun) {
+    updateVersion(state, config.to)
+    addMigrationRecord(state, config.from, config.to, 'completed')
+    removeCheckpoint(config.target)
+    writeState(config.target, state)
+    console.log(
+      `\n  \u2705 Migration complete: ${config.from} \u2192 ${config.to}`,
+    )
+    console.log(
+      `     State written to: ${join(config.target, '.pantheon', 'install-state.json')}`,
+    )
+  } else {
+    console.log(
+      `\n  \u2705 Migration would complete (dry-run): ${config.from} \u2192 ${config.to}`,
+    )
+  }
+}
+
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+  main()
+}

package/scripts/install/migrate.mjs

@@ -8,9 +8,10 @@
  *   node scripts/install/migrate.mjs --target ~/.config/opencode --force
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { readState, writeState, createInitialState } from './state.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..', '..')
@@ -33,16 +34,9 @@ function readPackageVersion() {
  * @returns {string|null} - version string or null for fresh install
  */
 export function detectVersion(target) {
-  const stateFile = join(target, '.pantheon', 'install-state.json')
-  if (existsSync(stateFile)) {
-    try {
-      const state = JSON.parse(readFileSync(stateFile, 'utf8'))
-      return state.pantheon_version || state.version || 'unknown'
-    } catch {
-      /* corrupted state — treat as unknown */
-    }
-  }
-  return null // fresh install
+  const state = readState(target)
+  if (state) return state.pantheon_version || state.version || 'unknown'
+  return null
 }
 
 /**
@@ -96,9 +90,42 @@ export function runMigrations(target, currentVersion, { dryRun = false } = {}) {
     semver[2] = 1
   }
 
+  // ── Migration: v3.19.1 → v3.19.2 ──────────────────────────────────
+  // Upgrade state schema from v1 to v2
+  if (semver && lt(semver, [3, 19, 2])) {
+    applied.push({
+      from: formatSemver(semver),
+      to: '3.19.2',
+      description: 'Upgrade install state schema to v2 with component tracking',
+    })
+    semver[0] = 3
+    semver[1] = 19
+    semver[2] = 2
+  }
+
   // ── Write updated state ───────────────────────────────────────────
   if (applied.length > 0 && !dryRun) {
-    writeInstallState(target, formatSemver(semver))
+    const newVersion = formatSemver(semver)
+    let state = readState(target)
+    if (!state) state = createInitialState(newVersion)
+    state.pantheon_version = newVersion
+    for (const m of applied) {
+      state.applied_migrations.push({
+        from: m.from,
+        to: m.to,
+        applied_at: new Date().toISOString(),
+        status: 'completed',
+      })
+    }
+    if (!state.components) {
+      state.components = {
+        agents: { version: 1, status: 'installed' },
+        skills: { version: 1, status: 'installed' },
+        plugins: { version: 1, status: 'installed' },
+        runtime: { version: 1, status: 'installed' },
+      }
+    }
+    writeState(target, state)
   }
 
   return {
@@ -107,20 +134,150 @@ export function runMigrations(target, currentVersion, { dryRun = false } = {}) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Checkpoint system for crash recovery
+// ---------------------------------------------------------------------------
+
+const CHECKPOINT_FILE = '.migration-checkpoint'
+const STATE_DIR = '.pantheon'
+
+/**
+ * Read the migration checkpoint file if it exists.
+ * @param {string} target
+ * @returns {object|null}
+ */
+export function readCheckpoint(target) {
+  const cpFile = join(target, STATE_DIR, CHECKPOINT_FILE)
+  if (!existsSync(cpFile)) return null
+  try {
+    return JSON.parse(readFileSync(cpFile, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Write a migration checkpoint before starting migrations.
+ * @param {string} target
+ * @param {string} fromVersion
+ * @param {string} toVersion
+ * @param {string[]} steps - Ordered list of step names
+ * @returns {object} The checkpoint object
+ */
+export function writeCheckpoint(target, fromVersion, toVersion, steps) {
+  const cpDir = join(target, STATE_DIR)
+  if (!existsSync(cpDir)) mkdirSync(cpDir, { recursive: true })
+  const cpFile = join(cpDir, CHECKPOINT_FILE)
+  const checkpoint = {
+    from: fromVersion,
+    to: toVersion,
+    started_at: new Date().toISOString(),
+    steps_completed: [],
+    steps_pending: [...steps],
+  }
+  writeFileSync(cpFile, `${JSON.stringify(checkpoint, null, 2)}\n`, 'utf8')
+  return checkpoint
+}
+
+/**
+ * Advance the checkpoint: mark a step as completed and remove from pending.
+ * @param {string} target
+ * @param {string} stepName
+ * @returns {object|null} Updated checkpoint, or null if none exists
+ */
+export function advanceCheckpoint(target, stepName) {
+  const cp = readCheckpoint(target)
+  if (!cp) return null
+  cp.steps_completed.push(stepName)
+  cp.steps_pending = cp.steps_pending.filter((s) => s !== stepName)
+  const cpFile = join(target, STATE_DIR, CHECKPOINT_FILE)
+  writeFileSync(cpFile, `${JSON.stringify(cp, null, 2)}\n`, 'utf8')
+  return cp
+}
+
+/**
+ * Remove the checkpoint file on successful completion.
+ * @param {string} target
+ */
+export function removeCheckpoint(target) {
+  const cpFile = join(target, STATE_DIR, CHECKPOINT_FILE)
+  if (existsSync(cpFile)) {
+    rmSync(cpFile, { force: true })
+  }
+}
+
+/**
+ * Resume from a pending checkpoint.
+ * Reads the checkpoint and reports what steps remain.
+ * @param {string} target
+ * @returns {object|null} The checkpoint, or null if none pending
+ */
+export function resumePendingMigration(target) {
+  const cp = readCheckpoint(target)
+  if (!cp) return null
+  console.log(`  \u{1F504} Resuming migration from checkpoint: ${cp.from} \u2192 ${cp.to}`)
+  console.log(`     Completed: ${cp.steps_completed.join(', ') || 'none'}`)
+  console.log(`     Pending: ${cp.steps_pending.join(', ') || 'none'}`)
+  return cp
+}
+
+// ---------------------------------------------------------------------------
+// Rollback support
+// ---------------------------------------------------------------------------
+
 /**
- * Write install state with current version to target.
+ * Roll back the last completed migration for a given version.
+ * Each migration step should define a corresponding down-migration.
+ * This is a stub — actual down-migration logic should be registered
+ * in a DOWN_MIGRATIONS registry.
+ *
+ * @param {string} target
+ * @param {string} version - The version to roll back from
+ * @returns {{ success: boolean, reason?: string, migration?: object }}
  */
-function writeInstallState(target, version) {
-  const stateDir = join(target, '.pantheon')
-  const stateFile = join(stateDir, 'install-state.json')
-  if (!existsSync(stateDir)) {
-    mkdirSync(stateDir, { recursive: true })
+export function rollbackMigration(target, version) {
+  const state = readState(target)
+  if (!state) {
+    console.log('  \u26A0\uFE0F  No install state found — nothing to roll back')
+    return { success: false, reason: 'No install state' }
   }
-  const state = {
-    pantheon_version: version,
-    updated_at: new Date().toISOString(),
+
+  const migrations = state.applied_migrations || []
+  const targetMigration = migrations.find(
+    (m) => m.to === version && m.status === 'completed',
+  )
+  if (!targetMigration) {
+    console.log(`  \u26A0\uFE0F  No completed migration found for version ${version}`)
+    return { success: false, reason: 'Migration not found' }
+  }
+
+  console.log(
+    `  \u{1F504} Rolling back migration: ${targetMigration.from} \u2192 ${targetMigration.to}`,
+  )
+
+  targetMigration.status = 'rolled_back'
+  state.pantheon_version = targetMigration.from
+  writeState(target, state)
+
+  console.log(`  \u2705 Rolled back to ${targetMigration.from}`)
+  return { success: true, migration: targetMigration }
+}
+
+/**
+ * List all applied migrations from the install state.
+ * @param {string} target
+ * @returns {{ currentVersion: string|null, previousVersion: string|null, migrations: object[] }}
+ */
+export function listAppliedMigrations(target) {
+  const state = readState(target)
+  if (!state) {
+    return { currentVersion: null, previousVersion: null, migrations: [] }
+  }
+  return {
+    currentVersion: state.pantheon_version,
+    previousVersion: state.previous_version,
+    migrations: state.applied_migrations || [],
   }
-  writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
 }
 
 // ---------------------------------------------------------------------------
@@ -172,15 +329,38 @@ function main() {
   const target = targetIdx !== -1 ? args[targetIdx + 1] : process.cwd()
   const dryRun = args.includes('--dry-run')
   const force = args.includes('--force')
+  const list = args.includes('--list')
+
+  if (list) {
+    const history = listAppliedMigrations(target)
+    if (!history.currentVersion) {
+      console.log('  \u2139\uFE0F  No install state found in: ' + target)
+      return
+    }
+    console.log(`  Current version: ${history.currentVersion}`)
+    console.log(`  Previous version: ${history.previousVersion || 'N/A'}`)
+    console.log(`  Applied migrations: ${history.migrations.length}`)
+    for (const m of history.migrations) {
+      const icon = m.status === 'completed' ? '\u2705' : m.status === 'rolled_back' ? '\u{1F504}' : '\u26A0\uFE0F'
+      console.log(`    ${icon} ${m.from} \u2192 ${m.to} [${m.status}] (${m.applied_at})`)
+    }
+    return
+  }
+
+  const rollbackTo = args.find((a) => a.startsWith('--rollback='))?.split('=', 2)[1]
+  if (rollbackTo) {
+    rollbackMigration(target, rollbackTo)
+    return
+  }
 
   const currentVersion = detectVersion(target)
   if (!currentVersion) {
-    // Fresh install — write state and exit
     if (!dryRun) {
-      writeInstallState(target, PANTHON_VERSION)
-      console.log(`  ✅ Fresh install — state written (${PANTHON_VERSION})`)
+      const state = createInitialState(PANTHON_VERSION)
+      writeState(target, state)
+      console.log(`  \u2705 Fresh install — state written (${PANTHON_VERSION})`)
     } else {
-      console.log(`  ✅ Fresh install — would write state (${PANTHON_VERSION})`)
+      console.log(`  \u2705 Fresh install — would write state (${PANTHON_VERSION})`)
     }
     return
   }
@@ -188,19 +368,19 @@ function main() {
   console.log(`  Current version: ${currentVersion}`)
 
   if (!force && currentVersion === PANTHON_VERSION) {
-    console.log('  ⏭️  Already at latest version — no migrations needed')
+    console.log('  \u23ED\uFE0F  Already at latest version — no migrations needed')
     return
   }
 
   const migration = runMigrations(target, currentVersion, { dryRun })
 
   if (migration.applied > 0) {
-    console.log(`  ✅ Applied ${migration.applied} migration(s):`)
+    console.log(`  \u2705 Applied ${migration.applied} migration(s):`)
     for (const msg of migration.messages) {
-      console.log(`     • ${msg}`)
+      console.log(`     \u2022 ${msg}`)
     }
   } else {
-    console.log('  ⏭️  No applicable migrations')
+    console.log('  \u23ED\uFE0F  No applicable migrations')
   }
 }