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

package/scripts/doctor.mjs

@@ -29,6 +29,8 @@ import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { listV2UnsupportedFeatures } from '../src/pantheon/v2-unsupported.mjs'
+
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
@@ -1000,7 +1002,7 @@ function checkVenvLayer(args) {
 /**
  * Return whether *dir* contains an executable code-mode target.
  *
- * Mirrors `_has_usable_scripts` in `scripts/code_mode_server.py`: a directory
+ * Mirrors `_has_usable_scripts` in `scripts/code_mode.py`: a directory
  * is only a valid resolver candidate when it is a real (non-symlink) directory
  * containing a regular `.py`/`.sh` direct child. This prevents an empty project
  * overlay from masking a lower-priority installation that actually ships
@@ -1430,6 +1432,153 @@ export function checkPluginVersionDrift(args) {
   return 'sync'
 }
 
+// ---------------------------------------------------------------------------
+// Check H4: V2 feature reduction (the surface a migrating user loses)
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether an opencode.json registers the V2 generation of the Pantheon plugin.
+ *
+ * The V2 contract is the PLURAL `plugins` key; V1 is the singular `plugin` key.
+ * So the key alone is not the test — a config can legitimately carry a
+ * third-party entry in `plugins`. What identifies the generation is a Pantheon
+ * V2 entry inside it. Matched on the `plugin-v2` marker so all three real
+ * spellings are recognised: the canonical DIRECTORY (`src/plugin-v2`), an
+ * absolute path to it, and the package export (`pantheon-opencode/plugin-v2`).
+ *
+ * @param {unknown} ref
+ * @returns {boolean}
+ */
+function isV2PluginRef(ref) {
+  const candidate =
+    typeof ref === 'string'
+      ? ref
+      : ref && typeof ref === 'object'
+        ? (ref.path ?? ref.source ?? ref.id ?? ref.name)
+        : undefined
+  return typeof candidate === 'string' && candidate.includes('plugin-v2')
+}
+
+/**
+ * Whether any reachable config registers the V2 generation of the Pantheon
+ * plugin. Split out of {@link collectV2UnsupportedFeatures} because "is the V2
+ * generation registered" and "does the seed list anything" are TWO facts: the
+ * first is about the user's config, the second about this repository's seed. A
+ * single `features.length === 0` cannot tell them apart, and conflating them
+ * let an emptied seed print "no V2 generation registered — nothing reduced".
+ *
+ * @param {{path:string, data:object}[]} configs
+ * @returns {boolean}
+ */
+export function isV2GenerationRegistered(configs) {
+  return configs.some((cfg) => {
+    const list = cfg.data?.plugins
+    return Array.isArray(list) && list.some(isV2PluginRef)
+  })
+}
+
+/**
+ * The V2 feature-reduction markers to report for a set of collected configs.
+ *
+ * Returns the shared seed verbatim when ANY reachable config registers the V2
+ * generation, and an empty list otherwise. The strings come from
+ * `src/pantheon/v2-unsupported.mjs` — the same seed `getUnsupportedFeatures()`
+ * is built from — so doctor cannot report a reduction the plugin does not, or
+ * miss one it does. Nothing is reworded here.
+ *
+ * An empty result is ambiguous on its own and deliberately not interpreted
+ * here: ask {@link isV2GenerationRegistered} for the registration fact, or
+ * {@link describeV2Reduction} to get both at once.
+ *
+ * @param {{path:string, data:object}[]} configs
+ * @returns {string[]}
+ */
+export function collectV2UnsupportedFeatures(configs) {
+  return isV2GenerationRegistered(configs) ? listV2UnsupportedFeatures() : []
+}
+
+/**
+ * Decide what H4 prints, from the two distinct facts rather than from one list
+ * length.
+ *
+ * Three cases, and the middle one used to be silently reported as the first:
+ *
+ *   - not registered → info. A V1 install is a supported configuration with
+ *     nothing to reduce, and saying so plainly is correct.
+ *   - registered, seed EMPTY → warn. This is a packaging fault in THIS repo,
+ *     not an absence of reduction: the V2 surface really is reduced and the
+ *     report is missing. It must never claim "nothing reduced".
+ *   - registered, seed populated → warn, listing every marker.
+ *
+ * Pure and exported so the empty-seed branch is testable without stubbing the
+ * frozen seed module. `status` is returned alongside the text so a caller never
+ * has to recover the case by matching on the message.
+ *
+ * @param {{registered:boolean, features:string[]}} input
+ * @returns {{status:'reported'|'empty-seed'|'no-v2-generation', level:'info'|'warn', message:string}}
+ */
+export function describeV2Reduction({ registered, features }) {
+  if (!registered) {
+    return {
+      status: 'no-v2-generation',
+      level: 'info',
+      message: 'No V2 plugin generation registered — nothing reduced',
+    }
+  }
+  if (features.length === 0) {
+    return {
+      status: 'empty-seed',
+      level: 'warn',
+      message:
+        'Pantheon IS registered on the V2 plugin generation, but the shared ' +
+        'unsupported-feature seed is empty, so the reduction cannot be reported. ' +
+        "That is a fault in this installation's reporting, not an absence of " +
+        'reduction: the V2 surface still drops the 3 goal tools and the ' +
+        'caller/target delegation matrix.',
+    }
+  }
+  return {
+    status: 'reported',
+    level: 'warn',
+    message:
+      'Pantheon is registered on the V2 plugin generation, which registers 3 tools ' +
+      "(hashline_edit, pantheon_cost, pantheon_model) instead of the V1 surface's 6 plus " +
+      `the BackgroundJobBoard and the caller/target delegation matrix. Unsupported: ${features.join(', ')}`,
+  }
+}
+
+/**
+ * Report the V2 feature reduction through doctor's own output shape
+ * (section + warn/info), so it lands in the health summary like every other
+ * finding and never changes the exit code: a V2 install is a supported
+ * configuration, not a broken one.
+ *
+ * @param {{target:string, env?:object}} args
+ * @returns {'reported'|'empty-seed'|'no-v2-generation'|'no-config'}
+ */
+export function checkV2UnsupportedFeatures(args) {
+  section('H4. V2 Feature Reduction')
+
+  const configs = collectMcpConfigs(args)
+  if (configs.length === 0) {
+    info('No opencode.json was found — V2 feature reduction check skipped')
+    return 'no-config'
+  }
+
+  // Branch on REGISTRATION, not on the marker count: an empty seed on a
+  // registered V2 generation is a reporting fault and must not be reported as
+  // the reassuring "nothing reduced".
+  const registered = isV2GenerationRegistered(configs)
+  const verdict = describeV2Reduction({
+    registered,
+    features: collectV2UnsupportedFeatures(configs),
+  })
+  if (verdict.level === 'info') info(verdict.message)
+  else warn(verdict.message)
+
+  return verdict.status
+}
+
 // ---------------------------------------------------------------------------
 // Check G: AGENTS.md freshness
 // ---------------------------------------------------------------------------
@@ -1802,6 +1951,7 @@ async function main() {
   checkAgentsMdFreshness(args)
   checkSubagentDepthPlacement(args)
   checkPermissionTaskPresence(args)
+  checkV2UnsupportedFeatures(args)
 
   printSummary(args.target)
 

package/scripts/install/agents-md.mjs

@@ -2,7 +2,7 @@
 /**
  * agents-md.mjs — Dynamic AGENTS.md generator from canonical agent frontmatter
  *
- * Reads all agents/*.agent.md files, extracts name + description from frontmatter,
+ * Reads all canonical src/agents/*.md files, extracts name + description from frontmatter,
  * and generates AGENTS.md content dynamically. Eliminates hardcoded agent tables
  * in platform installers (claude.mjs, cursor.mjs, windsurf.mjs, cline.mjs, etc.).
  *
@@ -21,7 +21,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import yaml from 'js-yaml'
+import { load } from 'js-yaml'
 
 // ---------------------------------------------------------------------------
 // Paths
@@ -47,7 +47,7 @@ function parseAgentFrontmatter(content) {
   if (!match) return null
 
   try {
-    const fm = yaml.load(match[1])
+    const fm = load(match[1])
     if (!fm || typeof fm !== 'object' || !fm.name) return null
     return {
       name: String(fm.name),
@@ -64,7 +64,7 @@ function parseAgentFrontmatter(content) {
 // ---------------------------------------------------------------------------
 
 /**
- * Read all canonical agents/*.agent.md files, parse frontmatter,
+ * Read all canonical src/agents/*.md files, parse frontmatter,
  * and return an array of agent metadata objects sorted alphabetically by name.
  *
  * Skips files that don't match the `*.agent.md` pattern, files without

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
 }