biblioplex 0.1.0

package/src/commands/writeHelpers.mjs

@@ -0,0 +1,82 @@
+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 };

package/src/constants.mjs

@@ -0,0 +1,25 @@
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+
+export const VERSION = pkg.version;
+export const DEFAULT_API_BASE = 'https://api.bensonperry.com';
+export const CLI_CLIENT_ID = 'biblioplex-cli';
+export const CLIENT_LABEL = 'biblioplex-cli';
+export const READ_SCOPE = 'collection.read';
+export const WRITE_SCOPE = 'collection.write';
+
+// Process exit codes. 3 = auth so scripts can detect "needs `bp login`".
+export const EXIT = { OK: 0, ERROR: 1, USAGE: 2, AUTH: 3, RATE_LIMIT: 4 };
+
+export function configDir() {
+  if (process.env.BIBLIOPLEX_CONFIG_DIR) return process.env.BIBLIOPLEX_CONFIG_DIR;
+  if (process.platform === 'win32') return join(process.env.APPDATA || homedir(), 'biblioplex');
+  return join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'biblioplex');
+}
+
+export function credentialsPath() { return join(configDir(), 'credentials.json'); }
+export function configPath() { return join(configDir(), 'config.json'); }

package/src/errors.mjs

@@ -0,0 +1,17 @@
+import { EXIT } from './constants.mjs';
+
+// A controlled, user-facing failure. The dispatcher prints it (respecting
+// --json) and exits with `code`. Anything else that throws is an unexpected
+// bug and exits 1 with a stack trace under --verbose.
+export class CliError extends Error {
+  constructor(message, code = EXIT.ERROR, extra = {}) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+    this.extra = extra;
+  }
+}
+
+export const usageError = (message) => new CliError(message, EXIT.USAGE);
+export const authError = (message = 'not logged in — run `bp login`') => new CliError(message, EXIT.AUTH);
+export const rateLimitError = (message = 'rate limited by the server — try again shortly') => new CliError(message, EXIT.RATE_LIMIT);

package/src/mutate.mjs

@@ -0,0 +1,76 @@
+// Unified write path. Every mutating command (add/rm/move/edit/tag/container/
+// import) expresses itself as a pure transform of the snapshot; we diff before
+// vs after into granular sync ops (reusing the app's diffSyncSnapshots) and push
+// once with optimistic concurrency, retrying on a revision conflict by
+// re-reading and re-diffing. This never emits snapshot.replace/history/ui ops,
+// so it stays within what a CLI OAuth token is allowed to push.
+import { diffSyncSnapshots } from '../vendor/syncOps.js';
+import { collectionKey } from '../vendor/collection.js';
+import { mergeIntoCollection } from '../vendor/importMerge.js';
+import { emptySnapshot } from './snapshot.mjs';
+import { CliError } from './errors.mjs';
+
+const clone = (v) => JSON.parse(JSON.stringify(v));
+
+// Capture the before-values of exactly the keys a set of ops touches, so `bp
+// undo` can restore them without disturbing anything else.
+function captureUndo(before, ops) {
+  const collectionKeys = new Set();
+  const containerKeys = new Set();
+  for (const op of ops) {
+    const p = op.payload || {};
+    if (op.type.startsWith('collection.')) {
+      for (const k of [p.key, p.beforeKey, p.afterKey]) if (k) collectionKeys.add(k);
+    } else if (op.type.startsWith('container.') && p.key) {
+      containerKeys.add(p.key);
+    }
+  }
+  const collection = {};
+  for (const key of collectionKeys) {
+    collection[key] = (before.app.collection || []).find(e => collectionKey(e) === key) || null;
+  }
+  const containers = {};
+  for (const key of containerKeys) containers[key] = (before.app.containers || {})[key] || null;
+  return { collection, containers };
+}
+
+export async function loadSnapshot(session) {
+  const boot = await session.bootstrap();
+  return {
+    snapshot: boot.hasCloudData && boot.snapshot ? boot.snapshot : emptySnapshot(),
+    revision: boot.revision || 0,
+    collectionId: boot.collectionId || null,
+    hasCloudData: !!boot.hasCloudData,
+  };
+}
+
+// mutate(draft) edits the snapshot clone in place. It may return metadata (e.g.
+// a human summary) and may throw a CliError to abort. Returns { ops, revision,
+// snapshot, noop, meta }. With dryRun, computes ops but does not push.
+export async function applyMutation(session, mutate, { attempts = 4, dryRun = false } = {}) {
+  let lastConflict;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const { snapshot, revision } = await loadSnapshot(session);
+    const before = clone(snapshot);
+    const draft = clone(snapshot);
+    const meta = mutate(draft) || {};
+    // Coalesce any stacks the mutation made collide on the same collectionKey
+    // (e.g. moving a copy into a container that already holds it, or editing
+    // finish/condition to match another stack). Without this, diffSyncSnapshots
+    // keys before/after by collectionKey and would silently drop the colliding
+    // entry, losing quantity. mergeIntoCollection sums qty and unions tags.
+    draft.app.collection = mergeIntoCollection([], draft.app.collection || []);
+    const ops = diffSyncSnapshots(before, draft);
+    if (!ops.length) return { ops: [], revision, snapshot: draft, noop: true, meta };
+    const undo = captureUndo(before, ops);
+    if (dryRun) return { ops, revision, snapshot: draft, dryRun: true, meta, undo };
+    try {
+      const result = await session.push({ ops, baseRevision: revision });
+      return { ops, revision: result.revision, snapshot: result.snapshot, meta, undo: { ...undo, resultRevision: result.revision } };
+    } catch (err) {
+      if (err.conflict && attempt < attempts - 1) { lastConflict = err; continue; }
+      throw err;
+    }
+  }
+  throw lastConflict || new CliError('could not apply change after several retries');
+}

package/src/oauth.mjs

@@ -0,0 +1,129 @@
+// OAuth 2.1 authorization-code + PKCE with an RFC 8252 loopback redirect, plus
+// refresh and revoke. Talks to the biblioplex worker's /authorize, /token and
+// /revoke endpoints. fetchImpl + openBrowser are injectable for tests.
+import http from 'node:http';
+import { execFile } from 'node:child_process';
+import { createPkce, randomState } from './pkce.mjs';
+import { CLI_CLIENT_ID } from './constants.mjs';
+import { CliError } from './errors.mjs';
+
+const SUCCESS_HTML = `<!doctype html><meta charset="utf-8"><title>biblioplex</title>
+<body style="font-family:system-ui;max-width:30rem;margin:4rem auto;text-align:center;color:#222">
+<h1 style="font-weight:500">you're signed in</h1>
+<p>biblioplex cli has your authorization. you can close this tab and return to the terminal.</p>
+</body>`;
+
+export function defaultOpenBrowser(url) {
+  const cmds = process.platform === 'darwin'
+    ? ['open', [url]]
+    : process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  return new Promise((resolve) => {
+    execFile(cmds[0], cmds[1], (err) => resolve(!err));
+  });
+}
+
+function postForm(base, path, body, fetchImpl) {
+  return fetchImpl(base + path, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+export async function exchangeCode({ base, code, verifier, redirectUri, fetchImpl = fetch }) {
+  const res = await postForm(base, '/token', {
+    grant_type: 'authorization_code',
+    code,
+    client_id: CLI_CLIENT_ID,
+    redirect_uri: redirectUri,
+    code_verifier: verifier,
+  }, fetchImpl);
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new CliError('token exchange failed: ' + (data.error_description || data.error || res.status));
+  return data;
+}
+
+export async function refreshTokens({ base, refreshToken, fetchImpl = fetch }) {
+  const res = await postForm(base, '/token', {
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: CLI_CLIENT_ID,
+  }, fetchImpl);
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new CliError('session expired — run `bp login` again', 3);
+  return data;
+}
+
+export async function revokeToken({ base, token, fetchImpl = fetch }) {
+  try {
+    await postForm(base, '/revoke', { token }, fetchImpl);
+  } catch { /* logout is best-effort; local creds are cleared regardless */ }
+}
+
+// Runs the interactive browser login. Returns the raw /token response.
+export async function login({
+  base, scope, out, noBrowser = false,
+  openBrowser = defaultOpenBrowser, fetchImpl = fetch, timeoutMs = 300000,
+}) {
+  const { verifier, challenge, method } = createPkce();
+  const state = randomState();
+
+  const { code, redirectUri } = await new Promise((resolve, reject) => {
+    let redirect = '';
+    let timer;
+    function cleanup() { clearTimeout(timer); try { server.close(); } catch {} }
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname === '/favicon.ico') { res.writeHead(204); res.end(); return; }
+      if (url.pathname !== '/callback') { res.writeHead(404); res.end('not found'); return; }
+
+      const params = url.searchParams;
+      // Validate CSRF state first — including on error responses — so a stray
+      // local request can't abort or influence the in-flight login.
+      if (params.get('state') !== state) {
+        res.writeHead(400, { 'Content-Type': 'text/plain' });
+        res.end('state mismatch');
+        cleanup(); reject(new CliError('login aborted: OAuth state mismatch (possible CSRF)', 3));
+        return;
+      }
+      if (params.get('error')) {
+        res.writeHead(400, { 'Content-Type': 'text/plain' });
+        res.end('authorization failed: ' + params.get('error'));
+        cleanup(); reject(new CliError('authorization denied: ' + params.get('error'), 3));
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(SUCCESS_HTML);
+      const code = params.get('code');
+      cleanup();
+      resolve({ code, redirectUri: redirect });
+    });
+
+    server.on('error', (e) => { cleanup(); reject(new CliError('could not start local login listener: ' + e.message)); });
+    server.listen(0, '127.0.0.1', async () => {
+      redirect = `http://127.0.0.1:${server.address().port}/callback`;
+      const authUrl = new URL(base + '/authorize');
+      authUrl.searchParams.set('response_type', 'code');
+      authUrl.searchParams.set('client_id', CLI_CLIENT_ID);
+      authUrl.searchParams.set('redirect_uri', redirect);
+      authUrl.searchParams.set('code_challenge', challenge);
+      authUrl.searchParams.set('code_challenge_method', method);
+      authUrl.searchParams.set('scope', scope);
+      authUrl.searchParams.set('state', state);
+
+      out.info('opening your browser to sign in…');
+      out.info('if it does not open, visit:\n  ' + authUrl.href + '\n');
+      timer = setTimeout(() => { cleanup(); reject(new CliError('login timed out after ' + Math.round(timeoutMs / 1000) + 's', 3)); }, timeoutMs);
+      if (!noBrowser) {
+        const opened = await openBrowser(authUrl.href);
+        if (!opened) out.info('(could not launch a browser automatically — open the link above)');
+      }
+    });
+  });
+
+  if (!code) throw new CliError('no authorization code received', 3);
+  return exchangeCode({ base, code, verifier, redirectUri, fetchImpl });
+}

package/src/output.mjs

@@ -0,0 +1,79 @@
+// Output layer. Two contracts at once:
+//  - humans get aligned tables / lines on stdout, colour only on a TTY
+//  - agents/scripts get a stable JSON envelope on stdout with --json
+// Diagnostics (spinners, "logged in as…") always go to stderr so --json stdout
+// stays a single clean JSON document.
+
+const COLORS = {
+  reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m',
+  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m',
+};
+
+export function createOutput({ json = false, color = true } = {}) {
+  const useColor = color && !!process.stdout.isTTY && !process.env.NO_COLOR;
+  const paint = (code, s) => (useColor ? code + s + COLORS.reset : String(s));
+
+  return {
+    json,
+    useColor,
+    c: {
+      dim: s => paint(COLORS.dim, s),
+      bold: s => paint(COLORS.bold, s),
+      red: s => paint(COLORS.red, s),
+      green: s => paint(COLORS.green, s),
+      yellow: s => paint(COLORS.yellow, s),
+      cyan: s => paint(COLORS.cyan, s),
+    },
+
+    // Primary success payload. JSON mode prints one envelope; otherwise calls
+    // humanFn to render whatever shape fits (table, lines, etc.).
+    emit(data, humanFn) {
+      if (json) {
+        process.stdout.write(JSON.stringify({ ok: true, data }, null, 2) + '\n');
+      } else if (humanFn) {
+        humanFn();
+      }
+    },
+
+    // A plain stdout line (human mode). No-op under --json.
+    line(str = '') {
+      if (!json) process.stdout.write(str + '\n');
+    },
+
+    // Diagnostics: always stderr, never part of the JSON document.
+    info(str) {
+      process.stderr.write(str + '\n');
+    },
+
+    // Render rows as an aligned table to stdout (human mode only).
+    table(columns, rows) {
+      if (json || !rows.length) return;
+      const widths = columns.map((col, i) =>
+        Math.max(col.header.length, ...rows.map(r => String(r[i] ?? '').length)));
+      const fmt = cells => cells
+        .map((cell, i) => {
+          const s = String(cell ?? '');
+          return columns[i].align === 'right' ? s.padStart(widths[i]) : s.padEnd(widths[i]);
+        })
+        .join('  ')
+        .replace(/\s+$/, '');
+      process.stdout.write(this.c.dim(fmt(columns.map(c => c.header))) + '\n');
+      for (const row of rows) process.stdout.write(fmt(row) + '\n');
+    },
+
+    // Raw text to stdout (e.g. CSV / deck export). Printed in both modes since
+    // it IS the requested artifact.
+    raw(str) {
+      process.stdout.write(str.endsWith('\n') ? str : str + '\n');
+    },
+
+    error(err) {
+      const message = err?.message || String(err);
+      if (json) {
+        process.stdout.write(JSON.stringify({ ok: false, error: { message, ...(err?.extra || {}) } }, null, 2) + '\n');
+      } else {
+        process.stderr.write(this.c.red('error: ') + message + '\n');
+      }
+    },
+  };
+}

package/src/pkce.mjs

@@ -0,0 +1,16 @@
+// PKCE (RFC 7636, S256) + CSRF state, using only node:crypto.
+import { randomBytes, createHash } from 'node:crypto';
+
+function base64url(buf) {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+}
+
+export function createPkce() {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash('sha256').update(verifier).digest());
+  return { verifier, challenge, method: 'S256' };
+}
+
+export function randomState() {
+  return base64url(randomBytes(24));
+}

package/src/render.mjs

@@ -0,0 +1,35 @@
+// 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' },
+];
+
+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 cardsToCsv(cards, format = 'canonical') {
+  const adapter = getAdapter(format) || canonicalAdapter;
+  return adapter.export(cards);
+}

package/src/scryfall.mjs

@@ -0,0 +1,81 @@
+// Direct Scryfall lookups for resolving printings on `add` and `import`.
+// Direct (not via the server's MCP tool) so bulk imports aren't throttled by the
+// worker's 60/60s MCP limit; we apply our own polite delay instead. Scryfall is
+// already the product's card-data source.
+import { VERSION } from './constants.mjs';
+import { getUsdPrice } from '../vendor/collection.js';
+import { CliError } from './errors.mjs';
+
+const SCRYFALL = 'https://api.scryfall.com';
+const USER_AGENT = `biblioplex-cli/${VERSION} (+https://biblioplex.bensonperry.com)`;
+
+export const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+async function sfGet(path, fetchImpl) {
+  const res = await fetchImpl(SCRYFALL + path, { headers: { 'User-Agent': USER_AGENT, Accept: 'application/json' } });
+  if (res.status === 404) return null;
+  const data = await res.json().catch(() => ({}));
+  if (res.status === 429) throw new CliError('scryfall rate limit — slow down and retry', 4);
+  if (!res.ok) throw new CliError('scryfall error: ' + (data.details || res.status));
+  return data;
+}
+
+export function getById(id, fetchImpl = fetch) {
+  return sfGet('/cards/' + encodeURIComponent(id), fetchImpl);
+}
+
+export function getBySetCn(set, cn, fetchImpl = fetch) {
+  return sfGet(`/cards/${encodeURIComponent(String(set).toLowerCase())}/${encodeURIComponent(cn)}`, fetchImpl);
+}
+
+export function getByName(name, { set, fetchImpl = fetch } = {}) {
+  const q = new URLSearchParams({ fuzzy: name });
+  if (set) q.set('set', String(set).toLowerCase());
+  return sfGet('/cards/named?' + q.toString(), fetchImpl);
+}
+
+// Resolve the most specific identifier available to a Scryfall card object.
+export async function resolvePrinting({ scryfallId, set, cn, name, fetchImpl = fetch }) {
+  let card = null;
+  if (scryfallId) card = await getById(scryfallId, fetchImpl);
+  else if (set && cn) card = await getBySetCn(set, cn, fetchImpl);
+  else if (name) card = await getByName(name, { set, fetchImpl });
+  if (!card || card.object === 'error') return null;
+  return card;
+}
+
+// Map a Scryfall card to the resolved-field shape normalizeCollectionEntry
+// expects (handles double-faced cards for colors/image/oracle).
+export function cardToFields(card, finish = 'normal') {
+  const faces = Array.isArray(card.card_faces) ? card.card_faces : [];
+  const front = faces[0] || {};
+  const back = faces[1];
+  const colors = card.colors ?? (faces.length ? [...new Set(faces.flatMap(f => f.colors || []))] : []);
+  // Match the web app's resolution: join faces with " // " and use getUsdPrice
+  // (which falls back to the non-foil price for foil/etched when the exact-finish
+  // price is missing, setting priceFallback).
+  const oracleText = card.oracle_text ?? (faces.length ? faces.map(f => f.oracle_text || '').join(' // ') : '');
+  const typeLine = card.type_line || (faces.length ? faces.map(f => f.type_line || '').filter(Boolean).join(' // ') : '') || '';
+  const { price, fallback } = getUsdPrice(card, finish);
+  return {
+    scryfallId: card.id,
+    setCode: card.set,
+    setName: card.set_name,
+    cn: card.collector_number,
+    name: card.name,
+    rarity: card.rarity,
+    cmc: card.cmc,
+    colors,
+    colorIdentity: card.color_identity || [],
+    typeLine,
+    oracleText,
+    legalities: card.legalities || {},
+    finishes: card.finishes || [],
+    imageUrl: card.image_uris?.normal || front.image_uris?.normal || null,
+    backImageUrl: back?.image_uris?.normal || null,
+    resolvedName: card.name,
+    scryfallUri: card.scryfall_uri || null,
+    price,
+    priceFallback: fallback,
+  };
+}

package/src/snapshot.mjs

@@ -0,0 +1,77 @@
+// Read-side helpers over a bootstrap snapshot, reusing the app's search core.
+import { tokenizeSearch, matchSearch, passesMultiselectFilters, compareCards } from '../vendor/searchCore.js';
+import { locationKey } from '../vendor/collection.js';
+
+export function emptySnapshot() {
+  return {
+    app: { schemaVersion: 1, collection: [], containers: {}, ui: { selectedFormat: '' } },
+    history: [],
+    shares: [],
+  };
+}
+
+export function collectionOf(snapshot) {
+  return snapshot?.app?.collection || [];
+}
+
+export function containersOf(snapshot) {
+  return snapshot?.app?.containers || {};
+}
+
+// Filter + sort a collection with the exact app grammar and sort order.
+export function runQuery(collection, query = '', { sort = 'name', dir = 'asc', filters = {} } = {}) {
+  const tokens = tokenizeSearch(query || '');
+  const filtered = (collection || []).filter(c => matchSearch(c, tokens) && passesMultiselectFilters(c, filters));
+  const sign = dir === 'desc' ? -1 : 1;
+  return [...filtered].sort((a, b) => sign * compareCards(a, b, sort));
+}
+
+// Parse a container reference like "deck:breya", "breya", or "binder:rares".
+// Returns { type, name } where type may be null if unqualified.
+export function parseContainerRef(ref) {
+  const m = String(ref || '').trim().match(/^(deck|container|binder|box)\s*[:]\s*(.+)$/i);
+  if (m) {
+    const t = m[1].toLowerCase();
+    return { type: t === 'deck' ? 'deck' : 'container', name: m[2].trim().toLowerCase() };
+  }
+  return { type: null, name: String(ref || '').trim().toLowerCase() };
+}
+
+export function listContainers(snapshot, type = null) {
+  const containers = Object.values(containersOf(snapshot));
+  const collection = collectionOf(snapshot);
+  return containers
+    .filter(c => !type || c.type === type)
+    .map(c => {
+      const key = c.type + ':' + c.name;
+      const cards = collection.filter(card => locationKey(card.location) === key);
+      const stats = summarize(cards);
+      return { type: c.type, name: c.name, unique: stats.unique, total: stats.total, value: stats.value, meta: c.deck || null };
+    })
+    .sort((a, b) => a.type.localeCompare(b.type) || a.name.localeCompare(b.name));
+}
+
+export function findContainer(snapshot, ref) {
+  const { type, name } = parseContainerRef(ref);
+  const containers = Object.values(containersOf(snapshot));
+  const matches = containers.filter(c => c.name === name && (!type || c.type === type));
+  return { matches, type, name };
+}
+
+export function containerCards(snapshot, container) {
+  const key = container.type + ':' + container.name;
+  return collectionOf(snapshot).filter(card => locationKey(card.location) === key);
+}
+
+export function summarize(collection) {
+  let unique = 0;
+  let total = 0;
+  let value = 0;
+  for (const c of collection || []) {
+    unique += 1;
+    const qty = parseInt(c.qty, 10) || 0;
+    total += qty;
+    if (typeof c.price === 'number') value += c.price * qty;
+  }
+  return { unique, total, value: Math.round(value * 100) / 100 };
+}