bod-cli 0.10.7 → 0.10.9

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

@@ -138,13 +138,42 @@ bod host ./assets --app my-api     # persistent app assets
 Manage environment variables.
 
 ```bash
-bod env list my-api
+bod env list my-api                   # values MASKED (key, masked value, length)
+bod env list my-api --reveal          # full plaintext, as KEY=VALUE lines
 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 list <app>` masks values by default.** It is the only scope that resolves
+plaintext secrets, and it used to print them straight to the terminal (and into any
+scrollback, log or pipe). The mask shows a short tail plus a length, enough to answer
+"is this the same key I have locally?" without exposing the value:
+
+- **Under 20 codepoints → nothing is revealed.** A short value is usually low-entropy
+  (`production`, `true`, a PIN, a short enum) and a tail plus the length gives it away
+  outright — `••••••on` / len 10 *is* `production`. Real secrets are long, so this
+  costs the useful case nothing.
+- **20 or more → `floor(len/5)` characters, capped at 4** — the familiar "…last four".
+- An **empty** value renders as a dim `(empty)`, not as dots: `••••••` with `len 0`
+  would be indistinguishable from a masked secret.
+- Everything is counted in **Unicode codepoints**, so an emoji is never sliced in half.
+  Characters that could corrupt the table are stripped from the tail: C0, DEL, C1
+  (U+0080–U+009F — a bare U+009B is a CSI that misaligns every column), U+2028/U+2029,
+  and the bidi controls (U+200E/U+200F, U+202A–U+202E, U+2066–U+2069) — U+202E alone
+  visually reverses the rest of the row.
+
+The `len` column is that same codepoint count, and is deliberately **exact** — masking
+cannot defeat low entropy anyway (the 20-codepoint threshold is what does), and an exact
+length is what makes the listing useful for **comparing** two values (spotting a
+truncated or whitespace-padded paste). It is not a byte count and not a grapheme count, so a decomposed-accent or flag-emoji string reports more than
+it visibly renders. Masking is **not** TTY-conditional: piping does not switch
+plaintext back on. For scripts use `--reveal`
+(byte-identical to the old `KEY=VALUE` output) or `bod env pull … --stdout`.
+`--reveal` is rejected with `--global/--group/--subs`, which only ever receive
+server-side masked values.
+
 **`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

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|pull; scoped by <app>/--global/--group (+ --env); set supports -f .env; pull NEVER clobbers (--merge/--force/--stdout)
+    ├── env.ts          # bod env list|set|unset|pull; scoped by <app>/--global/--group (+ --env); list MASKS values (--reveal for plaintext; never TTY-conditional); 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>

package/package.json

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

package/src/commands/env.ts

@@ -1,6 +1,8 @@
 import { defineCommand } from 'citty'
 import chalk from 'chalk'
-import { writeFileSync, appendFileSync, readFileSync, existsSync } 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'
@@ -132,11 +134,60 @@ function diffEnv(existing: Record<string, string>, incoming: Record<string, stri
   return { added, changed, removed }
 }
 
+/** Characters that must never reach a table cell, in one place.
+ *  C0 + DEL + C1 (U+0080-U+009F: a bare U+009B is a CSI, which makes cli-table3
+ *  miscount the cell width and misalign every column after it), the Unicode line and
+ *  paragraph separators U+2028/U+2029, and the bidi controls (U+200E/U+200F,
+ *  U+202A-U+202E, U+2066-U+2069) — U+202E alone visually REVERSES the rest of the row,
+ *  which is how a value lies about which key it belongs to. */
+const UNSAFE_CELL_CHARS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u200e\u200f\u202a-\u202e\u2066-\u2069]/g
+
+/** Shown instead of dots for a value that is the empty string: `••••••` with `len 0`
+ *  is indistinguishable from a masked secret at a glance, and "this var is set to
+ *  nothing" is a different, actionable fact. */
+export const EMPTY_MARKER = '(empty)'
+
+/** Mask a resolved value for on-screen display.
+ *
+ *  The tail is what makes a mask USEFUL — it is how you answer "is the deployed key
+ *  the same one I have locally?" without printing the secret. But a tail only stays
+ *  safe when the value is long enough that a few characters cannot reconstruct it:
+ *    len < 20  → 0 revealed. Anything shorter is likely low-entropy (`production`,
+ *                `true`, a PIN, a short enum) and a tail plus the length column
+ *                de-anonymises it outright — `••••••on` / len 10 IS `production`.
+ *                Real secrets are long, so this costs the useful case nothing.
+ *    len >= 20 → floor(len/5), capped at 4 — the familiar "…last four" affordance.
+ *  Everything is measured in CODEPOINTS, not UTF-16 code units, so an odd budget
+ *  cannot slice an astral character (emoji, some CJK) in half and emit a lone
+ *  surrogate. The `len` column reports the same unit.
+ *  UNSAFE_CELL_CHARS are dropped from the tail so a value cannot break, reverse or
+ *  misalign the table it is printed in.
+ *
+ *  NOTE on `len`: it is deliberately still exact. Masking cannot defeat low entropy
+ *  anyway — the length threshold above is the defence — and an exact length is what
+ *  makes the listing useful for spotting a truncated or whitespace-padded paste. It
+ *  counts codepoints of the resolved value: NOT a byte count and NOT a grapheme count
+ *  (a combining-accent/NFD or flag-emoji string reports more than it renders).
+ *  Compare it between two values; don't read it as "characters as a human counts". */
+export function maskValue(value: string): string {
+  if (value === '') return EMPTY_MARKER
+  const chars = [...value]
+  const reveal = chars.length < 20 ? 0 : Math.min(4, Math.floor(chars.length / 5))
+  const tail = reveal ? chars.slice(-reveal).join('').replace(UNSAFE_CELL_CHARS, '') : ''
+  return '••••••' + tail
+}
+
+/** Codepoint length — the unit the `len` column reports, matching maskValue's budget. */
+export function displayLength(value: string): number {
+  return [...value].length
+}
+
 const listCmd = defineCommand({
-  meta: { name: 'list', description: 'List env vars. Per-app: resolved KEY=VALUE. --global/--group/--subs: variables in that scope (masked).' },
+  meta: { name: 'list', description: 'List env vars (values MASKED by default; --reveal prints them in full). --global/--group/--subs: variables in that scope.' },
   args: {
     app: { type: 'positional', description: 'App name (or reads from bodify.yaml)', required: false },
     env: { type: 'string', alias: 'e', description: 'Environment (e.g. prod)' },
+    reveal: { type: 'boolean', description: 'Print full plaintext values (per-app scope) as KEY=VALUE' },
     global: { type: 'boolean', alias: 'g', description: 'List all variables across scopes (masked)' },
     group: { type: 'string', description: 'List masked entries scoped to a group; excludes <app>/--global' },
     subs: { type: 'boolean', description: 'List masked platform-GLOBAL subs provider secrets (__subs__~~global; money creds kept out of app envs)' },
@@ -148,6 +199,12 @@ const listCmd = defineCommand({
 
     const subs: SubsFlags = { subs: !!args.subs, subsApp: args['subs-app'] }
     assertScopeFlags(args.app, !!args.global, args.group, subs, args.env)
+    // The other scopes only ever receive server-side `masked` strings — there is no
+    // plaintext to reveal there. Say so instead of silently ignoring the flag.
+    if (args.reveal && (args.global || args.group || isSubsMode(subs))) {
+      console.error(chalk.red('--reveal only applies to the per-app scope; --global/--group/--subs return masked values from the server.'))
+      process.exit(1)
+    }
 
     if (isSubsMode(subs)) {
       const scopeApp = await buildSubsScopeApp(client, subs)
@@ -184,7 +241,7 @@ const listCmd = defineCommand({
       return
     }
 
-    // Per-app: show fully resolved values for the chosen environment.
+    // Per-app: the only scope that can resolve PLAINTEXT secrets. Mask unless asked.
     const appId = await resolveAppId(client, resolveAppName(args.app))
     const qs = args.env ? `?environment=${encodeURIComponent(args.env)}` : ''
     const res = await client.get<ResolvedEnv>(`/apps/${appId}/env${qs}`)
@@ -193,7 +250,26 @@ const listCmd = defineCommand({
       console.log(chalk.dim('No environment variables set.'))
       return
     }
-    for (const [k, v] of Object.entries(values)) console.log(`${k}=${v}`)
+
+    // Machine output: DELIBERATELY not TTY-conditional. Piping into a file or a log
+    // is exactly the case where leaking plaintext hurts most, so a pipe must not
+    // silently switch the output back to secrets — and a script must see what the
+    // human saw. Scripting keeps two explicit, unchanged paths: `--reveal` (emits the
+    // pre-masking KEY=VALUE format byte-for-byte) and `bod env pull --stdout`.
+    if (args.reveal) {
+      for (const [k, v] of Object.entries(values)) console.log(`${k}=${v}`)
+      return
+    }
+
+    printTable(
+      Object.entries(values).map(([key, v]) => {
+        const cell = maskValue(v)
+        return { key, value: cell === EMPTY_MARKER ? chalk.dim(cell) : cell, len: displayLength(v) }
+      }),
+      ['key', 'value', 'len'],
+    )
+    // Hint on stderr so stdout stays a clean, parseable table.
+    console.error(chalk.dim('  values masked — `bod env list … --reveal` to print them, or `bod env pull … --stdout`'))
   },
 })
 
@@ -307,10 +383,32 @@ 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). 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' },
@@ -325,11 +423,15 @@ const pullCmd = defineCommand({
 
     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'
+    // 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)
 
@@ -340,6 +442,7 @@ const pullCmd = defineCommand({
     }
 
     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
@@ -363,6 +466,7 @@ const pullCmd = defineCommand({
       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}`))
@@ -372,6 +476,9 @@ const pullCmd = defineCommand({
     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}`))

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/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/test/env-list-mask.test.ts

@@ -0,0 +1,214 @@
+// `bod env list <app>` is the ONLY scope that can resolve plaintext secrets. It must
+// mask them by default — including when piped — and reveal only on explicit request.
+// Verified at the REAL CLI surface (full citty parse) against a mock agent.
+import { test, expect, beforeAll, afterAll } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { maskValue, displayLength } from '../src/commands/env'
+
+const CLI = join(import.meta.dir, '..', 'src', 'cli.ts')
+const APP_ID = 'e1dba964-b944-4dd0-b971-fe72ee493bf6'
+const APP_NAME = 'blank'
+
+const REMOTE: Record<string, string> = {
+  STRIPE_KEY: 'sk_live_51NxAbCdEfGhIjKlMnOpQrStU',   // 33 cp -> 4 revealed
+  BOUND_19: 'abcdefghijklmnopqrs',            // 19 cp -> 0 revealed (last length hidden)
+  BOUND_20: 'abcdefghijklmnopqrst',           // 20 cp -> 4 revealed (first length shown)
+  LOW_ENTROPY: 'production',                  // 10 cp -> 0: the tail used to give it away
+  SHORT_PIN: '4821',
+  EMOJI_VAL: '\u{1F600}'.repeat(20),            // astral: budget must not split a pair
+  EMPTY_VAL: '',
+  // One fixture per control-char class, each 20 codepoints so a tail IS budgeted and
+  // the strip is actually exercised. Tail = the last 4 codepoints in every case.
+  C0_VAL: 'abcdefghijklmnop\r\n\tx',           // C0 + DEL family
+  DEL_VAL: 'abcdefghijklmnop\u007f\u007f\u007fx',
+  C1_VAL: 'abcdefghijklmnop\u009b\u0085\u0080x',     // U+009B = CSI (breaks table width), U+0085 = NEL
+  SEP_VAL: 'abcdefghijklmnop\u2028\u2029\u2028x',    // line / paragraph separators
+  BIDI_VAL: 'abcdefghijklmnop\u202e\u200f\u2066x', // RTL override + mark + isolate
+}
+
+// What the server returns for --global: it masks server-side, so `masked` is the
+// authoritative display string and the CLI must pass it through untouched.
+const GLOBAL_VARS = [
+  { key: 'SHARED_DB_URL', entries: [{ scope: {}, masked: 'post***rres', updatedAt: 0 }] },
+  { key: 'TEAM_TOKEN', entries: [{ scope: { group: 'infra' }, masked: 'ghp_***', updatedAt: 0 }] },
+]
+
+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 })
+      if (url.pathname === '/api/secrets/vars') return Response.json(GLOBAL_VARS)
+      return new Response('not found', { status: 404 })
+    },
+  })
+  home = mkdtempSync(join(tmpdir(), 'bod-list-home-'))
+  cwd = mkdtempSync(join(tmpdir(), 'bod-list-cwd-'))
+  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 })
+  rmSync(cwd, { recursive: true, force: true })
+})
+
+/** The `value` cell of one row of the masked table, for assertions that must not be
+ *  confused by the `len` column or another row. */
+function valueCell(stdout: string, key: string): string {
+  const row = stdout.split('\n').find(l => new RegExp(`\\|\\s*${key}\\s*\\|`).test(l))
+  if (!row) throw new Error(`no row for ${key} in:\n${stdout}`)
+  return row.split('|')[2]!.trim()
+}
+
+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 }
+}
+
+// NOTE: Bun.spawn gives the CLI a PIPE, not a TTY — so every test here is already the
+// piped case. Masking being non-TTY-conditional is what makes these assertions hold.
+test('masked by default (stdout is a pipe): keys visible, no plaintext secret anywhere', async () => {
+  const { code, stdout } = await runCli(['env', 'list', APP_NAME])
+  expect(code).toBe(0)
+  for (const k of Object.keys(REMOTE)) expect(stdout).toContain(k)
+  for (const v of Object.values(REMOTE)) if (v) expect(stdout).not.toContain(v)
+})
+
+test('reveal boundary: 19 codepoints show nothing, 20 show the last four', async () => {
+  const { stdout } = await runCli(['env', 'list', APP_NAME])
+  const DOTS = '\u2022'.repeat(6)
+  expect(valueCell(stdout, 'BOUND_20')).toBe(DOTS + 'qrst')
+  expect(valueCell(stdout, 'BOUND_19')).toBe(DOTS)
+  // and nothing of the 19-char value leaks by any suffix length
+  for (let i = 1; i <= 19; i++) expect(valueCell(stdout, 'BOUND_19')).not.toContain('abcdefghijklmnopqrs'.slice(-i))
+  expect(valueCell(stdout, 'STRIPE_KEY')).toBe(DOTS + 'rStU')      // 33 cp -> 4
+  // Length is exact and still shown — it is what spots a truncated paste.
+  expect(stdout).toMatch(/BOUND_19\s*\|.*\|\s*19\s*\|/)
+  expect(stdout).toMatch(/BOUND_20\s*\|.*\|\s*20\s*\|/)
+})
+
+test('a low-entropy value at the old boundary is no longer de-anonymised', async () => {
+  const { stdout } = await runCli(['env', 'list', APP_NAME])
+  const DOTS = '\u2022'.repeat(6)
+  // The regression this threshold exists for: `production` is 10 cp and used to render
+  // as ••••••on / len 10, which is the whole value.
+  expect(valueCell(stdout, 'LOW_ENTROPY')).toBe(DOTS)
+  expect(maskValue('production')).toBe(DOTS)
+  expect(maskValue('false')).toBe(DOTS)
+  expect(maskValue('true')).toBe(DOTS)
+})
+
+test('an empty value renders as (empty), not as a mask', async () => {
+  const { stdout } = await runCli(['env', 'list', APP_NAME])
+  expect(valueCell(stdout, 'EMPTY_VAL')).toBe('(empty)')
+  expect(valueCell(stdout, 'EMPTY_VAL')).not.toContain('\u2022')
+  expect(stdout).toMatch(/EMPTY_VAL\s*\|.*\|\s*0\s*\|/)
+  expect(maskValue('')).toBe('(empty)')
+})
+
+test('astral values are sliced by codepoint — no lone surrogate, len counts codepoints', async () => {
+  const { stdout } = await runCli(['env', 'list', APP_NAME])
+  expect(valueCell(stdout, 'EMOJI_VAL')).toBe('\u2022'.repeat(6) + '\u{1F600}'.repeat(4))
+  expect(stdout).not.toContain('\uFFFD')
+  for (const ch of stdout) expect(ch.codePointAt(0)! >= 0xd800 && ch.codePointAt(0)! <= 0xdfff).toBe(false)
+  expect(stdout).toMatch(/EMOJI_VAL\s*\|.*\|\s*20\s*\|/)
+})
+
+// Every class the strip must cover. A leaked one does one of two visible harms: it
+// breaks the row across lines (C0/NEL/LS/PS) or it reflows/miscounts the cell
+// (bidi override, C1 CSI) — so assert BOTH: one line, and not a single such char.
+const CONTROL_CASES: Array<[string, number, string, string[]]> = [
+  ['C0_VAL',   20, 'x', ['\r', '\n', '\t']],
+  ['DEL_VAL',  20, 'x', ['\u007f']],
+  ['C1_VAL',   20, 'x', ['\u009b', '\u0085', '\u0080']],
+  ['SEP_VAL',  20, 'x', ['\u2028', '\u2029']],
+  ['BIDI_VAL', 20, 'x', ['\u202e', '\u200f', '\u2066']],
+]
+
+test('control chars of every class are stripped and the row stays on one line', async () => {
+  const { stdout } = await runCli(['env', 'list', APP_NAME])
+  for (const [key, len, survivor, banned] of CONTROL_CASES) {
+    const cell = valueCell(stdout, key)
+    expect(cell).toBe('\u2022'.repeat(6) + survivor)          // only the safe tail char survives
+    for (const c of banned) expect(cell).not.toContain(c)
+    // ONE line: the key, the value and the len cell all sit on a single table row.
+    const row = stdout.split('\n').find(l => l.includes(key))!
+    for (const c of banned) expect(row).not.toContain(c)
+    expect(row).toMatch(new RegExp(`${key}\\s*\\|[^\\n]*\\|\\s*${len}\\s*\\|`))
+  }
+  // Column alignment is intact: with no stray CSI miscounting a cell, every border
+  // rule is the same width. (This is what a leaked U+009B used to break.)
+  const rules = stdout.split('\n').filter(l => l.startsWith('+')).map(l => l.length)
+  expect(rules.length).toBeGreaterThan(1)
+  expect(new Set(rules).size).toBe(1)
+})
+
+test('--reveal prints full plaintext in the original KEY=VALUE format', async () => {
+  const { code, stdout } = await runCli(['env', 'list', APP_NAME, '--reveal'])
+  expect(code).toBe(0)
+  // Byte-identical to the pre-masking format: one KEY=VALUE line per var, raw values.
+  expect(stdout).toBe(Object.entries(REMOTE).map(([k, v]) => `${k}=${v}`).join('\n') + '\n')
+})
+
+test('the --reveal hint goes to stderr, keeping stdout parseable', async () => {
+  const { stdout, stderr } = await runCli(['env', 'list', APP_NAME])
+  expect(stderr).toContain('--reveal')
+  expect(stdout).not.toContain('--reveal')
+})
+
+test('--reveal is rejected on scopes that only ever hold masked server values', async () => {
+  const { code, stderr } = await runCli(['env', 'list', '--global', '--reveal'])
+  expect(code).toBe(1)
+  expect(stderr).toContain('--reveal only applies to the per-app scope')
+})
+
+test('--global passes the SERVER masked string through — maskValue is per-app only', async () => {
+  const { code, stdout } = await runCli(['env', 'list', '--global'])
+  expect(code).toBe(0)
+  for (const v of GLOBAL_VARS) {
+    expect(stdout).toContain(v.key)
+    expect(stdout).toContain(v.entries[0].masked)   // verbatim, not re-masked
+  }
+  expect(stdout).not.toContain('\u2022')
+  expect(stdout).not.toMatch(/\blen\b/)
+})
+
+test('maskValue budget: nothing below 20 codepoints, then floor(len/5) capped at 4', () => {
+  const DOTS = '\u2022'.repeat(6)
+  expect(maskValue('4821')).toBe(DOTS)
+  expect(maskValue('production')).toBe(DOTS)
+  expect(maskValue('a'.repeat(19))).toBe(DOTS)              // 19 -> still nothing
+  expect(maskValue('abcdefghijklmnopqrst')).toBe(DOTS + 'qrst')  // 20 -> the first tail
+  expect(maskValue('a'.repeat(100))).toBe(DOTS + 'aaaa')
+  expect(maskValue('\u{1F600}'.repeat(20))).toBe(DOTS + '\u{1F600}'.repeat(4))
+  expect(maskValue('\u{1F600}'.repeat(19))).toBe(DOTS)        // 19 codepoints (38 UTF-16 units)
+  // A tail that is ENTIRELY unsafe strips to nothing — reveals less, never more.
+  expect(maskValue('abcdefghijklmnop\u202e\u2028\u009b\r')).toBe(DOTS)
+})
+
+test('displayLength counts codepoints, matching the slicing unit', () => {
+  expect(displayLength('\u{1F600}'.repeat(20))).toBe(20)   // not 40
+  expect(displayLength('abcdefghij\n')).toBe(11)
+})

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

@@ -169,3 +169,122 @@ test('-o <other file> is guarded too, not just .env', async () => {
   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')
+})