earnrate 0.1.4 → 0.2.1

package/dist/cli/explore.js

@@ -1,12 +1,12 @@
 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";
+import { resolveSpendLines, simulateAdditions, simulateCatalog, spendLineFor, TYPICAL_MONTHLY_SPEND, TYPICAL_SPEND_NOTE, } from "../engine/simulate.js";
+import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../format/explore.js";
+import { BOTH_CHANNELS, cardList, channelOf, dateProblem, membershipProblem, splitAmount, valuationProblem, } from "./args.js";
+import { cardsToUse, 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.
@@ -15,7 +15,7 @@ const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or point
   --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]
+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.
@@ -33,12 +33,12 @@ ${FILTER_OPTIONS}
   --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]
+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).
+(amazon, costco). With no amounts, it uses typical ones for a U.S. household.
 
 Examples:
   ${CLI_NAME} simulate groceries=600 dining=300 gas=150 other=1000
@@ -47,6 +47,7 @@ Examples:
 Options:
   --wallet                Start from your wallet and rank the cards that would
                           add the most to it, after their fee.
+  --cards <ids>           The same, for cards you name instead of your wallet.
 ${FILTER_OPTIONS}
   --start <YYYY-MM-DD>    First month of the year simulated. Default: today.
   --all                   List more results.
@@ -69,15 +70,13 @@ const FILTER_FLAGS = {
 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 problem = valuationProblem(values.valuation) ??
+        membershipProblem(catalog, values.member ?? []);
+    if (problem !== null)
+        return problem;
     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,
@@ -93,130 +92,6 @@ function settingsFrom(values, catalog) {
             : {},
     };
 }
-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 {
@@ -240,20 +115,23 @@ export async function runBest(argv, io) {
         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();
+    const split = splitAmount(positionals);
+    if (typeof split === 'string') {
+        io.stderr(`${split}\n`);
+        return USAGE_ERROR;
+    }
+    const { text, amount } = split;
     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');
+        io.stderr(`${BOTH_CHANNELS}\n`);
+        return USAGE_ERROR;
+    }
+    const dated = dateProblem(values.date);
+    if (dated !== null) {
+        io.stderr(`${dated}\n`);
         return USAGE_ERROR;
     }
     const catalog = await loadCatalog();
@@ -267,11 +145,7 @@ export async function runBest(argv, io) {
         merchant: category === null ? text : null,
         category,
         amount,
-        channel: values.online
-            ? 'online'
-            : values['in-store']
-                ? 'in_store'
-                : null,
+        channel: channelOf(values),
         date: values.date ?? io.today,
     }, settings);
     io.stdout(values.json
@@ -279,7 +153,7 @@ export async function runBest(argv, io) {
         : formatExploration(result, values.all ?? false));
     return 0;
 }
-export function parseSpend(catalog, args) {
+function parseSpend(catalog, args) {
     const lines = [];
     for (const arg of args) {
         const match = /^(.+)=\$?(\d+(?:\.\d+)?)$/.exec(arg);
@@ -306,6 +180,7 @@ export async function runSimulate(argv, io) {
             options: {
                 ...FILTER_FLAGS,
                 wallet: { type: 'boolean' },
+                cards: { type: 'string' },
                 start: { type: 'string' },
             },
         });
@@ -325,7 +200,10 @@ export async function runSimulate(argv, io) {
         io.stderr(`${settings}\n`);
         return USAGE_ERROR;
     }
-    const spend = parseSpend(catalog, positionals);
+    const typical = positionals.length === 0;
+    const spend = typical
+        ? TYPICAL_MONTHLY_SPEND.map((t) => spendLineFor(catalog, t.what, t.monthly))
+        : parseSpend(catalog, positionals);
     if (typeof spend === 'string') {
         io.stderr(`${spend}\n`);
         return USAGE_ERROR;
@@ -336,16 +214,22 @@ export async function runSimulate(argv, io) {
         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 started = dateProblem(values.start);
+    if (started !== null) {
+        io.stderr(`${started}\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('')}`);
+    if (values.wallet || values.cards !== undefined) {
+        const wallet = await cardsToUse(catalog, walletPath(io.env), io, {
+            cards: cardList(values.cards),
+            members: values.member ?? [],
+        });
+        if (wallet === null)
             return RUNTIME_ERROR;
+        if (wallet === 'none') {
+            io.stderr(`No saved wallet yet. Name your cards instead: --cards amex-gold,chase-prime-visa\n`);
+            return USAGE_ERROR;
         }
         const valued = values.valuation !== undefined && isValuationProfile(values.valuation)
             ? withValuationProfile(wallet, values.valuation)
@@ -353,12 +237,12 @@ export async function runSimulate(argv, io) {
         const result = simulateAdditions(catalog, valued, lines, options);
         io.stdout(values.json
             ? `${JSON.stringify(result, null, 2)}\n`
-            : formatAdditions(result, catalog, values.all ?? false));
+            : `${typical ? `${TYPICAL_SPEND_NOTE}\n\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));
+        : `${typical ? `${TYPICAL_SPEND_NOTE}\n\n` : ''}${formatCatalogSimulation(result, catalog, values.all ?? false)}`);
     return 0;
 }

package/dist/cli/import.js

@@ -6,13 +6,13 @@ import { z } from 'zod';
 import { CLI_NAME } from "../brand.js";
 import { walletProblems } from "../data/integrity.js";
 import { loadCatalog, walletPath } from "../data/load.js";
-import { writeBonusSpent, writeCapBooking } from "../data/wallet-write.js";
+import { writeProgress } from "../data/wallet-edit.js";
 import { isValuationProfile, withValuationProfile } from "../engine/profiles.js";
 import { cardValuation } from "../engine/valuation.js";
 import { analyzeStatement, } from "../import/analyze.js";
 import { parseStatement } from "../import/statement.js";
 import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
-export const IMPORT_HELP = `Usage: ${CLI_NAME} import <statement.csv> --card <card-id> [--apply]
+const IMPORT_HELP = `Usage: ${CLI_NAME} import <statement.csv> --card <card-id> [--apply]
        ${CLI_NAME} import <statement.csv>:<card-id> [<statement.csv>:<card-id> ...]
 
 Reads card statements (Amex and Chase activity CSVs) and reports:
@@ -241,12 +241,7 @@ export async function runImport(argv, io) {
             : `Nothing was written. Run again with --apply to record ${toRecord.join(' and ')}.\n`);
         return 0;
     }
-    for (const { booking } of analysis.bookings) {
-        await writeCapBooking(walletFile, booking);
-    }
-    for (const b of analysis.bonuses) {
-        await writeBonusSpent(walletFile, b.cardId, b.after);
-    }
+    await writeProgress(walletFile, analysis.bookings.map((e) => e.booking), analysis.bonuses);
     for (const entry of analysis.bookings)
         recorded.add(fingerprint(entry));
     for (const entry of bonusEntries)

package/dist/cli/offers.js

@@ -1,11 +1,12 @@
 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 { compareOffers, } from "../engine/offers.js";
+import { compareOffers } from "../engine/offers.js";
 import { isValuationProfile, withValuationProfile } from "../engine/profiles.js";
-import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
-export const OFFERS_HELP = `Usage: ${CLI_NAME} offers [--cash | --points] [--no-fee] [--business] [options]
+import { formatOffers } from "../format/offers.js";
+import { valuationProblem } from "./args.js";
+import { cardsToUse, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
+const OFFERS_HELP = `Usage: ${CLI_NAME} offers [--cash | --points] [--no-fee] [--business] [options]
 
 Ranks the welcome offers on cards you don't have by first-year value: the
 bonus at your point values minus the first year's annual fee.
@@ -21,48 +22,6 @@ Options:
   --json                 Print the full comparison as JSON.
   -h, --help             Show this help.
 `;
-const TOP = 10;
-const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
-function reward(o, currencyName) {
-    if (o.dollars !== null)
-        return usd(o.dollars);
-    return `${(o.points ?? 0).toLocaleString('en-US')} ${currencyName}`;
-}
-function feeText(o) {
-    if (o.annualFee === null)
-        return 'annual fee not on file';
-    if (o.annualFee === 0)
-        return 'no annual fee';
-    if (o.firstYearFee !== null && o.firstYearFee !== o.annualFee)
-        return `${usd(o.annualFee)} annual fee (${o.firstYearFee === 0 ? 'waived' : usd(o.firstYearFee)} the first year)`;
-    return `${usd(o.annualFee)} annual fee`;
-}
-export function formatOffers(c, currencyName, all) {
-    if (c.offers.length === 0) {
-        return `No published welcome offers match.${c.withoutOffer.length > 0 ? ` ${String(c.withoutOffer.length)} matching card(s) have none on file.` : ''}\n`;
-    }
-    const shown = all ? c.offers : c.offers.slice(0, TOP);
-    const width = Math.max(...shown.map((o) => o.cardName.length));
-    const lines = [];
-    shown.forEach((o, i) => {
-        const weeks = (o.months * 52) / 12;
-        const pace = o.spend > 0 ? ` (about ${usd(Math.round(o.spend / weeks))} a week)` : '';
-        const spend = o.spend > 0
-            ? `after ${usd(o.spend)} in ${String(o.months)} month${o.months === 1 ? '' : 's'}${pace}`
-            : 'with no spending required';
-        lines.push(`${String(i + 1).padStart(2)}. ${o.cardName.padEnd(width)}  about ${usd(Math.round(o.firstYearValue))} the first year`, `    ${reward(o, currencyName(o.currency))} ${spend}. ${feeText(o)[0]?.toUpperCase() ?? ''}${feeText(o).slice(1)}.${o.held ? ' In your wallet.' : ''}`);
-        if (o.validTo)
-            lines.push(`    Offer ends ${o.validTo}.`);
-        if (o.note)
-            lines.push(`    ${o.note}`);
-    });
-    if (c.offers.length > shown.length)
-        lines.push(`  + ${String(c.offers.length - shown.length)} more (--all lists them)`);
-    if (c.withoutOffer.length > 0)
-        lines.push('', `${String(c.withoutOffer.length)} matching card(s) have no published offer on file.`);
-    lines.push('', ...c.notes);
-    return `${lines.join('\n')}\n`;
-}
 export async function runOffers(argv, io) {
     let parsed;
     try {
@@ -94,20 +53,19 @@ export async function runOffers(argv, io) {
         io.stderr('Pick --cash or --points, not both.\n');
         return USAGE_ERROR;
     }
-    if (values.valuation !== undefined && !isValuationProfile(values.valuation)) {
-        io.stderr(`Unknown valuation "${values.valuation}". Use flat or points-heavy.\n`);
+    const problem = valuationProblem(values.valuation);
+    if (problem !== null) {
+        io.stderr(`${problem}\n`);
         return USAGE_ERROR;
     }
-    const walletFile = walletPath(io.env);
-    const loaded = await readWallet(walletFile, io);
-    if (!loaded)
-        return RUNTIME_ERROR;
     const catalog = await loadCatalog();
-    const problems = walletProblems(loaded, catalog);
-    if (problems.length > 0) {
-        io.stderr(`Your wallet at ${displayPath(walletFile)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+    const found = await cardsToUse(catalog, walletPath(io.env), io, {
+        cards: null,
+        members: [],
+    });
+    if (found === null)
         return RUNTIME_ERROR;
-    }
+    const loaded = found === 'none' ? { valuations: {}, memberships: [], cards: [] } : found;
     const wallet = values.valuation && isValuationProfile(values.valuation)
         ? withValuationProfile(loaded, values.valuation)
         : loaded;

package/dist/cli/run.js

@@ -1,26 +1,32 @@
+import { access } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CLI_NAME, CONFIG_DIR, LLM_ENV_VAR, LLM_MAX_CALLS_ENV_VAR, LLM_MODEL_ENV_VAR, MERCHANT_CACHE_ENV_VAR, WALLET_ENV_VAR, } from "../brand.js";
 import { walletProblems } from "../data/integrity.js";
 import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
-import { withValuationProfile } from "../engine/profiles.js";
+import { ALL_PERSONAL_CARDS, categoryResolution, exploreCards, findCategory, } from "../engine/explore.js";
+import { VALUATION_PROFILES, withValuationProfile } from "../engine/profiles.js";
 import { recommend } from "../engine/recommend.js";
+import { walletFromCards } from "../engine/transient.js";
+import { formatExploration } from "../format/explore.js";
+import { formatRecommendation, plain, } from "../format/recommendation.js";
 import { DEFAULT_LLM_MODEL } from "../merchants/anthropic.js";
 import { DEFAULT_MAX_CALLS } from "../merchants/fallback.js";
 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 { membershipProblem, parseCliArgs } from "./args.js";
 import { runCheatSheet } from "./cheatsheet.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]
+const HELP = `Usage: ${CLI_NAME} <merchant> [amount] [options]
 
-Picks the card in your wallet that earns the most at a merchant, and says why.
+Picks the card that earns the most at a merchant, and says why: from your
+wallet if you've saved one, from cards you name with --cards, or else from
+every card earnrate knows.
 
 Examples:
   ${CLI_NAME} whole foods 80
@@ -31,7 +37,7 @@ 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:
+Save your cards (optional):
   ${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.
@@ -39,10 +45,10 @@ Set up your wallet:
   ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime).
 
 Other commands:
-  ${CLI_NAME} cheatsheet                           Your best card for each category this quarter.
+  ${CLI_NAME} cheatsheet                           The best card for each category this quarter.
   ${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.
+  ${CLI_NAME} mcp                                  Run the MCP server over stdio, for AI assistants.
   Add --help to any command for its options.
 
 Options:
@@ -53,6 +59,9 @@ Options:
   --json                 Print the full recommendation as JSON.
   --date <YYYY-MM-DD>    Purchase date. Default: today.
   --country <code>       Where you're paying. Default: US.
+  --cards <ids>          Answer for these cards instead of your wallet, comma
+                         separated: --cards amex-gold,chase-prime-visa.
+  --member <name>        A membership you have, with --cards or no wallet.
   --category <id>        For a merchant earnrate doesn't know: its category,
                          e.g. grocery.supermarket. Ignored for known merchants.
   --llm, --no-llm        Ask Claude to classify merchants earnrate doesn't know.
@@ -75,6 +84,42 @@ export function displayPath(file) {
     const home = homedir();
     return file.startsWith(`${home}/`) ? `~${file.slice(home.length)}` : file;
 }
+// The cards to answer for: those named with --cards, else the wallet file.
+// 'none' means no wallet and no --cards, which answers from every card.
+export async function cardsToUse(catalog, file, io, named) {
+    const problem = membershipProblem(catalog, named.members);
+    if (problem !== null) {
+        io.stderr(`${problem}\n`);
+        return null;
+    }
+    if (named.cards !== null) {
+        const wallet = walletFromCards(catalog, {
+            cards: named.cards.map((id) => ({ id })),
+            memberships: named.members,
+        }, io.today);
+        if (typeof wallet === 'string') {
+            io.stderr(`${wallet}\n`);
+            return null;
+        }
+        return wallet;
+    }
+    try {
+        await access(file);
+    }
+    catch {
+        return 'none';
+    }
+    const loaded = await readWallet(file, io);
+    if (!loaded)
+        return null;
+    const problems = walletProblems(loaded, catalog);
+    if (problems.length > 0) {
+        io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+        return null;
+    }
+    return loaded;
+}
+export const NO_WALLET_HINT = `These are every card earnrate knows. For the best of your own cards, name them with --cards amex-gold,chase-prime-visa, or save them: ${CLI_NAME} add <card-id> (${CLI_NAME} cards finds ids).`;
 export async function readWallet(file, io) {
     try {
         return await loadWallet(file);
@@ -119,19 +164,10 @@ export async function run(argv, io) {
     }
     const { options } = args;
     const llmOn = options.llm ?? llmEnabled(io.env);
-    const file = walletPath(io.env);
-    const loaded = await readWallet(file, io);
-    if (!loaded)
-        return RUNTIME_ERROR;
     const catalog = await loadCatalog();
-    const problems = walletProblems(loaded, catalog);
-    if (problems.length > 0) {
-        io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+    const loaded = await cardsToUse(catalog, walletPath(io.env), io, options);
+    if (loaded === null)
         return RUNTIME_ERROR;
-    }
-    const wallet = options.valuation
-        ? withValuationProfile(loaded, options.valuation)
-        : loaded;
     const purchase = {
         merchant: options.merchant,
         amount: options.amount,
@@ -144,7 +180,14 @@ export async function run(argv, io) {
         io.stderr(`Unknown category "${options.category}". Use one of: ${catalog.categories.map((c) => c.id).join(', ')}.\n`);
         return USAGE_ERROR;
     }
-    let merchant = withCallerCategory(resolveMerchant(catalog, purchase.merchant, purchase.channel), options.category);
+    // Plain category words ("restaurants", "groceries") work like stores.
+    const resolvedName = resolveMerchant(catalog, purchase.merchant, purchase.channel);
+    const named = resolvedName.source === 'none' && options.category === null
+        ? findCategory(catalog, purchase.merchant)
+        : null;
+    let merchant = named === null
+        ? withCallerCategory(resolvedName, options.category)
+        : categoryResolution(catalog, named, purchase.channel);
     const notices = [];
     if (llmOn && merchant.source === 'none') {
         const opened = await openLlmSession({
@@ -161,6 +204,33 @@ export async function run(argv, io) {
         merchant = resolved.merchant;
         notices.push(...resolved.notices);
     }
+    if (loaded === 'none') {
+        const explored = exploreCards(catalog, {
+            merchant: purchase.merchant,
+            category: null,
+            amount: purchase.amount,
+            channel: purchase.channel,
+            date: purchase.date,
+        }, {
+            filters: ALL_PERSONAL_CARDS,
+            memberships: options.members,
+            valuations: options.valuation
+                ? VALUATION_PROFILES[options.valuation]
+                : {},
+        }, merchant);
+        if (options.json) {
+            io.stdout(`${JSON.stringify(explored, null, 2)}\n`);
+        }
+        else {
+            io.stdout(`${formatExploration(explored, options.all)}\n${NO_WALLET_HINT}\n`);
+        }
+        for (const n of notices)
+            io.stderr(`${n}\n`);
+        return 0;
+    }
+    const wallet = options.valuation
+        ? withValuationProfile(loaded, options.valuation)
+        : loaded;
     const rec = recommend(catalog, wallet, purchase, merchant);
     if (options.json) {
         io.stdout(`${JSON.stringify(rec, null, 2)}\n`);