biblioplex 0.1.1 → 0.2.1

package/src/commands/index.mjs

@@ -1,40 +1,64 @@
-import login from './login.mjs';
-import logout from './logout.mjs';
-import whoami from './whoami.mjs';
-import search from './search.mjs';
+// Command registry. Each command is { summary, help?, run(ctx) }.
 import summary from './summary.mjs';
+import search from './search.mjs';
 import ls from './ls.mjs';
-import show from './show.mjs';
 import deck from './deck.mjs';
+import value from './value.mjs';
+import prices from './prices.mjs';
+import history from './history.mjs';
+import resolve from './resolve.mjs';
+import exportCmd from './export.mjs';
+import importCmd from './import.mjs';
 import add from './add.mjs';
 import rm from './rm.mjs';
 import move from './move.mjs';
 import edit from './edit.mjs';
-import tag from './tag.mjs';
-import container from './container.mjs';
 import undo from './undo.mjs';
-import importCmd from './import.mjs';
-import exportCmd from './export.mjs';
+import recover from './recover.mjs';
+import login from './login.mjs';
+import logout from './logout.mjs';
+import whoami from './whoami.mjs';
 
-// Registry. commandOrder controls help-listing order.
 export const commands = {
-  login,
-  logout,
-  whoami,
-  search,
   summary,
+  search,
   ls,
-  show,
   deck,
+  value,
+  prices,
+  history,
+  resolve,
+  export: exportCmd,
+  import: importCmd,
   add,
   rm,
   move,
   edit,
-  tag,
-  container,
   undo,
-  import: importCmd,
-  export: exportCmd,
+  recover,
+  login,
+  logout,
+  whoami,
 };
 
-export const commandOrder = Object.keys(commands);
+export const commandOrder = [
+  'summary',
+  'search',
+  'ls',
+  'deck',
+  'value',
+  'prices',
+  'history',
+  'resolve',
+  'export',
+  'import',
+  'add',
+  'rm',
+  'move',
+  'edit',
+  'undo',
+  'recover',
+  'login',
+  'logout',
+  'whoami',
+];

package/src/commands/login.mjs

@@ -1,48 +1,39 @@
-import { login as oauthLogin } from '../oauth.mjs';
+import { login } from '../oauth.mjs';
 import { saveCredentials } from '../store.mjs';
-import { Session } from '../api.mjs';
-import { READ_SCOPE, WRITE_SCOPE } from '../constants.mjs';
+import { READ_SCOPE, WRITE_SCOPE, EXIT } from '../constants.mjs';
 import { boolFlag } from '../args.mjs';
-import { loadSnapshot } from '../mutate.mjs';
-import { summarize, collectionOf } from '../snapshot.mjs';
 
 export default {
-  summary: 'sign in to your collection',
-  help: [
-    'usage: bp login [--write] [--no-browser]',
-    '',
-    'opens your browser once to authorize the cli, then stores a refresh token',
-    'locally so future commands stay signed in (~30 days).',
-    '',
-    '  --write       also request permission to make changes (add/edit/import)',
-    '  --no-browser  print the url to open manually instead of launching a browser',
-  ].join('\n'),
-  async run(ctx) {
-    const { out, flags, apiBase } = ctx;
-    const scope = boolFlag(flags, 'write') ? `${READ_SCOPE} ${WRITE_SCOPE}` : READ_SCOPE;
-    const tokens = await oauthLogin({ base: apiBase, scope, out, noBrowser: boolFlag(flags, 'no-browser') });
+  summary: 'sign in via your browser',
+  help: `bp login [--write] [--no-browser]
+
+Authenticate via your browser (OAuth 2.0 + PKCE) and store credentials locally.
+Requests read-only access by default; --write also allows modifying your
+collection. --no-browser just prints the URL to open manually (useful over SSH).
 
-    const creds = {
+For headless / CI use, skip login and set BIBLIOPLEX_TOKEN to a personal access
+token (created in the Biblioplex web app) instead.`,
+  async run(ctx) {
+    const scope = boolFlag(ctx.flags, 'write') ? `${READ_SCOPE} ${WRITE_SCOPE}` : READ_SCOPE;
+    const { tokens, clientId, tokenEndpoint } = await login({
+      origin: ctx.apiOrigin,
+      scope,
+      out: ctx.out,
+      noBrowser: boolFlag(ctx.flags, 'no-browser'),
+    });
+    const granted = tokens.scope || scope;
+    saveCredentials({
       accessToken: tokens.access_token,
       refreshToken: tokens.refresh_token,
-      accessExpiresAt: Date.now() + (Number(tokens.expires_in) || 3600) * 1000,
-      scope: tokens.scope || scope,
-      apiBase,
-      loggedInAt: new Date().toISOString(),
-    };
-    saveCredentials(creds);
-
-    let stats = null;
-    try {
-      const session = new Session({ base: apiBase, credentials: creds, persist: saveCredentials });
-      const { snapshot } = await loadSnapshot(session);
-      stats = summarize(collectionOf(snapshot));
-    } catch { /* confirmation is best-effort */ }
-
-    out.emit({ loggedIn: true, scope: creds.scope, collection: stats }, () => {
-      out.info(out.c.green('✓ signed in') + ' — scope: ' + creds.scope);
-      if (stats) out.info(`cloud collection: ${stats.unique} unique · ${stats.total} cards · $${stats.value}`);
+      expiresAt: Date.now() + (tokens.expires_in ? tokens.expires_in * 1000 : 3_600_000),
+      scope: granted,
+      clientId,
+      tokenEndpoint,
+      origin: ctx.apiOrigin,
     });
-    return 0;
+    ctx.out.emit({ status: 'signed_in', scope: granted, origin: ctx.apiOrigin }, () =>
+      ctx.out.line(`signed in (${granted})`),
+    );
+    return EXIT.OK;
   },
 };

package/src/commands/logout.mjs

@@ -1,16 +1,19 @@
-import { loadCredentials, clearCredentials } from '../store.mjs';
-import { revokeToken } from '../oauth.mjs';
+import { clearCredentials } from '../store.mjs';
+import { EXIT } from '../constants.mjs';
 
 export default {
-  summary: 'sign out and revoke the session',
-  help: 'usage: bp logout\n\nrevokes the stored tokens server-side and deletes the local credentials file.',
+  summary: 'sign out (clears local credentials)',
+  help: `bp logout
+
+Remove locally stored credentials. Biblioplex has no server-side token
+revocation, so existing tokens remain valid until they expire (access ~1h,
+refresh ~30d). To kill a credential sooner, revoke the relevant personal access
+token in the Biblioplex web app.`,
   async run(ctx) {
-    const { out, apiBase } = ctx;
-    const creds = loadCredentials();
-    if (creds?.refreshToken) await revokeToken({ base: apiBase, token: creds.refreshToken });
-    if (creds?.accessToken) await revokeToken({ base: apiBase, token: creds.accessToken });
     clearCredentials();
-    out.emit({ loggedOut: true }, () => out.info(out.c.green('✓ signed out')));
-    return 0;
+    ctx.out.emit({ status: 'signed_out' }, () =>
+      ctx.out.line('signed out (local credentials cleared)'),
+    );
+    return EXIT.OK;
   },
 };

package/src/commands/ls.mjs

@@ -1,31 +1,19 @@
-import { loadSnapshot } from '../mutate.mjs';
-import { listContainers } from '../snapshot.mjs';
-import { usageError } from '../errors.mjs';
-
-// binder/box are legacy aliases for the unified container type.
-const TYPES = { decks: 'deck', deck: 'deck', containers: 'container', container: 'container', binders: 'container', boxes: 'container', binder: 'container', box: 'container' };
+import { emitResult, INVENTORY_COLUMNS, CONTAINER_COLUMNS } from '../render.mjs';
 
 export default {
-  summary: 'list containers (decks / containers)',
-  help: 'usage: bp ls [decks|containers]\n\nlists your decks and storage containers with card counts and value. with no argument, lists all.',
+  summary: 'list containers and their cards',
+  help: `bp ls [container]
+
+With no argument, lists your containers (decks, boxes, binders). With a
+container name, lists the cards stored in it.`,
   async run(ctx) {
-    const { out, args } = ctx;
-    let type = null;
-    if (args[0]) {
-      type = TYPES[args[0].toLowerCase()];
-      if (!type) throw usageError(`unknown container type: ${args[0]} (use decks or containers)`);
+    const session = await ctx.makeSession();
+    const name = ctx.args.join(' ').trim();
+    if (!name) {
+      const sc = await session.call('query_collection', { from: 'containers' });
+      return emitResult(ctx, sc, { columns: CONTAINER_COLUMNS });
     }
-    const session = ctx.makeSession();
-    const { snapshot } = await loadSnapshot(session);
-    const rows = listContainers(snapshot, type);
-
-    out.emit({ containers: rows }, () => {
-      if (!rows.length) { out.info('no containers.'); return; }
-      out.table(
-        [{ header: 'type' }, { header: 'name' }, { header: 'cards', align: 'right' }, { header: 'value', align: 'right' }],
-        rows.map(r => [r.type, r.name, String(r.total), '$' + r.value.toFixed(2)]),
-      );
-    });
-    return 0;
+    const sc = await session.call('query_collection', { from: 'inventory', location: name });
+    return emitResult(ctx, sc, { columns: INVENTORY_COLUMNS });
   },
 };

package/src/commands/move.mjs

@@ -1,41 +1,21 @@
-import { collectionKey } from '../../vendor/collection.js';
-import { applyMutation } from '../mutate.mjs';
-import { strFlag, boolFlag } from '../args.mjs';
-import { requireWrite, selectorFrom, requireStacks, parseLocationFlag, ensureContainer, persistUndo, printWrite } from './writeHelpers.mjs';
+import { intFlag, strFlag } from '../args.mjs';
 import { usageError } from '../errors.mjs';
+import { runMutation } from '../mutate.mjs';
 
 export default {
-  summary: 'move a card to a different container',
-  help: [
-    'usage: bp move <name> --to "deck:breya" [--board sideboard] [--set --cn --finish ...] [--all] [--dry-run]',
-    '',
-    'changes a stack\'s location. --to accepts "deck:x", "container:x", or a bare name',
-    '(treated as a container). --board sets the deck board (main/sideboard/maybe).',
-  ].join('\n'),
-  async run(ctx) {
-    const { out, flags, args } = ctx;
-    const session = ctx.makeSession();
-    requireWrite(session);
-    const to = parseLocationFlag(strFlag(flags, 'to'));
-    if (!to) throw usageError('move requires --to <container>');
-    const board = strFlag(flags, 'board');
-    const sel = selectorFrom(flags, args);
-
-    const result = await applyMutation(session, (draft) => {
-      const stacks = requireStacks(draft.app.collection, sel, { all: boolFlag(flags, 'all') });
-      ensureContainer(draft, to);
-      const keys = new Set(stacks.map(collectionKey));
-      for (const e of draft.app.collection) {
-        if (!keys.has(collectionKey(e))) continue;
-        e.location = { type: to.type, name: to.name };
-        if (to.type === 'deck') e.deckBoard = board || e.deckBoard || 'main';
-        else delete e.deckBoard;
-      }
-      return { moved: stacks.length, to: to.type + ':' + to.name };
-    }, { dryRun: boolFlag(flags, 'dry-run') });
+  summary: 'move cards between locations',
+  help: `bp move <itemKey> --to LOCATION [--qty N] [--yes] [--dry-run]
 
-    persistUndo(result);
-    printWrite(out, result, () => out.info(out.c.green('✓ moved') + ` ${result.meta.moved} stack(s) → ${result.meta.to}`));
-    return 0;
+Move an inventory row to another location (e.g. deck:breya, box:red).
+Get the itemKey from \`bp search ... --json\`.`,
+  async run(ctx) {
+    const itemKey = ctx.args[0] || strFlag(ctx.flags, 'item');
+    const to = strFlag(ctx.flags, 'to');
+    if (!itemKey || !to) throw usageError('usage: bp move <itemKey> --to LOCATION [--qty N]');
+    const session = await ctx.makeSession({ write: true });
+    const args = { operation: 'move', itemKey, toLocation: to };
+    const qty = intFlag(ctx.flags, 'qty');
+    if (qty != null) args.qty = qty;
+    return runMutation(ctx, session, args, { verb: 'move' });
   },
 };

package/src/commands/prices.mjs

@@ -0,0 +1,21 @@
+import { strFlag } from '../args.mjs';
+import { usageError } from '../errors.mjs';
+import { emitResult } from '../render.mjs';
+
+export default {
+  summary: 'price snapshots for a printing',
+  help: `bp prices <scryfallId> [--finish foil|nonfoil|etched]
+
+Per-source price snapshots for one owned printing (by Scryfall id).
+Find ids with: bp search "..." --json`,
+  async run(ctx) {
+    const scryfallId = ctx.args[0];
+    if (!scryfallId) throw usageError('usage: bp prices <scryfallId> [--finish ...]');
+    const session = await ctx.makeSession();
+    const args = { scryfallId };
+    const finish = strFlag(ctx.flags, 'finish');
+    if (finish) args.finish = finish;
+    const sc = await session.call('card_prices', args);
+    return emitResult(ctx, sc);
+  },
+};

package/src/commands/recover.mjs

@@ -0,0 +1,53 @@
+import { EXIT } from '../constants.mjs';
+import { usageError } from '../errors.mjs';
+import { emitResult } from '../render.mjs';
+import { confirm } from '../mutate.mjs';
+
+export default {
+  summary: 'list / preview / restore recovery points',
+  help: `bp recover list
+bp recover preview <id>
+bp recover restore <id> [--yes]
+
+Recovery points are server-side snapshots taken automatically before each
+change — your safety net if undo isn't enough.`,
+  async run(ctx) {
+    const sub = ctx.args[0] || 'list';
+
+    if (sub === 'list') {
+      const session = await ctx.makeSession();
+      const sc = await session.call('list_mcp_recovery_points', {});
+      return emitResult(ctx, sc, {
+        columns: [
+          { key: 'id', header: 'id' },
+          { key: 'createdAt', header: 'when' },
+          { key: 'summary', header: 'summary' },
+        ],
+      });
+    }
+
+    const id = ctx.args[1];
+    if (!id) throw usageError(`usage: bp recover ${sub} <id>`);
+
+    if (sub === 'preview') {
+      const session = await ctx.makeSession({ write: true });
+      const sc = await session.call('restore_mcp_recovery_point', { id, dryRun: true });
+      return emitResult(ctx, sc);
+    }
+
+    if (sub === 'restore') {
+      const session = await ctx.makeSession({ write: true });
+      const preview = await session.call('restore_mcp_recovery_point', { id, dryRun: true });
+      ctx.out.line('restore preview:');
+      ctx.out.line('  • ' + (preview.summary || preview.message || JSON.stringify(preview)));
+      if (!(await confirm(ctx, `restore recovery point ${id}?`))) {
+        ctx.out.info('aborted.');
+        return EXIT.OK;
+      }
+      const sc = await session.call('restore_mcp_recovery_point', { id });
+      return ctx.out.emit(sc, () => ctx.out.line('restored.')) ?? EXIT.OK;
+    }
+
+    throw usageError('usage: bp recover list | preview <id> | restore <id>');
+  },
+};

package/src/commands/resolve.mjs

@@ -0,0 +1,37 @@
+import { strFlag } from '../args.mjs';
+import { usageError } from '../errors.mjs';
+import { emitResult } from '../render.mjs';
+
+export default {
+  summary: 'resolve a Scryfall printing',
+  help: `bp resolve <query> [--set CODE] [--cn NUMBER] [--finish ...]
+
+Resolve a card to concrete printings (for adding/replacing). Examples:
+  bp resolve "lightning bolt"
+  bp resolve --set sld --cn 2144`,
+  async run(ctx) {
+    const session = await ctx.makeSession();
+    const args = {};
+    const query = ctx.args.join(' ').trim();
+    if (query) args.query = query;
+    const set = strFlag(ctx.flags, 'set');
+    const cn = strFlag(ctx.flags, 'cn');
+    const finish = strFlag(ctx.flags, 'finish');
+    if (set) args.setCode = set;
+    if (cn) args.cn = cn;
+    if (finish) args.finish = finish;
+    if (!query && !(set && cn)) {
+      throw usageError('usage: bp resolve <query>  (or --set CODE --cn NUMBER)');
+    }
+    const sc = await session.call('resolve_printing', args);
+    return emitResult(ctx, sc, {
+      columns: [
+        { key: 'name', header: 'name' },
+        { key: 'setCode', header: 'set' },
+        { key: 'cn', header: 'cn' },
+        { key: 'finish', header: 'finish' },
+        { key: 'price', header: 'price', align: 'right', money: true },
+      ],
+    });
+  },
+};

package/src/commands/rm.mjs

@@ -1,37 +1,20 @@
-import { collectionKey } from '../../vendor/collection.js';
-import { applyMutation } from '../mutate.mjs';
-import { boolFlag, intFlag } from '../args.mjs';
-import { requireWrite, selectorFrom, requireStacks, persistUndo, printWrite } from './writeHelpers.mjs';
+import { intFlag, strFlag } from '../args.mjs';
+import { usageError } from '../errors.mjs';
+import { runMutation } from '../mutate.mjs';
 
 export default {
-  summary: 'remove a card (stack) from your collection',
-  help: [
-    'usage: bp rm <name> [--set --cn --finish --condition --location] [--qty n] [--all] [--dry-run]',
-    '',
-    'removes whole matching stacks. --qty n removes only n copies. --all removes every',
-    'matching stack when a name is ambiguous.',
-  ].join('\n'),
-  async run(ctx) {
-    const { out, flags, args } = ctx;
-    const session = ctx.makeSession();
-    requireWrite(session);
-    const sel = selectorFrom(flags, args);
-    const removeQty = intFlag(flags, 'qty', null);
-
-    const result = await applyMutation(session, (draft) => {
-      const stacks = requireStacks(draft.app.collection, sel, { all: boolFlag(flags, 'all') });
-      const keys = new Set(stacks.map(collectionKey));
-      if (removeQty != null) {
-        for (const e of draft.app.collection) if (keys.has(collectionKey(e))) e.qty = Math.max(0, (parseInt(e.qty, 10) || 0) - removeQty);
-        draft.app.collection = draft.app.collection.filter(e => (parseInt(e.qty, 10) || 0) > 0);
-      } else {
-        draft.app.collection = draft.app.collection.filter(e => !keys.has(collectionKey(e)));
-      }
-      return { removed: stacks.length };
-    }, { dryRun: boolFlag(flags, 'dry-run') });
+  summary: 'remove cards from your collection',
+  help: `bp rm <itemKey> [--qty N] [--yes] [--dry-run]
 
-    persistUndo(result);
-    printWrite(out, result, () => out.info(out.c.green('✓ removed') + ` ${result.meta.removed} stack(s)`));
-    return 0;
+Delete an inventory row. Get its itemKey from \`bp search ... --json\`.
+Without --qty, removes the whole row.`,
+  async run(ctx) {
+    const itemKey = ctx.args[0] || strFlag(ctx.flags, 'item');
+    if (!itemKey) throw usageError('usage: bp rm <itemKey> [--qty N]');
+    const session = await ctx.makeSession({ write: true });
+    const args = { operation: 'delete', itemKey };
+    const qty = intFlag(ctx.flags, 'qty');
+    if (qty != null) args.qty = qty;
+    return runMutation(ctx, session, args, { verb: 'remove' });
   },
 };

package/src/commands/search.mjs

@@ -1,42 +1,32 @@
-import { loadSnapshot } from '../mutate.mjs';
-import { runQuery, collectionOf } from '../snapshot.mjs';
-import { cardRow, CARD_COLUMNS, cardsToCsv } from '../render.mjs';
-import { strFlag, intFlag, boolFlag } from '../args.mjs';
+import { intFlag, strFlag, boolFlag } from '../args.mjs';
+import { emitResult, INVENTORY_COLUMNS } from '../render.mjs';
 
 export default {
-  summary: 'search your collection (app query syntax)',
-  help: [
-    'usage: bp search <query> [--sort field] [--desc] [--limit n] [--csv|--json]',
-    '',
-    'uses the same query grammar as the web app, e.g.:',
-    '  bp search "t:creature c:rg cmc<=3 -t:legendary"',
-    '  bp search rare f:foil --sort price --desc',
-    '',
-    'fields: t/type c/color ci/identity cmc/mv o/oracle r/rarity s/set f/finish',
-    '        loc/location tag cond/condition lang qty   (prefix with - to negate)',
-    'sort:   name set cn finish rarity condition location qty price cmc',
-  ].join('\n'),
-  async run(ctx) {
-    const { out, flags, args } = ctx;
-    const session = ctx.makeSession();
-    const { snapshot } = await loadSnapshot(session);
-    const query = args.join(' ');
-    const sort = strFlag(flags, 'sort') || 'name';
-    const dir = boolFlag(flags, 'desc') ? 'desc' : (strFlag(flags, 'dir') || 'asc');
+  summary: 'search your inventory',
+  help: `bp search [query] [--limit N] [--sort FIELD] [--desc] [--cursor C]
 
-    let list = runQuery(collectionOf(snapshot), query, { sort, dir });
-    const limit = intFlag(flags, 'limit', null);
-    if (limit != null) list = list.slice(0, limit);
+Query physical inventory with Biblioplex's SQL-ish expression. Examples:
+  bp search "cmc=1 colors=blue"
+  bp search "finish=foil order by price desc" --limit 10
+  bp search 'select name,price from inventory where oracleText like "draw a card"'
 
-    if (boolFlag(flags, 'csv')) {
-      out.raw(cardsToCsv(list, strFlag(flags, 'format') || 'canonical'));
-      return 0;
+Fields: name,setCode,finish,condition,qty,location,tags,typeLine,setName,cmc,
+colors,colorIdentity,oracleText,price,totalValue.`,
+  async run(ctx) {
+    const session = await ctx.makeSession();
+    const args = { from: 'inventory' };
+    const query = ctx.args.join(' ').trim();
+    if (query) args.query = query;
+    const limit = intFlag(ctx.flags, 'limit');
+    if (limit != null) args.limit = limit;
+    const sort = strFlag(ctx.flags, 'sort');
+    if (sort) {
+      args.sortBy = sort;
+      args.sortDirection = boolFlag(ctx.flags, 'desc') ? 'desc' : 'asc';
     }
-    out.emit({ count: list.length, cards: list }, () => {
-      if (!list.length) { out.info('no cards match.'); return; }
-      out.table(CARD_COLUMNS, list.map(cardRow));
-      out.info(out.c.dim(`${list.length} stack${list.length === 1 ? '' : 's'}`));
-    });
-    return 0;
+    const cursor = strFlag(ctx.flags, 'cursor');
+    if (cursor) args.cursor = cursor;
+    const sc = await session.call('query_collection', args);
+    return emitResult(ctx, sc, { columns: INVENTORY_COLUMNS });
   },
 };

package/src/commands/summary.mjs

@@ -1,34 +1,31 @@
-import { loadSnapshot } from '../mutate.mjs';
-import { collectionOf, containersOf, summarize } from '../snapshot.mjs';
+import { emitResult, renderTable, fmtMoney, CONTAINER_COLUMNS } from '../render.mjs';
 
 export default {
-  summary: 'collection totals and top-value cards',
-  help: 'usage: bp summary [--json]\n\nshows unique stacks, total cards, estimated value, container count, and your most valuable cards.',
-  async run(ctx) {
-    const { out } = ctx;
-    const session = ctx.makeSession();
-    const { snapshot } = await loadSnapshot(session);
-    const collection = collectionOf(snapshot);
-    const stats = summarize(collection);
-    const containers = Object.values(containersOf(snapshot));
-    const top = collection
-      .filter(c => typeof c.price === 'number')
-      .map(c => ({ name: c.resolvedName || c.name, set: (c.setCode || '').toUpperCase(), qty: c.qty, price: c.price, value: Math.round(c.price * (c.qty || 1) * 100) / 100 }))
-      .sort((a, b) => b.value - a.value)
-      .slice(0, 10);
+  summary: 'collection overview (counts, value, containers)',
+  help: `bp summary
 
-    out.emit({ ...stats, containers: containers.length, topValue: top }, () => {
-      out.line(out.c.bold('collection summary'));
-      out.line(`  unique stacks : ${stats.unique}`);
-      out.line(`  total cards   : ${stats.total}`);
-      out.line(`  est. value    : $${stats.value.toFixed(2)}`);
-      out.line(`  containers    : ${containers.length}`);
-      if (top.length) {
-        out.line('');
-        out.line(out.c.bold('top value'));
-        for (const c of top) out.line(`  $${c.value.toFixed(2).padStart(8)}  ${c.name} (${c.set})${c.qty > 1 ? ' x' + c.qty : ''}`);
-      }
+One-shot overview: totals, recent changes, and your containers. Use --json for
+the full structured payload.`,
+  async run(ctx) {
+    const session = await ctx.makeSession();
+    const sc = await session.call('get_collection_overview', {});
+    return emitResult(ctx, sc, {
+      render: (out) => {
+        const s = sc.summary || sc.overview || sc;
+        const get = (...keys) => {
+          for (const k of keys) if (s?.[k] != null) return s[k];
+          return undefined;
+        };
+        const unique = get('uniqueCount', 'unique', 'uniqueCards');
+        const total = get('totalCount', 'total', 'totalCards', 'count');
+        const value = get('totalValue', 'value');
+        out.line(`unique ${unique ?? '?'} · total ${total ?? '?'} · value ${fmtMoney(value)}`);
+        if (Array.isArray(sc.containers) && sc.containers.length) {
+          out.line('');
+          out.line('containers:');
+          renderTable(out, sc.containers, CONTAINER_COLUMNS);
+        }
+      },
     });
-    return 0;
   },
 };

package/src/commands/undo.mjs

@@ -1,34 +1,19 @@
-import { collectionKey } from '../../vendor/collection.js';
-import { applyMutation } from '../mutate.mjs';
-import { loadUndo, clearUndo } from '../store.mjs';
-import { requireWrite, printWrite } from './writeHelpers.mjs';
+import { EXIT } from '../constants.mjs';
 import { CliError } from '../errors.mjs';
 
 export default {
-  summary: 'undo the last change made by this cli',
-  help: 'usage: bp undo\n\nrestores exactly the cards and containers your last cli write touched.',
-  async run(ctx) {
-    const { out } = ctx;
-    const session = ctx.makeSession();
-    requireWrite(session);
-    const record = loadUndo();
-    if (!record) throw new CliError('nothing to undo');
-
-    const result = await applyMutation(session, (draft) => {
-      for (const [key, before] of Object.entries(record.collection || {})) {
-        draft.app.collection = draft.app.collection.filter(e => collectionKey(e) !== key);
-        if (before) draft.app.collection.push(before);
-      }
-      if (Object.keys(record.containers || {}).length && !draft.app.containers) draft.app.containers = {};
-      for (const [key, before] of Object.entries(record.containers || {})) {
-        if (before) draft.app.containers[key] = before;
-        else delete draft.app.containers[key];
-      }
-      return { undone: true };
-    });
+  summary: 'undo your last collection change',
+  help: `bp undo
 
-    clearUndo();
-    printWrite(out, result, () => out.info(out.c.green('✓ undone')));
-    return 0;
+Undo the most recent change you made via the CLI/MCP. Only works if it is still
+the newest change; otherwise use \`bp recover\`.`,
+  async run(ctx) {
+    const session = await ctx.makeSession({ write: true });
+    const sc = await session.call('undo_last_mcp_change', {});
+    if (sc?.status === 'not_found') throw new CliError('nothing to undo', EXIT.NOT_FOUND, sc);
+    if (sc?.status === 'unsafe') {
+      throw new CliError('not the newest change — use `bp recover` instead', EXIT.CONFLICT, sc);
+    }
+    return ctx.out.emit(sc, () => ctx.out.line('undone.')) ?? EXIT.OK;
   },
 };