@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0-mvp.2

package/scripts/file-classes.mjs

@@ -42,6 +42,9 @@ const RULES = [
   {
     class: FILE_CLASSES.derived,
     patterns: [
+      // The managed root guidance file is rendered from the package template,
+      // refreshed by sync, and drift-checked by doctor — never hand-edited.
+      'AGENTS.md',
       'app/app/[[...slug]]/**',
       'app/lib/*/handlers.ts',
       'app/lib/*/handlers.core.ts',
@@ -55,6 +58,8 @@ const RULES = [
       'app/lib/*/cart-state.ts',
       'app/lib/*/actions.ts',
       'app/lib/*/catalog.ts',
+      'app/lib/*/section-sources.ts',
+      'app/lib/*/section-observation.ts',
       'app/lib/*/runtime.ts',
       'app/lib/*/registry.tsx',
       'app/lib/*/schema.ts',

package/scripts/migrate-english-routes.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// Opt-in migration for the retired Spanish route literals in an existing
+// consumer's USER-OWNED content files (change: storefront-english-routes,
+// task 3.4 / AC-EN-5.4).
+//
+// WHY THIS EXISTS: `storefront sync` never rewrites a user-owned file, so a
+// consumer created before the English-route change keeps Spanish links in its
+// own `lib/<name>/shell/content.ts` (and the user-owned static-page `path`
+// declarations in `lib/<name>/views/static/content.ts`). Changing the package
+// default cannot change an existing consumer's links, so this script is the
+// documented, CLI-bounded, opt-in transition. It:
+//   * rewrites ONLY the retired route literal at the START of an `href`/`path`
+//     string property value (root-relative), preserving the backend handle and
+//     any `?query`/`#hash`,
+//   * ONLY inside the two user-owned content files on the allow-list,
+//   * ONLY when run with `--apply` (dry-run by default),
+//   * keeps a no-clobber backup of each file it rewrites, and writes
+//     transactionally (all files or none),
+//   * and preserves unrelated prose, comments, absolute URLs, and nested
+//     `/api/...` paths — it never re-parses the whole file as a grammar.
+//
+// Usage:
+//   node scripts/migrate-english-routes.mjs <project-dir>          # dry run
+//   node scripts/migrate-english-routes.mjs <project-dir> --apply  # write
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs'
+import { resolve, join, relative, dirname, isAbsolute, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readManifest } from './manifest.mjs'
+import { assertInsideProject, atomicWrite, restoreSnapshot, takeSnapshot } from './plan-apply.mjs'
+
+// Retired route literal -> English route literal. These are matched ONLY as the
+// FIRST path segment of an `href`/`path` string property value.
+export const RETIRED = [
+  ['/categorias', '/categories'],
+  ['/productos', '/products'],
+  ['/cuenta', '/account'],
+  ['/contacto', '/contact'],
+  ['/terminos', '/terms'],
+  ['/privacidad', '/privacy'],
+  ['/sobre-nosotros', '/about'],
+]
+
+// A safe single-segment storefront name: no separators, no `..`, no leading dot.
+const SAFE_NAME = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/
+// The property keys whose string value is a route.
+const ROUTE_PROP = /(?:^|[^A-Za-z0-9_$.-])(?:href|path)\s*:\s*$/
+const QUOTES = new Set(["'", '"', '`'])
+const BACKUP_DIR = join('.opencode', 'backups', 'english-routes')
+
+/** The user-owned content files, relative to the project, that may carry a route literal. */
+export function userOwnedRouteFiles(name) {
+  return [join('lib', name, 'shell', 'content.ts'), join('lib', name, 'views', 'static', 'content.ts')]
+}
+
+/**
+ * Rewrite a route value only when it is a retired root-relative route:
+ * `/productos/<handle>?q#h` -> `/products/<handle>?q#h` (handle/query/hash kept).
+ * Returns null when the value is not a retired route (absolute URL, `/api/...`,
+ * prose, an already-English route, or a different route).
+ */
+export function migrateRouteValue(value) {
+  for (const [from, to] of RETIRED) {
+    if (
+      value === from ||
+      value.startsWith(`${from}/`) ||
+      value.startsWith(`${from}?`) ||
+      value.startsWith(`${from}#`)
+    ) {
+      return to + value.slice(from.length)
+    }
+  }
+  return null
+}
+
+// Split the source into code / string / comment tokens with a small scanner, so
+// a retired literal inside a comment or prose is never touched and only a string
+// token that directly follows an `href:`/`path:` property key is considered.
+function scan(text) {
+  const tokens = []
+  const n = text.length
+  let i = 0
+  let codeStart = 0
+  const pushCode = (end) => {
+    if (end > codeStart) tokens.push({ type: 'code', text: text.slice(codeStart, end) })
+  }
+  while (i < n) {
+    const c = text[i]
+    if (c === '/' && text[i + 1] === '/') {
+      pushCode(i)
+      let j = text.indexOf('\n', i)
+      if (j === -1) j = n
+      tokens.push({ type: 'comment', text: text.slice(i, j) })
+      i = j
+      codeStart = i
+      continue
+    }
+    if (c === '/' && text[i + 1] === '*') {
+      pushCode(i)
+      let j = text.indexOf('*/', i + 2)
+      j = j === -1 ? n : j + 2
+      tokens.push({ type: 'comment', text: text.slice(i, j) })
+      i = j
+      codeStart = i
+      continue
+    }
+    if (QUOTES.has(c)) {
+      pushCode(i)
+      let j = i + 1
+      while (j < n) {
+        if (text[j] === '\\') {
+          j += 2
+          continue
+        }
+        if (text[j] === c) {
+          j++
+          break
+        }
+        if (text[j] === '\n' && c !== '`') break
+        j++
+      }
+      tokens.push({ type: 'string', text: text.slice(i, j) })
+      i = j
+      codeStart = i
+      continue
+    }
+    i++
+  }
+  pushCode(n)
+  return tokens
+}
+
+/** Rewrite the retired route literals in an `href`/`path` value. Idempotent. */
+export function migrateText(text) {
+  const tokens = scan(text)
+  for (let k = 1; k < tokens.length; k++) {
+    const token = tokens[k]
+    if (token.type !== 'string') continue
+    const prev = tokens[k - 1]
+    if (!prev || prev.type !== 'code' || !ROUTE_PROP.test(prev.text)) continue
+    if (token.text.length < 2 || token.text[0] !== token.text[token.text.length - 1]) continue
+    const quote = token.text[0]
+    const migrated = migrateRouteValue(token.text.slice(1, -1))
+    if (migrated === null) continue
+    tokens[k] = { type: 'string', text: quote + migrated + quote }
+  }
+  return tokens.map((token) => token.text).join('')
+}
+
+// Containment: the resolved file must live under the project root, both
+// lexically and (when it exists) through any symlinked ancestor.
+function insideProject(projectDir, abs) {
+  const rel = relative(projectDir, abs)
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return false
+  if (!existsSync(abs)) return true
+  try {
+    const realRoot = realpathSync(projectDir)
+    const realAbs = realpathSync(abs)
+    return realAbs === realRoot || realAbs.startsWith(`${realRoot}${sep}`)
+  } catch {
+    return false
+  }
+}
+
+/** Plan the migration: the allow-listed files whose text would change. */
+export async function planMigration(projectDir) {
+  const manifest = await readManifest(projectDir)
+  if (!manifest) return { ok: false, error: `no storefront.config.json found in ${projectDir}` }
+  const name = manifest.name
+  if (typeof name !== 'string' || !SAFE_NAME.test(name)) {
+    return { ok: false, error: `storefront name ${JSON.stringify(name)} is not a safe path segment` }
+  }
+  const root = resolve(projectDir)
+  const changes = []
+  for (const rel of userOwnedRouteFiles(name)) {
+    const abs = join(root, rel)
+    if (!insideProject(root, abs)) {
+      return { ok: false, error: `allow-listed path escapes the project: ${rel}` }
+    }
+    if (!existsSync(abs)) continue
+    const raw = readFileSync(abs, 'utf8')
+    const next = migrateText(raw)
+    if (next === raw) continue
+    changes.push({ file: rel, abs, raw, next })
+  }
+  return { ok: true, root, name, changes }
+}
+
+// No-clobber backup: create exclusively; an existing backup is reused only when
+// it already holds this exact pre-migration content, otherwise the apply refuses.
+function ensureBackup(root, rel, raw) {
+  const abs = join(root, BACKUP_DIR, rel)
+  // A symlinked `.opencode/backups` must never redirect the backup outside the
+  // project; the same containment guard the retirement backup uses.
+  assertInsideProject(root, abs)
+  mkdirSync(dirname(abs), { recursive: true })
+  if (existsSync(abs)) {
+    if (readFileSync(abs, 'utf8') !== raw) {
+      throw new Error(`refusing to overwrite an existing backup with different content: ${abs}`)
+    }
+    return { path: abs, created: false }
+  }
+  writeFileSync(abs, raw, { flag: 'wx' })
+  return { path: abs, created: true }
+}
+
+export async function migrateProject(projectDir, { apply = false } = {}) {
+  const plan = await planMigration(projectDir)
+  if (!plan.ok) return { ok: false, error: plan.error, changed: [] }
+
+  const planned = plan.changes.map((change) => ({ file: change.file, applied: false }))
+  if (!apply || plan.changes.length === 0) {
+    return { ok: true, apply, changed: planned, files: plan.changes.map((c) => c.abs), backups: [] }
+  }
+
+  const snapshot = takeSnapshot(plan.root, plan.changes.map((c) => c.abs))
+  const backups = []
+  const createdBackups = []
+  try {
+    for (const change of plan.changes) {
+      const backup = ensureBackup(plan.root, change.file, change.raw)
+      backups.push(backup.path)
+      if (backup.created) createdBackups.push(backup.path)
+      atomicWrite(change.abs, change.next)
+    }
+  } catch (error) {
+    restoreSnapshot(snapshot)
+    for (const backup of createdBackups) rmSync(backup, { force: true })
+    return { ok: false, error: error instanceof Error ? error.message : String(error), changed: [] }
+  }
+  return {
+    ok: true,
+    apply,
+    changed: plan.changes.map((change) => ({ file: change.file, applied: true })),
+    files: plan.changes.map((c) => c.abs),
+    backups,
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  const projectDir = args.find((a) => !a.startsWith('-'))
+  const apply = args.includes('--apply')
+  if (!projectDir) {
+    console.error('Usage: node scripts/migrate-english-routes.mjs <project-dir> [--apply]')
+    return 1
+  }
+  const result = await migrateProject(resolve(projectDir), { apply })
+  if (!result.ok) {
+    console.error(result.error)
+    return 1
+  }
+  if (result.changed.length === 0) {
+    console.log('No retired Spanish route literal found in the user-owned content files — nothing to migrate.')
+    return 0
+  }
+  for (const entry of result.changed) {
+    console.log(`  ${apply ? 'migrated' : 'would migrate'} ${entry.file}`)
+  }
+  for (const backup of result.backups) console.log(`  backup ${backup}`)
+  if (!apply) {
+    console.log('Dry run — re-run with --apply to rewrite these user-owned files.')
+  }
+  return 0
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main()
+    .then((code) => {
+      process.exitCode = code
+    })
+    .catch((err) => {
+      console.error(err)
+      process.exitCode = 1
+    })
+}

package/scripts/pinning.mjs

@@ -41,7 +41,9 @@ export const TOOLCHAIN = {
 // The managed suite is the package-owned surface installed into `.opencode/`.
 // Its BOM is what `doctor` and `update` compare; user-owned storefront files
 // live outside it. Only these directories are ever treated as package-owned.
-export const MANAGED_SUITE_DIRS = ['commands', 'skills']
+// The suite ships skills only — the root `AGENTS.md` is a rendered project file
+// covered by derived drift (reconcile dry-run), not by this BOM.
+export const MANAGED_SUITE_DIRS = ['skills']
 
 // The CLI pins itself as a direct dependency so a generated project can
 // reproduce the exact toolchain that produced it.
@@ -80,18 +82,54 @@ export function satisfiesRange(version, range) {
   return semver.satisfies(version, range)
 }
 
+/**
+ * The package's operative skill set, read from the single declared source: the
+ * package skill layout. Under each managed suite directory, a directory that
+ * directly contains a `SKILL.md` is an operative skill; any other file under a
+ * skill is a scoped reference, never a skill. Returns sorted `<dir>/<name>`
+ * POSIX-relative paths. Installation, migration/refresh, and validation all
+ * read this one source — there is no separate registry or manifest that
+ * restates the set.
+ */
+export function declaredOperativeSkills(pkgRoot, dirs = MANAGED_SUITE_DIRS) {
+  const skills = []
+  for (const dir of dirs) {
+    const base = join(pkgRoot, dir)
+    if (!existsSync(base)) continue
+    for (const entry of readdirSync(base, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name)
+    )) {
+      if (!entry.isDirectory()) continue
+      if (existsSync(join(base, entry.name, 'SKILL.md'))) skills.push(`${dir}/${entry.name}`)
+    }
+  }
+  return skills.sort()
+}
+
+/**
+ * The scoped reference files shipped under the operative skills: every managed
+ * suite file that is not a skill's own root `SKILL.md`. References travel with
+ * their owning skill (so the installed skill can load them) but are never
+ * counted or installed as skills.
+ */
+export function declaredSuiteReferences(pkgRoot, dirs = MANAGED_SUITE_DIRS) {
+  const skillRoots = new Set(declaredOperativeSkills(pkgRoot, dirs).map((skill) => `${skill}/SKILL.md`))
+  return managedSuitePaths(pkgRoot, dirs).filter((rel) => !skillRoots.has(rel))
+}
+
 /**
  * The package-owned suite file set (sorted POSIX-relative paths) under the
  * managed suite directories of `pkgRoot`. This is the *complete owned asset
  * set*: only files shipped by the package are ever hashed or compared, so a
  * user's own skill/command files under `.opencode/` are neither stamped nor
- * treated as drift.
+ * treated as drift. The set is derived from the declared skill layout
+ * (`declaredOperativeSkills`), so a directory without a `SKILL.md` is not part
+ * of the suite.
  */
 export function managedSuitePaths(pkgRoot, dirs = MANAGED_SUITE_DIRS) {
   const paths = []
-  for (const dir of dirs) {
-    const base = join(pkgRoot, dir)
-    if (!existsSync(base)) continue
+  for (const skillRel of declaredOperativeSkills(pkgRoot, dirs)) {
+    const base = join(pkgRoot, skillRel)
     const walk = (current) => {
       for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) =>
         a.name.localeCompare(b.name)
@@ -129,6 +167,37 @@ export async function hashManagedSuite(rootDir, dirs = MANAGED_SUITE_DIRS) {
   return hashPaths(rootDir, managedSuitePaths(rootDir, dirs))
 }
 
+/**
+ * The owned-file set recorded in an install record, or `null` when the record
+ * predates the BOM (a legacy record) and the set cannot be derived. Callers
+ * MUST treat `null` conservatively: no file is retired from an undetermined
+ * set. Returns the `relpath -> digest` map itself (never a copy silently
+ * dropped), so callers can compare a recorded digest against the live file.
+ */
+export function recordedOwnedSet(record) {
+  if (!isPlainObject(record)) return null
+  if (isPlainObject(record.pinning) && isPlainObject(record.pinning.assets)) {
+    return record.pinning.assets
+  }
+  // An intermediate flattened shape that carried the BOM at the record root.
+  if (isPlainObject(record.assets)) return record.assets
+  return null
+}
+
+/**
+ * Retirement candidates: every path in the previously recorded owned-file set
+ * (the install-record BOM) that the incoming managed set no longer ships. A
+ * `null` or malformed recorded set yields no candidates, so retirement is never
+ * derived from an unknown set (the conservative legacy-record path).
+ */
+export function retirementCandidates(recordedAssets, incomingPaths) {
+  if (!isPlainObject(recordedAssets)) return []
+  const incoming = new Set(incomingPaths)
+  return Object.keys(recordedAssets)
+    .filter((rel) => !incoming.has(rel))
+    .sort()
+}
+
 /**
  * Read the consumer `package.json`. Returns `{ ok, pkg }` or `{ ok:false,
  * error }`; a missing or malformed file is an error, never an empty object.

package/scripts/plan-apply.mjs

@@ -35,6 +35,7 @@ import { classifyFile } from './file-classes.mjs'
 import { manifestPath, readManifest, writeManifest } from './manifest.mjs'
 import { parseOperationsEnvelope, reduceManifest } from './operations.mjs'
 import { detectOwnershipConflicts } from './ownership-conflict.mjs'
+import { preflightManifest } from './preflight.mjs'
 import { customizedViewFiles, reconcile, removeFeatureFiles, removeViewFiles } from './reconcile.mjs'
 
 const here = path.dirname(fileURLToPath(import.meta.url))
@@ -304,7 +305,7 @@ function diffFileState(before, after) {
 // existence of each ancestor directory under the project. Recording directories
 // is what lets a rollback remove the directories a create-only attempt made,
 // instead of leaving orphaned empty dirs behind a restored tree (E1 task 4.7).
-function takeSnapshot(projectDir, absPaths) {
+export function takeSnapshot(projectDir, absPaths) {
   const files = new Map()
   const dirs = new Map()
   for (const abs of absPaths) {
@@ -322,7 +323,7 @@ function takeSnapshot(projectDir, absPaths) {
   return { files, dirs }
 }
 
-function restoreSnapshot(snapshot) {
+export function restoreSnapshot(snapshot) {
   for (const [abs, prior] of snapshot.files) {
     if (prior.existed) {
       mkdirSync(path.dirname(abs), { recursive: true })
@@ -372,7 +373,10 @@ async function commitReduction(projectDir, reduction, { snapshot = false, inject
     }
     const result =
       rem.kind === 'view'
-        ? await removeViewFiles(projectDir, reduction.manifest, rem.name, { dryRun: true })
+        ? await removeViewFiles(projectDir, reduction.manifest, rem.name, {
+            dryRun: true,
+            legacyDerivedFiles: rem.legacyDerivedFiles,
+          })
         : await removeFeatureFiles(projectDir, reduction.manifest, rem.name, { dryRun: true })
     removalRemoved.push(...result.removed)
     preserved.push(...result.preserved)
@@ -394,7 +398,11 @@ async function commitReduction(projectDir, reduction, { snapshot = false, inject
   const snapshotState = snapshot ? takeSnapshot(projectDir, [...touched]) : null
   try {
     for (const rem of reduction.removals) {
-      if (rem.kind === 'view') await removeViewFiles(projectDir, reduction.manifest, rem.name)
+      if (rem.kind === 'view') {
+        await removeViewFiles(projectDir, reduction.manifest, rem.name, {
+          legacyDerivedFiles: rem.legacyDerivedFiles,
+        })
+      }
       if (rem.kind === 'feature') await removeFeatureFiles(projectDir, reduction.manifest, rem.name)
     }
     const result = await reconcile(projectDir, reduction.manifest)
@@ -453,6 +461,142 @@ export async function executeOperations(
   }
 }
 
+// The retired view ids the bounded `view remove` cleanup may still transition.
+// Exactly this list is permitted; any other unknown id fails closed so an
+// arbitrary unknown entry is never purged from a user-owned manifest
+// (change: storefront-retire-user-panel, Decision 4 / AC-UP-1.2).
+const LEGACY_VIEW_IDS = new Set(['user-panel'])
+// The derived files the retired view template shipped. They are regenerable and
+// unregistered after retirement, so the bounded cleanup removes exactly these
+// from a stale generated view directory; user-owned `schema.ts` and any unknown
+// file are preserved and reported (never a blind directory delete).
+const LEGACY_DERIVED_VIEW_FILES = Object.freeze({ 'user-panel': ['index.tsx', 'registry.tsx'] })
+const LEGACY_BACKUP_DIR = path.join('.opencode', 'backups', 'retire-user-panel')
+
+export function isLegacyViewId(name) {
+  return LEGACY_VIEW_IDS.has(name)
+}
+
+/**
+ * Containment guard for a path a caller is about to create under the project.
+ * Rejects a lexically-escaping path and, crucially, an existing ancestor whose
+ * realpath leaves the project (a symlinked `.opencode`/`backups` must never
+ * redirect a backup write outside the project). `root` must exist.
+ */
+export function assertInsideProject(root, abs) {
+  const rel = path.relative(root, abs)
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`refusing to write outside the project: ${abs}`)
+  }
+  const realRoot = realpathSync(root)
+  let probe = abs
+  while (!existsSync(probe)) {
+    const parent = path.dirname(probe)
+    if (parent === probe) break
+    probe = parent
+  }
+  if (existsSync(probe)) {
+    const realProbe = realpathSync(probe)
+    if (realProbe !== realRoot && !realProbe.startsWith(`${realRoot}${path.sep}`)) {
+      throw new Error(`refusing to write through a symlinked path outside the project: ${abs}`)
+    }
+  }
+  return abs
+}
+
+// No-clobber durable backup of the manifest before the bounded cleanup writes.
+// An existing backup is reused only when it already holds this exact content;
+// otherwise the cleanup refuses, so a backup is never silently replaced.
+function ensureLegacyManifestBackup(projectDir) {
+  const abs = path.join(projectDir, LEGACY_BACKUP_DIR, 'storefront.config.json')
+  assertInsideProject(projectDir, abs)
+  const raw = readFileSync(manifestPath(projectDir), 'utf8')
+  mkdirSync(path.dirname(abs), { recursive: true })
+  if (existsSync(abs)) {
+    if (readFileSync(abs, 'utf8') !== raw) {
+      throw new Error(`refusing to overwrite an existing backup with different content: ${abs}`)
+    }
+    return { path: abs, created: false }
+  }
+  writeFileSync(abs, raw, { flag: 'wx' })
+  return { path: abs, created: true }
+}
+
+/**
+ * Bounded legacy cleanup for a retired view id (`user-panel`). A manifest
+ * written before the view was retired carries an entry the registry no longer
+ * knows, so the normal reduce path refuses the input. This cleanup instead
+ * validates the resulting FUTURE manifest through the structural owner
+ * (`preflightManifest`), backs the manifest up, and commits transactionally
+ * through `commitReduction` — the same reconcile/plan-apply write boundary, no
+ * runtime-engine bypass and no re-enable. Only a `LEGACY_VIEW_IDS` member is
+ * permitted; any other id fails closed with an actionable diagnostic and no
+ * write. Idempotent: an already-absent entry is a truthful no-op.
+ */
+export async function removeLegacyView(projectDir, name, { inject = null } = {}) {
+  if (!isLegacyViewId(name)) {
+    const allowed = [...LEGACY_VIEW_IDS].map((id) => `"${id}"`).join(', ')
+    return {
+      ok: false,
+      diagnostics: [
+        diagnostic(
+          'E_UNKNOWN_VIEW',
+          `Unknown view "${name}". Only the retired legacy id ${allowed} can be removed by this cleanup; edit the canonical storefront.config.json to remove any other view.`,
+        ),
+      ],
+    }
+  }
+  const manifest = readManifest(projectDir)
+  if (!manifest) {
+    return {
+      ok: false,
+      diagnostics: [diagnostic('E_NO_MANIFEST', 'No storefront.config.json found in the project.')],
+    }
+  }
+  if (!manifest.views.some((view) => view.name === name)) {
+    return { ok: true, diagnostics: [], changed: [], preserved: [], alreadyRemoved: true }
+  }
+  const future = { ...manifest, views: manifest.views.filter((view) => view.name !== name) }
+  const preflight = preflightManifest(future)
+  if (!preflight.ok) {
+    return { ok: false, diagnostics: preflightDiagnostics(preflight.errors) }
+  }
+  // Same write-boundary ownership check as `executeOperations`: the future
+  // composition must not render a selected variant against a customized
+  // user-owned contract that no longer provides its data shape (E1 task 5.1).
+  const conflicts = detectOwnershipConflicts(projectDir, future)
+  if (!conflicts.ok) return { ok: false, diagnostics: conflicts.diagnostics }
+  let backup
+  try {
+    backup = ensureLegacyManifestBackup(projectDir)
+  } catch (error) {
+    return {
+      ok: false,
+      diagnostics: [
+        diagnostic('E_BACKUP_FAILED', error instanceof Error ? error.message : String(error)),
+      ],
+    }
+  }
+  const commit = await commitReduction(
+    projectDir,
+    {
+      ok: true,
+      manifest: future,
+      removals: [{ kind: 'view', name, legacyDerivedFiles: LEGACY_DERIVED_VIEW_FILES[name] ?? [] }],
+    },
+    { snapshot: true, inject },
+  )
+  if (!commit.ok) return { ok: false, diagnostics: commit.diagnostics, backup: backup.path }
+  return {
+    ok: true,
+    diagnostics: [],
+    changed: commit.changed,
+    preserved: commit.preserved,
+    backup: backup.path,
+    alreadyRemoved: false,
+  }
+}
+
 async function withStagedProject(projectDir, reduction, fn) {
   const stage = mkdtempSync(path.join(tmpdir(), 'cs-plan-stage-'))
   try {
@@ -691,7 +835,7 @@ export function assertSafeOutPath(projectDir, outPath, operationsPath = null) {
 // files are never touched. `inject(phase, context)` is a controlled test seam
 // (never read from the environment): production callers pass nothing, and a test
 // throws from `plan-after-temp-write` to prove the cleanup and byte-stability.
-function atomicWrite(abs, text, inject = null) {
+export function atomicWrite(abs, text, inject = null) {
   mkdirSync(path.dirname(abs), { recursive: true })
   const tmp = `${abs}.tmp-${process.pid}-${Date.now()}`
   try {