biblioplex 0.1.1 → 0.2.1

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');
+}

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