biblioplex 0.1.0 → 0.2.0

package/package.json

@@ -1,42 +1,38 @@
 {
   "name": "biblioplex",
-  "version": "0.1.0",
-  "description": "Command-line tool to manage your biblioplex Magic: The Gathering collection.",
+  "version": "0.2.0",
+  "description": "Manage your Biblioplex Magic: The Gathering collection from the terminal.",
+  "keywords": [
+    "mtg",
+    "magic-the-gathering",
+    "collection",
+    "deck",
+    "cli",
+    "biblioplex"
+  ],
+  "license": "MIT",
+  "author": "Benson Perry",
+  "homepage": "https://biblioplex.bensonperry.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/benson/biblioplex.git",
+    "directory": "apps/cli"
+  },
+  "bugs": "https://github.com/benson/biblioplex/issues",
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "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"
+    "test": "node --test \"src/**/__tests__/*.test.js\""
   }
 }

package/src/__tests__/args.test.js

@@ -0,0 +1,39 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseArgs, boolFlag, strFlag, intFlag } from '../args.mjs';
+
+test('parseArgs: positionals, booleans, =value, bare value', () => {
+  const { positionals, flags } = parseArgs([
+    'add',
+    'sol ring',
+    '--yes',
+    '--qty',
+    '2',
+    '--to=deck:breya',
+  ]);
+  assert.deepEqual(positionals, ['add', 'sol ring']);
+  assert.equal(flags.yes, true);
+  assert.equal(flags.qty, '2');
+  assert.equal(flags.to, 'deck:breya');
+});
+
+test('parseArgs: -- ends flag parsing', () => {
+  const { positionals } = parseArgs(['search', '--', '--not-a-flag']);
+  assert.deepEqual(positionals, ['search', '--not-a-flag']);
+});
+
+test('parseArgs: known boolean flags do not swallow the next token', () => {
+  const { positionals, flags } = parseArgs(['add', '--dry-run', 'sol ring']);
+  assert.equal(flags['dry-run'], true);
+  assert.deepEqual(positionals, ['add', 'sol ring']);
+});
+
+test('boolFlag / strFlag / intFlag', () => {
+  const { flags } = parseArgs(['x', '--json', '--limit', '5', '--name', 'bolt']);
+  assert.equal(boolFlag(flags, 'json'), true);
+  assert.equal(boolFlag(flags, 'missing'), false);
+  assert.equal(strFlag(flags, 'name'), 'bolt');
+  assert.equal(strFlag(flags, 'json'), null); // a boolean true is not a string value
+  assert.equal(intFlag(flags, 'limit'), 5);
+  assert.equal(intFlag(flags, 'missing', 9), 9);
+});

package/src/__tests__/csv.test.js

@@ -0,0 +1,33 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { toCsv, fromCsv } from '../csv.mjs';
+
+test('toCsv quotes fields with commas/quotes/newlines and joins arrays', () => {
+  const csv = toCsv(
+    [{ name: 'A, B', note: 'he said "hi"', tags: ['x', 'y'], qty: 2 }],
+    ['name', 'note', 'tags', 'qty'],
+  );
+  assert.equal(csv, 'name,note,tags,qty\n"A, B","he said ""hi""",x;y,2\n');
+});
+
+test('fromCsv parses header + quoted fields with embedded commas/quotes', () => {
+  const rows = fromCsv('name,note\n"A, B","he said ""hi"""\nplain,ok\n');
+  assert.deepEqual(rows, [
+    { name: 'A, B', note: 'he said "hi"' },
+    { name: 'plain', note: 'ok' },
+  ]);
+});
+
+test('round-trips a typical import shape', () => {
+  const original = [
+    { setCode: 'lea', cn: '161', finish: 'nonfoil', qty: '1', location: 'box:red' },
+    { setCode: 'cmm', cn: '2', finish: 'foil', qty: '3', location: 'deck:breya' },
+  ];
+  const parsed = fromCsv(toCsv(original));
+  assert.deepEqual(parsed, original);
+});
+
+test('fromCsv ignores blank trailing lines', () => {
+  assert.equal(fromCsv('a,b\n1,2\n\n').length, 1);
+  assert.equal(fromCsv('').length, 0);
+});

package/src/__tests__/mcp.test.js

@@ -0,0 +1,84 @@
+import { test, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createSession } from '../mcp.mjs';
+import { EXIT } from '../constants.mjs';
+
+const realFetch = globalThis.fetch;
+afterEach(() => {
+  globalThis.fetch = realFetch;
+  delete process.env.BIBLIOPLEX_TOKEN;
+  delete process.env.BIBLIOPLEX_CONFIG_DIR;
+});
+
+function jsonResponse(obj, status = 200) {
+  return new Response(JSON.stringify(obj), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+test('PAT session: posts to /mcp with Bearer + tools/call, returns structuredContent', async () => {
+  const calls = [];
+  globalThis.fetch = async (url, opts) => {
+    calls.push({ url, opts });
+    return jsonResponse({
+      jsonrpc: '2.0',
+      id: 1,
+      result: { structuredContent: { rows: [{ name: 'X' }] } },
+    });
+  };
+  process.env.BIBLIOPLEX_TOKEN = 'pat-xyz';
+  const s = await createSession({ origin: 'https://api.test' });
+  const sc = await s.call('query_collection', { from: 'inventory' });
+  assert.deepEqual(sc, { rows: [{ name: 'X' }] });
+  assert.equal(calls[0].url, 'https://api.test/mcp');
+  assert.equal(calls[0].opts.headers.Authorization, 'Bearer pat-xyz');
+  const body = JSON.parse(calls[0].opts.body);
+  assert.equal(body.method, 'tools/call');
+  assert.equal(body.params.name, 'query_collection');
+  assert.deepEqual(body.params.arguments, { from: 'inventory' });
+});
+
+test('PAT session: HTTP 401 -> auth error (exit AUTH), no retry', async () => {
+  let n = 0;
+  globalThis.fetch = async () => {
+    n += 1;
+    return jsonResponse({ error: 'unauthorized' }, 401);
+  };
+  process.env.BIBLIOPLEX_TOKEN = 'bad';
+  const s = await createSession({ origin: 'https://api.test' });
+  await assert.rejects(s.call('query_collection', {}), (e) => e.code === EXIT.AUTH);
+  assert.equal(n, 1);
+});
+
+test('JSON-RPC -32003 -> scope error (exit AUTH) mentioning write', async () => {
+  globalThis.fetch = async () =>
+    jsonResponse({
+      jsonrpc: '2.0',
+      id: 1,
+      error: {
+        code: -32003,
+        message: 'insufficient scope',
+        data: { requiredScope: 'collection.write' },
+      },
+    });
+  process.env.BIBLIOPLEX_TOKEN = 'pat';
+  const s = await createSession({ origin: 'https://api.test' });
+  await assert.rejects(
+    s.call('mutate_inventory', {}),
+    (e) => e.code === EXIT.AUTH && /write/.test(e.message),
+  );
+});
+
+test('no PAT and no stored creds -> auth error before any network', async () => {
+  let fetched = false;
+  globalThis.fetch = async () => {
+    fetched = true;
+    return jsonResponse({});
+  };
+  process.env.BIBLIOPLEX_CONFIG_DIR = join(tmpdir(), 'bp-empty-test-dir-xyz');
+  await assert.rejects(createSession({ origin: 'https://api.test' }), (e) => e.code === EXIT.AUTH);
+  assert.equal(fetched, false);
+});

package/src/__tests__/mutate.test.js

@@ -0,0 +1,91 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { runMutation } from '../mutate.mjs';
+import { EXIT } from '../constants.mjs';
+import { CliError } from '../errors.mjs';
+
+function fakeOut(json = false) {
+  return {
+    json,
+    emit(d, fn) {
+      if (json) this.emitted = d;
+      else if (fn) fn();
+      return undefined;
+    },
+    line() {},
+    info() {},
+  };
+}
+
+function recSession(applyBehavior) {
+  const calls = [];
+  let applyCount = 0;
+  return {
+    calls,
+    call: async (tool, args) => {
+      calls.push({ tool, args: { ...args } });
+      if (tool === 'mutate_inventory' && args.dryRun) {
+        return {
+          status: 'preview',
+          previews: [{ summary: 'preview' }],
+          idempotencyKey: 'idem-1',
+          expectedRevision: 7,
+        };
+      }
+      if (tool === 'mutate_inventory') {
+        applyCount += 1;
+        return applyBehavior ? applyBehavior(applyCount) : { status: 'applied' };
+      }
+      return {};
+    },
+  };
+}
+
+const ctx = (flags, out) => ({ out, flags });
+
+test('preview is dryRun; apply reuses idempotencyKey + expectedRevision and omits dryRun', async () => {
+  const s = recSession();
+  await runMutation(ctx({ yes: true, json: true }, fakeOut(true)), s, {
+    operation: 'add',
+    scryfallId: 'x',
+  });
+  assert.deepEqual(
+    s.calls.map((c) => c.tool + (c.args.dryRun ? ':dry' : '')),
+    ['mutate_inventory:dry', 'mutate_inventory'],
+  );
+  assert.equal(s.calls[1].args.idempotencyKey, 'idem-1');
+  assert.equal(s.calls[1].args.expectedRevision, 7);
+  assert.equal(s.calls[1].args.dryRun, undefined);
+});
+
+test('--dry-run stops before apply', async () => {
+  const s = recSession();
+  await runMutation(ctx({ 'dry-run': true, json: true }, fakeOut(true)), s, {
+    operation: 'add',
+    scryfallId: 'x',
+  });
+  assert.equal(s.calls.filter((c) => c.tool === 'mutate_inventory' && !c.args.dryRun).length, 0);
+});
+
+test('--json refuses to apply without --yes (exit USAGE), nothing applied', async () => {
+  const s = recSession();
+  await assert.rejects(
+    runMutation(ctx({ json: true }, fakeOut(true)), s, { operation: 'add', scryfallId: 'x' }),
+    (e) => e instanceof CliError && e.code === EXIT.USAGE,
+  );
+  assert.equal(s.calls.filter((c) => c.tool === 'mutate_inventory' && !c.args.dryRun).length, 0);
+});
+
+test('409 conflict re-previews then re-applies', async () => {
+  const s = recSession((n) => {
+    if (n === 1)
+      throw new CliError('conflict', EXIT.CONFLICT, { data: { recoveryStrategy: 're_preview' } });
+    return { status: 'applied' };
+  });
+  await runMutation(ctx({ yes: true, json: true }, fakeOut(true)), s, {
+    operation: 'add',
+    scryfallId: 'x',
+  });
+  assert.equal(s.calls.filter((c) => c.tool === 'mutate_inventory' && c.args.dryRun).length, 2);
+  assert.equal(s.calls.filter((c) => c.tool === 'mutate_inventory' && !c.args.dryRun).length, 2);
+});

package/src/__tests__/render.test.js

@@ -0,0 +1,103 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { pickRows, fmtMoney, emitResult, renderTable, CONTAINER_COLUMNS } from '../render.mjs';
+import { EXIT } from '../constants.mjs';
+
+function fakeOut(json = false) {
+  return {
+    json,
+    _lines: [],
+    _tables: [],
+    emitted: undefined,
+    emit(d, fn) {
+      if (json) this.emitted = d;
+      else if (fn) fn();
+    },
+    line(s = '') {
+      this._lines.push(s);
+    },
+    info() {},
+    table(c, r) {
+      this._tables.push({ c, r });
+    },
+  };
+}
+
+test('pickRows finds the first array among known keys', () => {
+  assert.deepEqual(pickRows({ rows: [1, 2] }), [1, 2]);
+  assert.deepEqual(pickRows({ containers: [{ a: 1 }] }), [{ a: 1 }]);
+  assert.deepEqual(pickRows([3, 4]), [3, 4]);
+  assert.deepEqual(pickRows({ nope: 1 }), []);
+});
+
+test('fmtMoney', () => {
+  assert.equal(fmtMoney(12.5), '$12.50');
+  assert.equal(fmtMoney(null), '—');
+  assert.equal(fmtMoney('3.2'), '$3.20');
+});
+
+test('emitResult maps error statuses to exit codes', () => {
+  const ctx = { out: fakeOut() };
+  assert.throws(
+    () => emitResult(ctx, { status: 'parse_error', message: 'bad' }),
+    (e) => e.code === EXIT.USAGE,
+  );
+  assert.throws(
+    () => emitResult(ctx, { status: 'not_found' }),
+    (e) => e.code === EXIT.NOT_FOUND,
+  );
+  assert.throws(
+    () => emitResult(ctx, { status: 'unsafe' }),
+    (e) => e.code === EXIT.CONFLICT,
+  );
+});
+
+test('emitResult emits raw structuredContent under --json', () => {
+  const ctx = { out: fakeOut(true) };
+  const sc = { rows: [{ name: 'X' }], hasMore: false };
+  emitResult(ctx, sc, { columns: [] });
+  assert.deepEqual(ctx.out.emitted, sc);
+});
+
+test('renderTable keeps present columns and formats money/location', () => {
+  const out = fakeOut();
+  renderTable(
+    out,
+    [{ qty: 1, name: 'Bolt', location: { type: 'box', name: 'red' }, price: 2 }],
+    [
+      { key: 'qty', align: 'right' },
+      { key: 'name' },
+      { key: 'location', header: 'loc', loc: true },
+      { key: 'price', money: true },
+      { key: 'absent' },
+    ],
+  );
+  const { c, r } = out._tables[0];
+  assert.deepEqual(
+    c.map((x) => x.header),
+    ['qty', 'name', 'loc', 'price'],
+  ); // 'absent' column dropped (no data)
+  assert.deepEqual(r[0], ['1', 'Bolt', 'box:red', '$2.00']);
+});
+
+test('container columns read cards/value from stats, not deckListCount', () => {
+  const out = fakeOut();
+  renderTable(
+    out,
+    [
+      {
+        name: 'bulk pile',
+        type: 'box',
+        stats: { unique: 161, total: 195, value: 242.3 },
+        deckListCount: 0,
+      },
+    ],
+    CONTAINER_COLUMNS,
+  );
+  const { c, r } = out._tables[0];
+  assert.deepEqual(
+    c.map((x) => x.header),
+    ['name', 'type', 'cards', 'value'],
+  );
+  assert.deepEqual(r[0], ['bulk pile', 'box', '195', '$242.30']);
+});

package/src/args.mjs

@@ -4,9 +4,25 @@
 // 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',
+  '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' };
@@ -24,12 +40,19 @@ export function parseArgs(argv) {
       i += 1;
       continue;
     }
-    if (tok === '--') { noMoreFlags = true; 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); }
+    if (eq !== -1) {
+      value = raw.slice(eq + 1);
+      raw = raw.slice(0, eq);
+    }
 
     const name = SHORT_ALIASES[raw] || raw;
 
@@ -66,7 +89,7 @@ export function strFlag(flags, ...names) {
 }
 
 export function boolFlag(flags, ...names) {
-  return names.some(n => flags[n] === true || flags[n] === 'true');
+  return names.some((n) => flags[n] === true || flags[n] === 'true');
 }
 
 export function intFlag(flags, name, fallback = null) {

package/src/cli.mjs

@@ -1,14 +1,17 @@
 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 { EXIT, VERSION, DEFAULT_API_ORIGIN } from './constants.mjs';
+import { loadConfig } from './store.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 resolveApiOrigin(flags) {
+  const origin =
+    strFlag(flags, 'api') ||
+    process.env.BIBLIOPLEX_API_ORIGIN ||
+    loadConfig().apiOrigin ||
+    DEFAULT_API_ORIGIN;
+  return origin.replace(/\/+$/, '');
 }
 
 function printHelp(out) {
@@ -16,19 +19,22 @@ function printHelp(out) {
   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);
+  if (commandOrder.length) {
+    out.line('commands:');
+    for (const name of commandOrder) {
+      out.line('  ' + name.padEnd(12) + commands[name].summary);
+    }
+    out.line('');
   }
-  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('  --json          machine-readable output ({ok,data}|{ok,error})');
+  out.line('  --no-color      disable colored output');
+  out.line('  --api <origin>  override the API origin (or set BIBLIOPLEX_API_ORIGIN)');
+  out.line('  --help          show help (also: bp <command> --help)');
+  out.line('  --version       print the version');
   out.line('');
-  out.line('start with: bp login');
+  out.line('auth: run `bp login`, or set BIBLIOPLEX_TOKEN to a personal access');
+  out.line('token for headless / CI use.');
 }
 
 export async function run(argv) {
@@ -36,13 +42,18 @@ export async function run(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; }
+  if (!command || command === 'help') {
+    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; }
+  if (boolFlag(flags, 'version')) {
+    out.line(VERSION);
+    return EXIT.OK;
+  }
 
   const cmd = commands[command];
   if (!cmd) {
@@ -58,11 +69,13 @@ export async function run(argv) {
     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 });
+    apiOrigin: resolveApiOrigin(flags),
+    // Lazily build an MCP session. Uses BIBLIOPLEX_TOKEN (a personal access
+    // token) when set, otherwise the stored OAuth credentials. Imported on
+    // demand so `help`/`version` work without auth wiring.
+    async makeSession({ write = false } = {}) {
+      const { createSession } = await import('./mcp.mjs');
+      return createSession({ origin: this.apiOrigin, requireWrite: write, out: this.out });
     },
   };
 

package/src/commands/add.mjs

@@ -1,57 +1,36 @@
-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';
+import { intFlag, strFlag } from '../args.mjs';
+import { usageError } from '../errors.mjs';
+import { runMutation, resolveOnePrinting } from '../mutate.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");
+  help: `bp add <name> [--set CODE] [--cn NUMBER] [--finish foil|nonfoil|etched] [--qty N] [--to LOCATION] [--tag a,b] [--yes] [--dry-run]
 
-    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;
+Resolves a printing, then adds it. For an exact printing use --set + --cn.
+Examples:
+  bp add "sol ring" --to deck:breya
+  bp add --set sld --cn 2144 --finish foil --qty 2`,
+  async run(ctx) {
+    const session = await ctx.makeSession({ write: true });
+    const query = ctx.args.join(' ').trim();
+    const setCode = strFlag(ctx.flags, 'set');
+    const cn = strFlag(ctx.flags, 'cn');
+    const finish = strFlag(ctx.flags, 'finish');
+    if (!query && !(setCode && cn)) {
+      throw usageError('usage: bp add <name>  (or --set CODE --cn NUMBER)');
+    }
+    const { scryfallId } = await resolveOnePrinting(session, { query, setCode, cn, finish });
+    const args = { operation: 'add', scryfallId, qty: intFlag(ctx.flags, 'qty', 1) };
+    if (finish) args.finish = finish;
+    const to = strFlag(ctx.flags, 'to');
+    if (to) args.location = to;
+    const tagStr = strFlag(ctx.flags, 'tag', 'tags');
+    if (tagStr) {
+      args.tags = tagStr
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    }
+    return runMutation(ctx, session, args, { verb: 'add' });
   },
 };