mango-cms 0.3.33 → 0.3.35

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

@@ -0,0 +1,114 @@
+// pathGuard.js
+//
+// Server-side denylist for vibe edits (HAP-1124, protection #1). The in-page
+// assistant must never be able to edit the Vibe system itself — the ⌘K drawer
+// and its client, the orchestrator service, the staging spine, the settings /
+// secrets build, the vibe Mango endpoints, and the deploy/CI scripts. If it
+// could, a single prompt could brick the very thing the owner uses to recover.
+//
+// This is PURE and prompt-independent: the preamble also tells the agent which
+// files are off-limits (good UX), but enforcement lives in the PreToolUse hook
+// (`scripts/path-guard-hook.mjs`) which imports `isProtectedPath` from here and
+// blocks the tool BEFORE the edit lands — regardless of what the prompt says.
+//
+// Patterns are matched against a POSIX, repo-root-relative path. Supported glob
+// tokens: `**` (any run of path segments, including none), `*` (any run within a
+// single segment). Everything else is matched literally.
+
+const PROTECTED_PATTERNS = [
+  // ⌘K palette / drawer UI and its orchestrator client
+  'src/components/layout/vibeAssistant.vue',
+  'src/components/layout/publishDialog.vue',
+  'src/helpers/orchestrator.js',
+
+  // The orchestrator service itself (entire tree)
+  'orchestrator/**',
+
+  // Staging spine — the overlay + build config that make the clone real
+  'mango/helpers/staging.mjs',
+  'vite.config.js',
+  'vite.staging.config.js',
+
+  // Settings / secrets and the settings build
+  'mango/config/settings.json',
+  'mango/config/settings.local.json',
+  'build-settings.mjs',
+  'mango/helpers/build-settings.mjs',
+
+  // Vibe server endpoints: owner-token mint + cost ingest
+  'mango/helpers/vibeToken.js',
+  'mango/helpers/vibeCosts.js',
+
+  // Deploy / CI / process management
+  'mango/helpers/deploy.sh',
+  'mango/helpers/update.sh',
+  '.github/**',
+  'nginx/**',
+  '**/*.nginx',
+  '**/nginx.conf',
+  '**/ecosystem.config.js',
+  '**/ecosystem.config.cjs',
+  '**/pm2.config.js',
+]
+
+/** Clear, owner-facing message surfaced when an edit is blocked. */
+const PROTECTED_MESSAGE =
+  'That file is part of the Vibe system and is protected — I can’t edit it.'
+
+/** Escape a string for literal use inside a RegExp. */
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** Compile a glob pattern (with `**` and `*`) into an anchored RegExp. */
+function globToRe(glob) {
+  let re = ''
+  let i = 0
+  while (i < glob.length) {
+    const c = glob[i]
+    if (c === '*' && glob[i + 1] === '*') {
+      // `**/` ⇒ optional run of segments; bare `**` ⇒ anything.
+      if (glob[i + 2] === '/') { re += '(?:.*/)?'; i += 3 } else { re += '.*'; i += 2 }
+    } else if (c === '*') {
+      re += '[^/]*'
+      i += 1
+    } else {
+      re += escapeRe(c)
+      i += 1
+    }
+  }
+  return new RegExp(`^${re}$`)
+}
+
+const COMPILED = PROTECTED_PATTERNS.map(globToRe)
+
+/**
+ * Normalize an arbitrary path into a POSIX, root-relative form with no leading
+ * `./` and no trailing slash. Backslashes are treated as separators.
+ * @param {string} p
+ * @returns {string}
+ */
+function normalizeRel(p) {
+  let s = String(p || '').trim().replace(/\\/g, '/')
+  // Collapse any `a/b/../c` etc. without touching the filesystem.
+  const out = []
+  for (const seg of s.split('/')) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..') out.pop()
+    else out.push(seg)
+  }
+  return out.join('/')
+}
+
+/**
+ * True when a repo-root-relative path targets a protected Vibe-system file.
+ * @param {string} relPath - path relative to the staging clone root
+ * @returns {boolean}
+ */
+function isProtectedPath(relPath) {
+  const rel = normalizeRel(relPath)
+  if (!rel) return false
+  return COMPILED.some((re) => re.test(rel))
+}
+
+export { isProtectedPath, normalizeRel, PROTECTED_PATTERNS, PROTECTED_MESSAGE }

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

@@ -0,0 +1,139 @@
+// preamble.js
+//
+// Builds the full prompt sent to the in-page Vibe Assistant agent (HAP-1111).
+// Without this the agent sees little more than the raw instruction. Here we give
+// it (a) durable orientation — who it is, where things live, the one hard rule —
+// injected once at the start of a conversation, and (b) a per-turn snapshot of
+// what the owner is looking at (route, theme, selection, clicked element,
+// console errors, a screenshot the agent can Read).
+
+const NEVER_EDIT = 'mango/config/settings.json'
+const MAX_SELECTION = 400
+const MAX_HTML = 600
+const MAX_ERROR = 300
+const MAX_ERRORS = 10
+
+/**
+ * Static orientation for the agent. Injected once per conversation (resumed
+ * turns already carry it in history). Plain, declarative, no fluff.
+ * @returns {string}
+ */
+function contextPreamble() {
+  return [
+    'You are the Vibe Assistant — an in-page coding assistant embedded in a live',
+    'website. The site is a Mango + Vue 3 project, and you are editing a private',
+    'staging clone of it. Your edits hot-reload: the owner sees them in the page',
+    'within a few seconds of you saving a file.',
+    '',
+    'Where things live:',
+    '  • src/components/pages/   — one Vue component per route (the page views)',
+    '  • src/components/layout/  — shared chrome (header, footer, nav, drawers)',
+    '  • src/components/         — reusable building blocks',
+    '  • src/helpers/            — JS helpers (data, the Mango client, utilities)',
+    '  • src/assets/, src/style/ — styling and static assets',
+    '  • mango/                  — server config and CMS (Mango)',
+    '',
+    'How to work:',
+    '  • Make the smallest change that satisfies the request, then stop.',
+    '  • Explain what you changed in plain language the owner can understand —',
+    '    no jargon and no code diffs in your reply.',
+    '  • Prefer editing an existing component over creating a new one.',
+    '  • When the owner says "this" or "here", use the page context below',
+    '    (route, selection, clicked element, screenshot) to find the target.',
+    '',
+    `HARD RULE: NEVER edit ${NEVER_EDIT}. It holds secrets and environment`,
+    'config that must not change. If a task seems to require it, stop and explain.',
+    '',
+    'PROTECTED FILES: the Vibe system itself is off-limits — the ⌘K drawer and its',
+    'client, the orchestrator service, the staging spine (staging.mjs, vite config),',
+    'the settings build, and the deploy/CI scripts. These edits are also blocked',
+    'server-side, so if a request needs one, stop and explain rather than trying.',
+    '',
+    'FETCHING FROM THE WEB: use the WebFetch and WebSearch tools for anything on the',
+    'internet. Shell network commands (curl, wget) are intentionally disabled and',
+    'will always fail — do NOT retry them; reach for WebFetch instead. WebFetch works',
+    'on ANY url, not just pages: to find a site\'s brand colors, WebFetch its',
+    'site.webmanifest / manifest.json (the theme_color field) and the <link rel=',
+    '"stylesheet"> CSS asset urls from its HTML, then read the hex values there —',
+    'fetching the homepage alone only returns the pre-render shell of a JS app. If a',
+    'value is still unclear, just ask the owner; they may have already pasted the',
+    'logo or color as an attachment above.',
+  ].join('\n')
+}
+
+function truncate(value, n) {
+  const s = String(value)
+  return s.length > n ? `${s.slice(0, n)}…` : s
+}
+
+/**
+ * Render a per-turn page-context object into a readable text block. Returns ''
+ * when there is nothing useful to say.
+ * @param {object} [ctx]
+ * @returns {string}
+ */
+function formatPageContext(ctx) {
+  if (!ctx || typeof ctx !== 'object') return ''
+  const lines = []
+  const push = (label, val) => {
+    if (val === undefined || val === null || val === '') return
+    lines.push(`  • ${label}: ${typeof val === 'string' ? val : JSON.stringify(val)}`)
+  }
+
+  push('URL', ctx.url)
+  push('Route', ctx.route)
+  push('Page title', ctx.title)
+  push('Theme', ctx.theme)
+  if (ctx.viewport && ctx.viewport.w) push('Viewport', `${ctx.viewport.w}×${ctx.viewport.h}`)
+  push('Site owner', ctx.owner)
+  if (ctx.selection) push('Selected text', truncate(ctx.selection, MAX_SELECTION))
+
+  if (ctx.clickTarget && (ctx.clickTarget.selector || ctx.clickTarget.html)) {
+    push('Clicked element (selector)', ctx.clickTarget.selector)
+    if (ctx.clickTarget.html) push('Clicked element (HTML)', truncate(ctx.clickTarget.html, MAX_HTML))
+  }
+
+  const errs = Array.isArray(ctx.consoleErrors) ? ctx.consoleErrors.filter(Boolean) : []
+  if (errs.length) {
+    lines.push('  • Recent console errors the owner is seeing:')
+    for (const e of errs.slice(-MAX_ERRORS)) lines.push(`      - ${truncate(String(e), MAX_ERROR)}`)
+  }
+
+  if (ctx.screenshotPath) {
+    push('Viewport screenshot', `${ctx.screenshotPath} (Read this image to see what the owner sees)`)
+  }
+
+  // HAP-1126: files the owner pasted/uploaded with this turn. Claude Code reads
+  // images AND PDFs natively, so just hand it the absolute paths.
+  const atts = Array.isArray(ctx.attachmentPaths) ? ctx.attachmentPaths.filter(Boolean) : []
+  if (atts.length) {
+    lines.push('  • Files the owner attached (Read each — images and PDFs are supported):')
+    for (const a of atts) {
+      const label = a && a.name ? `${a.name} → ` : ''
+      lines.push(`      - ${label}${a && a.path ? a.path : a}`)
+    }
+  }
+
+  if (!lines.length) return ''
+  return ['Current page context (what the owner is looking at right now):', ...lines].join('\n')
+}
+
+/**
+ * Compose the final prompt: orientation (first turn only) + page context +
+ * the owner's request.
+ * @param {object} opts
+ * @param {string} opts.prompt
+ * @param {object} [opts.pageContext]
+ * @param {boolean} [opts.includePreamble=true]
+ * @returns {string}
+ */
+function composePrompt({ prompt, pageContext, includePreamble = true } = {}) {
+  const parts = []
+  if (includePreamble) parts.push(contextPreamble())
+  const ctxBlock = formatPageContext(pageContext)
+  if (ctxBlock) parts.push(ctxBlock)
+  parts.push(`Owner request:\n${String(prompt || '').trim()}`)
+  return parts.join('\n\n')
+}
+
+export { contextPreamble, formatPageContext, composePrompt }

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 }