bod-cli 0.10.6 → 0.10.7

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.7",
   "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,11 @@
 import { defineCommand } from 'citty'
 import chalk from 'chalk'
-import { writeFileSync } from 'fs'
+import { writeFileSync, appendFileSync, readFileSync, existsSync } from 'fs'
 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 +114,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: {
@@ -289,13 +308,21 @@ const rmCmd = defineCommand({
 })
 
 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 },
     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))
@@ -303,11 +330,66 @@ const pullCmd = defineCommand({
     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}`))
+
+    const body = renderDotEnv(values)
+
+    // The always-safe escape hatch: look, don't touch.
+    if (args.stdout) {
+      process.stdout.write(body)
+      return
+    }
+
+    if (!existsSync(out)) {
+      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}`)
+      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 })
+      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/init/init.ts

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

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,171 @@
+// `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)
+})