biblioplex 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# biblioplex cli
+
+manage your [biblioplex](https://biblioplex.bensonperry.com) magic: the gathering
+collection from the terminal — search, edit, import, and export, all against your
+live cloud collection.
+
+cloud-first: every command reads and writes the same collection the web app uses,
+so the cli and the website stay perfectly in sync.
+
+## install
+
+requires **node 20+**.
+
+```sh
+npm install -g biblioplex      # then run `biblioplex` or `bp`
+# or, no install:
+npx biblioplex login
+```
+
+> the global command is `biblioplex`. it also installs a short `bp` alias; if some
+> other tool already owns `bp` on your machine, just use `biblioplex` (or add your
+> own alias).
+
+## sign in
+
+```sh
+bp login            # read-only (search/export)
+bp login --write    # also allow edits/imports
+```
+
+`bp login` opens your browser once to authorize the cli, then stores a refresh
+token locally so you stay signed in for ~30 days. `bp logout` revokes it.
+
+on a headless box: `bp login --no-browser` prints a url to open elsewhere.
+
+## examples
+
+```sh
+# search with the same query grammar as the web app
+bp search "t:creature c:rg cmc<=3 -t:legendary"
+bp search rare f:foil --sort price --desc --limit 20
+
+# totals and your most valuable cards
+bp summary
+
+# containers
+bp ls decks
+bp show "deck:breya"
+bp deck show breya
+bp deck export breya --preset moxfield > breya.txt
+
+# edits (need `bp login --write`)
+bp add "Sol Ring" --set c21 --cn 263 --qty 2 --location "box:bulk"
+bp edit "Sol Ring" --condition lightly_played
+bp move "Sol Ring" --to "deck:breya"
+bp tag add trade "Sol Ring"
+bp rm "Sol Ring"
+bp undo                      # revert the last cli change
+
+# bulk import / export (cloud stays the source of truth)
+bp import moxfield-export.csv          # auto-detects the format
+bp export "f:foil" --format moxfield > foils.txt
+bp export --archive --output backup.json
+```
+
+ambiguous card names list the matching stacks; narrow with
+`--set/--cn/--finish/--condition/--location`, or apply to all with `--all`.
+
+## scripting / agents
+
+every command accepts `--json` and prints a stable envelope to stdout:
+
+```json
+{ "ok": true, "data": { ... } }
+{ "ok": false, "error": { "message": "..." } }
+```
+
+diagnostics go to stderr, so `--json` stdout is always a single json document.
+exit codes: `0` ok · `1` error · `2` usage · `3` auth (run `bp login`) · `4` rate-limited.
+
+## configuration
+
+- credentials: `~/.config/biblioplex/credentials.json` (mode 600)
+- override the api endpoint: `--api <url>` or `BIBLIOPLEX_API_BASE`
+- override the config dir: `BIBLIOPLEX_CONFIG_DIR`
+
+## notes
+
+- zero runtime dependencies (node built-ins only).
+- card search/sort, csv adapters, and the collection model are shared verbatim
+  with the web app (see `vendor/`), so behavior matches exactly.
+- macOS and linux are supported in this release.

package/bin/biblioplex.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.mjs';
+
+run(process.argv.slice(2))
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    process.stderr.write('fatal: ' + (err?.stack || err?.message || String(err)) + '\n');
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "biblioplex",
+  "version": "0.1.0",
+  "description": "Command-line tool to manage your biblioplex Magic: The Gathering collection.",
+  "type": "module",
+  "bin": {
+    "biblioplex": "bin/biblioplex.mjs",
+    "bp": "bin/biblioplex.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "vendor/",
+    "README.md"
+  ],
+  "scripts": {
+    "sync-vendor": "node scripts/sync-vendor.mjs",
+    "test": "node --test __tests__/*.test.js",
+    "prepublishOnly": "node scripts/sync-vendor.mjs && node --test __tests__/*.test.js"
+  },
+  "keywords": [
+    "mtg",
+    "magic-the-gathering",
+    "collection",
+    "cli",
+    "biblioplex",
+    "scryfall"
+  ],
+  "license": "MIT",
+  "homepage": "https://biblioplex.bensonperry.com",
+  "bugs": {
+    "url": "https://github.com/benson/benson.github.io/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/benson/benson.github.io.git",
+    "directory": "mtgcollection/cli"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,110 @@
+// Authenticated transport to the biblioplex worker.
+//  - reads:  GET /sync/bootstrap (full snapshot)
+//  - writes: POST /sync/push (granular ops built locally from a diff)
+//  - tools:  POST /mcp JSON-RPC (search_card_printings, preview_*/apply, undo)
+// Refreshes the access token proactively (near expiry) and reactively (on 401),
+// persisting rotated tokens. The token is sent only in the Authorization header.
+import { refreshTokens } from './oauth.mjs';
+import { CliError, authError, rateLimitError } from './errors.mjs';
+import { CLIENT_LABEL } from './constants.mjs';
+
+export class Session {
+  constructor({ base, credentials, persist, fetchImpl = fetch }) {
+    this.base = base;
+    this.creds = credentials;
+    this.persist = persist || (() => {});
+    this.fetchImpl = fetchImpl;
+    this._rpcId = 0;
+  }
+
+  get scopes() { return (this.creds?.scope || '').split(/\s+/).filter(Boolean); }
+  hasScope(scope) { return this.scopes.includes(scope); }
+
+  async _refresh() {
+    if (!this.creds?.refreshToken) throw authError('session expired — run `bp login`');
+    this._absorb(await refreshTokens({ base: this.base, refreshToken: this.creds.refreshToken, fetchImpl: this.fetchImpl }));
+  }
+
+  _absorb(tokens) {
+    this.creds = {
+      ...this.creds,
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token || this.creds.refreshToken,
+      accessExpiresAt: Date.now() + (Number(tokens.expires_in) || 3600) * 1000,
+      scope: tokens.scope || this.creds.scope,
+    };
+    this.persist(this.creds);
+  }
+
+  async _authedFetch(path, opts = {}, retried = false) {
+    if (!this.creds?.accessToken) throw authError();
+    if (!retried && this.creds.accessExpiresAt && this.creds.accessExpiresAt - Date.now() < 30000) {
+      await this._refresh();
+    }
+    const headers = { ...(opts.headers || {}), Authorization: 'Bearer ' + this.creds.accessToken };
+    const res = await this.fetchImpl(this.base + path, { ...opts, headers });
+    if (res.status === 401 && !retried) { await this._refresh(); return this._authedFetch(path, opts, true); }
+    if (res.status === 401) throw authError('session expired — run `bp login`');
+    if (res.status === 403) {
+      const body = await res.json().catch(() => ({}));
+      const msg = body.error === 'insufficient_scope'
+        ? 'this session lacks write access — run `bp login --write`'
+        : (body.error || 'forbidden');
+      throw new CliError(msg, 1, body);
+    }
+    if (res.status === 429) throw rateLimitError();
+    return res;
+  }
+
+  async bootstrap() {
+    const res = await this._authedFetch('/sync/bootstrap');
+    if (!res.ok) throw new CliError('could not load collection (' + res.status + ')');
+    return res.json();
+  }
+
+  async push({ ops, baseRevision }) {
+    const res = await this._authedFetch('/sync/push', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ clientId: CLIENT_LABEL, baseRevision, requireBaseRevision: true, ops }),
+    });
+    if (res.status === 409) {
+      const data = await res.json().catch(() => ({}));
+      const err = new CliError('the cloud collection changed since this command started', 1, data);
+      err.conflict = true;
+      throw err;
+    }
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({}));
+      throw new CliError('push failed: ' + (data.error || res.status), 1, data);
+    }
+    return res.json();
+  }
+
+  async mcp(method, params = {}) {
+    const id = ++this._rpcId;
+    const res = await this._authedFetch('/mcp', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+    });
+    if (!res.ok) throw new CliError('mcp request failed (' + res.status + ')');
+    const data = await res.json().catch(() => ({}));
+    if (data.error) {
+      if (data.error.code === -32003 || /insufficient_scope/.test(data.error.message || '')) {
+        throw new CliError('this session lacks write access — run `bp login --write`', 1, data.error);
+      }
+      throw new CliError(data.error.message || 'mcp error', 1, data.error);
+    }
+    return data.result;
+  }
+
+  async callTool(name, args = {}) {
+    const result = await this.mcp('tools/call', { name, arguments: args });
+    if (result?.isError) {
+      const text = (result.content || []).map(c => c.text).filter(Boolean).join(' ');
+      throw new CliError(text || ('tool ' + name + ' failed'), 1, result);
+    }
+    return result?.structuredContent ?? result ?? null;
+  }
+}

package/src/args.mjs

@@ -0,0 +1,77 @@
+// Tiny, dependency-free argv parser.
+//   bp <command> [subcommand] [positionals...] [--flag value] [--flag=value] [--bool]
+// A flag consumes the next token as its value unless the flag is a known boolean
+// or the next token looks like another flag. `--` ends flag parsing.
+
+const BOOLEAN_FLAGS = new Set([
+  'json', 'yes', 'y', 'help', 'h', 'version', 'v',
+  'csv', 'table', 'dry-run', 'no-browser', 'no-color', 'all', 'force', 'verbose',
+  'desc', 'no-resolve', 'archive', 'write',
+]);
+
+const SHORT_ALIASES = { y: 'yes', h: 'help', v: 'version' };
+
+export function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  let i = 0;
+  let noMoreFlags = false;
+
+  while (i < argv.length) {
+    const tok = argv[i];
+    if (noMoreFlags || tok === '-' || !tok.startsWith('-')) {
+      positionals.push(tok);
+      i += 1;
+      continue;
+    }
+    if (tok === '--') { noMoreFlags = true; i += 1; continue; }
+
+    let raw = tok.startsWith('--') ? tok.slice(2) : tok.slice(1);
+    let value;
+    const eq = raw.indexOf('=');
+    if (eq !== -1) { value = raw.slice(eq + 1); raw = raw.slice(0, eq); }
+
+    const name = SHORT_ALIASES[raw] || raw;
+
+    if (value !== undefined) {
+      flags[name] = value;
+      i += 1;
+      continue;
+    }
+    if (BOOLEAN_FLAGS.has(raw) || BOOLEAN_FLAGS.has(name)) {
+      flags[name] = true;
+      i += 1;
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next === undefined || (next.startsWith('-') && next !== '-')) {
+      flags[name] = true;
+      i += 1;
+    } else {
+      flags[name] = next;
+      i += 2;
+    }
+  }
+
+  return { positionals, flags };
+}
+
+// Coerce a flag that may be a string or boolean into a trimmed string or null.
+export function strFlag(flags, ...names) {
+  for (const n of names) {
+    const v = flags[n];
+    if (typeof v === 'string') return v;
+  }
+  return null;
+}
+
+export function boolFlag(flags, ...names) {
+  return names.some(n => flags[n] === true || flags[n] === 'true');
+}
+
+export function intFlag(flags, name, fallback = null) {
+  const v = flags[name];
+  if (v == null || v === true) return fallback;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) ? n : fallback;
+}

package/src/cli.mjs

@@ -0,0 +1,76 @@
+import { parseArgs, boolFlag, strFlag } from './args.mjs';
+import { createOutput } from './output.mjs';
+import { CliError } from './errors.mjs';
+import { EXIT, VERSION, DEFAULT_API_BASE } from './constants.mjs';
+import { loadCredentials, saveCredentials, loadConfig } from './store.mjs';
+import { Session } from './api.mjs';
+import { commands, commandOrder } from './commands/index.mjs';
+
+function resolveApiBase(flags) {
+  const base = strFlag(flags, 'api') || process.env.BIBLIOPLEX_API_BASE || loadConfig().apiBase || DEFAULT_API_BASE;
+  return base.replace(/\/+$/, '');
+}
+
+function printHelp(out) {
+  out.line('biblioplex — manage your magic: the gathering collection from the terminal');
+  out.line('');
+  out.line('usage: bp <command> [options]');
+  out.line('');
+  out.line('commands:');
+  for (const name of commandOrder) {
+    out.line('  ' + name.padEnd(12) + commands[name].summary);
+  }
+  out.line('');
+  out.line('global options:');
+  out.line('  --json        machine-readable output ({ok,data}|{ok,error})');
+  out.line('  --no-color    disable colored output');
+  out.line('  --api <url>   override the API base url');
+  out.line('  --help        show help (also: bp <command> --help)');
+  out.line('  --version     print the version');
+  out.line('');
+  out.line('start with: bp login');
+}
+
+export async function run(argv) {
+  const { positionals, flags } = parseArgs(argv);
+  const out = createOutput({ json: boolFlag(flags, 'json'), color: !boolFlag(flags, 'no-color') });
+  const command = positionals[0];
+
+  if (!command) {
+    if (boolFlag(flags, 'version')) { out.line(VERSION); return EXIT.OK; }
+    printHelp(out);
+    return EXIT.OK;
+  }
+  if (command === 'help') { printHelp(out); return EXIT.OK; }
+  if (boolFlag(flags, 'version')) { out.line(VERSION); return EXIT.OK; }
+
+  const cmd = commands[command];
+  if (!cmd) {
+    out.error(new CliError(`unknown command: ${command} (try \`bp help\`)`, EXIT.USAGE));
+    return EXIT.USAGE;
+  }
+  if (boolFlag(flags, 'help')) {
+    out.line(cmd.help || cmd.summary);
+    return EXIT.OK;
+  }
+
+  const ctx = {
+    out,
+    flags,
+    args: positionals.slice(1),
+    apiBase: resolveApiBase(flags),
+    makeSession() {
+      const creds = loadCredentials();
+      if (!creds?.accessToken) throw new CliError('not logged in — run `bp login`', EXIT.AUTH);
+      return new Session({ base: this.apiBase, credentials: creds, persist: saveCredentials });
+    },
+  };
+
+  try {
+    return (await cmd.run(ctx)) ?? EXIT.OK;
+  } catch (err) {
+    out.error(err);
+    if (boolFlag(flags, 'verbose') && err?.stack && !(err instanceof CliError)) out.info(err.stack);
+    return err instanceof CliError ? err.code : EXIT.ERROR;
+  }
+}

package/src/commands/add.mjs

@@ -0,0 +1,57 @@
+import { resolvePrinting, cardToFields } from '../scryfall.mjs';
+import { normalizeCollectionEntry } from '../../vendor/collection.js';
+import { mergeIntoCollection } from '../../vendor/importMerge.js';
+import { applyMutation } from '../mutate.mjs';
+import { strFlag, intFlag, boolFlag } from '../args.mjs';
+import { requireWrite, parseLocationFlag, ensureContainer, persistUndo, printWrite } from './writeHelpers.mjs';
+import { usageError, CliError } from '../errors.mjs';
+
+export default {
+  summary: 'add a card to your collection',
+  help: [
+    'usage: bp add <name> [--set xxx --cn 123] [--finish foil] [--condition lightly_played]',
+    '                     [--qty 2] [--location "deck:breya"] [--tags trade,wishlist] [--dry-run]',
+    '       bp add --scryfall-id <id> [...]',
+    '',
+    'resolves the printing on scryfall (give --set + --cn to pin an exact printing),',
+    'then adds it to your cloud collection. coalesces with an identical existing stack.',
+  ].join('\n'),
+  async run(ctx) {
+    const { out, flags, args } = ctx;
+    const session = ctx.makeSession();
+    requireWrite(session);
+
+    const scryfallId = strFlag(flags, 'scryfall-id', 'id');
+    const set = strFlag(flags, 'set', 's');
+    const cn = strFlag(flags, 'cn');
+    const name = args.join(' ').trim();
+    if (!scryfallId && !(set && cn) && !name) throw usageError('usage: bp add <name> [--set --cn] | --scryfall-id <id>');
+
+    const finish = strFlag(flags, 'finish') || 'normal';
+    const card = await resolvePrinting({ scryfallId, set, cn, name });
+    if (!card) throw new CliError("couldn't find that printing — try specifying --set and --cn");
+
+    const tags = strFlag(flags, 'tags', 'tag');
+    const entry = normalizeCollectionEntry({
+      ...cardToFields(card, finish),
+      finish,
+      qty: intFlag(flags, 'qty', 1) || 1,
+      condition: strFlag(flags, 'condition', 'cond') || 'near_mint',
+      language: strFlag(flags, 'lang', 'language') || 'en',
+      location: parseLocationFlag(strFlag(flags, 'location', 'loc', 'to')),
+      tags: tags ? tags.split(',').map(s => s.trim()).filter(Boolean) : [],
+    }, { preserveResolvedFields: true });
+
+    const result = await applyMutation(session, (draft) => {
+      ensureContainer(draft, entry.location);
+      draft.app.collection = mergeIntoCollection(draft.app.collection, [entry]);
+      return { added: { name: entry.name, set: entry.setCode.toUpperCase(), cn: entry.cn, finish: entry.finish, qty: entry.qty } };
+    }, { dryRun: boolFlag(flags, 'dry-run') });
+
+    persistUndo(result);
+    printWrite(out, result, () => out.info(
+      out.c.green('✓ added') + ` ${entry.qty}x ${entry.name} (${entry.setCode.toUpperCase()} ${entry.cn}${entry.finish !== 'normal' ? ' ' + entry.finish : ''})`
+      + (entry.location ? ` → ${entry.location.type}:${entry.location.name}` : '')));
+    return 0;
+  },
+};

package/src/commands/container.mjs

@@ -0,0 +1,83 @@
+import { locationKey } from '../../vendor/collection.js';
+import { applyMutation } from '../mutate.mjs';
+import { parseContainerRef } from '../snapshot.mjs';
+import { boolFlag } from '../args.mjs';
+import { requireWrite, parseLocationFlag, ensureContainer, persistUndo, printWrite } from './writeHelpers.mjs';
+import { usageError, CliError } from '../errors.mjs';
+
+function resolveContainer(draft, ref) {
+  const containers = draft.app.containers || {};
+  const loc = parseLocationFlag(ref);
+  if (loc && containers[loc.type + ':' + loc.name]) return { key: loc.type + ':' + loc.name, container: containers[loc.type + ':' + loc.name] };
+  const name = parseContainerRef(ref).name;
+  const matches = Object.entries(containers).filter(([, c]) => c.name === name);
+  if (!matches.length) throw new CliError(`no container "${ref}"`);
+  if (matches.length > 1) throw new CliError(`"${ref}" is ambiguous — use type:name (${matches.map(([k]) => k).join(', ')})`);
+  return { key: matches[0][0], container: matches[0][1] };
+}
+
+export default {
+  summary: 'create / rename / delete a container',
+  help: [
+    'usage: bp container create <type:name>            (type = deck|container)',
+    '       bp container rename <type:name> <new-name>',
+    '       bp container delete <type:name> [--force]   (--force unfiles its cards)',
+    '',
+    'legacy "binder:"/"box:" prefixes are accepted and treated as containers.',
+  ].join('\n'),
+  async run(ctx) {
+    const { out, flags, args } = ctx;
+    const session = ctx.makeSession();
+    requireWrite(session);
+    const [sub, ref, ...rest] = args;
+
+    if (sub === 'create') {
+      const loc = parseLocationFlag(ref);
+      if (!loc) throw usageError('usage: bp container create <type:name>');
+      const result = await applyMutation(session, (draft) => { ensureContainer(draft, loc); return { created: loc.type + ':' + loc.name }; }, { dryRun: boolFlag(flags, 'dry-run') });
+      persistUndo(result);
+      printWrite(out, result, () => out.info(out.c.green('✓ created') + ` ${loc.type}:${loc.name}`));
+      return 0;
+    }
+
+    if (sub === 'rename') {
+      const newName = parseContainerRef(rest.join(' ')).name;
+      if (!ref || !newName) throw usageError('usage: bp container rename <type:name> <new-name>');
+      const result = await applyMutation(session, (draft) => {
+        const { key, container } = resolveContainer(draft, ref);
+        const newKey = container.type + ':' + newName;
+        if (draft.app.containers[newKey]) throw new CliError(`a ${container.type} named "${newName}" already exists`);
+        const renamed = { ...container, name: newName };
+        // Keep the deck's display title in sync if it tracked the old name.
+        if (renamed.deck && (!renamed.deck.title || renamed.deck.title === container.name)) {
+          renamed.deck = { ...renamed.deck, title: newName };
+        }
+        draft.app.containers[newKey] = renamed;
+        delete draft.app.containers[key];
+        for (const e of draft.app.collection) if (locationKey(e.location) === key) e.location = { type: container.type, name: newName };
+        return { renamed: key, to: newKey };
+      }, { dryRun: boolFlag(flags, 'dry-run') });
+      persistUndo(result);
+      printWrite(out, result, () => out.info(out.c.green('✓ renamed') + ` ${result.meta.renamed} → ${result.meta.to}`));
+      return 0;
+    }
+
+    if (sub === 'delete') {
+      const result = await applyMutation(session, (draft) => {
+        const { key, container } = resolveContainer(draft, ref);
+        const cards = draft.app.collection.filter(e => locationKey(e.location) === key);
+        if (cards.length && !boolFlag(flags, 'force')) {
+          throw new CliError(`${container.type}:${container.name} holds ${cards.length} stack(s) — pass --force to delete and unfile them`);
+        }
+        for (const e of draft.app.collection) if (locationKey(e.location) === key) { e.location = null; delete e.deckBoard; }
+        delete draft.app.containers[key];
+        return { deleted: key, unfiled: cards.length };
+      }, { dryRun: boolFlag(flags, 'dry-run') });
+      persistUndo(result);
+      printWrite(out, result, () => out.info(out.c.green('✓ deleted') + ` ${result.meta.deleted}` + (result.meta.unfiled ? ` (unfiled ${result.meta.unfiled})` : '')));
+      return 0;
+    }
+
+    throw usageError('usage: bp container <create|rename|delete> <type:name>');
+  },
+};

package/src/commands/deck.mjs

@@ -0,0 +1,52 @@
+import { loadSnapshot } from '../mutate.mjs';
+import { findContainer, containerCards } from '../snapshot.mjs';
+import { cardRow, CARD_COLUMNS } from '../render.mjs';
+import { usageError, CliError } from '../errors.mjs';
+import { runDeckExport } from './deckExport.mjs';
+
+const BOARDS = ['main', 'sideboard', 'maybe'];
+
+async function deckShow(ctx, name) {
+  const { out } = ctx;
+  if (!name) throw usageError('usage: bp deck show <name>');
+  const session = ctx.makeSession();
+  const { snapshot } = await loadSnapshot(session);
+  const { matches } = findContainer(snapshot, 'deck:' + name);
+  const decks = matches.filter(m => m.type === 'deck');
+  if (!decks.length) throw new CliError(`no deck named "${name}"`);
+
+  const deck = decks[0];
+  const cards = containerCards(snapshot, deck);
+  const boards = { main: [], sideboard: [], maybe: [] };
+  for (const c of cards) (boards[c.deckBoard] || boards.main).push(c);
+
+  out.emit({ deck: { name: deck.name, meta: deck.deck || null }, boards }, () => {
+    out.line(out.c.bold('deck: ' + deck.name));
+    const meta = deck.deck || {};
+    if (meta.format) out.line('  format: ' + meta.format);
+    if (meta.commander?.name) out.line('  commander: ' + meta.commander.name);
+    for (const b of BOARDS) {
+      const list = boards[b];
+      if (!list.length) continue;
+      const n = list.reduce((s, c) => s + (parseInt(c.qty, 10) || 0), 0);
+      out.line('');
+      out.line(out.c.bold(`${b} (${n})`));
+      out.table(CARD_COLUMNS, list.map(cardRow));
+    }
+  });
+  return 0;
+}
+
+export default {
+  summary: 'inspect or export a deck',
+  help: [
+    'usage: bp deck show <name>',
+    '       bp deck export <name> [--preset plain|moxfield|arena|mtgo|csv|json] [--boards main,sideboard,maybe]',
+  ].join('\n'),
+  async run(ctx) {
+    const [sub, ...rest] = ctx.args;
+    if (sub === 'show') return deckShow(ctx, rest.join(' '));
+    if (sub === 'export') return runDeckExport(ctx, rest);
+    throw usageError('usage: bp deck <show|export> <name>');
+  },
+};

package/src/commands/deckExport.mjs

@@ -0,0 +1,48 @@
+import { writeFileSync } from 'node:fs';
+import { loadSnapshot } from '../mutate.mjs';
+import { findContainer, containerCards } from '../snapshot.mjs';
+import { buildDeckExport } from '../../vendor/deckExport.js';
+import { strFlag } from '../args.mjs';
+import { usageError, CliError } from '../errors.mjs';
+
+// `bp deck export <name> [--preset ...] [--boards a,b] [--output file]`
+export async function runDeckExport(ctx, args) {
+  const { out, flags } = ctx;
+  const name = args.join(' ');
+  if (!name) throw usageError('usage: bp deck export <name> [--preset plain|moxfield|arena|mtgo|csv|json]');
+
+  const session = ctx.makeSession();
+  const { snapshot } = await loadSnapshot(session);
+  const { matches } = findContainer(snapshot, 'deck:' + name);
+  const decks = matches.filter(m => m.type === 'deck');
+  if (!decks.length) throw new CliError(`no deck named "${name}"`);
+
+  const deck = decks[0];
+  const cards = containerCards(snapshot, deck);
+  const preset = strFlag(flags, 'preset') || 'plain';
+  const boardsFlag = strFlag(flags, 'boards');
+  const boards = boardsFlag ? boardsFlag.split(',').map(s => s.trim()).filter(Boolean) : undefined;
+  const dm = deck.deck || {};
+  // buildDeckExport expects commander/partner as plain name strings; the app
+  // stores them as { name, scryfallId, ... } objects.
+  const meta = {
+    title: deck.name,
+    format: dm.format,
+    commander: dm.commander?.name || (typeof dm.commander === 'string' ? dm.commander : undefined),
+    partner: dm.partner?.name || (typeof dm.partner === 'string' ? dm.partner : undefined),
+  };
+
+  const result = buildDeckExport(cards, meta, { preset, ...(boards ? { boards } : {}) });
+  for (const w of result.warnings || []) out.info(out.c.yellow('! ' + w));
+
+  const file = strFlag(flags, 'output', 'o');
+  if (file) {
+    writeFileSync(file, result.body.endsWith('\n') ? result.body : result.body + '\n');
+    out.emit({ file, filename: result.filename, preset }, () => out.info(`wrote ${file}`));
+  } else if (out.json) {
+    out.emit({ preset, filename: result.filename, body: result.body, warnings: result.warnings });
+  } else {
+    out.raw(result.body);
+  }
+  return 0;
+}