biblioplex 0.1.0 → 0.2.0

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;
   },
 };

package/src/commands/value.mjs

@@ -0,0 +1,30 @@
+import { strFlag } from '../args.mjs';
+import { emitResult, fmtMoney } from '../render.mjs';
+
+export default {
+  summary: 'collection value totals',
+  help: `bp value [--source usd|eur|tix]
+
+Priced/unpriced counts and total value for a price source (default usd).`,
+  async run(ctx) {
+    const session = await ctx.makeSession();
+    const source = strFlag(ctx.flags, 'source') || 'usd';
+    const sc = await session.call('collection_value', { source });
+    return emitResult(ctx, sc, {
+      render: (out) => {
+        const get = (...k) => {
+          for (const key of k) if (sc?.[key] != null) return sc[key];
+          return undefined;
+        };
+        out.line(`source: ${get('source') ?? source}`);
+        const total = get('totalValue', 'total', 'value');
+        if (total != null) out.line(`total value: ${fmtMoney(total)}`);
+        const priced = get('pricedCount', 'priced');
+        const unpriced = get('unpricedCount', 'unpriced');
+        if (priced != null || unpriced != null) {
+          out.line(`priced: ${priced ?? '?'}   unpriced: ${unpriced ?? '?'}`);
+        }
+      },
+    });
+  },
+};

package/src/commands/whoami.mjs

@@ -1,26 +1,34 @@
 import { loadCredentials } from '../store.mjs';
-import { authError } from '../errors.mjs';
+import { READ_SCOPE, EXIT } from '../constants.mjs';
 
 export default {
-  summary: 'show the current session',
-  help: 'usage: bp whoami\n\nshows the api endpoint, granted scopes, and when you signed in.',
+  summary: 'show local auth status',
+  help: `bp whoami
+
+Show your current authentication state. Does not contact the server.`,
   async run(ctx) {
-    const { out, apiBase } = ctx;
+    const pat = (process.env.BIBLIOPLEX_TOKEN || '').trim();
+    if (pat) {
+      ctx.out.emit({ authenticated: true, method: 'token', origin: ctx.apiOrigin }, () =>
+        ctx.out.line('authenticated via BIBLIOPLEX_TOKEN (personal access token)'),
+      );
+      return EXIT.OK;
+    }
     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;
+    if (!creds?.accessToken && !creds?.refreshToken) {
+      ctx.out.emit({ authenticated: false }, () => ctx.out.line('not logged in — run `bp login`'));
+      return EXIT.OK;
+    }
+    ctx.out.emit(
+      {
+        authenticated: true,
+        method: 'oauth',
+        scope: creds.scope || READ_SCOPE,
+        origin: creds.origin || ctx.apiOrigin,
+      },
+      () =>
+        ctx.out.line(`logged in · ${creds.scope || READ_SCOPE} · ${creds.origin || ctx.apiOrigin}`),
+    );
+    return EXIT.OK;
   },
 };

package/src/constants.mjs

@@ -3,17 +3,39 @@ 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'));
+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';
+
+// The Biblioplex API origin (MCP + OAuth live here). Override for local
+// `wrangler dev` via BIBLIOPLEX_API_ORIGIN (e.g. http://localhost:8765).
+export const DEFAULT_API_ORIGIN = 'https://biblioplex-api.bensonperry.com';
+
+// Sent as client_name during dynamic OAuth client registration.
 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 };
+// Process exit codes — the CLI's contract for scripts and agents:
+//   0  ok
+//   1  generic error
+//   2  usage / parse error / needs input
+//   3  auth — not logged in, or insufficient scope (run `bp login [--write]`)
+//   4  not found
+//   5  conflict — unsafe undo, or revision mismatch (re-run after re-preview)
+//   75 temp-fail — rate limited or retryable server error (EX_TEMPFAIL)
+export const EXIT = {
+  OK: 0,
+  ERROR: 1,
+  USAGE: 2,
+  AUTH: 3,
+  NOT_FOUND: 4,
+  CONFLICT: 5,
+  TEMPFAIL: 75,
+};
 
 export function configDir() {
   if (process.env.BIBLIOPLEX_CONFIG_DIR) return process.env.BIBLIOPLEX_CONFIG_DIR;
@@ -21,5 +43,10 @@ export function configDir() {
   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'); }
+export function credentialsPath() {
+  return join(configDir(), 'credentials.json');
+}
+
+export function configPath() {
+  return join(configDir(), 'config.json');
+}