biblioplex 0.1.1 → 0.2.1

package/src/render.mjs

@@ -1,35 +1,140 @@
-// Shared rendering for card lists: aligned table rows and CSV (via the app's
-// adapters, so exports round-trip with the web app).
-import { formatLocationLabel } from '../vendor/collection.js';
-import { getAdapter, canonicalAdapter } from '../vendor/adapters.js';
-
-const COND_ABBR = { near_mint: 'NM', lightly_played: 'LP', moderately_played: 'MP', heavily_played: 'HP', damaged: 'DMG' };
-const FINISH_LABEL = { normal: '', foil: 'foil', etched: 'etched' };
-
-export const CARD_COLUMNS = [
-  { header: 'qty', align: 'right' },
-  { header: 'name' },
-  { header: 'set' },
-  { header: 'finish' },
-  { header: 'cond' },
-  { header: 'price', align: 'right' },
-  { header: 'location' },
+// Shape-tolerant rendering for MCP structuredContent results. The --json path
+// always emits the raw structuredContent (the stable, agent-facing contract);
+// human mode renders a best-effort table. Error statuses map to exit codes.
+import { EXIT } from './constants.mjs';
+import { CliError } from './errors.mjs';
+
+const ROW_KEYS = [
+  'rows',
+  'results',
+  'items',
+  'cards',
+  'inventory',
+  'containers',
+  'decklist',
+  'changes',
+  'history',
+  'candidates',
+  'data',
 ];
+const ERROR_STATUSES = new Set([
+  'parse_error',
+  'needs_input',
+  'invalid',
+  'not_found',
+  'unsafe',
+  'error',
+]);
+
+export function pickRows(sc) {
+  if (Array.isArray(sc)) return sc;
+  if (!sc || typeof sc !== 'object') return [];
+  for (const k of ROW_KEYS) if (Array.isArray(sc[k])) return sc[k];
+  return [];
+}
+
+function statusToExit(status) {
+  switch (status) {
+    case 'parse_error':
+    case 'needs_input':
+    case 'invalid':
+      return EXIT.USAGE;
+    case 'not_found':
+      return EXIT.NOT_FOUND;
+    case 'unsafe':
+      return EXIT.CONFLICT;
+    default:
+      return EXIT.ERROR;
+  }
+}
 
-export function cardRow(c) {
-  const price = typeof c.price === 'number' ? '$' + c.price.toFixed(2) : '';
-  return [
-    String(c.qty ?? ''),
-    c.resolvedName || c.name || '',
-    ((c.setCode || '').toUpperCase() + ' ' + (c.cn || '')).trim(),
-    FINISH_LABEL[c.finish] ?? c.finish ?? '',
-    COND_ABBR[c.condition] || c.condition || '',
-    price,
-    formatLocationLabel(c.location),
-  ];
+export function fmtMoney(v) {
+  if (v == null || v === '') return '—';
+  const n = typeof v === 'number' ? v : Number(v);
+  return Number.isFinite(n) ? '$' + n.toFixed(2) : String(v);
 }
 
-export function cardsToCsv(cards, format = 'canonical') {
-  const adapter = getAdapter(format) || canonicalAdapter;
-  return adapter.export(cards);
+function locLabel(v) {
+  if (!v) return '';
+  if (typeof v === 'string') return v;
+  if (typeof v === 'object') {
+    if (v.name) return v.type ? `${v.type}:${v.name}` : v.name;
+    return v.type || JSON.stringify(v);
+  }
+  return String(v);
 }
+
+function cell(value, col) {
+  if (value == null) return '';
+  if (col.loc) return locLabel(value);
+  if (col.money) return fmtMoney(value);
+  if (Array.isArray(value)) return value.join(',');
+  if (typeof value === 'object') return JSON.stringify(value);
+  return String(value);
+}
+
+function inferColumns(row) {
+  return Object.keys(row)
+    .slice(0, 6)
+    .map((key) => ({ key, header: key }));
+}
+
+export function renderTable(out, rows, columns) {
+  if (!rows.length) {
+    out.line('(no results)');
+    return;
+  }
+  // Keep only columns actually present in the data, so a projected SELECT or a
+  // shape we didn't anticipate still renders sensibly.
+  let cols =
+    columns && columns.length
+      ? columns.filter((c) => c.get || rows.some((r) => r[c.key] != null))
+      : [];
+  if (!cols.length) cols = inferColumns(rows[0]);
+  out.table(
+    cols.map((c) => ({ header: c.header || c.key, align: c.align })),
+    rows.map((r) => cols.map((c) => cell(c.get ? c.get(r) : r[c.key], c))),
+  );
+}
+
+// Standard read handler: raise error statuses (mapped to exit codes), else emit
+// JSON or a human table. Returns the exit code.
+export function emitResult(ctx, sc, { columns, render } = {}) {
+  const status = sc && typeof sc === 'object' ? sc.status : undefined;
+  if (status && ERROR_STATUSES.has(status)) {
+    throw new CliError(sc.message || sc.error || `request ${status}`, statusToExit(status), sc);
+  }
+  ctx.out.emit(sc, () => {
+    if (render) render(ctx.out, sc);
+    else renderTable(ctx.out, pickRows(sc), columns);
+    if (sc && (sc.hasMore || sc.nextCursor)) {
+      ctx.out.info(`… more available${sc.nextCursor ? ` (--cursor ${sc.nextCursor})` : ''}`);
+    }
+  });
+  return EXIT.OK;
+}
+
+export const INVENTORY_COLUMNS = [
+  { key: 'qty', header: 'qty', align: 'right' },
+  { key: 'name', header: 'name' },
+  { key: 'setCode', header: 'set' },
+  { key: 'finish', header: 'finish' },
+  { key: 'location', header: 'loc', loc: true },
+  { key: 'price', header: 'price', align: 'right', money: true },
+];
+
+export const CONTAINER_COLUMNS = [
+  { key: 'name', header: 'name' },
+  { key: 'type', header: 'type' },
+  // Physical cards in the container live in `stats`; deckListCount is the deck
+  // recipe size (0 for storage), so it can't be the "cards" count.
+  { header: 'cards', align: 'right', get: (r) => r.stats?.total ?? r.deckListCount ?? 0 },
+  { header: 'value', align: 'right', money: true, get: (r) => r.stats?.value },
+];
+
+export const DECKLIST_COLUMNS = [
+  { key: 'qty', header: 'qty', align: 'right' },
+  { key: 'name', header: 'name' },
+  { key: 'board', header: 'board' },
+  { key: 'typeLine', header: 'type' },
+];

package/src/store.mjs

@@ -1,22 +1,51 @@
 // Local persistence for credentials and config. The refresh token is a 30-day
 // bearer secret, so the file is 0600 inside a 0700 directory on POSIX. (Windows
-// relies on per-user ACLs; chmod is skipped there.)
-import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, chmodSync } from 'node:fs';
-import { join } from 'node:path';
+// relies on per-user ACLs; chmod is skipped there.) Credential writes are
+// atomic (tmp + rename) so an interrupted refresh can't truncate the file.
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  existsSync,
+  chmodSync,
+  renameSync,
+} from 'node:fs';
 import { credentialsPath, configPath, configDir } from './constants.mjs';
 
-const undoPath = () => join(configDir(), 'undo.json');
-
 const POSIX = process.platform !== 'win32';
 
 function readJson(path) {
-  try { return JSON.parse(readFileSync(path, 'utf8')); }
-  catch { return null; }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
 }
 
 function ensureDir() {
   mkdirSync(configDir(), { recursive: true });
-  if (POSIX) { try { chmodSync(configDir(), 0o700); } catch {} }
+  if (POSIX) {
+    try {
+      chmodSync(configDir(), 0o700);
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+function writeAtomic(path, data) {
+  ensureDir();
+  const tmp = path + '.tmp';
+  writeFileSync(tmp, data, { mode: 0o600 });
+  if (POSIX) {
+    try {
+      chmodSync(tmp, 0o600);
+    } catch {
+      /* best effort */
+    }
+  }
+  renameSync(tmp, path);
 }
 
 export function loadCredentials() {
@@ -24,10 +53,7 @@ export function loadCredentials() {
 }
 
 export function saveCredentials(creds) {
-  ensureDir();
-  const path = credentialsPath();
-  writeFileSync(path, JSON.stringify(creds, null, 2) + '\n', { mode: 0o600 });
-  if (POSIX) { try { chmodSync(path, 0o600); } catch {} }
+  writeAtomic(credentialsPath(), JSON.stringify(creds, null, 2) + '\n');
 }
 
 export function clearCredentials() {
@@ -39,15 +65,5 @@ export function loadConfig() {
 }
 
 export function saveConfig(config) {
-  ensureDir();
-  writeFileSync(configPath(), JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  writeAtomic(configPath(), JSON.stringify(config, null, 2) + '\n');
 }
-
-export function saveUndo(record) {
-  ensureDir();
-  writeFileSync(undoPath(), JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
-}
-
-export function loadUndo() { return readJson(undoPath()); }
-
-export function clearUndo() { if (existsSync(undoPath())) rmSync(undoPath()); }

package/src/api.mjs

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

package/src/commands/container.mjs

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

package/src/commands/deckExport.mjs

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

package/src/commands/show.mjs

@@ -1,33 +0,0 @@
-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/tag.mjs

@@ -1,40 +0,0 @@
-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/writeHelpers.mjs

@@ -1,82 +0,0 @@
-import { normalizeLocation, locationKey, makeContainer } from '../../vendor/collection.js';
-import { saveUndo } from '../store.mjs';
-import { CliError } from '../errors.mjs';
-import { strFlag, intFlag } from '../args.mjs';
-
-export function requireWrite(session) {
-  if (!session.hasScope('collection.write')) {
-    throw new CliError('this session is read-only — run `bp login --write`', 3);
-  }
-}
-
-export function parseLocationFlag(value) {
-  return value ? normalizeLocation(value) : null;
-}
-
-// Build a stack selector from the card name (positional) + qualifier flags.
-export function selectorFrom(flags, nameParts) {
-  const name = (nameParts || []).join(' ').trim();
-  return {
-    name: name || null,
-    scryfallId: strFlag(flags, 'scryfall-id', 'id'),
-    set: strFlag(flags, 'set', 's'),
-    cn: strFlag(flags, 'cn'),
-    finish: strFlag(flags, 'finish'),
-    condition: strFlag(flags, 'condition', 'cond'),
-    location: parseLocationFlag(strFlag(flags, 'location', 'loc')),
-  };
-}
-
-export function matchStack(c, sel) {
-  if (sel.scryfallId && c.scryfallId !== sel.scryfallId) return false;
-  if (sel.name && !(String(c.resolvedName || c.name || '').toLowerCase().includes(sel.name.toLowerCase()))) return false;
-  if (sel.set && String(c.setCode || '').toLowerCase() !== sel.set.toLowerCase()) return false;
-  if (sel.cn && String(c.cn) !== String(sel.cn)) return false;
-  if (sel.finish && c.finish !== sel.finish) return false;
-  if (sel.condition && c.condition !== sel.condition) return false;
-  if (sel.location && locationKey(c.location) !== locationKey(sel.location)) return false;
-  return true;
-}
-
-export function findStacks(collection, sel) {
-  return (collection || []).filter(c => matchStack(c, sel));
-}
-
-// Resolve a selector to exactly one stack unless `all`, with a helpful
-// disambiguation error listing the candidates.
-export function requireStacks(collection, sel, { all = false } = {}) {
-  if (!sel.name && !sel.scryfallId && !sel.set) throw new CliError('specify a card (name, or --set/--cn, or --scryfall-id)');
-  const stacks = findStacks(collection, sel);
-  if (!stacks.length) throw new CliError('no matching card in your collection');
-  if (stacks.length > 1 && !all) {
-    const lines = stacks.slice(0, 10).map(c =>
-      `  ${c.resolvedName || c.name} · ${(c.setCode || '').toUpperCase()} ${c.cn} · ${c.finish} · ${c.condition} · ${locationKey(c.location) || '—'}`);
-    throw new CliError(`${stacks.length} stacks match — narrow with --set/--cn/--finish/--condition/--location, or pass --all:\n${lines.join('\n')}`);
-  }
-  return stacks;
-}
-
-export function ensureContainer(draft, location) {
-  if (!location) return;
-  const key = location.type + ':' + location.name;
-  if (!draft.app.containers) draft.app.containers = {};
-  if (!draft.app.containers[key]) draft.app.containers[key] = makeContainer({ type: location.type, name: location.name });
-}
-
-export function persistUndo(result) {
-  if (result?.undo && !result.dryRun && !result.noop) saveUndo(result.undo);
-}
-
-export function printWrite(out, result, humanFn) {
-  if (result.noop) { out.emit({ changed: false }, () => out.info('no change.')); return; }
-  if (result.dryRun) {
-    out.emit(
-      { dryRun: true, ops: result.ops.length, opTypes: result.ops.map(o => o.type) },
-      () => out.info(out.c.dim(`dry run — ${result.ops.length} op(s): ${result.ops.map(o => o.type).join(', ')}`)),
-    );
-    return;
-  }
-  out.emit({ changed: true, revision: result.revision, ops: result.ops.length, ...(result.meta || {}) }, humanFn);
-}
-
-export { intFlag };