biblioplex 0.1.0

package/src/commands/edit.mjs

@@ -0,0 +1,45 @@
+import { collectionKey, normalizeCondition, normalizeFinish } from '../../vendor/collection.js';
+import { applyMutation } from '../mutate.mjs';
+import { strFlag, intFlag, boolFlag } from '../args.mjs';
+import { requireWrite, selectorFrom, requireStacks, persistUndo, printWrite } from './writeHelpers.mjs';
+import { usageError } from '../errors.mjs';
+
+export default {
+  summary: 'edit a stack (condition / finish / qty / tags)',
+  help: [
+    'usage: bp edit <name> [--set --cn ...] [--condition lightly_played] [--finish foil]',
+    '                      [--qty 3] [--tags trade,foil] [--all] [--dry-run]',
+    '',
+    'updates fields on a matching stack. --tags replaces the tag set ("" clears).',
+  ].join('\n'),
+  async run(ctx) {
+    const { out, flags, args } = ctx;
+    const session = ctx.makeSession();
+    requireWrite(session);
+    const sel = selectorFrom(flags, args);
+    const newCond = strFlag(flags, 'condition', 'cond');
+    const newFinish = strFlag(flags, 'finish');
+    const newQty = intFlag(flags, 'qty', null);
+    const setTags = strFlag(flags, 'tags');
+    if (newCond == null && newFinish == null && newQty == null && setTags == null) {
+      throw usageError('nothing to edit — pass --condition, --finish, --qty, or --tags');
+    }
+
+    const result = await applyMutation(session, (draft) => {
+      const stacks = requireStacks(draft.app.collection, sel, { all: boolFlag(flags, 'all') });
+      const keys = new Set(stacks.map(collectionKey));
+      for (const e of draft.app.collection) {
+        if (!keys.has(collectionKey(e))) continue;
+        if (newCond) e.condition = normalizeCondition(newCond);
+        if (newFinish) e.finish = normalizeFinish(newFinish);
+        if (newQty != null) e.qty = Math.max(1, newQty);
+        if (setTags != null) e.tags = setTags ? setTags.split(',').map(s => s.trim()).filter(Boolean) : [];
+      }
+      return { edited: stacks.length };
+    }, { dryRun: boolFlag(flags, 'dry-run') });
+
+    persistUndo(result);
+    printWrite(out, result, () => out.info(out.c.green('✓ edited') + ` ${result.meta.edited} stack(s)`));
+    return 0;
+  },
+};

package/src/commands/export.mjs

@@ -0,0 +1,56 @@
+import { writeFileSync } from 'node:fs';
+import { loadSnapshot } from '../mutate.mjs';
+import { runQuery, collectionOf } from '../snapshot.mjs';
+import { getAdapter } from '../../vendor/adapters.js';
+import { buildPortableArchive, portableArchiveToJson } from '../../vendor/portableArchive.js';
+import { strFlag, boolFlag } from '../args.mjs';
+import { usageError, CliError } from '../errors.mjs';
+
+const CSV_FORMATS = ['canonical', 'moxfield', 'manabox', 'deckbox'];
+
+export default {
+  summary: 'export your collection to csv / json',
+  help: [
+    'usage: bp export [query] [--format canonical|moxfield|manabox|deckbox|json] [--output file]',
+    '       bp export --archive [--output backup.json]   (full round-trippable backup)',
+    '',
+    'with a query, exports only the matching cards (e.g. bp export "f:foil" --format moxfield).',
+    'writes to stdout unless --output is given.',
+  ].join('\n'),
+  async run(ctx) {
+    const { out, flags, args } = ctx;
+    const session = ctx.makeSession();
+    const { snapshot } = await loadSnapshot(session);
+    const file = strFlag(flags, 'output', 'o');
+
+    let body;
+    let meta;
+    if (boolFlag(flags, 'archive')) {
+      const archive = buildPortableArchive({ snapshot });
+      if (!archive) throw new CliError('could not build archive');
+      body = portableArchiveToJson(archive);
+      meta = { kind: 'archive' };
+    } else {
+      const cards = runQuery(collectionOf(snapshot), args.join(' '));
+      const format = strFlag(flags, 'format') || 'canonical';
+      if (format === 'json') {
+        body = JSON.stringify(cards, null, 2);
+      } else if (CSV_FORMATS.includes(format)) {
+        body = getAdapter(format).export(cards);
+      } else {
+        throw usageError(`unknown format: ${format} (use ${CSV_FORMATS.join('/')}, json, or --archive)`);
+      }
+      meta = { format, count: cards.length };
+    }
+
+    if (file) {
+      writeFileSync(file, body.endsWith('\n') ? body : body + '\n');
+      out.emit({ file, ...meta }, () => out.info(`wrote ${file}`));
+    } else if (out.json) {
+      out.emit({ ...meta, body });
+    } else {
+      out.raw(body);
+    }
+    return 0;
+  },
+};

package/src/commands/import.mjs

@@ -0,0 +1,94 @@
+import { readFileSync } from 'node:fs';
+import { parseCsv } from '../../vendor/importParsing.js';
+import { detectAdapter } from '../../vendor/adapters.js';
+import { mergeIntoCollection } from '../../vendor/importMerge.js';
+import { normalizeCollectionEntry } from '../../vendor/collection.js';
+import { resolvePrinting, cardToFields, sleep } from '../scryfall.mjs';
+import { applyMutation } from '../mutate.mjs';
+import { boolFlag } from '../args.mjs';
+import { requireWrite, ensureContainer, printWrite } from './writeHelpers.mjs';
+import { usageError, CliError } from '../errors.mjs';
+
+// Pushed in chunks so a large import stays within the worker's per-request CPU
+// and payload limits; each chunk is one revision. Not undoable (too large).
+const CHUNK = 150;
+
+export default {
+  summary: 'import cards from a csv file (moxfield/manabox/deckbox/canonical)',
+  help: [
+    'usage: bp import <file.csv> [--no-resolve] [--dry-run]',
+    '',
+    'auto-detects the csv format and merges the cards into your cloud collection.',
+    'by default each card is resolved on scryfall so it is fully searchable; pass',
+    '--no-resolve to import as-is (faster, but no oracle/color/price data).',
+  ].join('\n'),
+  async run(ctx) {
+    const { out, flags, args } = ctx;
+    const session = ctx.makeSession();
+    requireWrite(session);
+    const path = args[0];
+    if (!path) throw usageError('usage: bp import <file.csv>');
+
+    let text;
+    try { text = readFileSync(path, 'utf8'); } catch { throw new CliError('cannot read file: ' + path); }
+    const rows = parseCsv(text);
+    if (rows.length < 2) throw new CliError('no rows found in ' + path);
+    const adapter = detectAdapter(rows[0]);
+    if (!adapter) throw new CliError('could not detect a supported csv format (moxfield/manabox/deckbox/canonical)');
+    let entries = adapter.parse(rows);
+    if (!entries.length) throw new CliError('no cards parsed from ' + path);
+
+    let resolved = 0;
+    let unresolved = 0;
+    if (!boolFlag(flags, 'no-resolve')) {
+      out.info(`resolving ${entries.length} card(s) on scryfall…`);
+      const next = [];
+      for (let i = 0; i < entries.length; i += 1) {
+        const e = entries[i];
+        let card = null;
+        try { card = await resolvePrinting({ scryfallId: e.scryfallId || null, set: e.setCode, cn: e.cn, name: e.name }); } catch { /* leave unresolved */ }
+        if (card) {
+          resolved += 1;
+          next.push(normalizeCollectionEntry({
+            ...cardToFields(card, e.finish), finish: e.finish, qty: e.qty,
+            condition: e.condition, language: e.language, location: e.location, tags: e.tags,
+            ...(e._source ? { _source: e._source } : {}),
+          }, { preserveResolvedFields: true }));
+        } else {
+          unresolved += 1;
+          next.push(e);
+        }
+        if ((i + 1) % 25 === 0) out.info(out.c.dim(`  ${i + 1}/${entries.length}`));
+        await sleep(80);
+      }
+      entries = next;
+    }
+
+    if (boolFlag(flags, 'dry-run')) {
+      const result = await applyMutation(session, (draft) => {
+        for (const e of entries) ensureContainer(draft, e.location);
+        draft.app.collection = mergeIntoCollection(draft.app.collection, entries);
+        return { format: adapter.id, imported: entries.length, resolved, unresolved };
+      }, { dryRun: true });
+      printWrite(out, result, () => out.info(out.c.dim(`dry run — would import ${entries.length} card(s) (${adapter.id})`)));
+      return 0;
+    }
+
+    let revision = 0;
+    for (let i = 0; i < entries.length; i += CHUNK) {
+      const chunk = entries.slice(i, i + CHUNK);
+      const result = await applyMutation(session, (draft) => {
+        for (const e of chunk) ensureContainer(draft, e.location);
+        draft.app.collection = mergeIntoCollection(draft.app.collection, chunk);
+      });
+      revision = result.revision || revision;
+      if (entries.length > CHUNK) out.info(out.c.dim(`  pushed ${Math.min(i + CHUNK, entries.length)}/${entries.length}`));
+    }
+
+    out.emit(
+      { changed: true, imported: entries.length, format: adapter.id, resolved, unresolved, revision },
+      () => out.info(out.c.green('✓ imported') + ` ${entries.length} card(s) (${adapter.id})` + (unresolved ? `, ${unresolved} unresolved` : '')),
+    );
+    return 0;
+  },
+};

package/src/commands/index.mjs

@@ -0,0 +1,40 @@
+import login from './login.mjs';
+import logout from './logout.mjs';
+import whoami from './whoami.mjs';
+import search from './search.mjs';
+import summary from './summary.mjs';
+import ls from './ls.mjs';
+import show from './show.mjs';
+import deck from './deck.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';
+
+// Registry. commandOrder controls help-listing order.
+export const commands = {
+  login,
+  logout,
+  whoami,
+  search,
+  summary,
+  ls,
+  show,
+  deck,
+  add,
+  rm,
+  move,
+  edit,
+  tag,
+  container,
+  undo,
+  import: importCmd,
+  export: exportCmd,
+};
+
+export const commandOrder = Object.keys(commands);

package/src/commands/login.mjs

@@ -0,0 +1,48 @@
+import { login as oauthLogin } from '../oauth.mjs';
+import { saveCredentials } from '../store.mjs';
+import { Session } from '../api.mjs';
+import { READ_SCOPE, WRITE_SCOPE } 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') });
+
+    const creds = {
+      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}`);
+    });
+    return 0;
+  },
+};

package/src/commands/logout.mjs

@@ -0,0 +1,16 @@
+import { loadCredentials, clearCredentials } from '../store.mjs';
+import { revokeToken } from '../oauth.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.',
+  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;
+  },
+};

package/src/commands/ls.mjs

@@ -0,0 +1,31 @@
+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' };
+
+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.',
+  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 = 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;
+  },
+};

package/src/commands/move.mjs

@@ -0,0 +1,41 @@
+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 { usageError } from '../errors.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') });
+
+    persistUndo(result);
+    printWrite(out, result, () => out.info(out.c.green('✓ moved') + ` ${result.meta.moved} stack(s) → ${result.meta.to}`));
+    return 0;
+  },
+};

package/src/commands/rm.mjs

@@ -0,0 +1,37 @@
+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';
+
+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') });
+
+    persistUndo(result);
+    printWrite(out, result, () => out.info(out.c.green('✓ removed') + ` ${result.meta.removed} stack(s)`));
+    return 0;
+  },
+};

package/src/commands/search.mjs

@@ -0,0 +1,42 @@
+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';
+
+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');
+
+    let list = runQuery(collectionOf(snapshot), query, { sort, dir });
+    const limit = intFlag(flags, 'limit', null);
+    if (limit != null) list = list.slice(0, limit);
+
+    if (boolFlag(flags, 'csv')) {
+      out.raw(cardsToCsv(list, strFlag(flags, 'format') || 'canonical'));
+      return 0;
+    }
+    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;
+  },
+};

package/src/commands/show.mjs

@@ -0,0 +1,33 @@
+import { loadSnapshot } from '../mutate.mjs';
+import { findContainer, containerCards } from '../snapshot.mjs';
+import { runQuery } from '../snapshot.mjs';
+import { cardRow, CARD_COLUMNS, cardsToCsv } from '../render.mjs';
+import { strFlag, boolFlag } from '../args.mjs';
+import { usageError, CliError } from '../errors.mjs';
+
+export default {
+  summary: 'show the cards in a container',
+  help: 'usage: bp show <container> [--sort field] [--csv|--json]\n\ncontainer may be "deck:breya", "binder:rares", or just "breya" if unambiguous.',
+  async run(ctx) {
+    const { out, args, flags } = ctx;
+    const ref = args.join(' ');
+    if (!ref) throw usageError('usage: bp show <container>');
+    const session = ctx.makeSession();
+    const { snapshot } = await loadSnapshot(session);
+    const { matches, name } = findContainer(snapshot, ref);
+    if (!matches.length) throw new CliError(`no container named "${name}"`);
+    if (matches.length > 1) {
+      throw new CliError(`"${name}" is ambiguous — try ${matches.map(m => m.type + ':' + m.name).join(', ')}`);
+    }
+    const container = matches[0];
+    const cards = runQuery(containerCards(snapshot, container), '', { sort: strFlag(flags, 'sort') || 'name', dir: boolFlag(flags, 'desc') ? 'desc' : 'asc' });
+
+    if (boolFlag(flags, 'csv')) { out.raw(cardsToCsv(cards, strFlag(flags, 'format') || 'canonical')); return 0; }
+    out.emit({ container: { type: container.type, name: container.name }, count: cards.length, cards }, () => {
+      out.line(out.c.bold(container.type + ':' + container.name));
+      if (!cards.length) { out.info('(empty)'); return; }
+      out.table(CARD_COLUMNS, cards.map(cardRow));
+    });
+    return 0;
+  },
+};

package/src/commands/summary.mjs

@@ -0,0 +1,34 @@
+import { loadSnapshot } from '../mutate.mjs';
+import { collectionOf, containersOf, summarize } from '../snapshot.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);
+
+    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 : ''}`);
+      }
+    });
+    return 0;
+  },
+};

package/src/commands/tag.mjs

@@ -0,0 +1,40 @@
+import { collectionKey, normalizeTag } from '../../vendor/collection.js';
+import { applyMutation } from '../mutate.mjs';
+import { boolFlag } from '../args.mjs';
+import { requireWrite, selectorFrom, requireStacks, persistUndo, printWrite } from './writeHelpers.mjs';
+import { usageError } from '../errors.mjs';
+
+export default {
+  summary: 'add or remove a tag on a stack',
+  help: [
+    'usage: bp tag add <tag> <name> [--set --cn --finish ...] [--all]',
+    '       bp tag rm  <tag> <name> [...]',
+    '',
+    'adds/removes a single tag on matching stacks.',
+  ].join('\n'),
+  async run(ctx) {
+    const { out, flags, args } = ctx;
+    const session = ctx.makeSession();
+    requireWrite(session);
+    const [op, rawTag, ...nameParts] = args;
+    if ((op !== 'add' && op !== 'rm') || !rawTag) throw usageError('usage: bp tag <add|rm> <tag> <name>');
+    const tag = normalizeTag(rawTag);
+    const sel = selectorFrom(flags, nameParts);
+
+    const result = await applyMutation(session, (draft) => {
+      const stacks = requireStacks(draft.app.collection, sel, { all: boolFlag(flags, 'all') });
+      const keys = new Set(stacks.map(collectionKey));
+      for (const e of draft.app.collection) {
+        if (!keys.has(collectionKey(e))) continue;
+        const tags = new Set((e.tags || []).map(normalizeTag).filter(Boolean));
+        if (op === 'add') tags.add(tag); else tags.delete(tag);
+        e.tags = [...tags];
+      }
+      return { tagged: stacks.length, op, tag };
+    }, { dryRun: boolFlag(flags, 'dry-run') });
+
+    persistUndo(result);
+    printWrite(out, result, () => out.info(out.c.green('✓ ' + (op === 'add' ? 'tagged' : 'untagged')) + ` ${result.meta.tagged} stack(s) (${tag})`));
+    return 0;
+  },
+};

package/src/commands/undo.mjs

@@ -0,0 +1,34 @@
+import { collectionKey } from '../../vendor/collection.js';
+import { applyMutation } from '../mutate.mjs';
+import { loadUndo, clearUndo } from '../store.mjs';
+import { requireWrite, printWrite } from './writeHelpers.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 };
+    });
+
+    clearUndo();
+    printWrite(out, result, () => out.info(out.c.green('✓ undone')));
+    return 0;
+  },
+};

package/src/commands/whoami.mjs

@@ -0,0 +1,26 @@
+import { loadCredentials } from '../store.mjs';
+import { authError } from '../errors.mjs';
+
+export default {
+  summary: 'show the current session',
+  help: 'usage: bp whoami\n\nshows the api endpoint, granted scopes, and when you signed in.',
+  async run(ctx) {
+    const { out, apiBase } = ctx;
+    const creds = loadCredentials();
+    if (!creds?.accessToken) throw authError();
+    const data = {
+      apiBase,
+      scope: creds.scope,
+      canWrite: (creds.scope || '').split(/\s+/).includes('collection.write'),
+      loggedInAt: creds.loggedInAt || null,
+      accessExpiresAt: creds.accessExpiresAt ? new Date(creds.accessExpiresAt).toISOString() : null,
+    };
+    out.emit(data, () => {
+      out.line('api:    ' + apiBase);
+      out.line('scope:  ' + creds.scope);
+      out.line('access: ' + (data.canWrite ? 'read + write' : 'read only'));
+      if (creds.loggedInAt) out.line('since:  ' + creds.loggedInAt);
+    });
+    return 0;
+  },
+};