@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/scripts/plan-apply.mjs

@@ -0,0 +1,987 @@
+#!/usr/bin/env node
+// Inspect / plan / apply boundary for the composition engine (E1 tasks 4.1 and
+// 4.3; the remaining 4.x tasks harden each branch).
+//
+// `plan` is read-only against the project: it reduces the operation envelope
+// through `operations.mjs`, records before/after identity fingerprints, and (when
+// `--out` is given) writes only the plan artifact. `apply` resolves the current
+// state against the recorded before/after fingerprints under a local lock, then
+// writes derived files and the manifest last, rolling back every touched file on
+// a handled failure. The legacy `view`/`feature` aliases reduce and commit
+// through the same code (`executeOperations`), so alias and plan/apply agree.
+
+import { createHash } from 'node:crypto'
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { cp, mkdir, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { getFeature } from '../recipes/validate.mjs'
+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))
+const PKG_ROOT = path.resolve(here, '..')
+
+export const PLAN_FORMAT_VERSION = 1
+
+const SKIP_DIRS = new Set(['node_modules', '.next', '.git', '.turbo', '.yarn', 'dist', 'build'])
+const SECRET_BASENAME = [/^\.env($|\.)/, /\.pem$/i, /\.key$/i]
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key)
+}
+
+function diagnostic(code, message, extra = {}) {
+  return { code, severity: 'error', message, ...extra }
+}
+
+function preflightDiagnostics(errors) {
+  return errors.map((message) => diagnostic('E_INVALID_COMPOSITION', message))
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value).sort()
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+function sha256(text) {
+  return createHash('sha256').update(text).digest('hex')
+}
+
+function sha256File(abs) {
+  return createHash('sha256').update(readFileSync(abs)).digest('hex')
+}
+
+function isSecret(rel) {
+  const base = path.basename(rel)
+  return SECRET_BASENAME.some((re) => re.test(base))
+}
+
+/**
+ * Copy a project tree (e.g. `app/` or `lib/`) into a staging directory while
+ * excluding secret-bearing files (`.env`, `.env.*`, `.env.local`, `*.pem`,
+ * `*.key`). `fs.cp`'s `filter` runs before a file is read, so a credential is
+ * never copied — and therefore never written to the OS temp dir — even though
+ * the fingerprint domain already skips it (E1 task 4.13). Exported for the
+ * regression test; production callers use it through `withStagedProject`.
+ */
+export async function copyTreeExcludingSecrets(from, to) {
+  await cp(from, to, { recursive: true, filter: (src) => !isSecret(src) })
+}
+
+function walkFiles(dir, base = dir, out = []) {
+  if (!existsSync(dir)) return out
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue
+      walkFiles(path.join(dir, entry.name), base, out)
+    } else {
+      out.push(path.relative(base, path.join(dir, entry.name)).split(path.sep).join('/'))
+    }
+  }
+  return out
+}
+
+// Classify a project-relative file into the identity domain's derived vs
+// user-owned buckets, reusing the single file-classification rules.
+function classifyProjectRel(rel, name) {
+  if (rel.startsWith('lib/')) {
+    const viewsPrefix = `lib/${name}/views/`
+    const featuresPrefix = `lib/${name}/features/`
+    if (rel.startsWith(viewsPrefix)) return classifyFile(`views/${rel.slice(viewsPrefix.length)}`)
+    if (rel.startsWith(featuresPrefix)) {
+      return classifyFile(`features/${rel.slice(featuresPrefix.length)}`)
+    }
+    return classifyFile(`app/${rel}`)
+  }
+  if (rel.startsWith('app/')) return classifyFile(`app/app/${rel.slice('app/'.length)}`)
+  return null
+}
+
+// The generator's meaningful inputs: the CLI entry, the generation scripts, the
+// recipe/config registry (archetypes, features, sections, catalog, schemas), and
+// the authoring templates/assemblies. Hashing the whole set — not only
+// `scripts/` — keeps a template, registry, or archetype change from
+// masquerading as an unchanged generator (E1 task 4.4).
+const GENERATOR_ROOTS = ['bin', 'scripts', 'recipes', 'assets/templates']
+
+// Consumer-side installed-toolset evidence. The install record is normalized to
+// drop its per-install `installedAt` timestamp (nonsemantic: it changes on every
+// install) while keeping `pinning` (the semantic declared/resolved/asset BOM).
+const INSTALL_RECORD = path.join('.opencode', 'storefront.json')
+
+function sha256FileOrNull(abs) {
+  return existsSync(abs) && statSync(abs).isFile() ? sha256File(abs) : null
+}
+
+function hashRoots(rootDir, relRoots) {
+  const entries = []
+  for (const relRoot of relRoots) {
+    const abs = path.join(rootDir, relRoot)
+    if (!existsSync(abs)) continue
+    if (statSync(abs).isFile()) {
+      entries.push(`${relRoot}\0${sha256File(abs)}`)
+      continue
+    }
+    for (const rel of walkFiles(abs)) {
+      entries.push(`${relRoot}/${rel}\0${sha256File(path.join(abs, rel))}`)
+    }
+  }
+  entries.sort()
+  return sha256(entries.join('\n'))
+}
+
+function readInstallRecord(projectDir) {
+  const abs = path.join(projectDir, INSTALL_RECORD)
+  if (!existsSync(abs) || !statSync(abs).isFile()) return null
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(abs, 'utf8'))
+  } catch {
+    return null
+  }
+  if (!isPlainObject(parsed)) return null
+  const normalized = { ...parsed }
+  delete normalized.installedAt
+  return normalized
+}
+
+/**
+ * The pinned toolkit/toolset identity (Decision 14). `catalog` and `generator`
+ * are the package's semantic catalog and generation-authoring sources; `toolset`
+ * is the consumer's actual installed-toolset evidence (package manifest,
+ * lockfile, and the `installedAt`-normalized install record). An absent consumer
+ * file is recorded as `null`, so no phantom pin is emitted.
+ */
+export function computePins({ pkgRoot = PKG_ROOT, projectDir } = {}) {
+  return {
+    catalog: sha256File(path.join(pkgRoot, 'recipes', 'catalog.json')),
+    generator: hashRoots(pkgRoot, GENERATOR_ROOTS),
+    toolset: sha256(
+      stableStringify({
+        packageJson: sha256FileOrNull(path.join(projectDir, 'package.json')),
+        lockfile: sha256FileOrNull(path.join(projectDir, 'yarn.lock')),
+        installRecord: readInstallRecord(projectDir),
+      }),
+    ),
+  }
+}
+
+/**
+ * The canonical identity domain (Decision 14): manifest, pins, derived and
+ * user-owned file-state hashes, and the canonical operations. Secret-bearing
+ * files are excluded by construction, so a fingerprint never absorbs `.env*`,
+ * `*.pem`, or `*.key`. Returns `{ identity, hash }`.
+ */
+export function projectIdentity(
+  projectDir,
+  manifest,
+  operations,
+  pins = computePins({ projectDir }),
+) {
+  const derived = {}
+  const userOwned = {}
+  const name = typeof manifest?.name === 'string' ? manifest.name : ''
+  for (const root of ['app', 'lib']) {
+    for (const rel of walkFiles(path.join(projectDir, root))) {
+      const projectRel = `${root}/${rel}`
+      if (isSecret(projectRel)) continue
+      const abs = path.join(projectDir, projectRel)
+      const fileClass = classifyProjectRel(projectRel, name)
+      const target = fileClass === 'derived' ? derived : userOwned
+      target[projectRel] = sha256File(abs)
+    }
+  }
+  const identity = {
+    formatVersion: PLAN_FORMAT_VERSION,
+    manifest,
+    pins,
+    derived,
+    userOwned,
+    operations,
+  }
+  return { identity, hash: sha256(stableStringify(identity)) }
+}
+
+export function resultEnvelope(command, ok, exitCode, diagnostics = [], result = null) {
+  return {
+    formatVersion: PLAN_FORMAT_VERSION,
+    command,
+    ok,
+    exitCode,
+    diagnostics,
+    result,
+  }
+}
+
+// The stable diagnostic for an unexpected internal failure (E1 task 4.11). It
+// carries no stack, no absolute path, and no captured value — only the error
+// class name — so the envelope is safe to print even when the underlying error
+// message embeds a secret or a machine path. The raw error is logged to stderr
+// (sanitized) by `runGuarded`, so it is never swallowed.
+export function unexpectedDiagnostic(error) {
+  return {
+    code: 'E_UNEXPECTED',
+    severity: 'error',
+    message: 'unexpected internal error',
+    detail: { name: error instanceof Error ? error.name : 'Error' },
+  }
+}
+
+// Replace the project root and the OS temp root with stable placeholders before
+// a message reaches stderr, so an unexpected error cannot leak an absolute
+// machine path even in the log.
+function sanitizeForLog(text, projectDir) {
+  let out = text
+  if (projectDir) out = out.split(projectDir).join('<project>')
+  out = out.split(tmpdir()).join('<tmp>')
+  return out
+}
+
+// Run a plan/apply body and convert an *unexpected* throw into an exit-2
+// envelope instead of an unhandled rejection. Handled failures already return
+// their own exit-1 envelope from inside the body, so they never reach here.
+async function runGuarded(command, projectDir, body) {
+  try {
+    return await body()
+  } catch (error) {
+    const name = error instanceof Error ? error.name : 'Error'
+    const message = error instanceof Error ? error.message : String(error)
+    console.error(
+      `storefront ${command}: unexpected internal error (${name}): ${sanitizeForLog(message, projectDir)}`,
+    )
+    return {
+      envelope: resultEnvelope(command, false, 2, [unexpectedDiagnostic(error)]),
+      exitCode: 2,
+    }
+  }
+}
+
+function diffManifests(before, after) {
+  return { before, after }
+}
+
+function diffFileState(before, after) {
+  const added = []
+  const removed = []
+  const changed = []
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)])
+  for (const key of [...keys].sort()) {
+    if (!hasOwn(before, key)) added.push(key)
+    else if (!hasOwn(after, key)) removed.push(key)
+    else if (before[key] !== after[key]) changed.push(key)
+  }
+  return { added, removed, changed }
+}
+
+// Capture the prior bytes of every file the attempt will touch plus the prior
+// 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).
+export function takeSnapshot(projectDir, absPaths) {
+  const files = new Map()
+  const dirs = new Map()
+  for (const abs of absPaths) {
+    if (existsSync(abs) && statSync(abs).isFile()) {
+      files.set(abs, { existed: true, content: readFileSync(abs) })
+    } else {
+      files.set(abs, { existed: false })
+    }
+    let dir = path.dirname(abs)
+    while (dir !== projectDir && dir.startsWith(`${projectDir}${path.sep}`)) {
+      if (!dirs.has(dir)) dirs.set(dir, existsSync(dir))
+      dir = path.dirname(dir)
+    }
+  }
+  return { files, dirs }
+}
+
+export function restoreSnapshot(snapshot) {
+  for (const [abs, prior] of snapshot.files) {
+    if (prior.existed) {
+      mkdirSync(path.dirname(abs), { recursive: true })
+      writeFileSync(abs, prior.content)
+    } else if (existsSync(abs)) {
+      rmSync(abs, { force: true })
+    }
+  }
+  // Remove directories the attempt created, deepest first, once empty. A dir
+  // that held a preexisting file is not in this set, so prior structure stays.
+  const created = [...snapshot.dirs.entries()]
+    .filter(([, existed]) => !existed)
+    .map(([dir]) => dir)
+    .sort((a, b) => b.length - a.length)
+  for (const dir of created) {
+    if (existsSync(dir) && statSync(dir).isDirectory() && readdirSync(dir).length === 0) {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  }
+}
+
+// Remove files for explicitly removed views/features, reconcile derived files
+// to the desired manifest, then write the manifest LAST (Decision 7). Returns
+// the changed derived files and the preserved customized files.
+//
+// `inject(phase, context)` is a controlled test seam (E1 task 4.7): production
+// callers pass nothing, so it is inert in the CLI. A test throws from it at a
+// named phase — `after-derived-writes` (writes and deletions have landed, the
+// manifest is not yet published), `before-manifest-write`, or
+// `after-manifest-write` — to prove the handled-failure rollback. It is never
+// read from the environment, so an untrusted env cannot arm it.
+async function commitReduction(projectDir, reduction, { snapshot = false, inject = null } = {}) {
+  const dry = await reconcile(projectDir, reduction.manifest, { dryRun: true })
+  if (!dry.ok) return { ok: false, diagnostics: preflightDiagnostics(dry.errors) }
+
+  const removalRemoved = []
+  const preserved = []
+  for (const rem of reduction.removals) {
+    // A `section.remove` drops an editorial instance from the manifest but keeps
+    // the instance's user-owned content: `reconcile` never rewrites the view's
+    // `content.ts`, so the removal only reports that file's location as
+    // preserved (E3 task 3.2, CU-15). Nothing is deleted or rewritten here.
+    if (rem.kind === 'section') {
+      const abs = path.join(projectDir, rem.contentPath)
+      if (existsSync(abs) && statSync(abs).isFile()) preserved.push(rem.contentPath)
+      continue
+    }
+    const result =
+      rem.kind === 'view'
+        ? 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)
+  }
+  for (const rem of reduction.removals) {
+    if (rem.kind !== 'feature') continue
+    for (const mount of getFeature(rem.name)?.mounts ?? []) {
+      for (const rel of await customizedViewFiles(projectDir, reduction.manifest, mount.host)) {
+        if (!preserved.includes(rel)) preserved.push(rel)
+      }
+    }
+  }
+
+  const touched = new Set([
+    ...dry.changed.map((rel) => path.resolve(projectDir, rel)),
+    ...removalRemoved.map((rel) => path.resolve(projectDir, rel)),
+    manifestPath(projectDir),
+  ])
+  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, {
+          legacyDerivedFiles: rem.legacyDerivedFiles,
+        })
+      }
+      if (rem.kind === 'feature') await removeFeatureFiles(projectDir, reduction.manifest, rem.name)
+    }
+    const result = await reconcile(projectDir, reduction.manifest)
+    if (!result.ok) throw new Error(result.errors.join('; '))
+    inject?.('after-derived-writes', { projectDir, manifest: reduction.manifest })
+    inject?.('before-manifest-write', {
+      projectDir,
+      manifest: reduction.manifest,
+      manifestPath: manifestPath(projectDir),
+    })
+    writeManifest(projectDir, reduction.manifest)
+    inject?.('after-manifest-write', {
+      projectDir,
+      manifest: reduction.manifest,
+      manifestPath: manifestPath(projectDir),
+    })
+    return { ok: true, changed: result.changed, preserved: [...new Set(preserved)] }
+  } catch (error) {
+    if (snapshotState) restoreSnapshot(snapshotState)
+    return {
+      ok: false,
+      diagnostics: [
+        diagnostic('E_WRITE_FAILED', error instanceof Error ? error.message : String(error)),
+      ],
+    }
+  }
+}
+
+/**
+ * Reduce and commit a set of operations against a project in one step. This is
+ * the shared path behind the `view`/`feature` aliases and the apply command's
+ * write step. Returns `{ ok, diagnostics, changed, preserved, manifest }`.
+ */
+export async function executeOperations(
+  projectDir,
+  manifest,
+  operations,
+  { force = true, inject = null, registry = null } = {},
+) {
+  const reduction = reduceManifest(manifest, operations, { force, registry })
+  if (!reduction.ok) return { ok: false, diagnostics: reduction.diagnostics }
+  // Ownership conflicts are a write-boundary check (E1 task 5.1 / CU-08): the
+  // legacy aliases must reject a customized contract that no longer provides a
+  // selected variant's data shape before any file is touched, exactly like
+  // plan/apply.
+  const conflicts = detectOwnershipConflicts(projectDir, reduction.manifest)
+  if (!conflicts.ok) return { ok: false, diagnostics: conflicts.diagnostics }
+  const commit = await commitReduction(projectDir, reduction, { snapshot: true, inject })
+  if (!commit.ok) return { ok: false, diagnostics: commit.diagnostics }
+  return {
+    ok: true,
+    diagnostics: [],
+    changed: commit.changed,
+    preserved: commit.preserved,
+    manifest: reduction.manifest,
+  }
+}
+
+// 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 {
+    // Stage `app`/`lib` without secret-bearing files, so the predicted after-state
+    // is computed from the same secret-free domain as the before-state and no
+    // credential is copied into the temp dir (E1 task 4.13).
+    for (const rel of ['app', 'lib']) {
+      const from = path.join(projectDir, rel)
+      if (existsSync(from)) await copyTreeExcludingSecrets(from, path.join(stage, rel))
+    }
+    writeManifest(stage, reduction.manifest)
+    await commitReduction(stage, reduction, { snapshot: false })
+    return await fn(stage)
+  } finally {
+    rmSync(stage, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Plan a set of operations: validate the whole intended state, record the
+ * before/after identity fingerprints and diffs, and write only the `--out`
+ * artifact (atomically) when requested. Never mutates the project. Returns
+ * `{ envelope, exitCode, outWritten }`.
+ */
+export function planProject(projectDir, rawOperations, options = {}) {
+  return runGuarded('plan', projectDir, () =>
+    planProjectInner(projectDir, rawOperations, options),
+  )
+}
+
+async function planProjectInner(projectDir, rawOperations, { outPath = null, operationsPath = null, inject = null, registry = null } = {}) {
+  // Every input goes through the versioned envelope parser (E1 task 4.10): a
+  // bare operations array, a missing/wrong `formatVersion`, or a non-array
+  // `operations` is `E_INVALID_ENVELOPE` and writes nothing. `registry` selects
+  // the active operation vocabulary (defaults to E1's six); E3 passes its own so
+  // a `section.add` is accepted and an unregistered op is still rejected.
+  const parsed = parseOperationsEnvelope(rawOperations, { registry })
+  const manifest = readManifest(projectDir)
+  if (!manifest) {
+    return {
+      envelope: resultEnvelope('plan', false, 1, [
+        ...parsed.diagnostics,
+        diagnostic('E_NO_MANIFEST', 'No storefront.config.json found in the project.'),
+      ]),
+      exitCode: 1,
+    }
+  }
+  // Validate every parsed operation against the resulting complete state even
+  // when some operations failed to parse, so parse-level and semantic errors are
+  // all reported together (E1 task 4.3). Any diagnostic means no plan is emitted
+  // and no file is written. The active `registry` dispatches E3's namespaced
+  // reducers through the same engine.
+  const reduction = reduceManifest(manifest, parsed.operations, { force: true, registry })
+  const diagnostics = [...parsed.diagnostics, ...reduction.diagnostics]
+  if (diagnostics.length > 0) {
+    return { envelope: resultEnvelope('plan', false, 1, diagnostics), exitCode: 1 }
+  }
+
+  // Ownership conflicts are detected before staging so `plan` reports the file
+  // and differing fields and emits no plan; it stays read-only against the
+  // project (E1 task 5.1 / CU-08).
+  const conflicts = detectOwnershipConflicts(projectDir, reduction.manifest)
+  if (!conflicts.ok) {
+    return { envelope: resultEnvelope('plan', false, 1, conflicts.diagnostics), exitCode: 1 }
+  }
+
+  // Controlled programmatic seam (E1 task 4.11): production callers pass
+  // nothing, so it is inert in the CLI and is never read from the environment.
+  // A test throws here to exercise the unexpected-internal-error branch (exit
+  // 2) on the real engine.
+  inject?.('plan-after-validation', { projectDir, operations: parsed.operations })
+
+  // Compute the pins once and reuse them for both states so the after-state
+  // retains the same catalog/generator/toolset identity as the before-state.
+  const pins = computePins({ projectDir })
+  const before = projectIdentity(projectDir, manifest, parsed.operations, pins)
+  const after = await withStagedProject(projectDir, reduction, (stage) =>
+    projectIdentity(stage, reduction.manifest, parsed.operations, pins),
+  )
+
+  const result = {
+    beforeFingerprint: before.hash,
+    afterFingerprint: after.hash,
+    operations: parsed.operations,
+    manifestDiff: diffManifests(manifest, reduction.manifest),
+    fileDiff: {
+      derived: diffFileState(before.identity.derived, after.identity.derived),
+      userOwned: diffFileState(before.identity.userOwned, after.identity.userOwned),
+    },
+  }
+  const envelope = resultEnvelope('plan', true, 0, [], result)
+
+  let outWritten = false
+  if (outPath) {
+    const safety = assertSafeOutPath(projectDir, outPath, operationsPath)
+    if (!safety.ok) {
+      // A refused path inside the project is reported as a project-root-relative
+      // POSIX path (E1 task 4.11); a path outside the project has no such path
+      // and is reported by message only.
+      const extra = safety.path ? { path: safety.path } : {}
+      return {
+        envelope: resultEnvelope('plan', false, 1, [
+          diagnostic('E_OUT_PATH_REFUSED', safety.message, extra),
+        ]),
+        exitCode: 1,
+      }
+    }
+    atomicWrite(resolveOut(outPath), `${JSON.stringify(envelope, null, 2)}\n`, inject)
+    outWritten = true
+  }
+  return { envelope, exitCode: 0, outWritten }
+}
+
+// `--out` resolves against the consumer cwd, not the project root (Decision 12).
+function resolveOut(outPath) {
+  return path.resolve(outPath)
+}
+
+const REFUSED_TOP_SEGMENTS = new Set([
+  'app',
+  'public',
+  'lib',
+  'node_modules',
+  '.next',
+  '.git',
+  '.opencode',
+  '.yarn',
+  'skills',
+  'commands',
+  'recipes',
+  'scripts',
+])
+const REFUSED_BASENAMES = new Set([
+  'package.json',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'pnpm-workspace.yaml',
+  'storefront.config.json',
+  'storefront.json',
+  '.npmrc',
+  '.yarnrc',
+  '.yarnrc.yml',
+  'components.json',
+  'tsconfig.json',
+  'jsconfig.json',
+  'next.config.js',
+  'next.config.mjs',
+  'next.config.ts',
+])
+
+// Resolve the canonical path of a possibly non-existent target by realpath-ing
+// its longest existing ancestor and re-appending the missing tail. `realpathSync`
+// alone throws `ENOENT` for a target whose *parent* is a symlink into a protected
+// tree (e.g. `link -> project/lib`, `--out link/plan.json`), so the lexical path
+// would otherwise look outside the project and be allowed while the write lands
+// in the owned tree. Returns the input unchanged when no ancestor can be resolved.
+function realpathThroughExistingAncestor(abs) {
+  const missing = []
+  let current = abs
+  while (!existsSync(current)) {
+    const parent = path.dirname(current)
+    if (parent === current) return abs
+    missing.unshift(path.basename(current))
+    current = parent
+  }
+  let resolved
+  try {
+    resolved = realpathSync(current)
+  } catch {
+    return abs
+  }
+  return missing.length > 0 ? path.join(resolved, ...missing) : resolved
+}
+
+/**
+ * Refuse an `--out` path that resolves to an owned, derived, secret-bearing, or
+ * installation file/path tree, a symlink-resolved equivalent, or the operation
+ * input file (Decision 12). Returns `{ ok }` or
+ * `{ ok: false, message, path? }`, where `path` is the project-root-relative
+ * POSIX path of the refused candidate when it lies inside the project (a
+ * diagnostic path is project-root-relative POSIX; E1 task 4.11).
+ */
+export function assertSafeOutPath(projectDir, outPath, operationsPath = null) {
+  const abs = path.resolve(outPath)
+  // Both the lexical path and its symlink-resolved equivalent are candidates, so
+  // a link whose target is owned/derived/secret/installation (including a
+  // non-existent child reached through a symlinked parent) is refused even when
+  // the link itself lives outside the project.
+  const candidates = [abs]
+  const resolved = realpathThroughExistingAncestor(abs)
+  if (resolved !== abs) candidates.push(resolved)
+
+  // The operations input must never be overwritten by `--out`. This is an input
+  // collision check, NOT a project-membership check, so it is compared directly
+  // against the out path (lexical and symlink-resolved) rather than by adding
+  // the input to the candidate tree list — which would otherwise refuse every
+  // safe `--out` because the input always equals itself.
+  if (operationsPath) {
+    const opsLexical = path.resolve(operationsPath)
+    const opsResolved = realpathThroughExistingAncestor(opsLexical)
+    if (candidates.includes(opsLexical) || candidates.includes(opsResolved)) {
+      return { ok: false, message: '--out must not overwrite the operations input.' }
+    }
+  }
+
+  for (const candidate of candidates) {
+    const rel = path.relative(projectDir, candidate)
+    const inside = rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+    const projectRel = inside && rel !== '' ? rel.split(path.sep).join('/') : null
+    const refuse = (message) =>
+      projectRel !== null ? { ok: false, message, path: projectRel } : { ok: false, message }
+    if (rel === '') return refuse('--out must not resolve to the project root.')
+    // Owned/derived/installation trees are project-relative: a path *outside*
+    // the project is a safe explicit artifact even if a segment shares a name
+    // (e.g. `/tmp/lib/plan.json`). Only a candidate that is genuinely inside the
+    // project — lexically or through a symlink — is checked against the tree set.
+    if (inside) {
+      const segments = rel.split(path.sep)
+      if (segments.some((segment) => REFUSED_TOP_SEGMENTS.has(segment))) {
+        return refuse(`--out resolves inside the owned tree "${segments[0]}".`)
+      }
+    }
+    const base = path.basename(candidate)
+    if (REFUSED_BASENAMES.has(base) || SECRET_BASENAME.some((re) => re.test(base))) {
+      return refuse(`--out resolves to the owned or secret-bearing file "${base}".`)
+    }
+  }
+  return { ok: true }
+}
+
+// Atomic artifact write: a same-directory temp file plus `rename` so a reader
+// never observes a partial plan, and the pre-existing artifact stays byte-exact
+// until the rename commits. On any failure between the temp write and the
+// rename, the attempt's OWN temp file is removed; pre-existing directories and
+// 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.
+export function atomicWrite(abs, text, inject = null) {
+  mkdirSync(path.dirname(abs), { recursive: true })
+  const tmp = `${abs}.tmp-${process.pid}-${Date.now()}`
+  try {
+    writeFileSync(tmp, text)
+    inject?.('plan-after-temp-write', { outPath: abs, tmpPath: tmp })
+    renameSync(tmp, abs)
+  } catch (error) {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      // The temp may never have been created, or may already be gone.
+    }
+    throw error
+  }
+}
+
+// Exclusive-create retry budget for the local apply lock (E1 task 4.6). The
+// wait must comfortably exceed a normal apply so a concurrent run observes the
+// winner's after-state and resolves to a verified no-op instead of giving up
+// with `E_LOCK_HELD`. A lock left by a crashed process is NOT stolen: there is no
+// PID probing and no liveness check, so a stale lock can only be cleared by a
+// human removing `.opencode/.storefront-apply.lock` (the lock this worker
+// created, never another process's). Interruption recovery is `sync`, which
+// repairs the manifest/derived divergence and does not need or release the lock
+// (E1 task 4.8).
+const LOCK_RETRIES = 300
+const LOCK_WAIT_MS = 20
+
+function sleepSync(ms) {
+  const buffer = new Int32Array(new SharedArrayBuffer(4))
+  Atomics.wait(buffer, 0, 0, ms)
+}
+
+function acquireLock(projectDir) {
+  const lockPath = path.join(projectDir, '.opencode', '.storefront-apply.lock')
+  mkdirSync(path.dirname(lockPath), { recursive: true })
+  for (let attempt = 0; attempt < LOCK_RETRIES; attempt++) {
+    try {
+      const fd = openSync(lockPath, 'wx')
+      writeFileSync(fd, String(process.pid))
+      closeSync(fd)
+      return { ok: true, lockPath }
+    } catch (error) {
+      if (error.code !== 'EEXIST') return { ok: false, message: error.message }
+      sleepSync(LOCK_WAIT_MS)
+    }
+  }
+  return { ok: false, message: 'another apply holds the project lock' }
+}
+
+function releaseLock(lock) {
+  if (!lock?.lockPath) return
+  try {
+    unlinkSync(lock.lockPath)
+  } catch {
+    // A lock already gone is not an error.
+  }
+}
+
+/**
+ * Apply a recorded plan. Under a local lock, re-evaluate the current state into
+ * three branches: matching the before-state applies; matching the recorded
+ * after-state is a verified no-op; matching neither is `E_STALE_PLAN`. All
+ * validation happens before any write, and a handled write failure restores
+ * every touched file. Returns `{ envelope, exitCode }`.
+ */
+export function applyProject(projectDir, planArtifact, options = {}) {
+  return runGuarded('apply', projectDir, () => applyProjectInner(projectDir, planArtifact, options))
+}
+
+async function applyProjectInner(projectDir, planArtifact, { inject = null, registry = null } = {}) {
+  if (
+    !isPlainObject(planArtifact) ||
+    planArtifact.formatVersion !== PLAN_FORMAT_VERSION ||
+    !isPlainObject(planArtifact.result) ||
+    !Array.isArray(planArtifact.result.operations)
+  ) {
+    return {
+      envelope: resultEnvelope('apply', false, 1, [
+        diagnostic('E_PLAN_INVALID', 'the plan artifact is missing a version-1 result envelope.'),
+      ]),
+      exitCode: 1,
+    }
+  }
+  // Controlled programmatic seam (E1 task 4.11) invoked BEFORE the handled
+  // commit region: production callers pass nothing; a test throws here to
+  // exercise the unexpected-internal-error branch (exit 2) rather than the
+  // handled-failure rollback (which is reached only through `commitReduction`).
+  inject?.('apply-before-lock', { projectDir, operations: planArtifact.result.operations })
+  const { operations, beforeFingerprint, afterFingerprint } = planArtifact.result
+  const lock = acquireLock(projectDir)
+  if (!lock.ok) {
+    return {
+      envelope: resultEnvelope('apply', false, 1, [diagnostic('E_LOCK_HELD', lock.message)]),
+      exitCode: 1,
+    }
+  }
+  try {
+    const manifest = readManifest(projectDir)
+    if (!manifest) {
+      return {
+        envelope: resultEnvelope('apply', false, 1, [
+          diagnostic('E_NO_MANIFEST', 'No storefront.config.json found in the project.'),
+        ]),
+        exitCode: 1,
+      }
+    }
+    const reduction = reduceManifest(manifest, operations, { force: true, registry })
+    if (!reduction.ok) {
+      return { envelope: resultEnvelope('apply', false, 1, reduction.diagnostics), exitCode: 1 }
+    }
+    // Re-check ownership conflicts under the lock, before any state resolution
+    // or write, so an apply never renders against an unprovided shape
+    // (E1 task 5.1 / CU-08).
+    const conflicts = detectOwnershipConflicts(projectDir, reduction.manifest)
+    if (!conflicts.ok) {
+      return { envelope: resultEnvelope('apply', false, 1, conflicts.diagnostics), exitCode: 1 }
+    }
+    const current = projectIdentity(projectDir, manifest, operations, computePins({ projectDir }))
+    if (current.hash === afterFingerprint) {
+      return {
+        envelope: resultEnvelope('apply', true, 0, [], { state: 'verified-noop' }),
+        exitCode: 0,
+      }
+    }
+    if (current.hash !== beforeFingerprint) {
+      return {
+        envelope: resultEnvelope('apply', false, 1, [
+          diagnostic('E_STALE_PLAN', 'the project state matches neither the before-state nor the after-state.'),
+        ]),
+        exitCode: 1,
+      }
+    }
+    const commit = await commitReduction(projectDir, reduction, { snapshot: true, inject })
+    if (!commit.ok) {
+      return { envelope: resultEnvelope('apply', false, 1, commit.diagnostics), exitCode: 1 }
+    }
+    return {
+      envelope: resultEnvelope('apply', true, 0, [], {
+        state: 'applied',
+        changed: commit.changed,
+        preserved: commit.preserved,
+      }),
+      exitCode: 0,
+    }
+  } finally {
+    releaseLock(lock)
+  }
+}