mango-cms 0.3.34 → 0.3.35

package/lib/vibe-orchestrator/src/publisher.js

@@ -0,0 +1,376 @@
+// publisher.js
+//
+// Staging → production publish via the EXISTING pipeline only (CEO Decision 3,
+// HAP-1096 / HAP-1103). No parallel deploy: we commit on the staging clone and
+// `git push` the deploy branch, which triggers `.github/workflows/ssh-deploy.yml`
+// → `mango/helpers/update.sh` on the prod droplet.
+//
+// Hard constraint: the env-specific `mango/config/settings.json` is NEVER
+// pushed. The staging overlay (`mango/helpers/staging.mjs up`) materializes the
+// staging block (ports/db/domains) into that file, so before committing we run
+// the overlay `down` semantics — `git checkout -- <settings>` — restoring the
+// push-safe prod tree so prod config is never clobbered.
+//
+// Two operations, mirroring the gated UI:
+//   diff(site)    — pure, read-only: what *would* be published (settings excluded)
+//   publish(site) — restore settings → add → commit → push; requires confirm:true
+
+import { execFile } from 'node:child_process'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { resolveSiteDir, config } from './config.js'
+
+/** Promisified `git` invocation scoped to a working dir. Never throws on a
+ *  non-zero exit unless `mustSucceed` — returns { code, stdout, stderr } so the
+ *  caller can branch (e.g. "nothing to commit"). */
+function git(cwd, args, { mustSucceed = false } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      const code = err && typeof err.code === 'number' ? err.code : err ? 1 : 0
+      if (err && mustSucceed) {
+        const e = new Error(`git ${args[0]} failed: ${(stderr || err.message || '').trim()}`)
+        e.code = code
+        e.stderr = stderr
+        return reject(e)
+      }
+      resolve({ code, stdout: stdout || '', stderr: stderr || '' })
+    })
+  })
+}
+
+const SETTINGS_PATH = config.settingsPath
+// Exclude pathspec keeps env-specific settings out of every diff/commit.
+const EXCLUDE_SETTINGS = `:(exclude)${SETTINGS_PATH}`
+
+/** Parse `git status --porcelain=v1 -z` into { path, status, untracked } rows. */
+function parsePorcelain(out) {
+  const rows = []
+  // -z separates entries with NUL; rename entries carry an extra NUL field.
+  const parts = out.split('\0')
+  for (let i = 0; i < parts.length; i++) {
+    const entry = parts[i]
+    if (!entry) continue
+    const xy = entry.slice(0, 2)
+    const path = entry.slice(3)
+    // Renames/copies (R/C) consume the following NUL field (the new path).
+    if (xy[0] === 'R' || xy[0] === 'C') i++
+    rows.push({ status: xy, path, untracked: xy === '??' })
+  }
+  return rows
+}
+
+/** Current branch name (or 'HEAD' when detached). */
+async function currentBranch(cwd) {
+  const { stdout } = await git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'], { mustSucceed: true })
+  return stdout.trim()
+}
+
+/** ahead/behind counts vs the upstream deploy ref; nulls when no upstream. */
+async function aheadBehind(cwd, remote, branch) {
+  const ref = `${remote}/${branch}`
+  const { code, stdout } = await git(cwd, ['rev-list', '--left-right', '--count', `${ref}...HEAD`])
+  if (code !== 0) return { ahead: null, behind: null, upstream: ref, hasUpstream: false }
+  const [behind, ahead] = stdout.trim().split(/\s+/).map((n) => Number.parseInt(n, 10))
+  return { ahead: ahead || 0, behind: behind || 0, upstream: ref, hasUpstream: true }
+}
+
+/**
+ * Read-only: compute exactly what a publish would push. Excludes settings.json.
+ *
+ * @returns {Promise<{
+ *   site, dir, branch, remote, upstream, hasUpstream, ahead, behind,
+ *   files: {path,status,untracked}[], settingsDirty, settingsExcluded,
+ *   diff, diffTruncated, publishable, reason
+ * }>}
+ */
+async function diff(site, opts = {}) {
+  const dir = resolveSiteDir(site)
+  const remote = opts.remote || config.publishRemote
+  const branch = await currentBranch(dir)
+  const { ahead, behind, upstream, hasUpstream } = await aheadBehind(dir, remote, branch)
+
+  const status = await git(dir, ['status', '--porcelain=v1', '-z', '--untracked-files=all'], { mustSucceed: true })
+  const allRows = parsePorcelain(status.stdout)
+  const settingsDirty = allRows.some((r) => r.path === SETTINGS_PATH)
+  const files = allRows.filter((r) => r.path !== SETTINGS_PATH)
+
+  // Tracked-change diff (working tree vs HEAD), settings excluded.
+  const tracked = await git(dir, ['-c', 'core.quotepath=false', 'diff', 'HEAD', '--', '.', EXCLUDE_SETTINGS])
+  let diffText = tracked.stdout
+  // Surface untracked files explicitly — `git diff HEAD` omits them.
+  const untracked = files.filter((f) => f.untracked).map((f) => f.path)
+  if (untracked.length) {
+    diffText += `\n${untracked.map((p) => `?? new file: ${p}`).join('\n')}\n`
+  }
+
+  const MAX = 200 * 1024
+  let diffTruncated = false
+  if (diffText.length > MAX) {
+    diffText = diffText.slice(0, MAX)
+    diffTruncated = true
+  }
+
+  const publishable = files.length > 0 || (hasUpstream && ahead > 0)
+  let reason = ''
+  if (!publishable) {
+    reason = hasUpstream
+      ? 'Working tree is clean and nothing is ahead of production — nothing to publish.'
+      : 'Working tree is clean (no upstream to compare commits against).'
+  }
+
+  return {
+    site,
+    dir,
+    branch,
+    remote,
+    upstream,
+    hasUpstream,
+    ahead,
+    behind,
+    files,
+    settingsDirty,
+    settingsExcluded: settingsDirty, // we exclude it whenever it's dirty
+    settingsPath: SETTINGS_PATH,
+    diff: diffText,
+    diffTruncated,
+    publishable,
+    reason,
+  }
+}
+
+/**
+ * Merge a workspace branch into the deploy branch (e.g. main) in a THROWAWAY
+ * worktree and push it — this is what actually triggers ssh-deploy → prod
+ * (HAP-1174). The primary worktree (`dir`) stays on `<branch>` and is never
+ * touched; the deploy branch may be checked out in another worktree, which is
+ * why we use a detached throwaway worktree rather than checking main out here.
+ *
+ * Hard rules:
+ *   - `settings.json` is NEVER carried into the deploy branch — after the merge we
+ *     restore the deploy branch's own settings and amend, so prod config is intact.
+ *   - A conflict aborts cleanly and throws 409 with the file list; `<publishBranch>`
+ *     on the remote is never pushed/corrupted.
+ *
+ * @returns {Promise<{merged, alreadyUpToDate, mergeSha, deployBranch, pushOutput, steps}>}
+ */
+async function mergeToDeployBranch(dir, { site, branch, remote, publishBranch, message }) {
+  const steps = []
+  const deployRef = `${remote}/${publishBranch}`
+
+  // Always merge from the latest published main, not a stale local ref.
+  await git(dir, ['fetch', remote, publishBranch], { mustSucceed: true })
+  steps.push({ step: 'fetch', ok: true, ref: deployRef })
+
+  // Detached throwaway worktree at the tip of the deploy branch. Detached so it
+  // never collides with `<publishBranch>` being checked out in another worktree.
+  await git(dir, ['worktree', 'prune'])
+  const wt = path.join(os.tmpdir(), `vibe-publish-${site}-${process.pid}-${Date.now()}`)
+  await git(dir, ['worktree', 'add', '--detach', wt, deployRef], { mustSucceed: true })
+
+  try {
+    // Merge the (just-committed) workspace branch. --no-ff guarantees one merge
+    // commit we own, so the settings restore below can amend it safely.
+    const m = await git(wt, ['merge', '--no-ff', '-m', message, branch])
+
+    if (m.code !== 0) {
+      // Conflict. settings.json can't really conflict (publish never commits it),
+      // but if it's the ONLY conflict, resolve to the deploy branch's copy and go
+      // on — otherwise abort and surface 409 with the file list; main untouched.
+      const conflictOut = await git(wt, ['diff', '--name-only', '--diff-filter=U'])
+      const conflicts = conflictOut.stdout.split('\n').map((s) => s.trim()).filter(Boolean)
+      const onlySettings = conflicts.length > 0 && conflicts.every((p) => p === SETTINGS_PATH)
+      if (!onlySettings) {
+        await git(wt, ['merge', '--abort'])
+        const e = new Error(`merge conflict publishing ${branch} → ${publishBranch}`)
+        e.statusCode = 409
+        e.conflicts = conflicts
+        e.deployBranch = publishBranch
+        throw e
+      }
+      // Take the deploy branch's settings ("ours" — the worktree is on main).
+      await git(wt, ['checkout', '--ours', '--', SETTINGS_PATH])
+      await git(wt, ['add', '--', SETTINGS_PATH], { mustSucceed: true })
+      await git(wt, ['commit', '--no-edit'], { mustSucceed: true })
+    }
+
+    // Already merged (no new commits on the branch) ⇒ HEAD still == deploy tip.
+    const head = await git(wt, ['rev-parse', 'HEAD'], { mustSucceed: true })
+    const tip = await git(wt, ['rev-parse', deployRef], { mustSucceed: true })
+    const alreadyUpToDate = head.stdout.trim() === tip.stdout.trim()
+    if (alreadyUpToDate) {
+      steps.push({ step: 'merge', ok: true, skipped: `${branch} already merged into ${publishBranch}` })
+      return { merged: false, alreadyUpToDate: true, mergeSha: null, deployBranch: publishBranch, pushOutput: '', steps }
+    }
+    steps.push({ step: 'merge', ok: true, branch, into: publishBranch })
+
+    // Belt-and-suspenders: never let the merge carry settings.json into prod.
+    // Normally a no-op (branch never commits it); amend the merge commit if it did.
+    await git(wt, ['checkout', deployRef, '--', SETTINGS_PATH])
+    const settingsDirty = await git(wt, ['status', '--porcelain', '--', SETTINGS_PATH])
+    if (settingsDirty.stdout.trim()) {
+      await git(wt, ['add', '--', SETTINGS_PATH], { mustSucceed: true })
+      await git(wt, ['commit', '--amend', '--no-edit'], { mustSucceed: true })
+      steps.push({ step: 'exclude-settings-on-merge', ok: true, path: SETTINGS_PATH })
+    }
+
+    const mergeShaRes = await git(wt, ['rev-parse', 'HEAD'], { mustSucceed: true })
+    const mergeSha = mergeShaRes.stdout.trim()
+
+    // Push the merge to the deploy branch → ssh-deploy → update.sh on prod.
+    const p = await git(wt, ['push', remote, `HEAD:${publishBranch}`])
+    const pushOutput = (p.stderr || p.stdout || '').trim()
+    if (p.code !== 0) {
+      steps.push({ step: 'push-deploy', ok: false, remote, branch: publishBranch, output: pushOutput })
+      const e = new Error(`git push to ${publishBranch} failed: ${pushOutput}`)
+      e.statusCode = 502
+      e.steps = steps
+      throw e
+    }
+    steps.push({ step: 'push-deploy', ok: true, remote, branch: publishBranch, sha: mergeSha, output: pushOutput })
+
+    return { merged: true, alreadyUpToDate: false, mergeSha, deployBranch: publishBranch, pushOutput, steps }
+  } finally {
+    // Always tear the throwaway worktree down, even on conflict/abort.
+    await git(dir, ['worktree', 'remove', '--force', wt])
+    try { fs.rmSync(wt, { recursive: true, force: true }) } catch { /* already gone */ }
+  }
+}
+
+/**
+ * Settings-safe publish. Requires an explicit confirm — this is the owner-gated,
+ * intentional production deploy. Steps:
+ *   1. exclude settings.json so prod config is never clobbered
+ *   2. git add -A (settings excluded)
+ *   3. commit on the workspace branch (skipped if nothing staged)
+ *   4. push the workspace branch (preserves origin/<branch> for collaborators)
+ *   5. if <branch> is not the deploy branch: merge it → <publishBranch> in a
+ *      throwaway worktree and push → ssh-deploy → prod (HAP-1174). When the
+ *      workspace IS on the deploy branch, step 4's push is itself the deploy.
+ *
+ * @param {string} site
+ * @param {{message?:string, confirm?:boolean, remote?:string, push?:boolean}} opts
+ */
+async function publish(site, opts = {}) {
+  if (opts.confirm !== true) {
+    const e = new Error('publish requires explicit confirm:true')
+    e.statusCode = 400
+    throw e
+  }
+  if (!config.publishEnabled) {
+    const e = new Error('publishing is disabled (set VIBE_PUBLISH_ENABLED=true)')
+    e.statusCode = 403
+    throw e
+  }
+
+  const dir = resolveSiteDir(site)
+  const remote = opts.remote || config.publishRemote
+  const branch = await currentBranch(dir)
+  const publishBranch = opts.publishBranch || config.publishBranch
+  const doPush = opts.push !== false
+  const isDeployBranch = branch === publishBranch
+  const message = (opts.message && String(opts.message).trim()) ||
+    `Publish from staging (${site})`
+
+  const steps = []
+
+  // 1. Keep env-specific settings.json OUT of the commit WITHOUT touching the
+  //    working file. The staging overlay (`staging.mjs up`) leaves settings.json
+  //    dirty with staging ports/db/domains. The old approach reverted it here
+  //    (`git checkout -- settings.json`), but this clone runs `mango dev` with a
+  //    live file watcher: reverting to prod ports made the watcher rebuild
+  //    build/index.js on the PROD mango port and rebind it, EADDRINUSE-crashing
+  //    the live prod mango in a restart loop (the HAP-1096 publish outage). So we
+  //    never modify the file — we only ensure it is not staged, then stage the rest.
+  const tracked = await git(dir, ['ls-files', '--error-unmatch', SETTINGS_PATH])
+  let settingsExcluded = false
+  if (tracked.code === 0) {
+    // Unstage settings.json if a prior op left it in the index (working tree untouched).
+    await git(dir, ['reset', '-q', '--', SETTINGS_PATH])
+    settingsExcluded = true
+    steps.push({ step: 'exclude-settings', ok: true, path: SETTINGS_PATH, note: 'working-tree settings preserved; excluded from commit' })
+  } else {
+    steps.push({ step: 'exclude-settings', ok: true, skipped: 'settings.json not tracked' })
+  }
+
+  // 2. Stage everything EXCEPT settings.json. The exclude pathspec keeps the
+  //    staging overlay out of the commit even though it stays dirty on disk, so
+  //    the pushed tree carries the committed (prod) settings untouched.
+  await git(dir, ['add', '-A', '--', '.', EXCLUDE_SETTINGS], { mustSucceed: true })
+  steps.push({ step: 'add', ok: true })
+
+  // 3. Commit only if there is something staged.
+  const staged = await git(dir, ['diff', '--cached', '--quiet'])
+  let committed = false
+  let commitSha = null
+  if (staged.code !== 0) {
+    const c = await git(dir, ['commit', '-m', message], { mustSucceed: true })
+    committed = true
+    const sha = await git(dir, ['rev-parse', 'HEAD'], { mustSucceed: true })
+    commitSha = sha.stdout.trim()
+    steps.push({ step: 'commit', ok: true, sha: commitSha, message })
+  } else {
+    steps.push({ step: 'commit', ok: true, skipped: 'nothing to commit after restore' })
+  }
+
+  // 4. Push the workspace branch. When the workspace IS on the deploy branch,
+  //    this push is itself the prod deploy (ssh-deploy triggers on it). Otherwise
+  //    it just keeps origin/<branch> current for same-branch collaborators; the
+  //    actual prod deploy happens in step 5.
+  let pushed = false
+  let pushOutput = ''
+  if (doPush) {
+    const p = await git(dir, ['push', remote, `HEAD:${branch}`])
+    pushed = p.code === 0
+    pushOutput = (p.stderr || p.stdout || '').trim()
+    steps.push({ step: 'push', ok: pushed, remote, branch, output: pushOutput })
+    if (!pushed) {
+      const e = new Error(`git push failed: ${pushOutput}`)
+      e.statusCode = 502
+      e.steps = steps
+      throw e
+    }
+  } else {
+    steps.push({ step: 'push', ok: true, skipped: 'push:false (dry commit only)' })
+  }
+
+  // 5. Merge the workspace branch into the deploy branch and push it → ssh-deploy
+  //    → prod (HAP-1174). Skipped when the workspace is already on the deploy
+  //    branch (step 4 deployed) or when push is disabled (dry commit).
+  let deployed = false
+  let merge = null
+  if (doPush && !isDeployBranch) {
+    merge = await mergeToDeployBranch(dir, { site, branch, remote, publishBranch, message })
+    deployed = merge.merged
+    steps.push(...merge.steps)
+  } else if (isDeployBranch && pushed) {
+    deployed = committed
+    steps.push({ step: 'merge', ok: true, skipped: `workspace is on the deploy branch (${publishBranch}); push deployed directly` })
+  } else {
+    steps.push({ step: 'merge', ok: true, skipped: 'push:false (no deploy)' })
+  }
+
+  const nothingToPublish = !committed && !pushed && !deployed
+  return {
+    ok: true,
+    site,
+    branch,
+    remote,
+    publishBranch,
+    deployBranch: publishBranch,
+    settingsExcluded,
+    settingsPath: SETTINGS_PATH,
+    committed,
+    commitSha,
+    message,
+    pushed,
+    pushOutput,
+    deployed,
+    mergeSha: merge ? merge.mergeSha : (isDeployBranch ? commitSha : null),
+    mergedToDeployBranch: !!(merge && merge.merged),
+    nothingToPublish,
+    steps,
+  }
+}
+
+export { diff, publish, parsePorcelain, SETTINGS_PATH }

package/lib/vibe-orchestrator/src/recovery.js

@@ -0,0 +1,199 @@
+// recovery.js
+//
+// Always a way back (HAP-1124, protection #2). A vibe edit must never leave the
+// staging clone in a non-recoverable state, so:
+//
+//   • autoCommit(site)      — after every run, stage the clone (settings.json
+//                             excluded, exactly like publish) and commit any
+//                             change with a structured message. History always
+//                             exists, so any edit is verifiable + reversible.
+//   • ensureBaseline(site)  — on the first auto-commit, tag the pre-edit tree as
+//                             the known-good baseline `vibe-baseline`.
+//   • revertLast(site)      — undo the most recent vibe edit (git revert, keeps
+//                             history; non-destructive).
+//   • resetToBaseline(site) — hard-reset the clone back to the baseline tag,
+//                             discarding all vibe edits (recoverable via reflog).
+//   • status(site)          — baseline + recent vibe commits + what's available.
+//
+// All of this is plain git on the staging clone — no engineer required. The
+// orchestrator exposes it as endpoints and a one-command script (scripts/
+// vibe-recover.sh) so the client/board can recover with one call/click.
+
+import { execFile } from 'node:child_process'
+import { resolveSiteDir, config } from './config.js'
+import { SETTINGS_PATH } from './publisher.js'
+
+const EXCLUDE_SETTINGS = `:(exclude)${SETTINGS_PATH}`
+const COMMIT_PREFIX = 'vibe:'
+
+/** Promisified git scoped to a dir. Resolves { code, stdout, stderr }; rejects
+ *  only when mustSucceed and the command fails. */
+function git(cwd, args, { mustSucceed = false } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+      const code = err && typeof err.code === 'number' ? err.code : err ? 1 : 0
+      if (err && mustSucceed) {
+        const e = new Error(`git ${args[0]} failed: ${(stderr || err.message || '').trim()}`)
+        e.code = code
+        return reject(e)
+      }
+      resolve({ code, stdout: stdout || '', stderr: stderr || '' })
+    })
+  })
+}
+
+async function headSha(cwd) {
+  const r = await git(cwd, ['rev-parse', 'HEAD'])
+  return r.code === 0 ? r.stdout.trim() : null
+}
+
+async function tagSha(cwd, tag) {
+  const r = await git(cwd, ['rev-parse', '--verify', '--quiet', `${tag}^{commit}`])
+  return r.code === 0 ? r.stdout.trim() : null
+}
+
+/** Build a single-line, structured commit message for an applied vibe edit. */
+function commitMessage({ summary, sessionId }) {
+  const s = String(summary || 'edit').replace(/\s+/g, ' ').trim().slice(0, 140) || 'edit'
+  const sess = sessionId ? ` [session ${sessionId}]` : ''
+  return `${COMMIT_PREFIX} ${s}${sess}`
+}
+
+/**
+ * Ensure the known-good baseline tag exists, pointing at the current HEAD. Called
+ * before the first auto-commit so the baseline captures the pre-edit tree.
+ * Idempotent — never moves an existing tag.
+ * @returns {Promise<{tag, sha, created}>}
+ */
+async function ensureBaseline(site, opts = {}) {
+  const dir = opts.dir || resolveSiteDir(site)
+  const tag = opts.tag || config.baselineTag
+  const existing = await tagSha(dir, tag)
+  if (existing) return { tag, sha: existing, created: false }
+  const sha = await headSha(dir)
+  if (!sha) return { tag, sha: null, created: false } // no commits yet — nothing to tag
+  await git(dir, ['tag', '-a', tag, '-m', 'vibe known-good baseline (HAP-1124)'], { mustSucceed: true })
+  return { tag, sha, created: true }
+}
+
+/**
+ * Auto-commit any working-tree change from a vibe run. settings.json is excluded
+ * (same hard rule as publish). No-op when the tree is clean. Tags the baseline on
+ * the first commit.
+ * @returns {Promise<{committed, sha?, message?, baseline}>}
+ */
+async function autoCommit(site, opts = {}) {
+  const dir = opts.dir || resolveSiteDir(site)
+
+  // Tag the pre-edit tree as baseline before the first commit lands.
+  const baseline = await ensureBaseline(site, { dir, tag: opts.tag })
+
+  // Stage everything except settings.json (overlay-materialized; never committed
+  // by vibe — it is also on the protected denylist).
+  await git(dir, ['add', '-A', '--', '.', EXCLUDE_SETTINGS], { mustSucceed: true })
+
+  const staged = await git(dir, ['diff', '--cached', '--quiet'])
+  if (staged.code === 0) return { committed: false, baseline } // nothing changed
+
+  const message = commitMessage(opts)
+  await git(dir, ['commit', '-m', message], { mustSucceed: true })
+  const sha = await headSha(dir)
+  return { committed: true, sha, message, baseline }
+}
+
+/** Recent vibe commits (newest first), most-recent `limit`. */
+async function vibeCommits(dir, limit = 20) {
+  const r = await git(dir, ['log', `-n${limit}`, '--pretty=format:%H%x1f%s%x1f%cI'])
+  if (r.code !== 0 || !r.stdout.trim()) return []
+  return r.stdout.trim().split('\n').map((line) => {
+    const [sha, subject, date] = line.split('\x1f')
+    return { sha, subject, date, isVibe: (subject || '').startsWith(COMMIT_PREFIX) }
+  })
+}
+
+/**
+ * Recovery status: baseline, current HEAD, recent commits, and which recovery
+ * actions are currently available.
+ */
+async function status(site, opts = {}) {
+  const dir = opts.dir || resolveSiteDir(site)
+  const tag = opts.tag || config.baselineTag
+  const [head, baseline, commits] = await Promise.all([
+    headSha(dir),
+    tagSha(dir, tag),
+    vibeCommits(dir),
+  ])
+  const lastIsVibe = commits.length > 0 && commits[0].isVibe
+  const aheadOfBaseline = !!(baseline && head && baseline !== head)
+  return {
+    site,
+    dir,
+    head,
+    baselineTag: tag,
+    baselineSha: baseline,
+    hasBaseline: !!baseline,
+    aheadOfBaseline,
+    recentCommits: commits,
+    canRevertLast: lastIsVibe,
+    canResetToBaseline: !!baseline && aheadOfBaseline,
+  }
+}
+
+/**
+ * Revert the most recent vibe edit (git revert HEAD — keeps full history, never
+ * destructive). Refuses when HEAD is not a vibe commit so we never revert manual
+ * engineer work.
+ * @returns {Promise<{ok, revertedSha, newSha, message}>}
+ */
+async function revertLast(site, opts = {}) {
+  const dir = opts.dir || resolveSiteDir(site)
+  const commits = await vibeCommits(dir, 1)
+  if (!commits.length || !commits[0].isVibe) {
+    const e = new Error('the most recent commit is not a vibe edit — nothing to revert')
+    e.statusCode = 409
+    throw e
+  }
+  const revertedSha = commits[0].sha
+  // Guard against a dirty tree wedging the revert: commit any stray change first.
+  await git(dir, ['add', '-A', '--', '.', EXCLUDE_SETTINGS])
+  const dirty = await git(dir, ['diff', '--cached', '--quiet'])
+  if (dirty.code !== 0) {
+    await git(dir, ['commit', '-m', `${COMMIT_PREFIX} snapshot before revert`], { mustSucceed: true })
+  }
+  await git(dir, ['revert', '--no-edit', revertedSha], { mustSucceed: true })
+  const newSha = await headSha(dir)
+  return { ok: true, revertedSha, newSha, message: `Reverted ${revertedSha.slice(0, 8)}` }
+}
+
+/**
+ * Reset the clone hard back to the known-good baseline, discarding all vibe edits
+ * since. Destructive on the working branch but fully recoverable via the reflog,
+ * and the baseline tag itself is never moved.
+ * @returns {Promise<{ok, baselineTag, baselineSha, previousHead}>}
+ */
+async function resetToBaseline(site, opts = {}) {
+  const dir = opts.dir || resolveSiteDir(site)
+  const tag = opts.tag || config.baselineTag
+  const baseline = await tagSha(dir, tag)
+  if (!baseline) {
+    const e = new Error(`no baseline tag (${tag}) to reset to`)
+    e.statusCode = 409
+    throw e
+  }
+  const previousHead = await headSha(dir)
+  await git(dir, ['reset', '--hard', tag], { mustSucceed: true })
+  // Drop untracked files a vibe edit may have created so the tree truly matches
+  // the baseline. settings.json (and anything gitignored) is preserved with -e.
+  await git(dir, ['clean', '-fd', '-e', SETTINGS_PATH])
+  return { ok: true, baselineTag: tag, baselineSha: baseline, previousHead }
+}
+
+export {
+  autoCommit,
+  ensureBaseline,
+  revertLast,
+  resetToBaseline,
+  status,
+  commitMessage,
+  COMMIT_PREFIX,
+}

package/lib/vibe-orchestrator/src/screenshot.js

@@ -0,0 +1,38 @@
+// screenshot.js
+//
+// Persist a client-sent viewport screenshot (a base64 data URL) to a temp file
+// the agent can Read — Claude Code reads images. The file lives in the OS temp
+// dir, NOT in the staging repo, so it is never committed or published. One file
+// per site is reused (overwritten each turn) to avoid unbounded growth.
+
+import { writeFileSync, mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const DIR = join(tmpdir(), 'vibe-orchestrator')
+const DATA_URL = /^data:image\/(png|jpeg|jpg|webp);base64,([A-Za-z0-9+/=]+)$/
+
+/**
+ * Write a data-URL screenshot to disk and return its absolute path, or null when
+ * the input is missing/invalid or the write fails (best-effort — never throws).
+ * @param {string} site
+ * @param {string} dataUrl
+ * @returns {string|null}
+ */
+function persistScreenshot(site, dataUrl) {
+  if (!dataUrl || typeof dataUrl !== 'string') return null
+  const m = DATA_URL.exec(dataUrl.trim())
+  if (!m) return null
+  try {
+    mkdirSync(DIR, { recursive: true })
+    const ext = m[1] === 'jpeg' ? 'jpg' : m[1]
+    const safe = String(site || 'site').replace(/[^a-z0-9_-]/gi, '_')
+    const path = join(DIR, `${safe}-viewport.${ext}`)
+    writeFileSync(path, Buffer.from(m[2], 'base64'))
+    return path
+  } catch {
+    return null
+  }
+}
+
+export { persistScreenshot }