earnrate 0.1.1 → 0.1.3

package/dist/cli/explore.js

@@ -0,0 +1,364 @@
+import { parseArgs } from 'node:util';
+import { CLI_NAME } from "../brand.js";
+import { walletProblems } from "../data/integrity.js";
+import { loadCatalog, walletPath } from "../data/load.js";
+import { ALL_PERSONAL_CARDS, exploreCards, findCategory, } from "../engine/explore.js";
+import { isValuationProfile, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
+import { resolveSpendLines, simulateAdditions, simulateCatalog, } from "../engine/simulate.js";
+import { knownMemberships } from "../engine/setup.js";
+import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or points and miles cards only.
+  --no-fee                Cards with no annual fee.
+  --issuer <id>           One issuer's cards, e.g. chase or amex.
+  --business              Business cards instead of personal ones.
+  --closed                Include cards the issuer no longer takes applications for.
+  --member <name>         A membership you have, e.g. amazon-prime. Repeatable.
+  --valuation <profile>   flat (points at 1¢, the default) or points-heavy
+                          (MR and UR at 1.7¢).`;
+export const BEST_HELP = `Usage: ${CLI_NAME} best <merchant or category> [amount] [options]
+
+Ranks every card in earnrate's catalog for one purchase, not just yours. Each
+card is set up at its best: the right category pick, activated, cap unused.
+
+Examples:
+  ${CLI_NAME} best groceries
+  ${CLI_NAME} best amazon 120 --member amazon-prime
+  ${CLI_NAME} best dining --no-fee
+
+Options:
+${FILTER_OPTIONS}
+  --online, --in-store    How you're paying. Default: inferred from the merchant.
+  --date <YYYY-MM-DD>     Purchase date. Default: today.
+  --all                   List every card, not just the top 10.
+  --json                  Print the full result as JSON.
+  -h, --help              Show this help.
+`;
+export const SIMULATE_HELP = `Usage: ${CLI_NAME} simulate <what>=<dollars a month>... [options]
+
+Spends this much every month for a year and ranks the cards, and the
+two-card pairs, that earn the most after annual fees. Each <what> is a
+category (groceries, dining, gas, travel, streaming, other) or a merchant
+(amazon, costco).
+
+Examples:
+  ${CLI_NAME} simulate groceries=600 dining=300 gas=150 other=1000
+  ${CLI_NAME} simulate groceries=600 amazon=150 other=800 --wallet
+
+Options:
+  --wallet                Start from your wallet and rank the cards that would
+                          add the most to it, after their fee.
+${FILTER_OPTIONS}
+  --start <YYYY-MM-DD>    First month of the year simulated. Default: today.
+  --all                   List more results.
+  --json                  Print the full result as JSON.
+  -h, --help              Show this help.
+`;
+const FILTER_FLAGS = {
+    cash: { type: 'boolean' },
+    points: { type: 'boolean' },
+    'no-fee': { type: 'boolean' },
+    issuer: { type: 'string' },
+    business: { type: 'boolean' },
+    closed: { type: 'boolean' },
+    member: { type: 'string', multiple: true },
+    valuation: { type: 'string' },
+    all: { type: 'boolean' },
+    json: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+};
+function settingsFrom(values, catalog) {
+    if (values.cash && values.points)
+        return 'Pick --cash or --points, not both.';
+    if (values.valuation !== undefined && !isValuationProfile(values.valuation))
+        return `Unknown valuation "${values.valuation}". Use flat or points-heavy.`;
+    const issuers = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
+    if (values.issuer !== undefined && !issuers.includes(values.issuer))
+        return `Unknown issuer "${values.issuer}". Use one of: ${issuers.join(', ')}.`;
+    const known = knownMemberships(catalog);
+    const unknown = (values.member ?? []).filter((m) => !known.includes(m));
+    if (unknown.length > 0)
+        return `Unknown membership "${unknown.join('", "')}". Use one of: ${known.join(', ')}.`;
+    return {
+        filters: {
+            ...ALL_PERSONAL_CARDS,
+            kind: values.cash ? 'cash' : values.points ? 'points' : 'any',
+            business: values.business ?? false,
+            noAnnualFee: values['no-fee'] ?? false,
+            issuer: values.issuer ?? null,
+            includeClosed: values.closed ?? false,
+        },
+        memberships: values.member ?? [],
+        valuations: values.valuation !== undefined && isValuationProfile(values.valuation)
+            ? VALUATION_PROFILES[values.valuation]
+            : {},
+    };
+}
+const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
+const wholeUsd = (n) => usd(Math.round(n));
+const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
+function feeText(e) {
+    if (e.annualFee === null)
+        return 'annual fee not on file';
+    if (e.annualFee === 0)
+        return 'no annual fee';
+    if (e.firstYearFee !== null && e.firstYearFee !== e.annualFee)
+        return `${usd(e.annualFee)} annual fee (${e.firstYearFee === 0 ? 'waived' : usd(e.firstYearFee)} the first year)`;
+    return `${usd(e.annualFee)} annual fee`;
+}
+const TOP_BEST = 10;
+export function formatExploration(r, all) {
+    const m = r.merchant;
+    const title = m.source === 'caller'
+        ? m.resolvedName.toLowerCase()
+        : m.source === 'none'
+            ? `"${m.input}" (not recognized)`
+            : m.resolvedName;
+    if (r.ranked.length === 0)
+        return `No cards match at ${title}.\n`;
+    const shown = all ? r.ranked : r.ranked.slice(0, TOP_BEST);
+    const width = Math.max(...shown.map((e) => e.cardName.length));
+    const lines = [`Best cards for ${title}:`, ''];
+    shown.forEach((e, i) => {
+        const earned = e.earned === null ? '' : `  ${usd(e.earned)}`;
+        lines.push(`${String(i + 1).padStart(2)}. ${e.cardName.padEnd(width)}  ${pct(e.effectiveReturnPct).padStart(5)}${earned}  ${feeText(e)}`);
+        for (const c of e.conditions)
+            lines.push(`    ${c}`);
+        const upgrade = e.withMembership[0];
+        if (upgrade)
+            lines.push(`    With ${upgrade.membership}: ${pct(upgrade.effectiveReturnPct)}.`);
+        for (const w of e.warnings)
+            lines.push(`    ! ${w}`);
+    });
+    if (r.ranked.length > shown.length)
+        lines.push(`  + ${String(r.ranked.length - shown.length)} more (--all lists them)`);
+    for (const w of r.warnings)
+        lines.push('', `! ${w}`);
+    lines.push('', ...r.assumptions);
+    return `${lines.join('\n')}\n`;
+}
+function picksText(picks) {
+    const parts = Object.entries(picks).map(([choice, options]) => `${choice}: ${options.join(', ')}`);
+    return parts.length === 0 ? '' : ` (picks ${parts.join('; ')})`;
+}
+function cardNamer(catalog) {
+    return (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
+}
+function splitText(sim, name) {
+    const byCard = new Map();
+    for (const line of sim.lines) {
+        const first = line.cards[0];
+        if (first === undefined)
+            continue;
+        byCard.set(first, [...(byCard.get(first) ?? []), line.label]);
+    }
+    return [...byCard].map(([id, labels]) => `${labels.join(', ')} → ${name(id)}`);
+}
+const TOP_SIMULATED = 5;
+export function formatCatalogSimulation(r, catalog, all) {
+    const name = cardNamer(catalog);
+    const first = r.singles[0];
+    if (!first)
+        return 'No cards match.\n';
+    const top = all ? 20 : TOP_SIMULATED;
+    const lines = [
+        `A year of this spending: ${wholeUsd(first.spend)}.`,
+        '',
+        'Best single cards (rewards minus annual fee, per year):',
+    ];
+    r.singles.slice(0, top).forEach((s, i) => {
+        const card = s.cards[0];
+        if (!card)
+            return;
+        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeUsd(s.net)}  (${wholeUsd(s.rewards)} rewards, ${wholeUsd(s.annualFees)} fee)${picksText(card.picks)}`);
+    });
+    const pairs = r.pairs.slice(0, top);
+    if (pairs.length > 0) {
+        lines.push('', 'Best two-card pairs:');
+        pairs.forEach((s, i) => {
+            lines.push(`${String(i + 1).padStart(2)}. ${s.cards.map((c) => `${name(c.cardId)}${picksText(c.picks)}`).join(' + ')}  ${wholeUsd(s.net)}`);
+            if (s.alternatives.length > 0)
+                lines.push(`    Same result with ${s.alternatives.map(name).join(' or ')} as the second card.`);
+            for (const split of splitText(s, name))
+                lines.push(`    ${split}`);
+        });
+        const bestPair = r.pairs[0];
+        if (bestPair && bestPair.net <= first.net)
+            lines.push('', `One card is enough here: no pair beats ${name(first.cards[0]?.cardId ?? '')}.`);
+    }
+    const notes = new Set([
+        ...r.singles.slice(0, top).flatMap((s) => s.notes),
+        ...pairs.flatMap((s) => s.notes),
+    ]);
+    if (notes.size > 0)
+        lines.push('', ...notes);
+    lines.push('', "Assumes each card's best picks, activations done each quarter, and no welcome bonuses.");
+    return `${lines.join('\n')}\n`;
+}
+export function formatAdditions(r, catalog, all) {
+    const name = cardNamer(catalog);
+    const lines = [
+        `Your wallet earns about ${wholeUsd(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeUsd(r.current.annualFees)} in annual fees` : ''}.`,
+    ];
+    for (const split of splitText(r.current, name))
+        lines.push(`  ${split}`);
+    const gains = r.additions.filter((a) => a.gain > 0);
+    if (gains.length === 0) {
+        lines.push('', 'No card would add more than its annual fee costs.');
+    }
+    else {
+        lines.push('', 'Cards that would add the most (after their annual fee):');
+        gains.slice(0, all ? 20 : TOP_SIMULATED).forEach((a, i) => {
+            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeUsd(a.gain)} a year  (+${wholeUsd(a.extraRewards)} rewards, ${wholeUsd(a.annualFee)} fee)${picksText(a.picks)}`);
+        });
+    }
+    const notes = new Set(r.current.notes);
+    if (notes.size > 0)
+        lines.push('', ...notes);
+    lines.push('', 'Assumes your picks carry over, rotating categories get activated, and caps start fresh.');
+    return `${lines.join('\n')}\n`;
+}
+export async function runBest(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                ...FILTER_FLAGS,
+                online: { type: 'boolean' },
+                'in-store': { type: 'boolean' },
+                date: { type: 'string' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${BEST_HELP}`);
+        return USAGE_ERROR;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(BEST_HELP);
+        return 0;
+    }
+    const words = [...positionals];
+    const last = words.at(-1);
+    const amount = words.length > 1 && last !== undefined && /^\$?\d+(\.\d+)?$/.test(last)
+        ? Number(last.replace('$', ''))
+        : null;
+    if (amount !== null)
+        words.pop();
+    const text = words.join(' ').trim();
+    if (text === '') {
+        io.stderr(`Say what you're buying, e.g. ${CLI_NAME} best groceries.\n`);
+        return USAGE_ERROR;
+    }
+    if (values.online && values['in-store']) {
+        io.stderr('Pick --online or --in-store, not both.\n');
+        return USAGE_ERROR;
+    }
+    const catalog = await loadCatalog();
+    const settings = settingsFrom(values, catalog);
+    if (typeof settings === 'string') {
+        io.stderr(`${settings}\n`);
+        return USAGE_ERROR;
+    }
+    const category = findCategory(catalog, text);
+    const result = exploreCards(catalog, {
+        merchant: category === null ? text : null,
+        category,
+        amount,
+        channel: values.online
+            ? 'online'
+            : values['in-store']
+                ? 'in_store'
+                : null,
+        date: values.date ?? io.today,
+    }, settings);
+    io.stdout(values.json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : formatExploration(result, values.all ?? false));
+    return 0;
+}
+export function parseSpend(catalog, args) {
+    const lines = [];
+    for (const arg of args) {
+        const match = /^(.+)=\$?(\d+(?:\.\d+)?)$/.exec(arg);
+        if (!match?.[1] || match[2] === undefined)
+            return `"${arg}" isn't <what>=<dollars a month>, e.g. groceries=600.`;
+        const what = match[1].replace(/[-_]/g, ' ');
+        const category = findCategory(catalog, what);
+        lines.push({
+            merchant: category === null ? what : null,
+            category,
+            monthly: Number(match[2]),
+        });
+    }
+    if (lines.length === 0)
+        return `Give your monthly spending, e.g. ${CLI_NAME} simulate groceries=600 dining=300 other=1000.`;
+    return lines;
+}
+export async function runSimulate(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                ...FILTER_FLAGS,
+                wallet: { type: 'boolean' },
+                start: { type: 'string' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${SIMULATE_HELP}`);
+        return USAGE_ERROR;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(SIMULATE_HELP);
+        return 0;
+    }
+    const catalog = await loadCatalog();
+    const settings = settingsFrom(values, catalog);
+    if (typeof settings === 'string') {
+        io.stderr(`${settings}\n`);
+        return USAGE_ERROR;
+    }
+    const spend = parseSpend(catalog, positionals);
+    if (typeof spend === 'string') {
+        io.stderr(`${spend}\n`);
+        return USAGE_ERROR;
+    }
+    const lines = resolveSpendLines(catalog, spend);
+    const unknown = lines.filter((l) => l.merchant.source === 'none');
+    if (unknown.length > 0) {
+        io.stderr(`Not a category or a merchant earnrate knows: ${unknown.map((l) => `"${l.merchant.input}"`).join(', ')}. Categories include groceries, dining, gas, travel, streaming and other.\n`);
+        return USAGE_ERROR;
+    }
+    const options = { ...settings, start: values.start ?? io.today };
+    if (values.wallet) {
+        const file = walletPath(io.env);
+        const wallet = await readWallet(file, io);
+        if (!wallet)
+            return RUNTIME_ERROR;
+        const problems = walletProblems(wallet, catalog);
+        if (problems.length > 0) {
+            io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+            return RUNTIME_ERROR;
+        }
+        const valued = values.valuation !== undefined && isValuationProfile(values.valuation)
+            ? withValuationProfile(wallet, values.valuation)
+            : wallet;
+        const result = simulateAdditions(catalog, valued, lines, options);
+        io.stdout(values.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : formatAdditions(result, catalog, values.all ?? false));
+        return 0;
+    }
+    const result = simulateCatalog(catalog, lines, options);
+    io.stdout(values.json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : formatCatalogSimulation(result, catalog, values.all ?? false));
+    return 0;
+}

package/dist/cli/run.js

@@ -12,8 +12,10 @@ import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { packageVersion } from "../version.js";
 import { parseCliArgs } from "./args.js";
+import { runBest, runSimulate } from "./explore.js";
 import { runImport } from "./import.js";
 import { runOffers } from "./offers.js";
+import { runWalletCommand, WALLET_HELP } from "./wallet.js";
 import { formatRecommendation, plain } from "./format.js";
 export const HELP = `Usage: ${CLI_NAME} <merchant> [amount] [options]
 
@@ -24,11 +26,22 @@ Examples:
   ${CLI_NAME} costco --in-store
   ${CLI_NAME} delta.com 450 --valuation points-heavy
 
+Compare every card, no wallet needed:
+  ${CLI_NAME} best <merchant or category>          Rank all cards for one purchase.
+  ${CLI_NAME} simulate groceries=600 dining=300    Best cards and pairs for a year of spending.
+
+Set up your wallet:
+  ${CLI_NAME} cards [search words]                 Find cards and their ids.
+  ${CLI_NAME} add <card-id> [--pick ...]           Add a card you hold.
+  ${CLI_NAME} update <card-id> [--pick ...]        Change picks, label or activations.
+  ${CLI_NAME} remove <card-id>                     Remove a card.
+  ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime).
+
 Other commands:
   ${CLI_NAME} import <statement.csv> --card <id>   Replay a statement against your wallet.
   ${CLI_NAME} offers [--cash | --points]           Rank welcome offers on cards you don't have.
   ${CLI_NAME} mcp                                  Run the MCP server over stdio, for AI agents.
-  Add --help to import or offers for its options.
+  Add --help to any command for its options.
 
 Options:
   --online, --in-store   How you're paying. Default: inferred from the merchant.
@@ -66,7 +79,7 @@ export async function readWallet(file, io) {
     }
     catch (e) {
         if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
-            io.stderr(`No wallet at ${displayPath(file)}. Copy the example there and edit it:\n  mkdir -p ${displayPath(path.dirname(file))} && cp ${displayPath(EXAMPLE_WALLET)} ${displayPath(file)}\nOr set ${WALLET_ENV_VAR} to your wallet's path.\n`);
+            io.stderr(`No wallet at ${displayPath(file)} yet. Add the cards you hold:\n  ${CLI_NAME} cards sapphire          find a card's id\n  ${CLI_NAME} add chase-sapphire-preferred\nOr start from the example: mkdir -p ${displayPath(path.dirname(file))} && cp ${displayPath(EXAMPLE_WALLET)} ${displayPath(file)}\nOr set ${WALLET_ENV_VAR} to your wallet's path.\n`);
         }
         else {
             io.stderr(`Couldn't read your wallet:\n${e instanceof Error ? e.message : String(e)}\n`);
@@ -79,6 +92,14 @@ export async function run(argv, io) {
         return runImport(argv.slice(1), io);
     if (argv[0] === 'offers')
         return runOffers(argv.slice(1), io);
+    if (argv[0] === 'best')
+        return runBest(argv.slice(1), io);
+    if (argv[0] === 'simulate')
+        return runSimulate(argv.slice(1), io);
+    const command = argv[0];
+    if (command !== undefined && Object.hasOwn(WALLET_HELP, command)) {
+        return runWalletCommand(command, argv.slice(1), io);
+    }
     if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) {
         io.stdout(`${CLI_NAME} ${await packageVersion()}\n`);
         return 0;

package/dist/cli/wallet.js

@@ -0,0 +1,194 @@
+import { parseArgs } from 'node:util';
+import { CLI_NAME } from "../brand.js";
+import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
+import { addCard, removeCard, setMemberships, updateCard, } from "../data/wallet-setup.js";
+import { knownMemberships, searchCards } from "../engine/setup.js";
+import { formatCardInfo, formatNotes } from "./cards.js";
+import { displayPath, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
+const CARD_OPTIONS = `Options:
+  --label <text>             How the card appears at checkout, e.g. "Amex Gold".
+  --pick <choice>=<options>  Bonus categories you picked for this period, e.g.
+                             --pick five-percent=fast-food,movie-theaters.
+                             Repeat for each choice.
+  --anniversary <MM-DD>      Account anniversary, for caps that reset on it.
+  --activated <rules>        Rules you've activated with the issuer, comma
+                             separated. Replaces the current list.
+  -h, --help                 Show this help.`;
+export const WALLET_HELP = {
+    cards: `Usage: ${CLI_NAME} cards [search words]
+
+Finds cards in earnrate's catalog by name or issuer, with the id to add them
+by and anything they need set up. With no words, lists every card.
+
+Examples:
+  ${CLI_NAME} cards sapphire
+  ${CLI_NAME} cards bofa
+`,
+    add: `Usage: ${CLI_NAME} add <card-id> [options]
+
+Adds a card you hold to your wallet, creating the wallet if needed. Find the
+id with \`${CLI_NAME} cards\`.
+
+${CARD_OPTIONS}
+`,
+    update: `Usage: ${CLI_NAME} update <card-id> [options]
+
+Changes a card in your wallet: picks for this period, label, anniversary or
+activations. Picks for the current period are merged with ones already set.
+
+${CARD_OPTIONS}
+`,
+    remove: `Usage: ${CLI_NAME} remove <card-id>
+
+Removes a card from your wallet, with its tracked cap usage.
+`,
+    memberships: `Usage: ${CLI_NAME} memberships [<membership>...] [--none]
+
+With no arguments, shows your memberships and the ones earnrate knows. With
+names, replaces the list. --none clears it.
+`,
+};
+const HINTS = {
+    pick: (id) => `${CLI_NAME} update ${id} --pick <choice>=<option>,...`,
+    membership: () => `${CLI_NAME} memberships <membership>...`,
+    activation: (id) => `${CLI_NAME} update ${id} --activated <rule>,...`,
+    anniversary: (id) => `${CLI_NAME} update ${id} --anniversary MM-DD`,
+};
+function parsePicks(values) {
+    const picks = {};
+    for (const v of values) {
+        const [choice, options] = v.split('=', 2);
+        const ids = (options ?? '')
+            .split(',')
+            .map((o) => o.trim())
+            .filter((o) => o !== '');
+        if (!choice || ids.length === 0) {
+            return `"--pick ${v}" should look like --pick five-percent=fast-food,movie-theaters.`;
+        }
+        picks[choice] = ids;
+    }
+    return picks;
+}
+async function heldWallet(io) {
+    try {
+        return await loadWallet(walletPath(io.env));
+    }
+    catch {
+        return null;
+    }
+}
+function report(result, message, cardId, io) {
+    if (!result.ok) {
+        io.stderr(`${result.error}\n`);
+        return RUNTIME_ERROR;
+    }
+    const lines = [message];
+    if (cardId !== null) {
+        lines.push(formatNotes(result.notes));
+        const hints = [...new Set(result.notes.map((n) => n.kind))]
+            .map((kind) => HINTS[kind]?.(cardId))
+            .filter((h) => h !== undefined);
+        if (hints.length > 0)
+            lines.push(`Set them with:\n${hints.map((h) => `  ${h}`).join('\n')}`);
+    }
+    io.stdout(`${lines.join('\n')}\n`);
+    return 0;
+}
+export async function runWalletCommand(command, argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                label: { type: 'string' },
+                pick: { type: 'string', multiple: true },
+                anniversary: { type: 'string' },
+                activated: { type: 'string' },
+                none: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\nRun ${CLI_NAME} ${command} --help for usage.\n`);
+        return USAGE_ERROR;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(WALLET_HELP[command]);
+        return 0;
+    }
+    const usage = (message) => {
+        io.stderr(`${message}\nRun ${CLI_NAME} ${command} --help for usage.\n`);
+        return USAGE_ERROR;
+    };
+    const cardOptionsGiven = values.label !== undefined ||
+        values.pick !== undefined ||
+        values.anniversary !== undefined ||
+        values.activated !== undefined;
+    if (command !== 'add' && command !== 'update' && cardOptionsGiven) {
+        return usage(`${CLI_NAME} ${command} doesn't take card options.`);
+    }
+    if (command !== 'memberships' && values.none) {
+        return usage('--none is only for memberships.');
+    }
+    const catalog = await loadCatalog();
+    const file = walletPath(io.env);
+    const where = displayPath(file);
+    if (command === 'cards') {
+        const query = positionals.join(' ');
+        const result = searchCards(catalog, query, await heldWallet(io), io.today);
+        if (result.cards.length === 0) {
+            io.stderr(`No card matches "${query}". Run ${CLI_NAME} cards with no words to list all ${String(catalog.cards.length)}.\n`);
+            return RUNTIME_ERROR;
+        }
+        const header = result.exact ? '' : 'No card matches every word. Closest:\n';
+        io.stdout(`${header}${result.cards.map(formatCardInfo).join('\n')}\n`);
+        return 0;
+    }
+    if (command === 'memberships') {
+        if (positionals.length === 0 && !values.none) {
+            const held = await heldWallet(io);
+            io.stdout(`Yours: ${held && held.memberships.length > 0 ? held.memberships.join(', ') : 'none'}\nKnown: ${knownMemberships(catalog).join(', ')}\n`);
+            return 0;
+        }
+        if (positionals.length > 0 && values.none) {
+            return usage('Give memberships or --none, not both.');
+        }
+        const list = values.none ? [] : positionals;
+        return report(await setMemberships(file, catalog, list), list.length > 0
+            ? `Memberships set to ${list.join(', ')} in ${where}.`
+            : `Memberships cleared in ${where}.`, null, io);
+    }
+    if (positionals.length !== 1) {
+        return usage('Give one card id.');
+    }
+    const id = positionals[0] ?? '';
+    const name = catalog.cards.find((c) => c.id === id)?.name ?? id;
+    if (command === 'remove') {
+        return report(await removeCard(file, catalog, id), `Removed ${name} from ${where}.`, null, io);
+    }
+    const input = { id };
+    if (values.label !== undefined)
+        input.checkoutLabel = values.label;
+    if (values.anniversary !== undefined)
+        input.anniversary = values.anniversary;
+    if (values.activated !== undefined) {
+        input.activated = values.activated
+            .split(',')
+            .map((r) => r.trim())
+            .filter((r) => r !== '');
+    }
+    if (values.pick !== undefined) {
+        const picks = parsePicks(values.pick);
+        if (typeof picks === 'string')
+            return usage(picks);
+        input.picks = picks;
+    }
+    if (command === 'add') {
+        const result = await addCard(file, catalog, input, io.today);
+        return report(result, `Added ${name} to ${where}${result.ok && result.created ? ' (a new wallet)' : ''}.`, id, io);
+    }
+    return report(await updateCard(file, catalog, input, io.today), `Updated ${name} in ${where}.`, id, io);
+}

package/dist/data/integrity.js

@@ -136,6 +136,20 @@ function cardProblems(card, catalog, merchantIds) {
             problems.push(`${where} ${context}: unknown cap '${rule.cap}'`);
         }
     }
+    for (const cap of card.caps.filter((c) => c.rotating)) {
+        const rules = card.rules.filter((r) => r.cap === cap.id);
+        if (rules.length === 0) {
+            problems.push(`${where} cap ${cap.id}: rotating, but no rule uses it`);
+        }
+        for (const r of rules) {
+            if (r.valid_from === undefined || r.valid_to === undefined) {
+                problems.push(`${where} rule ${r.id}: rules on rotating cap '${cap.id}' need valid_from and valid_to`);
+            }
+        }
+        if (cap.period === 'cardmember_year') {
+            problems.push(`${where} cap ${cap.id}: a rotating cap can't use cardmember years`);
+        }
+    }
     return problems;
 }
 export function catalogProblems(catalog) {