docs: re-record the README demos and make re-recording reproducible

CONTRIBUTING.md

@@ -71,6 +71,31 @@ integration suite and the smoke sweep run once per provisioned server.
 
 Requires Docker. See `docker/compose.test.yml` and `scripts/testbed.ts`.
 
+## Re-recording the README demos
+
+`docs/vhs/hero.gif` and `docs/vhs/workflow.gif` are [VHS](https://github.com/charmbracelet/vhs)
+recordings of the real CLI, so they go stale whenever the service list or output
+changes. Regenerating them is one command plus two renders:
+
+```bash
+bun run testbed:up      # optional — includes Jellyfin in the recording
+bun run recording:up    # start Radarr/Sonarr/Lidarr/Prowlarr, write .tsarr.json
+vhs docs/vhs/hero.tape
+vhs docs/vhs/workflow.tape
+bun run recording:down
+```
+
+`recording:up` starts the services, waits for each to generate its API key,
+writes a gitignored `.tsarr.json`, and drops a `.recording-bin/tsarr` shim that
+runs the CLI from source — the tapes put that first on `PATH`, so recordings
+always show current behaviour rather than an installed release.
+
+Readarr is deliberately absent: upstream is archived and publishes no arm64
+image. Bazarr, qBittorrent and Seerr are not included either, so they show as
+"not configured" in the `doctor` demo.
+
+Requires `vhs` (`brew install vhs`) and Docker.
+
 ## Making changes
 
 1. Create a branch from `main`.

docs/vhs/compose.recording.yml

@@ -0,0 +1,41 @@
+# Services used only for re-recording the README demos.
+#
+#   bun run recording:up     # start + configure, write .tsarr.json and .recording-bin
+#   vhs docs/vhs/hero.tape
+#   vhs docs/vhs/workflow.tape
+#   bun run recording:down
+#
+# Readarr is absent: upstream is archived and publishes no arm64 image.
+# Separate from docker/compose.test.yml on purpose: that one is for CI and must
+# stay fast, this one exists so the GIFs can be regenerated without hand setup.
+
+name: tsarr-recording
+
+x-arr: &arr
+  environment:
+    - PUID=1000
+    - PGID=1000
+    - TZ=Etc/UTC
+  restart: 'no'
+
+services:
+  radarr:
+    <<: *arr
+    image: lscr.io/linuxserver/radarr:latest
+    container_name: tsarr-rec-radarr
+    ports: ['127.0.0.1:17878:7878']
+  sonarr:
+    <<: *arr
+    image: lscr.io/linuxserver/sonarr:latest
+    container_name: tsarr-rec-sonarr
+    ports: ['127.0.0.1:18989:8989']
+  lidarr:
+    <<: *arr
+    image: lscr.io/linuxserver/lidarr:latest
+    container_name: tsarr-rec-lidarr
+    ports: ['127.0.0.1:18686:8686']
+  prowlarr:
+    <<: *arr
+    image: lscr.io/linuxserver/prowlarr:latest
+    container_name: tsarr-rec-prowlarr
+    ports: ['127.0.0.1:19696:9696']

package.json

@@ -139,6 +139,8 @@
     "testbed:down": "bun run scripts/testbed.ts down",
     "testbed:env": "bun run scripts/testbed.ts env",
     "testbed:smoke": "bun run scripts/jellyfin-smoke.ts",
+    "recording:up": "bun run scripts/recording.ts up",
+    "recording:down": "bun run scripts/recording.ts down",
     "dev": "bun run src/index.ts",
     "cli": "bun run src/cli/index.ts",
     "lint": "biome check .",

scripts/recording.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env bun
+/**
+ * Environment for re-recording the README demos.
+ *
+ *   bun run recording:up     start the services, wait for them, write config
+ *   vhs docs/vhs/hero.tape
+ *   vhs docs/vhs/workflow.tape
+ *   bun run recording:down   stop everything and remove the local config
+ *
+ * The GIFs went stale once because re-recording meant hand-configuring a stack.
+ * This makes it one command.
+ *
+ * Writes `.tsarr.json` and `.recording-bin/tsarr` — both gitignored. The tapes
+ * put `.recording-bin` first on PATH so `tsarr` runs from source.
+ */
+
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+
+const COMPOSE_FILE = './docs/vhs/compose.recording.yml';
+const CONFIG_FILE = './.tsarr.json';
+const BIN_DIR = './.recording-bin';
+
+interface Service {
+  name: string;
+  container: string;
+  baseUrl: string;
+}
+
+const SERVICES: Service[] = [
+  { name: 'radarr', container: 'tsarr-rec-radarr', baseUrl: 'http://localhost:17878' },
+  { name: 'sonarr', container: 'tsarr-rec-sonarr', baseUrl: 'http://localhost:18989' },
+  { name: 'lidarr', container: 'tsarr-rec-lidarr', baseUrl: 'http://localhost:18686' },
+  { name: 'prowlarr', container: 'tsarr-rec-prowlarr', baseUrl: 'http://localhost:19696' },
+];
+
+const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+function run(cmd: string[]) {
+  const proc = Bun.spawnSync(cmd, { stdout: 'inherit', stderr: 'pipe' });
+  if (proc.exitCode !== 0) {
+    throw new Error(
+      `Command failed: ${cmd.join(' ')}\n${proc.stderr ? new TextDecoder().decode(proc.stderr) : ''}`
+    );
+  }
+}
+
+function capture(cmd: string[]): string {
+  const proc = Bun.spawnSync(cmd, { stdout: 'pipe', stderr: 'pipe' });
+  return proc.stdout ? new TextDecoder().decode(proc.stdout) : '';
+}
+
+/** The arr apps write their generated key into config.xml on first start. */
+async function waitForApiKey(service: Service, timeoutMs = 240_000): Promise<string> {
+  const start = Date.now();
+  process.stdout.write(`⏳ ${service.name}`);
+  while (Date.now() - start < timeoutMs) {
+    const xml = capture(['docker', 'exec', service.container, 'cat', '/config/config.xml']);
+    const key = xml.match(/<ApiKey>([^<]+)<\/ApiKey>/)?.[1];
+    if (key) {
+      // The key exists before the HTTP API is listening; wait for both.
+      try {
+        const response = await fetch(`${service.baseUrl}/api/v3/system/status`, {
+          headers: { 'X-Api-Key': key },
+          signal: AbortSignal.timeout(5000),
+        });
+        if (response.ok || response.status === 404) {
+          console.log(`\n✅ ${service.name} ready at ${service.baseUrl}`);
+          return key;
+        }
+      } catch {
+        // not listening yet
+      }
+    }
+    process.stdout.write('.');
+    await sleep(3000);
+  }
+  throw new Error(`${service.name} did not become ready within ${timeoutMs}ms`);
+}
+
+function writeShim() {
+  mkdirSync(BIN_DIR, { recursive: true });
+  const shim = `${BIN_DIR}/tsarr`;
+  writeFileSync(
+    shim,
+    `#!/bin/sh\n# Runs the CLI from source so recordings show current behaviour.\nexec bun run "${process.cwd()}/src/cli/index.ts" "$@"\n`
+  );
+  chmodSync(shim, 0o755);
+  console.log(`🔧 Wrote ${shim}`);
+}
+
+async function up() {
+  console.log('🐳 Starting recording services...');
+  run(['docker', 'compose', '-f', COMPOSE_FILE, 'up', '-d']);
+
+  const services: Record<string, unknown> = {};
+  for (const service of SERVICES) {
+    services[service.name] = { baseUrl: service.baseUrl, apiKey: await waitForApiKey(service) };
+  }
+
+  // Reuse the Jellyfin the integration test bed already provisions, if it is up.
+  if (existsSync('./.env.test')) {
+    const env = Object.fromEntries(
+      require('node:fs')
+        .readFileSync('./.env.test', 'utf-8')
+        .split('\n')
+        .filter((l: string) => l.includes('='))
+        .map((l: string) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)])
+    );
+    if (env.JELLYFIN_BASE_URL && env.JELLYFIN_API_KEY) {
+      services.jellyfin = { baseUrl: env.JELLYFIN_BASE_URL, apiKey: env.JELLYFIN_API_KEY };
+      console.log('✅ jellyfin picked up from the integration test bed');
+    }
+  } else {
+    console.log('ℹ️  Run `bun run testbed:up` first to include Jellyfin in the recording.');
+  }
+
+  writeFileSync(CONFIG_FILE, `${JSON.stringify({ services }, null, 2)}\n`);
+  console.log(`📝 Wrote ${CONFIG_FILE}`);
+  writeShim();
+
+  console.log('\n🎬 Ready to record:\n');
+  console.log('   vhs docs/vhs/hero.tape');
+  console.log('   vhs docs/vhs/workflow.tape');
+  console.log('   bun run recording:down');
+}
+
+function down() {
+  console.log('🧹 Stopping recording services...');
+  run(['docker', 'compose', '-f', COMPOSE_FILE, 'down', '-v']);
+  rmSync(CONFIG_FILE, { force: true });
+  rmSync(BIN_DIR, { recursive: true, force: true });
+  console.log('✅ Recording environment removed');
+}
+
+const command = process.argv[2];
+try {
+  if (command === 'up') await up();
+  else if (command === 'down') down();
+  else {
+    console.error('Usage: bun run scripts/recording.ts <up|down>');
+    process.exit(1);
+  }
+} catch (error) {
+  console.error(`\n💥 ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}