bod-cli 0.10.6 → 0.10.8

package/.cursor/skills/using-bod-cli/SKILL.md

@@ -134,7 +134,7 @@ bod host ./dist --slug my-site     # reuse/update an existing slug
 bod host ./assets --app my-api     # persistent app assets
 ```
 
-### `bod env list|set|unset <app>`
+### `bod env list|set|unset|pull <app>`
 Manage environment variables.
 
 ```bash
@@ -142,8 +142,27 @@ bod env list my-api
 bod env set my-api DATABASE_URL=postgres://...
 bod env set my-api -f .env            # bulk set from .env file
 bod env unset my-api OLD_VAR
+bod env pull my-api                   # write the resolved env to ./.env (0600)
 ```
 
+**`bod env pull` never clobbers an existing file.** A `.env` is hand-maintained and
+usually holds local-only credentials the server has never seen — replacing it can
+destroy the only copy. If the output file already exists, `pull` **refuses**, prints a
+key-level diff (added / changed / removed — key names only, never values) and exits 1:
+
+```bash
+bod env pull my-api --merge     # add ONLY the missing keys; existing lines and local
+                                # values are kept verbatim (usually what you want)
+bod env pull my-api --force     # replace the whole file
+bod env pull my-api --stdout    # print, write nothing
+```
+
+`--merge` and `--force` both write a timestamped `<file>.backup-YYYYMMDD-HHMMSS`
+(mode 0600) before touching anything. Add `.env.backup-*` to `.gitignore`.
+
+The same rule applies to `bod db get|query -o <file>`: it refuses to overwrite an
+existing file unless you pass `--force` (which backs it up first).
+
 ### `bod db get|set|update|push|delete|query <path>`
 Read and write the per-app BodDB. Requires `database: true` in `bodify.yaml`.
 

package/CLAUDE.md

@@ -33,7 +33,7 @@ src/
     ├── rollback.ts     # bod rollback [app]
     ├── apps.ts         # bod apps list|status
     ├── logs.ts         # bod logs <app> [-f]
-    ├── env.ts          # bod env list|set|unset; scoped by <app>/--global/--group (+ --env); set supports -f .env
+    ├── env.ts          # bod env list|set|unset|pull; scoped by <app>/--global/--group (+ --env); set supports -f .env; pull NEVER clobbers (--merge/--force/--stdout)
     ├── open.ts         # bod open <app>
     ├── add.ts          # bod add <pkg>
     └── remove.ts       # bod remove <pkg>
@@ -47,4 +47,8 @@ src/
 - First-run redirects to `bod login`
 - Global `--instance` flag / `BOD_INSTANCE` env var for multi-instance
 - `resolveAppId` in `utils/resolve.ts` — shared name→ID lookup
+- **Never silently overwrite a file in the user's working tree.** Anything that writes
+  into cwd (`env pull`, `db -o`, `init`) must refuse when the target exists unless the
+  user opted in explicitly — then back it up first. Helpers: `utils/safe-write.ts`
+  (`guardOverwrite`, `backupFile`).
 - Templates use proper CaaB Resource convention from bodify scaffolding docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bod-cli",
-  "version": "0.10.6",
+  "version": "0.10.8",
   "type": "module",
   "bin": {
     "bod": "./src/cli.ts"

package/src/commands/db.ts

@@ -1,6 +1,7 @@
 import { defineCommand } from 'citty'
 import chalk from 'chalk'
 import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { backupFile, guardOverwrite } from '../utils/safe-write'
 import { join } from 'path'
 import { loadConfig, getResolvedInstance } from '../config'
 import { BodClient } from '../client'
@@ -166,11 +167,15 @@ async function readBody(positional: string | undefined, file: string | undefined
   }
 }
 
-function printResult(data: unknown, output: string | undefined) {
+function printResult(data: unknown, output: string | undefined, force = false) {
   const text = JSON.stringify(data, null, 2)
   if (output) {
+    // Same rule as `bod env pull`: never silently destroy a file in the user's tree.
+    guardOverwrite(output, force, 'Pass --force to replace it (a timestamped backup is written first), or choose another -o path.')
+    const backup = force ? backupFile(output) : undefined
     writeFileSync(output, text)
     console.log(chalk.green(`✓ Wrote ${output}`))
+    if (backup) console.log(chalk.dim(`  Backup: ${backup}`))
   } else {
     console.log(text)
   }
@@ -232,9 +237,10 @@ const getCmd = defineCommand({
     limit: { type: 'string', alias: 'n', description: 'Shallow only: max keys to return' },
     offset: { type: 'string', description: 'Shallow only: skip N keys' },
     output: { type: 'string', alias: 'o', description: 'Write to file instead of stdout' },
+    force: { type: 'boolean', alias: 'F', description: 'Overwrite the -o file if it exists (backs it up first)' },
   },
   async run({ args }) {
-    strictArgs(['path', 'app', 'a', 'deep', 'd', 'limit', 'n', 'offset', 'output', 'o'])
+    strictArgs(['path', 'app', 'a', 'deep', 'd', 'limit', 'n', 'offset', 'output', 'o', 'force', 'F'])
     const target = await resolveDbTarget(args.app, readLocalFlag())
     printTargetBanner(target)
     const path = normalizePath(args.path)
@@ -246,7 +252,7 @@ const getCmd = defineCommand({
     }
     const sub = `/db${path ? '/' + path : '/'}${qs.length ? '?' + qs.join('&') : ''}`
     const res = await target.request<DbResponse & { shallow?: boolean }>('GET', sub)
-    printResult(res.data ?? null, args.output)
+    printResult(res.data ?? null, args.output, !!args.force)
     if (res.shallow && !args.output) {
       console.error(chalk.dim(`(shallow — pass -d for deep read; target: ${target.label})`))
     }
@@ -369,9 +375,10 @@ const queryCmd = defineCommand({
     offset: { type: 'string', description: 'Skip N results' },
     deep: { type: 'boolean', alias: 'd', description: 'Return full matched documents. Default: shallow (keys only).', default: false },
     output: { type: 'string', alias: 'o', description: 'Write to file instead of stdout' },
+    force: { type: 'boolean', alias: 'F', description: 'Overwrite the -o file if it exists (backs it up first)' },
   },
   async run({ args }) {
-    strictArgs(['path', 'app', 'a', 'filter', 'f', 'where', 'w', 'order', 'limit', 'n', 'offset', 'deep', 'd', 'output', 'o'])
+    strictArgs(['path', 'app', 'a', 'filter', 'f', 'where', 'w', 'order', 'limit', 'n', 'offset', 'deep', 'd', 'output', 'o', 'force', 'F'])
     // Merge --filter (shorthand) and --where (canonical). Both are repeatable.
     const filters: Array<{ field: string; op: string; value: unknown }> = []
     const filterList = args.filter ? (Array.isArray(args.filter) ? args.filter : [args.filter]) : []
@@ -396,7 +403,7 @@ const queryCmd = defineCommand({
     if (!args.deep && Array.isArray(rows)) {
       rows = rows.map(r => ({ _path: r._path, _key: r._key }))
     }
-    printResult(rows ?? null, args.output)
+    printResult(rows ?? null, args.output, !!args.force)
     if (!args.deep && !args.output && Array.isArray(rows)) {
       console.error(chalk.dim(`(${rows.length} match${rows.length === 1 ? '' : 'es'}; shallow — pass -d for full docs)`))
     }

package/src/commands/deploy.ts

@@ -13,7 +13,7 @@ async function detectBranch(explicit?: string): Promise<string> {
   return branch || 'main'
 }
 
-async function uploadDeploy(client: BodClient, appId: string, branch: string) {
+export async function uploadDeploy(client: BodClient, appId: string, branch: string) {
   const allExcludes = resolveExcludes(readExcludesFromYaml())
   const excludeFlags = allExcludes.map(e => `--exclude=${e}`)
 
@@ -55,54 +55,58 @@ async function uploadDeploy(client: BodClient, appId: string, branch: string) {
   }
 
   // Rewrite root + workspace package.jsons (file:../X → file:./X for included siblings)
-  rewritePkg(join(process.cwd(), 'package.json'))
+  // try/finally: a throw anywhere below would otherwise leave the user's
+  // package.json files rewritten on disk. Never exit un-restored.
   try {
-    const rootPkg = JSON.parse(fs.readFileSync(join(process.cwd(), 'package.json'), 'utf8'))
-    for (const pattern of rootPkg.workspaces ?? []) {
-      const base = join(process.cwd(), pattern.replace(/\/?\*$/, ''))
-      if (!fs.existsSync(base)) continue
-      for (const sub of fs.readdirSync(base)) {
-        rewritePkg(join(base, sub, 'package.json'))
+    rewritePkg(join(process.cwd(), 'package.json'))
+    try {
+      const rootPkg = JSON.parse(fs.readFileSync(join(process.cwd(), 'package.json'), 'utf8'))
+      for (const pattern of rootPkg.workspaces ?? []) {
+        const base = join(process.cwd(), pattern.replace(/\/?\*$/, ''))
+        if (!fs.existsSync(base)) continue
+        for (const sub of fs.readdirSync(base)) {
+          rewritePkg(join(base, sub, 'package.json'))
+        }
       }
-    }
-  } catch {}
+    } catch {}
 
-  // Rewrite sibling package.jsons: file:.. deps that aren't included become "*" (npm fallback)
-  const includedSiblings = new Set([...siblingMap.values()])
-  for (const sp of siblingPaths) {
-    const abs = resolve(sp)
-    const sibPkgPath = join(abs, 'package.json')
-    if (!fs.existsSync(sibPkgPath)) continue
-    const original = fs.readFileSync(sibPkgPath, 'utf8')
-    const sibPkg = JSON.parse(original)
-    let changed = false
-    for (const field of ['dependencies', 'devDependencies']) {
-      if (!sibPkg[field]) continue
-      for (const [name, ver] of Object.entries(sibPkg[field]) as [string, string][]) {
-        if (!ver.startsWith('file:') || !ver.includes('..')) continue
-        const depName = basename(resolve(abs, ver.slice(5)))
-        if (!includedSiblings.has(depName)) {
-          sibPkg[field][name] = '*'
-          changed = true
+    // Rewrite sibling package.jsons: file:.. deps that aren't included become "*" (npm fallback)
+    const includedSiblings = new Set([...siblingMap.values()])
+    for (const sp of siblingPaths) {
+      const abs = resolve(sp)
+      const sibPkgPath = join(abs, 'package.json')
+      if (!fs.existsSync(sibPkgPath)) continue
+      const original = fs.readFileSync(sibPkgPath, 'utf8')
+      const sibPkg = JSON.parse(original)
+      let changed = false
+      for (const field of ['dependencies', 'devDependencies']) {
+        if (!sibPkg[field]) continue
+        for (const [name, ver] of Object.entries(sibPkg[field]) as [string, string][]) {
+          if (!ver.startsWith('file:') || !ver.includes('..')) continue
+          const depName = basename(resolve(abs, ver.slice(5)))
+          if (!includedSiblings.has(depName)) {
+            sibPkg[field][name] = '*'
+            changed = true
+          }
         }
       }
+      if (changed) {
+        rewritten.push({ path: sibPkgPath, original })
+        fs.writeFileSync(sibPkgPath, JSON.stringify(sibPkg, null, 2) + '\n')
+      }
     }
-    if (changed) {
-      rewritten.push({ path: sibPkgPath, original })
-      fs.writeFileSync(sibPkgPath, JSON.stringify(sibPkg, null, 2) + '\n')
-    }
-  }
 
-  const tar = Bun.spawnSync(['tar', 'czh', ...excludeFlags, '-f', tmpFile, '.', ...siblingArgs], {
-    stderr: 'pipe',
-    env,
-  })
-
-  // Restore original package.json files
-  for (const { path, original } of rewritten) fs.writeFileSync(path, original)
-  if (tar.exitCode !== 0) {
-    const errText = tar.stderr.toString()
-    throw new Error(`tar failed: ${errText}`)
+    const tar = Bun.spawnSync(['tar', 'czh', ...excludeFlags, '-f', tmpFile, '.', ...siblingArgs], {
+      stderr: 'pipe',
+      env,
+    })
+    if (tar.exitCode !== 0) {
+      const errText = tar.stderr.toString()
+      throw new Error(`tar failed: ${errText}`)
+    }
+  } finally {
+    // Restore original package.json files
+    for (const { path, original } of rewritten) fs.writeFileSync(path, original)
   }
 
   const file = Bun.file(tmpFile)

package/src/commands/env.ts

@@ -1,10 +1,13 @@
 import { defineCommand } from 'citty'
 import chalk from 'chalk'
-import { writeFileSync } from 'fs'
+import { writeFileSync, appendFileSync, readFileSync, existsSync, mkdirSync, chmodSync } from 'fs'
+import { dirname, resolve as resolvePath } from 'path'
+import { homedir } from 'os'
 import { loadConfig, getResolvedInstance } from '../config'
 import { BodClient } from '../client'
 import { printTable } from '../utils/output'
 import { resolveAppId, resolveAppName } from '../utils/resolve'
+import { backupFile } from '../utils/safe-write'
 
 // --- Subs PLATFORM PROVIDER scope (mirror bodify subs.secrets.ts) ---
 // Provider credentials (Stripe secret key, Apple shared secret, Play SA) are money
@@ -113,6 +116,24 @@ function quoteDotEnvValue(value: string): string {
   return value
 }
 
+/** Serialize resolved values to dotenv text (trailing newline; '' for no vars). */
+function renderDotEnv(values: Record<string, string>): string {
+  const body = Object.entries(values).map(([k, v]) => `${k}=${quoteDotEnvValue(v)}`).join('\n')
+  return body ? body + '\n' : ''
+}
+
+/** Key-level diff of a pull against what is already in the file. */
+function diffEnv(existing: Record<string, string>, incoming: Record<string, string>) {
+  const added: string[] = []
+  const changed: string[] = []
+  for (const [k, v] of Object.entries(incoming)) {
+    if (!(k in existing)) added.push(k)
+    else if (existing[k] !== v) changed.push(k)
+  }
+  const removed = Object.keys(existing).filter(k => !(k in incoming))
+  return { added, changed, removed }
+}
+
 const listCmd = defineCommand({
   meta: { name: 'list', description: 'List env vars. Per-app: resolved KEY=VALUE. --global/--group/--subs: variables in that scope (masked).' },
   args: {
@@ -288,26 +309,120 @@ const rmCmd = defineCommand({
   },
 })
 
+/** `env pull` takes <app> and an optional destination path, either of which may be
+ *  omitted (app falls back to bodify.yaml). With ONE positional the two are
+ *  ambiguous, so a token that is EXPLICITLY a path ('/', '~', or a leading '.') is
+ *  read as the destination. A bare `name.ext` is NOT enough: an app may legitimately
+ *  be called `my.app`, and guessing wrong writes another app's secrets into cwd. */
+export function splitPullPositionals(a?: string, b?: string): { app?: string; dest?: string } {
+  if (b !== undefined) return { app: a, dest: b }
+  if (a !== undefined && looksLikePath(a)) return { app: undefined, dest: a }
+  return { app: a, dest: undefined }
+}
+
+/** A '~' reaching us unexpanded (quoted, or an argv built by a script) must not become
+ *  a literal './~/...' directory holding real secrets. */
+function expandTilde(p: string): string {
+  return p === '~' || p.startsWith('~/') ? homedir() + p.slice(1) : p
+}
+
+function looksLikePath(s: string): boolean {
+  return s.includes('/') || s.startsWith('~') || s.startsWith('.')
+}
+
 const pullCmd = defineCommand({
-  meta: { name: 'pull', description: 'Write an app\'s resolved env to a dotenv file (default .env, mode 0600).' },
+  meta: { name: 'pull', description: 'Write an app\'s resolved env to a dotenv file (default .env, mode 0600). Refuses to clobber an existing file; use --merge or --force.' },
   args: {
     app: { type: 'positional', description: 'App name (or reads from bodify.yaml)', required: false },
+    dest: { type: 'positional', description: 'Output file (default .env). A lone positional is only read as the destination when it is explicitly a path (./x, ~/x, a/b).', required: false },
     env: { type: 'string', alias: 'e', description: 'Environment (e.g. prod)' },
     output: { type: 'string', alias: 'o', description: 'Output file (default .env)' },
+    stdout: { type: 'boolean', description: 'Print to stdout instead of writing any file' },
+    merge: { type: 'boolean', alias: 'm', description: 'Add only the keys missing from the file; never touch existing lines' },
+    force: { type: 'boolean', alias: 'F', description: 'Replace the whole file (a timestamped backup is written first)' },
   },
   async run({ args }) {
+    if (args.merge && args.force) {
+      console.error(chalk.red('Pass only one of --merge, --force — they are mutually exclusive.'))
+      process.exit(1)
+    }
+
     const { url, apiKey } = getResolvedInstance(loadConfig())
     const client = new BodClient(url, apiKey)
-    const appId = await resolveAppId(client, resolveAppName(args.app))
+    const { app, dest } = splitPullPositionals(args.app, args.dest)
+    const appId = await resolveAppId(client, resolveAppName(app))
     const qs = args.env ? `?environment=${encodeURIComponent(args.env)}` : ''
     const res = await client.get<ResolvedEnv>(`/apps/${appId}/env${qs}`)
     const values = res.values ?? {}
-    const out = args.output ?? '.env'
-    const body = Object.entries(values)
-      .map(([k, v]) => `${k}=${quoteDotEnvValue(v)}`)
-      .join('\n')
-    writeFileSync(out, body ? body + '\n' : '', { mode: 0o600 })
-    console.log(chalk.green(`✓ Wrote ${Object.keys(values).length} var(s) to ${out}`))
+    // Every branch below (fresh write / refuse / merge / force / backup) acts on THIS
+    // resolved path. A destination that was silently dropped is how a real pull once
+    // dumped 22 secrets into an unrelated repo's cwd.
+    const out = resolvePath(process.cwd(), expandTilde(args.output ?? dest ?? '.env'))
+
+    const body = renderDotEnv(values)
+
+    // The always-safe escape hatch: look, don't touch.
+    if (args.stdout) {
+      process.stdout.write(body)
+      return
+    }
+
+    if (!existsSync(out)) {
+      mkdirSync(dirname(out), { recursive: true })
+      writeFileSync(out, body, { mode: 0o600 })
+      console.log(chalk.green(`✓ Wrote ${Object.keys(values).length} var(s) to ${out}`))
+      return
+    }
+
+    // ── The file already exists. It is hand-maintained, often holds local-only
+    // credentials that exist nowhere else, and is NOT recoverable from the
+    // server. Never replace it on a bare `bod env pull`.
+    const existingText = readFileSync(out, 'utf8')
+    const existing = parseDotEnv(existingText)
+    const d = diffEnv(existing, values)
+
+    if (!d.added.length && !d.changed.length) {
+      console.log(chalk.dim(`${out} already has every pulled var (${Object.keys(values).length}) — nothing to do.`))
+      if (d.removed.length) console.log(chalk.dim(`  ${d.removed.length} local-only key(s) not on the server: ${d.removed.join(', ')}`))
+      return
+    }
+
+    if (args.merge) {
+      const backup = backupFile(out)
+      const addition = renderDotEnv(Object.fromEntries(d.added.map(k => [k, values[k]])))
+      const sep = existingText.length && !existingText.endsWith('\n') ? '\n' : ''
+      appendFileSync(out, `${sep}${addition}`)
+      chmodSync(out, 0o600)
+      console.log(chalk.green(`✓ Added ${d.added.length} var(s) to ${out}: ${d.added.join(', ')}`))
+      if (d.changed.length) console.log(chalk.yellow(`  Kept your local value for ${d.changed.length} differing key(s): ${d.changed.join(', ')}`))
+      if (backup) console.log(chalk.dim(`  Backup: ${backup}`))
+      return
+    }
+
+    if (args.force) {
+      const backup = backupFile(out)
+      writeFileSync(out, body, { mode: 0o600 })
+      // `mode` only applies when the file is CREATED — an existing 0644 dotenv would
+      // otherwise stay world-readable after being filled with the server's secrets.
+      chmodSync(out, 0o600)
+      console.log(chalk.green(`✓ Replaced ${out} with ${Object.keys(values).length} var(s)`))
+      if (d.removed.length) console.log(chalk.yellow(`  Dropped ${d.removed.length} local-only key(s): ${d.removed.join(', ')}`))
+      if (backup) console.log(chalk.dim(`  Backup: ${backup}`))
+      return
+    }
+
+    // Default: refuse, and show WHAT would change (key names only — never print
+    // the secret values of a file we are not allowed to touch).
+    console.error(chalk.red(`Refusing to overwrite existing ${out} — it may hold local values that exist nowhere else.`))
+    console.error('')
+    if (d.added.length) console.error(chalk.green(`  + ${d.added.length} would be added:   ${d.added.join(', ')}`))
+    if (d.changed.length) console.error(chalk.yellow(`  ~ ${d.changed.length} would be changed: ${d.changed.join(', ')}`))
+    if (d.removed.length) console.error(chalk.red(`  - ${d.removed.length} would be removed: ${d.removed.join(', ')}`))
+    console.error('')
+    console.error(chalk.dim('  bod env pull … --merge   add only the missing keys, keep your file (usually what you want)'))
+    console.error(chalk.dim('  bod env pull … --force   replace the file (a timestamped backup is written first)'))
+    console.error(chalk.dim('  bod env pull … --stdout  print to stdout, write nothing'))
+    process.exit(1)
   },
 })
 

package/src/commands/host.ts

@@ -3,6 +3,7 @@ import chalk from 'chalk'
 import { statSync, readdirSync, readFileSync, existsSync } from 'fs'
 import { join, relative, basename, extname } from 'path'
 import { loadConfig, getResolvedInstance } from '../config'
+import { buildMediaPreview } from '../utils/media-preview'
 
 const MIME: Record<string, string> = {
   '.html': 'text/html; charset=utf-8', '.htm': 'text/html; charset=utf-8',
@@ -42,6 +43,9 @@ export default defineCommand({
     path: { type: 'positional', description: 'File or directory to publish', required: true },
     slug: { type: 'string', description: 'Reuse/update an existing site slug' },
     app: { type: 'string', description: 'Link to a Bodify app id → persistent (else ephemeral, 48h)' },
+    // citty/mri folds `--no-preview` into `preview: false`; a literal 'no-preview' arg
+    // never receives it, so the documented opt-out silently did nothing.
+    preview: { type: 'boolean', default: true, description: 'Auto-generate an OG landing page for a single video/audio file (--no-preview to skip)' },
   },
   async run({ args }) {
     const root = args.path
@@ -50,6 +54,16 @@ export default defineCommand({
     const files = collect(root)
     if (!files.length) { console.error(chalk.red('No files to publish')); process.exit(1) }
 
+    // A bare video/mp4 URL cannot unfurl in WhatsApp/iMessage/Slack — those need an
+    // HTML document with og:* tags. For a single media file, synthesize one.
+    const preview = (args.preview !== false && files.length === 1 && statSync(root).isFile())
+      ? buildMediaPreview(files[0].abs, mimeFor(files[0].rel))
+      : null
+    if (preview) {
+      if (preview.warning) console.log(chalk.yellow(`! ${preview.warning}`))
+      files.push(...preview.extras)
+    }
+
     const { url, apiKey, name: instanceName } = getResolvedInstance(loadConfig())
     const auth: Record<string, string> = apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
     const totalBytes = files.reduce((n, f) => n + statSync(f.abs).size, 0)
@@ -68,6 +82,9 @@ export default defineCommand({
       upload: { uploads: Array<{ path: string; url: string | null; key: string }>; finalizeUrl: string }
     }
 
+    // 2a. og:* URLs must be absolute — re-render index.html now that the slug is known.
+    if (preview) preview.render(`${site.siteUrl.replace(/\/+$/, '')}`)
+
     // 2. Upload each file — presigned PUT (R2) or direct-to-agent PUT (local provider).
     const byPath = new Map(files.map(f => [f.rel, f.abs]))
     for (const u of site.upload.uploads) {
@@ -87,7 +104,9 @@ export default defineCommand({
     const finRes = await fetch(`${url}${site.upload.finalizeUrl}`, { method: 'POST', headers: { ...auth } })
     if (!finRes.ok) { console.error(chalk.red(`Finalize failed: ${finRes.status} ${await finRes.text()}`)); process.exit(1) }
 
-    console.log(chalk.green(`✓ Live: ${site.siteUrl}`))
+    const shareUrl = preview ? `${site.siteUrl.replace(/\/+$/, '')}/` : site.siteUrl
+    console.log(chalk.green(`✓ Live: ${shareUrl}`))
+    if (preview) console.log(chalk.dim(`  share this URL — it previews in WhatsApp/iMessage/Slack`))
     console.log(chalk.dim(`  slug: ${site.slug}${args.app ? `  (persistent, app ${args.app})` : site.expiresAt ? `  (expires ${new Date(site.expiresAt).toISOString()})` : ''}`))
   },
 })

package/src/commands/init/init.ts

@@ -109,6 +109,7 @@ function generateGitignore(): string {
 dist/
 .env
 .env.local
+.env.backup-*
 *.log
 `
 }

package/src/utils/media-preview.ts

@@ -0,0 +1,158 @@
+import { spawnSync } from 'child_process'
+import { statSync, mkdtempSync, existsSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join, basename } from 'path'
+
+/**
+ * Chat apps (WhatsApp/iMessage/Slack) unfurl HTML with Open Graph tags — never a
+ * bare `video/mp4` response. A single-media `bod host ./clip.mp4` therefore has
+ * nothing to unfurl. This synthesizes the missing landing page: an `index.html`
+ * carrying og:* + twitter:* and a `poster.jpg` frame pulled with ffmpeg, so the
+ * bare `…/s/<slug>/` URL previews and plays.
+ */
+
+/** WhatsApp drops og:image over ~600 KB entirely — stay well under. */
+const POSTER_MAX_BYTES = 500 * 1024
+
+export type PreviewExtra = { rel: string; abs: string }
+
+function esc(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+function run(cmd: string, args: string[]): { ok: boolean; stdout: string } {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' })
+  return { ok: r.status === 0, stdout: r.stdout ?? '' }
+}
+
+function probe(abs: string): { width?: number; height?: number; duration?: number } {
+  const r = run('ffprobe', ['-v', 'error', '-select_streams', 'v:0',
+    '-show_entries', 'stream=width,height:format=duration', '-of', 'csv=p=0', abs])
+  if (!r.ok) return {}
+  const nums = r.stdout.trim().split(/[\s,]+/).map(Number).filter(n => Number.isFinite(n))
+  const [width, height, duration] = nums
+  return { width, height, duration }
+}
+
+/** Grab a representative frame as JPEG, shrinking quality until it fits the cap. */
+function extractPoster(abs: string, outDir: string, duration?: number): string | null {
+  const out = join(outDir, 'poster.jpg')
+  // A frame ~10% in beats frame 0, which is often black/a fade-in.
+  const seek = duration && duration > 2 ? Math.min(duration * 0.1, 5) : 0
+  for (const q of ['3', '6', '9']) {
+    const r = run('ffmpeg', ['-y', '-ss', String(seek), '-i', abs, '-frames:v', '1',
+      '-vf', "scale='min(1280,iw)':-2", '-q:v', q, out])
+    if (!r.ok || !existsSync(out)) return null
+    if (statSync(out).size <= POSTER_MAX_BYTES) return out
+  }
+  return existsSync(out) && statSync(out).size <= POSTER_MAX_BYTES ? out : null
+}
+
+function page(o: {
+  title: string; fileName: string; kind: 'video' | 'audio'
+  poster: boolean; width?: number; height?: number; mime: string
+  posterWidth?: number; posterHeight?: number
+  /** Absolute site base, e.g. https://bodify.bod.ee/s/<slug> (no trailing slash). */
+  base: string
+}): string {
+  const t = esc(o.title)
+  // og:*/twitter:* MUST be absolute — crawlers do not resolve relative URLs.
+  const f = `${o.base}/${encodeURIComponent(o.fileName)}`
+  const posterUrl = `${o.base}/poster.jpg`
+  const media = o.kind === 'video'
+    ? `<video src="${f}" ${o.poster ? `poster="${posterUrl}"` : ''} controls playsinline autoplay muted loop></video>`
+    : `<audio src="${f}" controls></audio>`
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${t}</title>
+<meta property="og:type" content="${o.kind}.other">
+<meta property="og:title" content="${t}">
+<meta property="og:description" content="${esc(o.fileName)}">
+${o.kind === 'video' ? `<meta property="og:video" content="${f}">
+<meta property="og:video:secure_url" content="${f}">
+<meta property="og:video:type" content="${o.mime}">
+${o.width ? `<meta property="og:video:width" content="${o.width}">` : ''}
+${o.height ? `<meta property="og:video:height" content="${o.height}">` : ''}` : `<meta property="og:audio" content="${f}">
+<meta property="og:audio:type" content="${o.mime}">`}
+${o.poster ? `<meta property="og:image" content="${posterUrl}">
+<meta property="og:image:type" content="image/jpeg">
+${o.posterWidth ? `<meta property="og:image:width" content="${o.posterWidth}">` : ''}
+${o.posterHeight ? `<meta property="og:image:height" content="${o.posterHeight}">` : ''}` : ''}
+<meta name="twitter:card" content="${o.poster ? 'summary_large_image' : 'summary'}">
+<meta name="twitter:title" content="${t}">
+${o.poster ? `<meta name="twitter:image" content="${posterUrl}">` : ''}
+<style>
+:root{color-scheme:dark}
+html,body{margin:0;height:100%;background:#0b0b0d;color:#e8e8ea;
+  font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+body{display:grid;place-items:center;padding:16px;box-sizing:border-box}
+video,audio{max-width:100%;max-height:92vh;border-radius:12px;display:block}
+</style>
+</head>
+<body>${media}</body>
+</html>
+`
+}
+
+export type MediaPreview = {
+  /** Files to add to the publish manifest (poster only — index.html is rendered later). */
+  extras: PreviewExtra[]
+  /** Render + write index.html once the absolute site base URL is known. Returns its abs path. */
+  render: (base: string) => string
+  warning?: string
+}
+
+/**
+ * Prepare the OG landing page + poster for a single-media publish.
+ * Returns null when not applicable (the file isn't video/audio).
+ * og:* URLs must be absolute, and the slug is only known after /v1/publish —
+ * so the poster is produced now and the HTML is rendered by `render(base)`.
+ */
+export function buildMediaPreview(abs: string, mime: string): MediaPreview | null {
+  const kind = mime.startsWith('video/') ? 'video' : mime.startsWith('audio/') ? 'audio' : null
+  if (!kind) return null
+
+  const dir = mkdtempSync(join(tmpdir(), 'bod-host-og-'))
+  const fileName = basename(abs)
+  const extras: PreviewExtra[] = []
+  let warning: string | undefined
+  let posterAbs: string | null = null
+  let meta: ReturnType<typeof probe> = {}
+
+  if (kind === 'video') {
+    if (!run('ffmpeg', ['-version']).ok) {
+      warning = 'ffmpeg not found — no poster frame, so chat apps will show a title-only preview.'
+    } else {
+      meta = probe(abs)
+      posterAbs = extractPoster(abs, dir, meta.duration)
+      if (!posterAbs) warning = 'Could not extract a poster frame — preview will be title-only.'
+    }
+  }
+
+  const htmlPath = join(dir, 'index.html')
+  if (posterAbs) extras.push({ rel: 'poster.jpg', abs: posterAbs })
+
+  const posterDims = posterAbs ? probe(posterAbs) : {}
+  const render = (base: string): string => {
+    const html = page({
+      title: fileName.replace(/\.[^.]+$/, ''),
+      fileName, kind, mime,
+      poster: !!posterAbs,
+      width: meta.width, height: meta.height,
+      posterWidth: posterDims.width, posterHeight: posterDims.height,
+      base: base.replace(/\/+$/, ''),
+    })
+    writeFileSync(htmlPath, html)
+    return htmlPath
+  }
+
+  // Write a placeholder now so the manifest can declare a size; finalize verifies
+  // existence, not size, and render() rewrites it with the real absolute URLs.
+  render('https://placeholder.invalid/s/placeholder')
+  extras.unshift({ rel: 'index.html', abs: htmlPath })
+
+  return { extras, render, warning }
+}

package/src/utils/safe-write.ts

@@ -0,0 +1,45 @@
+import { existsSync, copyFileSync, chmodSync } from 'fs'
+import chalk from 'chalk'
+
+/**
+ * Timestamp suffix for backup files. Local time, filename-safe, sorts lexically.
+ * e.g. `20260827-141503`
+ */
+function stamp(now = new Date()): string {
+  const p = (n: number) => String(n).padStart(2, '0')
+  return `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}-${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`
+}
+
+/**
+ * Copy `path` aside before it is overwritten. Returns the backup path, or
+ * undefined when there was nothing to back up.
+ *
+ * Backups inherit 0600 — a dotenv backup holds the same secrets as the original,
+ * so it must not be world-readable just because it has a different name.
+ */
+export function backupFile(path: string, now = new Date()): string | undefined {
+  if (!existsSync(path)) return undefined
+  let dest = `${path}.backup-${stamp(now)}`
+  // Two pulls inside the same second must not silently eat the first backup.
+  let n = 1
+  while (existsSync(dest)) dest = `${path}.backup-${stamp(now)}.${n++}`
+  copyFileSync(path, dest)
+  chmodSync(dest, 0o600)
+  return dest
+}
+
+/**
+ * Refuse to clobber an existing file unless the caller explicitly opted in.
+ *
+ * The default for ANY command that writes into the user's working tree is
+ * non-destructive: a file already on disk is assumed to be hand-maintained and
+ * possibly unrecoverable (this guard exists because `bod env pull` silently
+ * destroyed a developer's hand-written `.env`). `hint` must tell the user what
+ * to type next.
+ */
+export function guardOverwrite(path: string, force: boolean, hint: string): void {
+  if (!existsSync(path) || force) return
+  console.error(chalk.red(`Refusing to overwrite existing file: ${path}`))
+  console.error(chalk.dim(hint))
+  process.exit(1)
+}

package/test/db-output-guard.test.ts

@@ -0,0 +1,77 @@
+// Sibling consistency with `bod env pull`: any command that writes into the user's
+// working tree must refuse to clobber an existing file. Guarding one command while
+// its sibling still overwrites is not a fix. Real CLI surface, mock agent.
+import { test, expect, beforeAll, afterAll, beforeEach } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+const CLI = join(import.meta.dir, '..', 'src', 'cli.ts')
+const APP_ID = 'e1dba964-b944-4dd0-b971-fe72ee493bf6'
+
+let server: ReturnType<typeof Bun.serve>
+let home: string
+let cwd: string
+
+beforeAll(() => {
+  server = Bun.serve({
+    port: 0,
+    fetch(req) {
+      const url = new URL(req.url)
+      if (url.pathname === '/api/apps') return Response.json([{ id: APP_ID, name: 'bodify' }])
+      if (url.pathname.startsWith(`/api/apps/${APP_ID}/db`)) return Response.json({ ok: true, data: { a: 1 } })
+      return new Response('not found', { status: 404 })
+    },
+  })
+  home = mkdtempSync(join(tmpdir(), 'bod-db-home-'))
+  mkdirSync(join(home, '.bod'), { recursive: true })
+  writeFileSync(join(home, '.bod', 'config.json'), JSON.stringify({
+    defaultInstance: 'test',
+    instances: { test: { url: `http://localhost:${server.port}`, apiKey: 'test-key' } },
+  }))
+})
+
+afterAll(() => { server?.stop(true); rmSync(home, { recursive: true, force: true }) })
+beforeEach(() => { cwd = mkdtempSync(join(tmpdir(), 'bod-db-cwd-')) })
+
+async function runCli(args: string[]) {
+  const proc = Bun.spawn(['bun', CLI, ...args], {
+    cwd, env: { ...process.env, HOME: home, BOD_INSTANCE: '', FORCE_COLOR: '0' },
+    stdout: 'pipe', stderr: 'pipe',
+  })
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited,
+  ])
+  return { stdout, stderr, code }
+}
+
+const OUT = 'dump.json'
+const MINE = '{"hand":"written"}'
+
+test('db get -o <existing file> → refuses, file untouched', async () => {
+  writeFileSync(join(cwd, OUT), MINE)
+  const { code, stderr } = await runCli(['db', 'get', '/', '-o', OUT])
+  expect(code).toBe(1)
+  expect(stderr).toContain('Refusing to overwrite')
+  expect(stderr).toContain(OUT)
+  expect(stderr).toContain('--force')
+  expect(readFileSync(join(cwd, OUT), 'utf8')).toBe(MINE)
+  expect(readdirSync(cwd)).toEqual([OUT])
+})
+
+test('db get -o --force → writes, and the original survives in a backup', async () => {
+  writeFileSync(join(cwd, OUT), MINE)
+  const { code } = await runCli(['db', 'get', '/', '-o', OUT, '--force'])
+  expect(code).toBe(0)
+  expect(readFileSync(join(cwd, OUT), 'utf8')).toContain('"a"')
+  const backups = readdirSync(cwd).filter(f => f.startsWith(`${OUT}.backup-`))
+  expect(backups).toHaveLength(1)
+  expect(readFileSync(join(cwd, backups[0]), 'utf8')).toBe(MINE)
+})
+
+test('db get -o <new file> → writes normally', async () => {
+  const { code } = await runCli(['db', 'get', '/', '-o', OUT])
+  expect(code).toBe(0)
+  expect(readFileSync(join(cwd, OUT), 'utf8')).toContain('"a"')
+  expect(readdirSync(cwd)).toEqual([OUT])
+})

package/test/deploy-restore.test.ts

@@ -0,0 +1,41 @@
+// `bod deploy --upload` temporarily rewrites the user's package.json files (file:../X →
+// file:./X) and restores them afterwards. If anything throws in between, the restore MUST
+// still run — otherwise a failed deploy leaves the developer's package.json mangled.
+import { test, expect, afterEach } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, realpathSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { uploadDeploy } from '../src/commands/deploy'
+
+const origCwd = process.cwd()
+let root: string
+afterEach(() => { process.chdir(origCwd); if (root) rmSync(root, { recursive: true, force: true }) })
+
+/** app/ depends on ../sib; sib/package.json is INVALID JSON → JSON.parse throws in the
+ *  sibling-rewrite loop, AFTER app/package.json has already been rewritten on disk. */
+function fixture(sibPkgBody: string) {
+  root = realpathSync(mkdtempSync(join(tmpdir(), 'bod-deploy-')))
+  mkdirSync(join(root, 'app')); mkdirSync(join(root, 'sib'))
+  const appPkg = JSON.stringify({ name: 'app', dependencies: { sib: 'file:../sib' } }, null, 2)
+  writeFileSync(join(root, 'app', 'package.json'), appPkg)
+  writeFileSync(join(root, 'sib', 'package.json'), sibPkgBody)
+  process.chdir(join(root, 'app'))
+  return appPkg
+}
+
+const client = { request: async () => { throw new Error('should not reach upload') } } as any
+
+test('a throw during the rewrite leaves package.json RESTORED, not mangled', async () => {
+  const appPkg = fixture('{ this is not json')
+  await expect(uploadDeploy(client, 'id', 'main')).rejects.toThrow()
+  // The rewrite definitely happened (file:../sib → file:./sib) — and was undone.
+  expect(readFileSync(join(root, 'app', 'package.json'), 'utf8')).toBe(appPkg)
+  expect(readFileSync(join(root, 'app', 'package.json'), 'utf8')).toContain('file:../sib')
+})
+
+test('the happy path also restores package.json after packing', async () => {
+  const appPkg = fixture(JSON.stringify({ name: 'sib' }, null, 2))
+  // Packing succeeds; the upload call is what fails, well after the finally block.
+  await expect(uploadDeploy(client, 'id', 'main')).rejects.toThrow()
+  expect(readFileSync(join(root, 'app', 'package.json'), 'utf8')).toBe(appPkg)
+})

package/test/env-pull-guard.test.ts

@@ -0,0 +1,290 @@
+// `bod env pull` must NEVER silently destroy a hand-maintained .env — a dotenv holds
+// local credentials that exist nowhere else on the server. Verified at the REAL CLI
+// surface (full citty parse, real fs writes in a scratch cwd) against a mock agent.
+import { test, expect, beforeAll, afterAll, beforeEach } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync, statSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+const CLI = join(import.meta.dir, '..', 'src', 'cli.ts')
+const APP_ID = 'e1dba964-b944-4dd0-b971-fe72ee493bf6'
+const APP_NAME = 'blank'
+
+// What the server would hand back for `bod env pull blank`.
+const REMOTE: Record<string, string> = {
+  BOD_AI_URL: 'https://ai.bod.ee',
+  BLANK_WALLET_MODE: 'platform',
+  SHARED_KEY: 'server-value',
+}
+
+let server: ReturnType<typeof Bun.serve>
+let home: string
+let cwd: string
+
+beforeAll(() => {
+  server = Bun.serve({
+    port: 0,
+    fetch(req) {
+      const url = new URL(req.url)
+      if (url.pathname === '/api/apps') return Response.json([{ id: APP_ID, name: APP_NAME }])
+      if (url.pathname === `/api/apps/${APP_ID}/env`) return Response.json({ values: REMOTE })
+      return new Response('not found', { status: 404 })
+    },
+  })
+  home = mkdtempSync(join(tmpdir(), 'bod-pull-home-'))
+  mkdirSync(join(home, '.bod'), { recursive: true })
+  writeFileSync(join(home, '.bod', 'config.json'), JSON.stringify({
+    defaultInstance: 'test',
+    instances: { test: { url: `http://localhost:${server.port}`, apiKey: 'test-key' } },
+  }))
+})
+
+afterAll(() => {
+  server?.stop(true)
+  rmSync(home, { recursive: true, force: true })
+})
+
+beforeEach(() => {
+  cwd = mkdtempSync(join(tmpdir(), 'bod-pull-cwd-'))
+})
+
+async function runCli(args: string[]) {
+  const proc = Bun.spawn(['bun', CLI, ...args], {
+    cwd,
+    env: { ...process.env, HOME: home, BOD_INSTANCE: '', FORCE_COLOR: '0' },
+    stdout: 'pipe', stderr: 'pipe',
+  })
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+  return { stdout, stderr, code }
+}
+
+const envPath = () => join(cwd, '.env')
+const backups = () => readdirSync(cwd).filter(f => f.startsWith('.env.backup-'))
+
+/** A hand-maintained file: a comment, a local-only key, and a key the server also has
+ *  but with a DIFFERENT (local) value. Exactly the shape that got destroyed. */
+const LOCAL = '# my notes\nLOCAL_ONLY_SECRET=irreplaceable\nSHARED_KEY=my-local-value\n'
+
+test('no existing file → writes it, 0600', async () => {
+  const { code, stdout } = await runCli(['env', 'pull', APP_NAME])
+  expect(code).toBe(0)
+  expect(stdout).toContain('Wrote 3 var(s)')
+  expect(readFileSync(envPath(), 'utf8')).toBe('BOD_AI_URL=https://ai.bod.ee\nBLANK_WALLET_MODE=platform\nSHARED_KEY=server-value\n')
+  expect(statSync(envPath()).mode & 0o777).toBe(0o600)
+})
+
+test('existing file → REFUSES, leaves the file byte-identical, names the next step', async () => {
+  writeFileSync(envPath(), LOCAL)
+  const { code, stderr } = await runCli(['env', 'pull', APP_NAME])
+  expect(code).toBe(1)
+  // The whole point: the user's bytes are untouched.
+  expect(readFileSync(envPath(), 'utf8')).toBe(LOCAL)
+  expect(backups()).toEqual([])
+  expect(stderr).toContain('Refusing to overwrite')
+  expect(stderr).toContain('.env')
+  // It must say WHAT would change, by key.
+  expect(stderr).toContain('BOD_AI_URL')          // added
+  expect(stderr).toContain('SHARED_KEY')          // changed
+  expect(stderr).toContain('LOCAL_ONLY_SECRET')   // would be removed
+  // ...and never leak the local secret's value while refusing.
+  expect(stderr).not.toContain('irreplaceable')
+  expect(stderr).toContain('--merge')
+  expect(stderr).toContain('--force')
+})
+
+test('--merge → appends only missing keys, keeps local lines and local values, backs up', async () => {
+  writeFileSync(envPath(), LOCAL)
+  const { code, stdout } = await runCli(['env', 'pull', APP_NAME, '--merge'])
+  expect(code).toBe(0)
+  const after = readFileSync(envPath(), 'utf8')
+  // Original content preserved verbatim as a prefix — comment, local-only key, local value.
+  expect(after.startsWith(LOCAL)).toBe(true)
+  expect(after).toContain('BOD_AI_URL=https://ai.bod.ee')
+  expect(after).toContain('BLANK_WALLET_MODE=platform')
+  // The server's value for a key I already have must NOT be applied.
+  expect(after).not.toContain('SHARED_KEY=server-value')
+  expect(stdout).toContain('Added 2 var(s)')
+  expect(stdout).toContain('Kept your local value')
+  // A backup of the pre-merge file exists and holds the original.
+  expect(backups()).toHaveLength(1)
+  expect(readFileSync(join(cwd, backups()[0]), 'utf8')).toBe(LOCAL)
+})
+
+test('--merge on a file with no trailing newline does not glue keys together', async () => {
+  writeFileSync(envPath(), 'LOCAL_ONLY_SECRET=x')
+  const { code } = await runCli(['env', 'pull', APP_NAME, '--merge'])
+  expect(code).toBe(0)
+  const after = readFileSync(envPath(), 'utf8')
+  expect(after).toContain('LOCAL_ONLY_SECRET=x\nBOD_AI_URL=')
+})
+
+test('--force → replaces, but the original survives in a backup', async () => {
+  writeFileSync(envPath(), LOCAL)
+  const { code, stdout } = await runCli(['env', 'pull', APP_NAME, '--force'])
+  expect(code).toBe(0)
+  expect(readFileSync(envPath(), 'utf8')).toBe('BOD_AI_URL=https://ai.bod.ee\nBLANK_WALLET_MODE=platform\nSHARED_KEY=server-value\n')
+  expect(stdout).toContain('Dropped 1 local-only key(s): LOCAL_ONLY_SECRET')
+  expect(backups()).toHaveLength(1)
+  expect(readFileSync(join(cwd, backups()[0]), 'utf8')).toBe(LOCAL)
+  // The backup carries the same secrets — it must not be world-readable.
+  expect(statSync(join(cwd, backups()[0])).mode & 0o777).toBe(0o600)
+})
+
+test('--stdout → prints to stdout and writes nothing', async () => {
+  writeFileSync(envPath(), LOCAL)
+  const { code, stdout, stderr } = await runCli(['env', 'pull', APP_NAME, '--stdout'])
+  expect(stderr).toBe('')
+  expect(code).toBe(0)
+  expect(stdout).toContain('BOD_AI_URL=https://ai.bod.ee')
+  expect(readFileSync(envPath(), 'utf8')).toBe(LOCAL)
+  expect(readdirSync(cwd)).toEqual(['.env'])
+})
+
+test('file already up to date → no write, no backup, exit 0', async () => {
+  const identical = 'BOD_AI_URL=https://ai.bod.ee\nBLANK_WALLET_MODE=platform\nSHARED_KEY=server-value\n'
+  writeFileSync(envPath(), identical)
+  const { code, stdout } = await runCli(['env', 'pull', APP_NAME])
+  expect(code).toBe(0)
+  expect(stdout).toContain('nothing to do')
+  expect(readFileSync(envPath(), 'utf8')).toBe(identical)
+  expect(backups()).toEqual([])
+})
+
+test('--merge --force → rejected as mutually exclusive, file untouched', async () => {
+  writeFileSync(envPath(), LOCAL)
+  const { code, stderr } = await runCli(['env', 'pull', APP_NAME, '--merge', '--force'])
+  expect(code).toBe(1)
+  expect(stderr).toContain('mutually exclusive')
+  expect(readFileSync(envPath(), 'utf8')).toBe(LOCAL)
+})
+
+test('-o <other file> is guarded too, not just .env', async () => {
+  writeFileSync(join(cwd, 'prod.env'), LOCAL)
+  const { code, stderr } = await runCli(['env', 'pull', APP_NAME, '-o', 'prod.env'])
+  expect(code).toBe(1)
+  expect(stderr).toContain('prod.env')
+  expect(readFileSync(join(cwd, 'prod.env'), 'utf8')).toBe(LOCAL)
+})
+
+
+// ── The destination argument must actually be honoured. Regression: `bod env pull
+// <app> <path> --force` ignored <path>, printed "Wrote 22 var(s) to .env" and dumped
+// 22 real secrets into the CURRENT directory of an unrelated repo.
+const BODY = 'BOD_AI_URL=https://ai.bod.ee\nBLANK_WALLET_MODE=platform\nSHARED_KEY=server-value\n'
+
+test('explicit path positional → writes THERE, 0600, creates nothing in cwd', async () => {
+  const dest = join(cwd, 'sub', 'dir', 'feedox.vars')
+  const { code, stdout } = await runCli(['env', 'pull', APP_NAME, dest])
+  expect(code).toBe(0)
+  expect(readFileSync(dest, 'utf8')).toBe(BODY)
+  expect(statSync(dest).mode & 0o777).toBe(0o600)
+  // Parent dirs created, and the only thing in cwd is the tree we asked for.
+  expect(readdirSync(cwd)).toEqual(['sub'])
+  expect(existsSync(envPath())).toBe(false)
+  // ...and the line names the real path it wrote.
+  expect(stdout).toContain(`Wrote 3 var(s) to ${dest}`)
+})
+
+test('--force applies to the RESOLVED destination, never to cwd .env', async () => {
+  const dest = join(cwd, 'other.vars')
+  writeFileSync(dest, LOCAL)
+  const { code, stdout } = await runCli(['env', 'pull', APP_NAME, dest, '--force'])
+  expect(code).toBe(0)
+  expect(readFileSync(dest, 'utf8')).toBe(BODY)
+  expect(existsSync(envPath())).toBe(false)
+  expect(stdout).toContain(dest)
+  // The clobbered file is recoverable, next to the destination — not in cwd by luck.
+  const bak = readdirSync(cwd).filter(f => f.startsWith('other.vars.backup-'))
+  expect(bak).toHaveLength(1)
+  expect(readFileSync(join(cwd, bak[0]), 'utf8')).toBe(LOCAL)
+})
+
+test('--merge applies to the RESOLVED destination', async () => {
+  const dest = join(cwd, 'other.vars')
+  writeFileSync(dest, LOCAL)
+  const { code } = await runCli(['env', 'pull', APP_NAME, dest, '--merge'])
+  expect(code).toBe(0)
+  expect(readFileSync(dest, 'utf8').startsWith(LOCAL)).toBe(true)
+  expect(existsSync(envPath())).toBe(false)
+})
+
+test('the refusal guard applies to an explicit path destination', async () => {
+  const dest = join(cwd, 'other.vars')
+  writeFileSync(dest, LOCAL)
+  const { code, stderr } = await runCli(['env', 'pull', APP_NAME, dest])
+  expect(code).toBe(1)
+  expect(readFileSync(dest, 'utf8')).toBe(LOCAL)
+  expect(stderr).toContain(dest)
+  expect(existsSync(envPath())).toBe(false)
+})
+
+test('a LONE path positional is a destination, with the app from bodify.yaml', async () => {
+  writeFileSync(join(cwd, 'bodify.yaml'), `name: ${APP_NAME}\n`)
+  const dest = join(cwd, 'nested', 'out.vars')
+  const { code, stdout } = await runCli(['env', 'pull', dest])
+  expect(code).toBe(0)
+  expect(stdout).toContain('from bodify.yaml')
+  expect(readFileSync(dest, 'utf8')).toBe(BODY)
+  expect(existsSync(envPath())).toBe(false)
+})
+
+test('a LONE app positional is still an app, not a path', async () => {
+  const { code } = await runCli(['env', 'pull', APP_NAME])
+  expect(code).toBe(0)
+  expect(readFileSync(envPath(), 'utf8')).toBe(BODY)
+})
+
+test('no positional at all → app from bodify.yaml, default .env in cwd', async () => {
+  writeFileSync(join(cwd, 'bodify.yaml'), `name: ${APP_NAME}\n`)
+  const { code } = await runCli(['env', 'pull'])
+  expect(code).toBe(0)
+  expect(readFileSync(envPath(), 'utf8')).toBe(BODY)
+})
+
+test('-o wins over a destination positional', async () => {
+  const { code } = await runCli(['env', 'pull', APP_NAME, join(cwd, 'ignored.vars'), '-o', 'chosen.vars'])
+  expect(code).toBe(0)
+  expect(readFileSync(join(cwd, 'chosen.vars'), 'utf8')).toBe(BODY)
+  expect(existsSync(join(cwd, 'ignored.vars'))).toBe(false)
+})
+
+// ── Fixes found while reviewing the destination change itself.
+
+test('a lone `name.ext` is an APP, never a file in cwd — an app may be called my.app', async () => {
+  writeFileSync(join(cwd, 'bodify.yaml'), `name: ${APP_NAME}\n`)
+  const { code, stderr } = await runCli(['env', 'pull', 'my.app'])
+  // Loud refusal, not a silent write of the bodify.yaml app's secrets into ./my.app.
+  expect(code).toBe(1)
+  expect(stderr).toContain('App not found: my.app')
+  expect(readdirSync(cwd)).toEqual(['bodify.yaml'])
+})
+
+test('an unexpanded ~ destination goes HOME, never to a literal ~ dir in cwd', async () => {
+  const { code, stdout } = await runCli(['env', 'pull', APP_NAME, '~/pull-probe/out.vars'])
+  expect(code).toBe(0)
+  expect(existsSync(join(cwd, '~'))).toBe(false)
+  const dest = join(home, 'pull-probe', 'out.vars')
+  expect(readFileSync(dest, 'utf8')).toBe(BODY)
+  expect(stdout).toContain(dest)
+  rmSync(join(home, 'pull-probe'), { recursive: true, force: true })
+})
+
+test('--force onto an existing 0644 file leaves it 0600, not world-readable', async () => {
+  const dest = join(cwd, 'wide.vars')
+  writeFileSync(dest, 'OLD=1\n', { mode: 0o644 })
+  const { code } = await runCli(['env', 'pull', APP_NAME, dest, '--force'])
+  expect(code).toBe(0)
+  expect(statSync(dest).mode & 0o777).toBe(0o600)
+})
+
+test('--merge into an existing 0644 file narrows it to 0600', async () => {
+  const dest = join(cwd, 'wide2.vars')
+  writeFileSync(dest, 'OLD=1\n', { mode: 0o644 })
+  const { code } = await runCli(['env', 'pull', APP_NAME, dest, '--merge'])
+  expect(code).toBe(0)
+  expect(statSync(dest).mode & 0o777).toBe(0o600)
+})

package/test/host-no-preview.test.ts

@@ -0,0 +1,75 @@
+// `bod host --no-preview` must actually opt out. citty/mri folds `--no-preview` into
+// `preview: false`, so the literal 'no-preview' arg never saw it and the flag was inert:
+// a single mp4 still got an index.html + poster.jpg. Verified at the CLI surface against
+// a mock publish API — the assertion is the file COUNT in the real manifest.
+import { test, expect, beforeAll, afterAll } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+const CLI = join(import.meta.dir, '..', 'src', 'cli.ts')
+let server: ReturnType<typeof Bun.serve>
+let home: string
+let media: string
+let manifests: string[][] = []
+
+beforeAll(() => {
+  server = Bun.serve({
+    port: 0,
+    async fetch(req) {
+      const url = new URL(req.url)
+      if (url.pathname === '/api/v1/publish') {
+        const body = await req.json() as { files: Array<{ path: string }> }
+        manifests.push(body.files.map(f => f.path))
+        return Response.json({
+          slug: 'abc', siteUrl: `http://localhost:${server.port}/s/abc`,
+          upload: { uploads: [], finalizeUrl: '/api/v1/publish/abc/finalize' },
+        })
+      }
+      if (url.pathname.endsWith('/finalize')) return Response.json({ ok: true })
+      return new Response('not found', { status: 404 })
+    },
+  })
+  home = mkdtempSync(join(tmpdir(), 'bod-host-home-'))
+  mkdirSync(join(home, '.bod'), { recursive: true })
+  writeFileSync(join(home, '.bod', 'config.json'), JSON.stringify({
+    defaultInstance: 'test',
+    instances: { test: { url: `http://localhost:${server.port}`, apiKey: 'test-key' } },
+  }))
+  media = mkdtempSync(join(tmpdir(), 'bod-host-media-'))
+  // Not a decodable video; ffmpeg fails, the page is still synthesized (title-only).
+  writeFileSync(join(media, 'clip.mp4'), 'not-a-real-mp4')
+})
+
+afterAll(() => {
+  server?.stop(true)
+  rmSync(home, { recursive: true, force: true })
+  rmSync(media, { recursive: true, force: true })
+})
+
+async function runCli(args: string[]) {
+  const proc = Bun.spawn(['bun', CLI, ...args], {
+    cwd: media,
+    env: { ...process.env, HOME: home, BOD_INSTANCE: '', FORCE_COLOR: '0' },
+    stdout: 'pipe', stderr: 'pipe',
+  })
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited,
+  ])
+  return { stdout, stderr, code }
+}
+
+test('a single video publishes with the synthesized OG page', async () => {
+  manifests = []
+  const { code } = await runCli(['host', join(media, 'clip.mp4')])
+  expect(code).toBe(0)
+  expect(manifests[0]).toContain('index.html')
+})
+
+test('--no-preview publishes the media file ALONE', async () => {
+  manifests = []
+  const { code, stdout } = await runCli(['host', join(media, 'clip.mp4'), '--no-preview'])
+  expect(code).toBe(0)
+  expect(manifests[0]).toEqual(['clip.mp4'])
+  expect(stdout).not.toContain('previews in WhatsApp')
+})