earnrate 0.2.0 → 0.2.2

package/dist/cli/args.js

@@ -1,5 +1,8 @@
 import { parseArgs } from 'node:util';
 import { isValuationProfile, } from "../engine/profiles.js";
+import { knownMemberships } from "../engine/setup.js";
+// Shared by every subcommand, so each flag means the same thing everywhere.
+// A string result is the error to show.
 const LOOKS_LIKE_AMOUNT = /^\$?[\d,]*\.?\d+$/;
 const AMOUNT = /^\$?(\d{1,3}(,\d{3})+|\d+)(\.\d{1,2})?$/;
 function parseAmount(text) {
@@ -9,11 +12,54 @@ function parseAmount(text) {
     const amount = Number(text.replace(/[$,]/g, ''));
     return amount > 0 ? amount : 'The amount must be more than $0.';
 }
-function isValidDate(text) {
-    if (!/^\d{4}-\d{2}-\d{2}$/.test(text))
-        return false;
+// A trailing number is the amount only when something comes before it, so
+// a merchant named "76" still works on its own.
+export function splitAmount(positionals) {
+    const words = [...positionals];
+    const last = words.at(-1);
+    let amount = null;
+    if (words.length > 1 && last !== undefined && LOOKS_LIKE_AMOUNT.test(last)) {
+        const result = parseAmount(last);
+        if (typeof result === 'string')
+            return result;
+        amount = result;
+        words.pop();
+    }
+    return { text: words.join(' ').trim(), amount };
+}
+export function dateProblem(text) {
+    if (text === undefined)
+        return null;
     const date = new Date(`${text}T00:00:00Z`);
-    return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(text);
+    return /^\d{4}-\d{2}-\d{2}$/.test(text) &&
+        !Number.isNaN(date.getTime()) &&
+        date.toISOString().startsWith(text)
+        ? null
+        : `"${text}" isn't a date. Use YYYY-MM-DD.`;
+}
+export function valuationProblem(text) {
+    return text === undefined || isValuationProfile(text)
+        ? null
+        : `Unknown valuation "${text}". Use flat or points-heavy.`;
+}
+export function membershipProblem(catalog, members) {
+    const known = knownMemberships(catalog);
+    const unknown = members.filter((m) => !known.includes(m));
+    return unknown.length === 0
+        ? null
+        : `Unknown membership "${unknown.join('", "')}". Use one of: ${known.join(', ')}.`;
+}
+export const BOTH_CHANNELS = 'Pick --online or --in-store, not both.';
+export function channelOf(values) {
+    return values.online ? 'online' : values['in-store'] ? 'in_store' : null;
+}
+export function cardList(text) {
+    return text === undefined
+        ? null
+        : text
+            .split(',')
+            .map((c) => c.trim())
+            .filter((c) => c !== '');
 }
 export function parseCliArgs(argv) {
     let parsed;
@@ -47,49 +93,21 @@ export function parseCliArgs(argv) {
     const { values, positionals } = parsed;
     if (values.help)
         return { kind: 'help' };
-    // A trailing number is the amount only when something comes before it, so
-    // a merchant named "76" still works on its own.
-    const words = [...positionals];
-    let amount = null;
-    const last = words.at(-1);
-    if (words.length > 1 && last !== undefined && LOOKS_LIKE_AMOUNT.test(last)) {
-        const result = parseAmount(last);
-        if (typeof result === 'string')
-            return { kind: 'error', message: result };
-        amount = result;
-        words.pop();
-    }
-    const merchant = words.join(' ').trim();
+    const split = splitAmount(positionals);
+    if (typeof split === 'string')
+        return { kind: 'error', message: split };
+    const { text: merchant, amount } = split;
     if (merchant === '') {
         return { kind: 'error', message: 'Name a merchant, like "whole foods".' };
     }
-    if (values.online && values['in-store']) {
-        return {
-            kind: 'error',
-            message: 'Pick one of --online and --in-store.',
-        };
-    }
-    const channel = values.online
-        ? 'online'
-        : values['in-store']
-            ? 'in_store'
-            : null;
-    let valuation = null;
-    if (values.valuation !== undefined) {
-        if (!isValuationProfile(values.valuation)) {
-            return {
-                kind: 'error',
-                message: `Unknown valuation "${values.valuation}". Use flat or points-heavy.`,
-            };
-        }
-        valuation = values.valuation;
-    }
-    if (values.date !== undefined && !isValidDate(values.date)) {
-        return {
-            kind: 'error',
-            message: `"${values.date}" isn't a date. Use YYYY-MM-DD.`,
-        };
-    }
+    if (values.online && values['in-store'])
+        return { kind: 'error', message: BOTH_CHANNELS };
+    const problem = valuationProblem(values.valuation) ?? dateProblem(values.date);
+    if (problem !== null)
+        return { kind: 'error', message: problem };
+    const valuation = values.valuation !== undefined && isValuationProfile(values.valuation)
+        ? values.valuation
+        : null;
     const country = values.country ?? 'US';
     if (!/^[A-Za-z]{2}$/.test(country)) {
         return {
@@ -102,7 +120,7 @@ export function parseCliArgs(argv) {
         options: {
             merchant,
             amount,
-            channel,
+            channel: channelOf(values),
             valuation,
             date: values.date ?? null,
             country: country.toUpperCase(),
@@ -110,12 +128,7 @@ export function parseCliArgs(argv) {
             all: values.all ?? false,
             category: values.category ?? null,
             llm: values.llm ?? null,
-            cards: values.cards === undefined
-                ? null
-                : values.cards
-                    .split(',')
-                    .map((c) => c.trim())
-                    .filter((c) => c !== ''),
+            cards: cardList(values.cards),
             members: values.member ?? [],
         },
     };

package/dist/cli/cheatsheet.js

@@ -2,11 +2,12 @@ import { parseArgs } from 'node:util';
 import { CLI_NAME } from "../brand.js";
 import { loadCatalog, walletPath } from "../data/load.js";
 import { catalogCheatSheet, cheatSheet } from "../engine/cheat-sheet.js";
-import { formatCheatSheet } from "../format/cheat-sheet.js";
 import { ALL_PERSONAL_CARDS } from "../engine/explore.js";
 import { isValuationProfile, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
+import { formatCheatSheet } from "../format/cheat-sheet.js";
+import { cardList, dateProblem, valuationProblem } from "./args.js";
 import { cardsToUse, NO_WALLET_HINT, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
-export const CHEATSHEET_HELP = `Usage: ${CLI_NAME} cheatsheet [options]
+const CHEATSHEET_HELP = `Usage: ${CLI_NAME} cheatsheet [options]
 
 The card to use for each everyday kind of purchase this quarter: from your
 wallet (with your caps, picks and activations as they are now), from cards you
@@ -44,21 +45,18 @@ export async function runCheatSheet(argv, io) {
         io.stdout(CHEATSHEET_HELP);
         return 0;
     }
-    if (values.valuation !== undefined && !isValuationProfile(values.valuation)) {
-        io.stderr(`Unknown valuation "${values.valuation}". Use flat or points-heavy.\n`);
-        return USAGE_ERROR;
-    }
-    if (values.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(values.date)) {
-        io.stderr(`"${values.date}" isn't a date. Use YYYY-MM-DD.\n`);
+    const problem = valuationProblem(values.valuation) ?? dateProblem(values.date);
+    if (problem !== null) {
+        io.stderr(`${problem}\n`);
         return USAGE_ERROR;
     }
-    const loaded = await cardsToUse(walletPath(io.env), io, {
-        cards: values.cards === undefined ? null : values.cards.split(','),
+    const catalog = await loadCatalog();
+    const loaded = await cardsToUse(catalog, walletPath(io.env), io, {
+        cards: cardList(values.cards),
         members: values.member ?? [],
     });
     if (loaded === null)
         return RUNTIME_ERROR;
-    const catalog = await loadCatalog();
     const date = values.date ?? io.today;
     if (loaded === 'none') {
         const sheet = catalogCheatSheet(catalog, date, {
@@ -82,4 +80,3 @@ export async function runCheatSheet(argv, io) {
         : formatCheatSheet(sheet));
     return 0;
 }
-export { formatCheatSheet };

package/dist/cli/explore.js

@@ -4,8 +4,8 @@ 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, spendLineFor, TYPICAL_MONTHLY_SPEND, TYPICAL_SPEND_NOTE, } from "../engine/simulate.js";
-import { knownMemberships } from "../engine/setup.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.
@@ -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,7 +33,7 @@ ${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
@@ -70,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,
@@ -117,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();
@@ -144,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
@@ -156,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);
@@ -217,10 +214,15 @@ 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 || values.cards !== undefined) {
-        const wallet = await cardsToUse(walletPath(io.env), io, {
-            cards: values.cards === undefined ? null : values.cards.split(','),
+        const wallet = await cardsToUse(catalog, walletPath(io.env), io, {
+            cards: cardList(values.cards),
             members: values.member ?? [],
         });
         if (wallet === null)
@@ -244,4 +246,3 @@ export async function runSimulate(argv, io) {
         : `${typical ? `${TYPICAL_SPEND_NOTE}\n\n` : ''}${formatCatalogSimulation(result, catalog, values.all ?? false)}`);
     return 0;
 }
-export { formatAdditions, formatCatalogSimulation, formatExploration };

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

@@ -4,8 +4,9 @@ import { loadCatalog, walletPath } from "../data/load.js";
 import { compareOffers } from "../engine/offers.js";
 import { isValuationProfile, withValuationProfile } from "../engine/profiles.js";
 import { formatOffers } from "../format/offers.js";
+import { valuationProblem } from "./args.js";
 import { cardsToUse, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
-export const OFFERS_HELP = `Usage: ${CLI_NAME} offers [--cash | --points] [--no-fee] [--business] [options]
+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.
@@ -52,17 +53,18 @@ 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 found = await cardsToUse(walletPath(io.env), io, {
+    const catalog = await loadCatalog();
+    const found = await cardsToUse(catalog, walletPath(io.env), io, {
         cards: null,
         members: [],
     });
     if (found === null)
         return RUNTIME_ERROR;
-    const catalog = await loadCatalog();
     const loaded = found === 'none' ? { valuations: {}, memberships: [], cards: [] } : found;
     const wallet = values.valuation && isValuationProfile(values.valuation)
         ? withValuationProfile(loaded, values.valuation)
@@ -81,4 +83,3 @@ export async function runOffers(argv, io) {
     io.stdout(formatOffers(comparison, currencyName, values.all ?? false));
     return 0;
 }
-export { formatOffers };

package/dist/cli/run.js

@@ -5,23 +5,24 @@ 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 { VALUATION_PROFILES, 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 { formatExploration, runBest, runSimulate } from "./explore.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 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
@@ -36,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.
@@ -44,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:
@@ -85,8 +86,12 @@ export function displayPath(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(file, io, named) {
-    const catalog = await loadCatalog();
+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 })),
@@ -159,11 +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 cardsToUse(file, io, options);
+    const catalog = await loadCatalog();
+    const loaded = await cardsToUse(catalog, walletPath(io.env), io, options);
     if (loaded === null)
         return RUNTIME_ERROR;
-    const catalog = await loadCatalog();
     const purchase = {
         merchant: options.merchant,
         amount: options.amount,

package/dist/cli/wallet.js

@@ -1,9 +1,9 @@
 import { parseArgs } from 'node:util';
 import { CLI_NAME } from "../brand.js";
+import { FileWalletStore } from "../data/file-store.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 { formatCardInfo, formatNotes } from "../format/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".
@@ -148,6 +148,7 @@ export async function runWalletCommand(command, argv, io) {
     const catalog = await loadCatalog();
     const file = walletPath(io.env);
     const where = displayPath(file);
+    const store = new FileWalletStore(catalog, file);
     if (command === 'cards') {
         const query = positionals.join(' ');
         const result = searchCards(catalog, query, await heldWallet(io), io.today);
@@ -169,7 +170,7 @@ export async function runWalletCommand(command, argv, io) {
             return usage('Give memberships or --none, not both.');
         }
         const list = values.none ? [] : positionals;
-        return report(await setMemberships(file, catalog, list), list.length > 0
+        return report(await store.setMemberships(list), list.length > 0
             ? `Memberships set to ${list.join(', ')} in ${where}.`
             : `Memberships cleared in ${where}.`, null, io);
     }
@@ -179,7 +180,7 @@ export async function runWalletCommand(command, argv, io) {
     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);
+        return report(await store.removeCard(id), `Removed ${name} from ${where}.`, null, io);
     }
     const input = { id };
     if (values.label !== undefined)
@@ -227,8 +228,8 @@ export async function runWalletCommand(command, argv, io) {
         return usage('Give --bonus-opened with the other --bonus options.');
     }
     if (command === 'add') {
-        const result = await addCard(file, catalog, input, io.today);
+        const result = await store.addCard(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);
+    return report(await store.updateCard(input, io.today), `Updated ${name} in ${where}.`, id, io);
 }

package/dist/data/file-store.js

@@ -1,9 +1,22 @@
 import { bookPurchase } from "../engine/record.js";
+import { addToWallet, removeFromWallet, updateInWallet, withMemberships, } from "../engine/wallet-change.js";
 import { loadWallet } from "./load.js";
-import { addCard, removeCard, setMemberships, updateCard, } from "./wallet-setup.js";
-import { withWalletLock, writeBonusSpent, writeCapBooking, } from "./wallet-write.js";
-// The wallet as a YAML file (the CLI, the local MCP server, the .mcpb and the
-// local plugin). Edits splice lines so the user's comments survive.
+import { addCardText, commitWalletText, readWalletText, removeCardText, setMembershipsText, updateCardText, writeProgress, } from "./wallet-edit.js";
+const failed = (error) => ({ ok: false, error });
+const errorText = (e) => (e instanceof Error ? e.message : String(e));
+const queues = new Map();
+// Runs `task` after every earlier task for the same file has settled, so a
+// read-modify-write of the wallet never interleaves with another.
+function withWalletLock(file, task) {
+    const previous = queues.get(file) ?? Promise.resolve();
+    const run = previous.then(task, task);
+    queues.set(file, run.catch(() => undefined));
+    return run;
+}
+// The wallet as a YAML file (the CLI, the local MCP server and the .mcpb).
+// Each change is worked out on the parsed wallet, then spliced into the text,
+// which must re-parse to exactly that wallet before it's written, so the
+// user's comments survive.
 export class FileWalletStore {
     where;
     catalog;
@@ -21,34 +34,60 @@ export class FileWalletStore {
             throw e;
         }
     }
+    change(plan, edit) {
+        return withWalletLock(this.where, async () => {
+            try {
+                const { text, wallet } = await readWalletText(this.where);
+                const change = plan(wallet);
+                if (typeof change === 'string')
+                    return failed(change);
+                if (!change.ok)
+                    return change;
+                await commitWalletText(this.where, edit(text, change), change.wallet);
+                return {
+                    ok: true,
+                    wallet: change.wallet,
+                    created: text === null,
+                    notes: change.notes,
+                };
+            }
+            catch (e) {
+                return failed(errorText(e));
+            }
+        });
+    }
+    // Changes other than adding a card need a wallet file to change.
+    existing(apply) {
+        return (wallet) => wallet === null
+            ? `No wallet at ${this.where} yet. Add a card first to create it.`
+            : apply(wallet);
+    }
     addCard(input, today) {
-        return withWalletLock(this.where, () => addCard(this.where, this.catalog, input, today));
+        return this.change((wallet) => addToWallet(this.catalog, wallet, input, today), (text, change) => addCardText(text, { id: input.id, ...change.fields }));
     }
     updateCard(input, today) {
-        return withWalletLock(this.where, () => updateCard(this.where, this.catalog, input, today));
+        return this.change(this.existing((w) => updateInWallet(this.catalog, w, input, today)), (text, change) => updateCardText(text ?? '', input.id, change.fields));
     }
     removeCard(cardId) {
-        return withWalletLock(this.where, () => removeCard(this.where, this.catalog, cardId));
+        return this.change(this.existing((w) => removeFromWallet(w, cardId)), (text) => removeCardText(text ?? '', cardId));
     }
     setMemberships(memberships) {
-        return withWalletLock(this.where, () => setMemberships(this.where, this.catalog, memberships));
+        return this.change(this.existing((w) => withMemberships(this.catalog, w, memberships)), (text, change) => setMembershipsText(text ?? '', change.wallet.memberships));
     }
     record(purchase, merchant) {
         return withWalletLock(this.where, async () => {
             const wallet = await this.load();
             if (!wallet)
-                return { ok: false, error: "There's no saved wallet to record it in." };
+                return failed("There's no saved wallet to record it in.");
             if (!wallet.cards.some((c) => c.id === purchase.cardId))
-                return { ok: false, error: `${purchase.cardId} isn't in the wallet.` };
+                return failed(`${purchase.cardId} isn't in the wallet.`);
             const booked = bookPurchase(this.catalog, wallet, purchase, merchant);
             try {
-                if (booked.cap)
-                    await writeCapBooking(this.where, booked.cap);
-                if (booked.bonus)
-                    await writeBonusSpent(this.where, purchase.cardId, booked.bonus.after);
+                if (booked.cap || booked.bonus)
+                    await writeProgress(this.where, booked.cap ? [booked.cap] : [], booked.bonus ? [booked.bonus] : []);
             }
             catch (e) {
-                return { ok: false, error: e instanceof Error ? e.message : String(e) };
+                return failed(errorText(e));
             }
             return { ok: true, ...booked };
         });

package/dist/data/load.js

@@ -11,7 +11,7 @@ import { CurrenciesFileSchema } from "../schema/currency.js";
 import { MerchantsFileSchema } from "../schema/merchant.js";
 import { WalletSchema } from "../schema/wallet.js";
 export const DATA_DIR = fileURLToPath(new URL('../../data/', import.meta.url));
-export async function readYaml(file, schema) {
+async function readYaml(file, schema) {
     const raw = parse(await readFile(file, 'utf8'));
     const result = schema.safeParse(raw);
     if (!result.success) {