biblioplex 0.1.1 → 0.2.0

package/src/csv.mjs

@@ -0,0 +1,71 @@
+// Minimal, dependency-free CSV (RFC-4180-ish): quotes fields containing
+// comma/quote/newline, doubles embedded quotes, and round-trips cleanly. Good
+// enough for collection import/export; the CLI deliberately owns this rather
+// than depend on the web app's adapters.
+
+export function toCsv(rows, columns) {
+  const cols = columns && columns.length ? columns : rows[0] ? Object.keys(rows[0]) : [];
+  const esc = (v) => {
+    const s =
+      v == null
+        ? ''
+        : Array.isArray(v)
+          ? v.join(';')
+          : typeof v === 'object'
+            ? JSON.stringify(v)
+            : String(v);
+    return /[",\n\r]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s;
+  };
+  const lines = [cols.join(',')];
+  for (const r of rows) lines.push(cols.map((c) => esc(r[c])).join(','));
+  return lines.join('\n') + '\n';
+}
+
+export function fromCsv(text) {
+  const records = [];
+  let field = '';
+  let record = [];
+  let inQuotes = false;
+  let started = false;
+  const pushField = () => {
+    record.push(field);
+    field = '';
+  };
+  const pushRecord = () => {
+    if (started || record.length) {
+      pushField();
+      records.push(record);
+      record = [];
+      started = false;
+    }
+  };
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    started = true;
+    if (inQuotes) {
+      if (ch === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i += 1;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += ch;
+      }
+      continue;
+    }
+    if (ch === '"') inQuotes = true;
+    else if (ch === ',') pushField();
+    else if (ch === '\r') continue;
+    else if (ch === '\n') pushRecord();
+    else field += ch;
+  }
+  pushRecord();
+  if (!records.length) return [];
+  const header = records[0].map((h) => h.trim());
+  return records
+    .slice(1)
+    .filter((r) => r.some((c) => c !== ''))
+    .map((r) => Object.fromEntries(header.map((h, idx) => [h, r[idx] ?? ''])));
+}

package/src/errors.mjs

@@ -13,5 +13,16 @@ export class CliError extends Error {
 }
 
 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);
+
+export const authError = (message = 'not logged in — run `bp login`') =>
+  new CliError(message, EXIT.AUTH);
+
+export const scopeError = (message = 'this needs write access — run `bp login --write`') =>
+  new CliError(message, EXIT.AUTH);
+
+export const notFoundError = (message) => new CliError(message, EXIT.NOT_FOUND);
+
+export const conflictError = (message) => new CliError(message, EXIT.CONFLICT);
+
+export const rateLimitError = (message = 'rate limited by the server — try again shortly') =>
+  new CliError(message, EXIT.TEMPFAIL);

package/src/mcp.mjs

@@ -0,0 +1,227 @@
+// JSON-RPC 2.0 client + session for the Biblioplex MCP endpoint (POST /mcp).
+// All reads and writes go through here. Auth is a Bearer token — either a
+// personal access token (BIBLIOPLEX_TOKEN, for headless/CI) or stored OAuth
+// credentials, which are refreshed on demand. The whole endpoint is Bearer-
+// gated and stateless (no MCP session handshake), so each tools/call is a
+// standalone authenticated POST.
+import { openSync, closeSync, unlinkSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadCredentials, saveCredentials } from './store.mjs';
+import { configDir, WRITE_SCOPE } from './constants.mjs';
+import { discover, refreshTokens } from './oauth.mjs';
+import { CliError, authError, scopeError, rateLimitError } from './errors.mjs';
+
+const REFRESH_SKEW_MS = 60_000;
+
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function scopeHasWrite(scope) {
+  return typeof scope === 'string' && scope.split(/\s+/).includes(WRITE_SCOPE);
+}
+
+// ---- refresh lock: serialize refreshes across concurrent CLI processes, so a
+// single-use rotating refresh token can't be burned by a race (which would
+// revoke the whole token family server-side). ----
+function lockPath() {
+  return join(configDir(), 'refresh.lock');
+}
+
+async function withRefreshLock(fn, { timeoutMs = 15_000 } = {}) {
+  const path = lockPath();
+  const start = Date.now();
+  let fd;
+  for (;;) {
+    try {
+      fd = openSync(path, 'wx');
+      break;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // Steal an obviously-stale lock (a crashed prior refresh).
+      try {
+        if (Date.now() - statSync(path).mtimeMs > 30_000) {
+          unlinkSync(path);
+          continue;
+        }
+      } catch {
+        /* lock vanished — retry the open */
+      }
+      if (Date.now() - start > timeoutMs) {
+        throw new CliError('timed out waiting for a concurrent `bp` refresh — try again', 75);
+      }
+      await delay(120);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    try {
+      closeSync(fd);
+    } catch {
+      /* already closed */
+    }
+    try {
+      unlinkSync(path);
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+async function ensureFreshToken(origin, creds, { force = false } = {}) {
+  return withRefreshLock(async () => {
+    // Re-read inside the lock: another process may have just refreshed.
+    const latest = loadCredentials() || creds;
+    if (
+      !force &&
+      latest.accessToken &&
+      latest.expiresAt &&
+      Date.now() < latest.expiresAt - REFRESH_SKEW_MS
+    ) {
+      return latest;
+    }
+    if (!latest.refreshToken) throw authError('session expired — run `bp login`');
+    const tokenEndpoint = latest.tokenEndpoint || (await discover(origin)).tokenEndpoint;
+    let tokens;
+    try {
+      tokens = await refreshTokens({
+        tokenEndpoint,
+        clientId: latest.clientId,
+        refreshToken: latest.refreshToken,
+      });
+    } catch (e) {
+      if (e.invalidClient) throw authError('your CLI registration expired — run `bp login` again');
+      throw e;
+    }
+    const updated = {
+      ...latest,
+      accessToken: tokens.access_token,
+      refreshToken: tokens.refresh_token || latest.refreshToken,
+      expiresAt: Date.now() + (tokens.expires_in ? tokens.expires_in * 1000 : 3_600_000),
+      scope: tokens.scope || latest.scope,
+      tokenEndpoint,
+    };
+    saveCredentials(updated);
+    return updated;
+  });
+}
+
+function mapJsonRpcError(error) {
+  const code = error?.code;
+  const message = error?.message || 'request failed';
+  if (code === -32003) {
+    const need = error?.data?.requiredScope || WRITE_SCOPE;
+    return scopeError(`needs ${need} — run \`bp login --write\` (or use a write-scoped token)`);
+  }
+  if (code === -32601) return new CliError('unsupported by this server: ' + message, 2);
+  if (code === -32602) return new CliError('invalid request: ' + message, 2);
+  if (code === -32000) return rateLimitError('server busy — ' + message);
+  return new CliError(message, 1, error?.data ? { data: error.data } : {});
+}
+
+// MCP tools/call returns { content:[{type:'text',text}], structuredContent }.
+// Prefer structuredContent; fall back to parsing the text content.
+function readStructured(result) {
+  if (result && result.structuredContent !== undefined) return result.structuredContent;
+  const text = result?.content?.find?.((c) => c?.type === 'text')?.text;
+  if (text) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return { text };
+    }
+  }
+  return result ?? {};
+}
+
+async function backoff(res, attempt) {
+  const ra = Number(res.headers.get('retry-after'));
+  const ms = Number.isFinite(ra) && ra > 0 ? ra * 1000 : Math.min(8000, 500 * 2 ** attempt);
+  await delay(ms);
+}
+
+// Build an authenticated MCP session. Resolves auth eagerly enough to fail fast
+// with a clear message, but defers the network until a tool is called.
+export async function createSession({ origin, requireWrite = false } = {}) {
+  const mcpUrl = origin + '/mcp';
+  const pat = (process.env.BIBLIOPLEX_TOKEN || '').trim();
+
+  let kind;
+  let getToken;
+  let refresh = null;
+
+  if (pat) {
+    kind = 'pat';
+    getToken = async () => pat; // a PAT's scope is unknown client-side; -32003 surfaces it
+  } else {
+    kind = 'oauth';
+    let current = loadCredentials();
+    if (!current?.accessToken && !current?.refreshToken) throw authError();
+    if (requireWrite && current.scope && !scopeHasWrite(current.scope)) throw scopeError();
+    getToken = async () => {
+      if (
+        current.accessToken &&
+        current.expiresAt &&
+        Date.now() < current.expiresAt - REFRESH_SKEW_MS
+      ) {
+        return current.accessToken;
+      }
+      current = await ensureFreshToken(origin, current);
+      return current.accessToken;
+    };
+    refresh = async () => {
+      current = await ensureFreshToken(origin, current, { force: true });
+      return current.accessToken;
+    };
+  }
+
+  let rpcId = 0;
+  async function call(name, args = {}) {
+    let token = await getToken();
+    for (let attempt = 0; ; attempt++) {
+      let res;
+      try {
+        res = await fetch(mcpUrl, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            Authorization: 'Bearer ' + token,
+          },
+          body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: ++rpcId,
+            method: 'tools/call',
+            params: { name, arguments: args },
+          }),
+        });
+      } catch (e) {
+        throw new CliError(`could not reach ${origin}: ${e.message}`, 75);
+      }
+
+      if (res.status === 401) {
+        if (kind === 'oauth' && refresh && attempt === 0) {
+          token = await refresh();
+          continue;
+        }
+        throw authError(
+          kind === 'pat'
+            ? 'personal access token rejected — check BIBLIOPLEX_TOKEN'
+            : 'not authorized — run `bp login`',
+        );
+      }
+      if (res.status === 429) {
+        if (attempt < 4) {
+          await backoff(res, attempt);
+          continue;
+        }
+        throw rateLimitError();
+      }
+
+      const body = await res.json().catch(() => ({}));
+      if (body.error) throw mapJsonRpcError(body.error);
+      return readStructured(body.result || {});
+    }
+  }
+
+  return { call, origin, kind, requireWrite };
+}

package/src/mutate.mjs

@@ -1,76 +1,151 @@
-// 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);
-    }
+// Safe write flow for mutate_inventory. Public clients can't use the two-phase
+// changeToken path (the server never issues a token to non-chat clients), so we
+// use single-call mutate_inventory: ALWAYS preview with dryRun, let the user
+// confirm, then apply WITHOUT dryRun — reusing the dryRun-suggested
+// idempotencyKey + expectedRevision. Safety (recovery point, 409 concurrency,
+// idempotent retry) is enforced server-side; we just drive it correctly.
+import { createInterface } from 'node:readline';
+import { boolFlag } from './args.mjs';
+import { CliError, usageError } from './errors.mjs';
+import { EXIT } from './constants.mjs';
+import { pickRows } from './render.mjs';
+
+const STATUS_EXIT = {
+  parse_error: EXIT.USAGE,
+  needs_input: EXIT.USAGE,
+  invalid: EXIT.USAGE,
+  not_found: EXIT.NOT_FOUND,
+  unsafe: EXIT.CONFLICT,
+};
+
+function isErrorStatus(sc) {
+  const s = sc && typeof sc === 'object' ? sc.status : undefined;
+  return !!s && s in STATUS_EXIT;
+}
+
+function statusError(sc) {
+  return new CliError(
+    sc.message || sc.error || `mutation ${sc.status}`,
+    STATUS_EXIT[sc.status] || EXIT.ERROR,
+    sc,
+  );
+}
+
+function isConflict(err) {
+  return (
+    err?.code === EXIT.CONFLICT ||
+    err?.extra?.data?.recoveryStrategy === 're_preview' ||
+    err?.extra?.status === 409
+  );
+}
+
+function promptYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(`${question} [y/N] `, (ans) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(ans.trim()));
+    });
+  });
+}
+
+// Confirm a side-effecting action. --yes/--force skips; under --json or a
+// non-TTY we refuse rather than hang waiting for input.
+export async function confirm(ctx, question) {
+  if (boolFlag(ctx.flags, 'yes', 'force')) return true;
+  if (ctx.out.json || !process.stdin.isTTY) {
+    throw usageError('refusing to proceed without confirmation — pass --yes (or --dry-run)');
+  }
+  return promptYesNo(question);
+}
+
+function showPreview(out, preview) {
+  const items = preview.previews || preview.preview || pickRows(preview);
+  if (Array.isArray(items) && items.length) {
+    for (const p of items) out.line('  • ' + (p.summary || p.description || JSON.stringify(p)));
+  } else if (preview.summary) {
+    out.line('  • ' + preview.summary);
   }
-  const collection = {};
-  for (const key of collectionKeys) {
-    collection[key] = (before.app.collection || []).find(e => collectionKey(e) === key) || null;
+  if (preview.tagsCleanup)
+    out.info('note: tags normalized — ' + JSON.stringify(preview.tagsCleanup));
+  const removes = preview.removeCount ?? preview.totalRemoves;
+  if (typeof removes === 'number' && removes >= 20) {
+    out.info(`warning: this removes ${removes} rows (server caps removes at 25/operation).`);
   }
-  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,
-  };
+function applyArgsFrom(baseArgs, preview) {
+  const out = { ...baseArgs };
+  const key = preview.idempotencyKey || preview.suggestedIdempotencyKey;
+  if (key) out.idempotencyKey = key;
+  const rev = preview.expectedRevision ?? preview.revision;
+  if (rev != null) out.expectedRevision = rev;
+  return out;
 }
 
-// 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;
+// Drive a mutate_inventory operation. baseArgs is everything except dryRun.
+export async function runMutation(ctx, session, baseArgs, { verb = 'apply' } = {}) {
+  const { out } = ctx;
+
+  let preview = await session.call('mutate_inventory', { ...baseArgs, dryRun: true });
+  if (isErrorStatus(preview)) throw statusError(preview);
+
+  out.line(`${verb}:`);
+  showPreview(out, preview);
+
+  if (boolFlag(ctx.flags, 'dry-run')) {
+    return out.emit(preview, () => out.line('(dry run — nothing applied)')) ?? EXIT.OK;
+  }
+
+  if (!(await confirm(ctx, 'apply this change?'))) {
+    out.info('aborted.');
+    return EXIT.OK;
+  }
+
+  let applied;
+  try {
+    applied = await session.call('mutate_inventory', applyArgsFrom(baseArgs, preview));
+  } catch (err) {
+    if (!isConflict(err)) throw err;
+    // Collection changed between preview and apply: re-preview, re-confirm, re-apply.
+    out.info('collection changed since preview — re-previewing…');
+    preview = await session.call('mutate_inventory', { ...baseArgs, dryRun: true });
+    if (isErrorStatus(preview)) throw statusError(preview);
+    showPreview(out, preview);
+    if (!(await confirm(ctx, 're-apply with the updated state?'))) {
+      out.info('aborted.');
+      return EXIT.OK;
     }
+    applied = await session.call('mutate_inventory', applyArgsFrom(baseArgs, preview));
+  }
+
+  if (isErrorStatus(applied)) throw statusError(applied);
+  return (
+    out.emit(applied, () => {
+      out.line('done.');
+      showPreview(out, applied);
+    }) ?? EXIT.OK
+  );
+}
+
+// Resolve a single concrete printing for `add`. Throws with guidance when
+// ambiguous so the user can narrow with --set/--cn.
+export async function resolveOnePrinting(session, { query, setCode, cn, finish }) {
+  const args = {};
+  if (query) args.query = query;
+  if (setCode) args.setCode = setCode;
+  if (cn) args.cn = cn;
+  if (finish) args.finish = finish;
+  const res = await session.call('resolve_printing', args);
+  if (res?.status === 'not_found') {
+    throw new CliError('no printing matched — try `bp resolve` to explore', EXIT.NOT_FOUND);
+  }
+  const candidates = pickRows(res);
+  if (res?.status === 'ambiguous' || candidates.length > 1) {
+    throw usageError('multiple printings match — narrow with --set and --cn (see `bp resolve`)');
   }
-  throw lastConflict || new CliError('could not apply change after several retries');
+  const one = candidates[0] || res;
+  const scryfallId = one.scryfallId || one.id || res.scryfallId;
+  if (!scryfallId) throw new CliError('could not resolve a printing id', EXIT.ERROR, res);
+  return { scryfallId, candidate: one };
 }