biblioplex 0.1.1 → 0.2.1

package/README.md

@@ -1,92 +1,66 @@
-# biblioplex cli
+# biblioplex
 
-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.
+Manage your [Biblioplex](https://biblioplex.bensonperry.com) Magic: The Gathering
+collection from the terminal — search, edit, import/export, and recover, with
+first-class machine-readable output for scripts and agents.
 
 ## install
 
-requires **node 20+**.
-
-```sh
-npm install -g biblioplex      # then run `biblioplex` or `bp`
-# or, no install:
-npx biblioplex login
+```bash
+npm install -g biblioplex
+# or
+brew install benson/tap/biblioplex
 ```
 
-> 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).
+Installs two commands: `biblioplex` and the short alias `bp`. Requires Node.js ≥ 22.
 
-## sign in
+## quick start
 
-```sh
-bp login            # read-only (search/export)
-bp login --write    # also allow edits/imports
+```bash
+bp login                 # sign in via your browser (read-only by default)
+bp summary               # overview: unique/total counts, value, containers
+bp search "finish=foil order by price desc" --limit 10
 ```
 
-`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
+## auth
 
-# totals and your most valuable cards
-bp summary
+- **interactive** (people): `bp login` opens your browser (OAuth 2.0 + PKCE). Add
+  `--write` to allow changes; `bp logout` clears local credentials.
+- **headless / CI** (no browser): set `BIBLIOPLEX_TOKEN` to a personal access token
+  created in the Biblioplex web app (account menu → access tokens).
 
-# containers
-bp ls decks
-bp show "deck:breya"
-bp deck show breya
-bp deck export breya --preset moxfield > breya.txt
+## commands
 
-# 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
+|                             |                                                                     |
+| --------------------------- | ------------------------------------------------------------------- |
+| **read**                    | `summary` `search` `ls` `deck` `value` `prices` `history` `resolve` |
+| **write** (needs `--write`) | `add` `rm` `move` `edit` `import` `export`                          |
+| **recover**                 | `undo` `recover`                                                    |
+| **auth**                    | `login` `logout` `whoami`                                           |
 
-# 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`.
+Run `bp help` or `bp <command> --help` for usage.
 
-## scripting / agents
+### writes are previewed
 
-every command accepts `--json` and prints a stable envelope to stdout:
+Every change shows a dry-run preview and asks for confirmation. Pass `--yes` to
+skip the prompt or `--dry-run` to preview without applying. Changes apply
+server-side with automatic recovery points, so `bp undo` and `bp recover` can roll
+them back.
 
-```json
-{ "ok": true, "data": { ... } }
-{ "ok": false, "error": { "message": "..." } }
-```
+## for scripts & agents
 
-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.
+- `--json` on any command emits a stable envelope: `{ "ok": true, "data": … }` or
+  `{ "ok": false, "error": … }`.
+- meaningful exit codes: `0` ok · `2` usage · `3` auth/scope · `4` not found ·
+  `5` conflict · `75` rate-limited / retryable.
+- override the API origin with `BIBLIOPLEX_API_ORIGIN` (e.g. a local dev worker).
 
-## configuration
+## notes
 
-- credentials: `~/.config/biblioplex/credentials.json` (mode 600)
-- override the api endpoint: `--api <url>` or `BIBLIOPLEX_API_BASE`
-- override the config dir: `BIBLIOPLEX_CONFIG_DIR`
+- cloud-first: the CLI operates on your live Biblioplex collection (the web app is
+  the source of truth).
+- zero runtime dependencies.
 
-## notes
+## license
 
-- 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.
+MIT

package/package.json

@@ -1,42 +1,32 @@
 {
   "name": "biblioplex",
-  "version": "0.1.1",
-  "description": "Command-line tool to manage your biblioplex Magic: The Gathering collection.",
+  "version": "0.2.1",
+  "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",
   "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) {