pantheon-opencode 1.6.0-beta.10 → 1.6.0-beta.11

package/scripts/install/backup.mjs

@@ -0,0 +1,475 @@
+/**
+ * backup.mjs — Exact backup sets for the Pantheon installer (Beta 11 Setup,
+ * phase 2).
+ *
+ * Before the installer modifies or creates a file, the CURRENT state of every
+ * affected path is preserved byte-for-byte under
+ * `<configDir>/.pantheon/backups/<UTC-timestamp>/`, mirroring the path relative
+ * to `configDir`, and described by a `manifest.json`. Files that do not exist
+ * yet are recorded as absent so a restore can reproduce the original state
+ * exactly.
+ *
+ * SECURITY
+ * --------
+ * A backup is an exact copy, so it can contain API keys or tokens that were
+ * already in the user's files. This module therefore:
+ *   - never prints file contents, values or hashes (only paths / counts / modes);
+ *   - writes the backup directory `0700` and every file `0600`.
+ * Windows is best-effort: `chmodSync` is attempted and a failure never aborts.
+ *
+ * SCOPE
+ * -----
+ * IN scope (byte-for-byte, restorable): every regular file the install can
+ * modify, rewrite, or remove INSIDE the config dir — including stale files that
+ * a `--clean` run deletes.
+ * OUT of scope (recorded in `manifest.notRevertible`, never restored): bulk
+ * directories whose byte-for-byte copy is not feasible (`.venv`, the plugin
+ * dir with its `node_modules`) and files OUTSIDE the config dir (the global
+ * `tui.json` copies and the global `opencode-vision.json`). The manifest states
+ * these explicitly rather than silently omitting them.
+ *
+ * The functions are `pure-ish`: they take explicit paths and an injectable
+ * `clock`, return data (never logging), and are safe to unit-test without a
+ * running installer.
+ */
+
+import { createHash } from 'node:crypto'
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+/** Directory (relative to the config dir) that holds the backup sets. */
+export const BACKUP_SUBDIR = join('.pantheon', 'backups')
+
+/** Number of most-recent backup sets retained. */
+export const DEFAULT_KEEP = 5
+
+/** UTC timestamp directory name: `YYYY-MM-DDTHH-MM-SSZ` (filesystem-safe). */
+const TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z$/
+
+/**
+ * Format a Date as the backup-directory timestamp.
+ * @param {Date} date
+ * @returns {string}
+ */
+export function formatTimestamp(date = new Date()) {
+  return date
+    .toISOString()
+    .replace(/\.\d+Z$/, 'Z')
+    .replace(/:/g, '-')
+}
+
+/**
+ * Whether a directory name is one of our timestamped backup sets. Used as the
+ * guard so retention can never delete a directory we did not create.
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isBackupDirName(name) {
+  return typeof name === 'string' && TIMESTAMP_RE.test(name)
+}
+
+/** Absolute path of the backups root for a config dir. */
+export function backupRoot(configDir) {
+  return join(configDir, BACKUP_SUBDIR)
+}
+
+/** Absolute path of a named backup set. */
+export function backupSetPath(configDir, name) {
+  return join(backupRoot(configDir), name)
+}
+
+/**
+ * Whether `candidate` is a direct child of `root` (no traversal). Pure string
+ * check — the retention path guard.
+ * @param {string} root
+ * @param {string} candidate
+ * @returns {boolean}
+ */
+export function isWithin(root, candidate) {
+  const rel = relative(resolve(root), resolve(candidate))
+  if (rel === '') return false
+  return (
+    !rel.startsWith('..') && !rel.split(sep).includes('..') && !resolve(candidate).startsWith('..')
+  )
+}
+
+/**
+ * Guard for a deletable backup set: it must live directly under
+ * `<configDir>/.pantheon/backups/` AND its name must match the timestamp
+ * pattern. Nothing else may ever be removed by retention.
+ * @param {string} configDir
+ * @param {string} dir
+ * @returns {boolean}
+ */
+export function isDeletableBackupDir(configDir, dir) {
+  const root = backupRoot(configDir)
+  if (!isWithin(root, dir)) return false
+  const rel = relative(resolve(root), resolve(dir))
+  return isBackupDirName(rel)
+}
+
+/** List backup sets, newest first. */
+export function listBackupSets(configDir) {
+  const root = backupRoot(configDir)
+  if (!existsSync(root)) return []
+  const sets = []
+  for (const name of readdirSync(root)) {
+    if (!isBackupDirName(name)) continue
+    const dir = join(root, name)
+    try {
+      if (!statSync(dir).isDirectory()) continue
+    } catch {
+      continue
+    }
+    sets.push({ name, dir })
+  }
+  sets.sort((a, b) => (a.name < b.name ? 1 : a.name > b.name ? -1 : 0))
+  return sets
+}
+
+/**
+ * Choose the next free backup-set name for `configDir`. Second-granularity names
+ * collide when two sets are created in the same second (apply immediately
+ * followed by a pre-restore snapshot); the seconds are bumped until the name is
+ * free so a new set never overwrites an existing one. Shared by the apply path
+ * and the dry-run preview so both agree.
+ *
+ * @param {string} configDir
+ * @param {Date} [base]
+ * @returns {string}
+ */
+export function nextBackupName(configDir, base = new Date()) {
+  let name = formatTimestamp(base)
+  let bump = 0
+  while (existsSync(backupSetPath(configDir, name))) {
+    bump += 1
+    name = formatTimestamp(new Date(base.getTime() + bump * 1000))
+  }
+  return name
+}
+
+/** sha256 hex of a buffer. */
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex')
+}
+
+function chmodBestEffort(path, mode) {
+  try {
+    chmodSync(path, mode)
+  } catch {
+    // Windows / exotic filesystems: best-effort only.
+  }
+}
+
+/**
+ * Create a directory ONLY when it is absent, and never chmod a directory that
+ * already exists. Chmodding a pre-existing directory is an irreversible side
+ * effect on the user's tree (F1): restoring into a project would otherwise
+ * rewrite the project root to 0700. Bulk-directory modes are out of scope for
+ * the exact backup (see `notRevertible`).
+ */
+function ensureDir(path, mode) {
+  if (existsSync(path)) return
+  try {
+    mkdirSync(path, { recursive: true, mode })
+    chmodBestEffort(path, mode)
+  } catch {
+    // A concurrent creator won the race; leave it untouched.
+  }
+}
+
+/**
+ * Create an exact backup set for `entries` (paths relative to `configDir`).
+ *
+ * A path that exists as a regular file is copied byte-for-byte with mode 0600
+ * and hashed; anything else (absent, directory, symlink) is recorded as absent.
+ * The whole set is written before this function returns, so a caller can run it
+ * BEFORE the first modifying write.
+ *
+ * @param {object} opts
+ * @param {string} opts.configDir
+ * @param {string[]} opts.entries - relative paths (deduped, order preserved)
+ * @param {string[]} [opts.notRevertible] - paths the run may delete but cannot
+ *   capture byte-for-byte (bulk dirs like `.venv`/plugin `node_modules`, or
+ *   out-of-target global files). Recorded in the manifest so the guarantee is
+ *   honest, never restored.
+ * @param {string} [opts.packageVersion]
+ * @param {() => Date} [opts.clock]
+ * @param {number} [opts.keep=DEFAULT_KEEP] - retained sets (0 = no pruning)
+ * @returns {{ dir: string, name: string, manifest: object }}
+ */
+export function createBackupSet({
+  configDir,
+  entries,
+  notRevertible = [],
+  packageVersion = 'unknown',
+  clock = () => new Date(),
+  keep = DEFAULT_KEEP,
+} = {}) {
+  const base = clock()
+  const name = nextBackupName(configDir, base)
+  const dir = backupSetPath(configDir, name)
+  ensureDir(backupRoot(configDir), 0o700)
+  ensureDir(dir, 0o700)
+
+  const seen = new Set()
+  const manifestEntries = []
+  for (const relativePath of entries ?? []) {
+    const rel = String(relativePath)
+    if (rel === '' || seen.has(rel)) continue
+    seen.add(rel)
+    const source = join(configDir, rel)
+    let stat = null
+    try {
+      stat = lstatSync(source)
+    } catch {
+      stat = null
+    }
+    if (stat?.isFile()) {
+      const buffer = readFileSync(source)
+      const dest = join(dir, rel)
+      ensureDir(dirname(dest), 0o700)
+      writeFileSync(dest, buffer, { mode: 0o600 })
+      chmodBestEffort(dest, 0o600)
+      manifestEntries.push({
+        relativePath: rel,
+        existed: true,
+        sha256: sha256(buffer),
+        bytes: buffer.length,
+        mode: stat.mode & 0o777,
+      })
+    } else {
+      manifestEntries.push({
+        relativePath: rel,
+        existed: false,
+        sha256: null,
+        bytes: 0,
+        mode: null,
+      })
+    }
+  }
+
+  const manifest = {
+    createdAt: base.toISOString(),
+    packageVersion,
+    configDir,
+    notRevertible: [...new Set((notRevertible ?? []).map(String))],
+    entries: manifestEntries,
+  }
+  const manifestPath = join(dir, 'manifest.json')
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 })
+  chmodBestEffort(manifestPath, 0o600)
+
+  const pruned = keep > 0 ? pruneBackups(configDir, keep) : { removed: [], failures: [] }
+  return { dir, name, manifest, pruned }
+}
+
+/**
+ * A manifest entry path must be a plain relative path inside the config dir —
+ * no absolute path and no `..` segment (the backup mirrors the config dir).
+ * Rejected at read time so a crafted manifest can never steer verify or restore
+ * outside the tree.
+ * @param {unknown} rel
+ * @returns {boolean}
+ */
+function isSafeRelativePath(rel) {
+  if (typeof rel !== 'string' || rel === '') return false
+  if (isAbsolute(rel)) return false
+  return !rel.split(/[\\/]/).includes('..')
+}
+
+/**
+ * Read and validate the manifest of a backup set.
+ *
+ * VALIDATION SCOPE (documented, not implied): this rejects a malformed manifest
+ * and any entry whose `relativePath` is absolute or contains `..` (fail closed).
+ * It does NOT make the manifest self-verifying — a DROPPED entry or a flipped
+ * `existed` flag cannot be detected from the manifest alone. Tampering with the
+ * CONTENT of a listed file (newline/truncation/hash change) IS detected by
+ * {@link verifyBackupSet}, because each listed file is re-hashed.
+ *
+ * @param {string} dir
+ * @returns {{ ok: true, manifest: object } | { ok: false, reason: string }}
+ */
+export function readManifest(dir) {
+  const manifestPath = join(dir, 'manifest.json')
+  if (!existsSync(manifestPath)) return { ok: false, reason: 'missing-manifest' }
+  try {
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+    if (!manifest || !Array.isArray(manifest.entries)) {
+      return { ok: false, reason: 'invalid-manifest' }
+    }
+    if (manifest.entries.some((e) => !e || !isSafeRelativePath(e.relativePath))) {
+      return { ok: false, reason: 'unsafe-path' }
+    }
+    return { ok: true, manifest }
+  } catch {
+    return { ok: false, reason: 'invalid-manifest' }
+  }
+}
+
+/**
+ * Verify every backed-up file still matches its manifest hash. Any missing file
+ * or hash mismatch is reported (no silent partial restore).
+ * @param {string} dir
+ * @returns {{ ok: boolean, reason?: string, mismatches: string[] }}
+ */
+export function verifyBackupSet(dir) {
+  const read = readManifest(dir)
+  if (!read.ok) return { ok: false, reason: read.reason, mismatches: [] }
+  const mismatches = []
+  for (const entry of read.manifest.entries) {
+    if (!entry.existed) continue
+    const file = join(dir, entry.relativePath)
+    if (!existsSync(file)) {
+      mismatches.push(entry.relativePath)
+      continue
+    }
+    if (sha256(readFileSync(file)) !== entry.sha256) mismatches.push(entry.relativePath)
+  }
+  return { ok: mismatches.length === 0, mismatches }
+}
+
+/** Order for writes: `opencode.json` strictly last. */
+function restoreOrder(a, b) {
+  const last = (rel) => (rel === 'opencode.json' ? 1 : 0)
+  if (last(a.relativePath) !== last(b.relativePath))
+    return last(a.relativePath) - last(b.relativePath)
+  return a.relativePath.localeCompare(b.relativePath)
+}
+
+/**
+ * Compute the restore plan by PATH ONLY (no contents exposed). Absent-in-backup
+ * entries that now exist become `remove`; a present target is hashed internally
+ * to classify it as `unchanged` or `update`. Hashes are never returned or
+ * printed at this layer — only `{ relativePath, action }`.
+ *
+ * @param {string} dir - backup set directory
+ * @param {string} configDir
+ * @returns {{ entries: Array<{relativePath: string, action: string}>, manifest: object } | { error: string }}
+ */
+export function planRestore(dir, configDir) {
+  const read = readManifest(dir)
+  if (!read.ok) return { error: read.reason }
+  const verify = verifyBackupSet(dir)
+  if (!verify.ok) return { error: verify.reason ?? 'integrity', mismatches: verify.mismatches }
+
+  const entries = []
+  for (const entry of [...read.manifest.entries].sort(restoreOrder)) {
+    const target = join(configDir, entry.relativePath)
+    if (entry.existed) {
+      let action = 'create'
+      try {
+        const st = lstatSync(target)
+        if (st.isFile()) {
+          const current = readFileSync(target)
+          action = sha256(current) === entry.sha256 ? 'unchanged' : 'update'
+        } else {
+          action = 'update'
+        }
+      } catch {
+        action = 'create'
+      }
+      entries.push({ relativePath: entry.relativePath, action })
+    } else {
+      const exists = existsSync(target)
+      entries.push({ relativePath: entry.relativePath, action: exists ? 'remove' : 'unchanged' })
+    }
+  }
+  return { entries, manifest: read.manifest }
+}
+
+/**
+ * Restore a verified backup set into `configDir`. Refuses (throws) if the
+ * manifest is missing/invalid or any backed-up file is tampered.
+ *
+ * @param {string} dir
+ * @param {string} configDir
+ * @param {{ dryRun?: boolean }} [opts]
+ * @returns {{ entries: Array<{relativePath: string, action: string}> }}
+ */
+export function restoreBackupSet(dir, configDir, { dryRun = false } = {}) {
+  const plan = planRestore(dir, configDir)
+  if (plan.error) {
+    const detail = plan.mismatches?.length ? ` (${plan.mismatches.length} mismatch(es))` : ''
+    throw new Error(`Backup is not restorable: ${plan.error}${detail}`)
+  }
+  if (dryRun) return { entries: plan.entries }
+
+  for (const item of plan.entries) {
+    const backUpFile = join(dir, item.relativePath)
+    const target = join(configDir, item.relativePath)
+    if (item.action === 'unchanged') continue
+
+    // Refuse to write through/over a symlink (mirrors writeIfChanged).
+    let linkStat = null
+    try {
+      linkStat = lstatSync(target)
+    } catch {
+      linkStat = null
+    }
+    if (linkStat?.isSymbolicLink()) {
+      throw new Error(`Refusing to restore through symlink: ${item.relativePath}`)
+    }
+
+    if (item.action === 'remove') {
+      if (linkStat?.isFile()) rmSync(target, { force: true })
+      continue
+    }
+
+    const buffer = readFileSync(backUpFile)
+    ensureDir(dirname(target), 0o700)
+    writeFileSync(target, buffer, { mode: 0o600 })
+    const recorded = plan.manifest.entries.find((e) => e.relativePath === item.relativePath)
+    if (recorded && recorded.mode !== null) chmodBestEffort(target, recorded.mode)
+  }
+  return { entries: plan.entries }
+}
+
+/**
+ * Delete all but the `keep` most-recent backup sets under the config dir.
+ * Only directories that pass {@link isDeletableBackupDir} are ever removed;
+ * deletion failures are reported, never thrown.
+ *
+ * @param {string} configDir
+ * @param {number} [keep=DEFAULT_KEEP]
+ * @returns {{ removed: string[], failures: string[] }}
+ */
+export function pruneBackups(configDir, keep = DEFAULT_KEEP) {
+  const removed = []
+  const failures = []
+  const sets = listBackupSets(configDir)
+  for (const set of sets.slice(keep)) {
+    if (!isDeletableBackupDir(configDir, set.dir)) continue
+    try {
+      rmSync(set.dir, { recursive: true, force: true })
+      removed.push(set.name)
+    } catch {
+      failures.push(set.name)
+    }
+  }
+  return { removed, failures }
+}
+
+/**
+ * The one-time, exact, secret-safe warning printed before the installer applies.
+ * @param {string} backupPath
+ * @returns {string}
+ */
+export function backupWarning(backupPath) {
+  return (
+    `Backup created at ${backupPath} (mode 0600). It is an exact copy of your ` +
+    `current files and therefore also contains any API keys or tokens already ` +
+    `present in them. It is never printed. Restore with: pantheon-opencode restore`
+  )
+}

package/scripts/install/cli-ui.mjs

@@ -33,7 +33,12 @@ export function configure(opts = {}) {
   if (opts.dryRun !== undefined) _dryRun = opts.dryRun
 }
 
-function tag(msg) {
+/**
+ * Prefix a message with the `[DRY-RUN]` marker while a dry run is configured.
+ * Exported so callers that print through raw `console.log` (e.g. the per-file
+ * change plan) stay consistent with every other dry-run line.
+ */
+export function tag(msg) {
   return _dryRun ? `[DRY-RUN] ${msg}` : msg
 }
 

package/scripts/install/exit-codes.mjs

@@ -0,0 +1,26 @@
+/**
+ * exit-codes.mjs — the process exit code the `init` CLI returns for an
+ * `installOpenCode` result. Pure, so the mapping is unit-testable without
+ * spawning the CLI.
+ *
+ *   `0`   success, or plan-only / declined (nothing applied)
+ *   `1`   failure (the CLI handles thrown errors separately)
+ *   `2`   apply requested without authorization (non-interactive, no --yes)
+ *   `3`   drift detected — a planned target changed between plan and apply
+ *   `130` canceled
+ */
+
+export function resolveInstallExitCode(result, isDryRun) {
+  if (isDryRun) return 0
+  if (result?.applied !== false) return 0
+  switch (result.reason) {
+    case 'not-authorized':
+      return 2
+    case 'drift':
+      return 3
+    case 'canceled':
+      return 130
+    default:
+      return 0
+  }
+}

package/scripts/install/interactive.mjs

@@ -184,7 +184,7 @@ export async function promptConfirm(message, { default: def = true } = {}) {
       reject(new Error('Canceled'))
     }
 
-    function handler(_str, key) {
+    function handler(str, key) {
       if (!key) return
       if ((key.ctrl && key.name === 'c') || key.name === 'escape') {
         cancel()
@@ -208,6 +208,20 @@ export async function promptConfirm(message, { default: def = true } = {}) {
   })
 }
 
+/**
+ * Apply-gate prompt. Unlike the pre-install confirm this defaults to NO, so a
+ * bare Enter never authorizes a write. In a non-TTY it returns the default
+ * (`false`) without blocking — callers that must not prompt at all should branch
+ * on TTY before calling.
+ *
+ * @param {string} planSummary e.g. "Apply these 12 changes?"
+ * @param {{ default?: boolean }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function promptReview(planSummary, { default: def = false } = {}) {
+  return promptConfirm(planSummary, { default: def })
+}
+
 export async function promptList(options, { title = '' } = {}) {
   if (options.length === 0) throw new Error('No options provided')
   if (options.length === 1) return options[0].value

package/scripts/install/migrate.mjs

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { ACTIONS, recordChange, snapshot } from './plan.mjs'
 import { createInitialState, readState, writeState } from './state.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -44,10 +45,10 @@ export function detectVersion(target) {
  *
  * @param {string} target - Installation directory
  * @param {string|null} currentVersion - Detected version (null = fresh install)
- * @param {{ dryRun?: boolean }} [options]
+ * @param {{ dryRun?: boolean, recorder?: (change: object) => void }} [options]
  * @returns {{ applied: number, messages: string[] }}
  */
-export function runMigrations(target, currentVersion, { dryRun = false } = {}) {
+export function runMigrations(target, currentVersion, { dryRun = false, recorder = null } = {}) {
   const applied = []
   const semver = parseSemver(currentVersion)
 
@@ -104,28 +105,46 @@ export function runMigrations(target, currentVersion, { dryRun = false } = {}) {
   }
 
   // ── Write updated state ───────────────────────────────────────────
-  if (applied.length > 0 && !dryRun) {
-    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' },
+  if (applied.length > 0) {
+    const statePath = join(target, '.pantheon', 'install-state.json')
+    if (dryRun) {
+      // State-only bookkeeping write: recorded so the preview is complete, but
+      // unscored because the install summary does not count it. Classified as
+      // an update — a migration that applies implies a state file existed.
+      recordChange({ path: statePath, action: ACTIONS.UPDATE, bytes: 0, scored: false }, recorder)
+    } else {
+      const newVersion = formatSemver(semver)
+      let state = readState(target)
+      const stateExisted = state !== null
+      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)
+      recordChange(
+        {
+          path: statePath,
+          action: stateExisted ? ACTIONS.UPDATE : ACTIONS.CREATE,
+          bytes: snapshot(statePath).size,
+          scored: false,
+        },
+        recorder,
+      )
     }
-    writeState(target, state)
   }
 
   return {