driggsby 0.7.5 → 0.8.0

package/README.md

@@ -117,9 +117,19 @@ counterparty's name, or tags on a set of transactions. `rules describe`
 prints the rule format and the process. `rules preview` shows exactly what a
 new or changed rule would do and returns the confirm token `rules save`
 needs to apply it; renaming, pausing, or resuming a rule needs its
-`rule_ref` and no preview. `rules delete` needs `--yes`. Every action prints JSON. If you
-signed in with an earlier version of the CLI, run
-`npx driggsby@latest login` once more to use rules.
+`rule_ref` and no preview. `rules delete` needs `--yes`. Every action prints
+JSON.
+
+## Items
+
+`npx driggsby@latest items` saves and removes the items behind your charges:
+what an order or a receipt actually bought, each in a category, so Driggsby
+counts a charge by what was in it. `items describe` prints the item format
+and the process. `items save --params-file order.json` saves the items of up
+to 25 charges (saving a charge again replaces its items); each charge is
+saved or refused on its own, and the JSON result says which and why.
+`items delete` needs `--yes`. Read items back with
+`npx driggsby@latest query query_item_sql --sql "..."`.
 
 ## License
 

package/dist/args-items.js

@@ -0,0 +1,24 @@
+// Argv parsing for `driggsby items <ACTION> [--params <JSON> | --params-file
+// <PATH>] [--yes]`: the rules command's grammar (args-rules.ts) over the
+// item tools.
+import { parseActionCommand } from "./args-rules.js";
+import {} from "./args-shared.js";
+import { ITEMS_HELP } from "./help.js";
+import { isItemAction, ITEM_ACTIONS } from "./items/item-actions.js";
+const ITEMS_SPEC = {
+    name: "items",
+    article: "an",
+    usage: "Usage: npx driggsby@latest items <ACTION> [--params <JSON>] [--yes]",
+    help: ITEMS_HELP,
+    actions: ITEM_ACTIONS,
+    isAction: isItemAction,
+    describeAction: "describe",
+    deleteAction: "delete",
+    deleteNeedsYes: "error: removing a charge's items can't be undone — Spending counts it whole\n" +
+        "again. To remove them, run the same command again with --yes.",
+    exampleParams: `'{"transaction_refs":["txn_..."]}'`,
+};
+export function parseItems(argv) {
+    const parsed = parseActionCommand(argv, ITEMS_SPEC);
+    return parsed.kind === "action" ? { kind: "items", action: parsed.action, params: parsed.params, yes: parsed.yes } : parsed;
+}

package/dist/args-query.js

@@ -1,7 +1,7 @@
 // Argv parsing for `driggsby query <TOOL> [--sql <SQL>] [--params <JSON>]`.
 // Same behavior contract as the rest of the tree: help on -h/--help, usage
 // errors exit 2, echoed argv is sanitized. The tool is checked against the
-// allowlist here so a typo is a usage error naming the twelve, not a
+// allowlist here so a typo is a usage error naming the thirteen, not a
 // server round trip.
 import { helpCommand, unexpectedArgument } from "./args-shared.js";
 import { didYouMean } from "./clap-suggestions.js";
@@ -9,9 +9,9 @@ import { CliError } from "./cli-error.js";
 import { APP_TOOL_ALLOWLIST } from "./dev/tool-allowlist.js";
 import { QUERY_HELP } from "./help.js";
 import { quotedForTerminal, wrapNames } from "./terminal-text.js";
-// The two tools that take SQL: --sql applies only to these, and a retry
+// The tools that take SQL: --sql applies only to these, and a retry
 // line names --sql only for them.
-export const SQL_TOOLS = new Set(["query_cash_sql", "query_investment_sql"]);
+export const SQL_TOOLS = new Set(["query_cash_sql", "query_investment_sql", "query_item_sql"]);
 const QUERY_USAGE = "Usage: npx driggsby@latest query <TOOL> [--sql <SQL>] [--params <JSON>]";
 export function parseQuery(argv) {
     let tool = null;
@@ -114,7 +114,7 @@ function unknownTool(tool) {
         `${wrapNames([...APP_TOOL_ALLOWLIST], "  ")}\n\n${tip}${QUERY_USAGE}\n\nFor more information, try '--help'.`, 2);
 }
 function sqlForNonSqlTool(tool) {
-    return new CliError(`error: '--sql' only applies to query_cash_sql or query_investment_sql;\n` +
+    return new CliError(`error: '--sql' only applies to query_cash_sql, query_investment_sql, or query_item_sql;\n` +
         `'${tool}' takes no SQL.\n\n` +
         `${QUERY_USAGE}\n\nFor more information, try '--help'.`, 2);
 }

package/dist/args-rules.js

@@ -12,11 +12,28 @@ import { RULES_HELP } from "./help.js";
 import { isRuleAction, RULE_ACTIONS } from "./rules/rule-actions.js";
 import { quotedForTerminal } from "./terminal-text.js";
 const RULES_USAGE = "Usage: npx driggsby@latest rules <ACTION> [--params <JSON>] [--yes]";
+const RULES_SPEC = {
+    name: "rules",
+    article: "a",
+    usage: RULES_USAGE,
+    help: RULES_HELP,
+    actions: RULE_ACTIONS,
+    isAction: isRuleAction,
+    describeAction: "describe",
+    deleteAction: "delete",
+    deleteNeedsYes: "error: deleting a rule can't be undone — its categories and tags come off every\n" +
+        "transaction it covers. To delete it, run the same command again with --yes.",
+    exampleParams: `'{"rule_ref":"rule_..."}'`,
+};
 // A saved rule with learned patterns and its answers is a few KB; this
 // bounds a mistaken path to something like a log file.
 export const MAX_PARAMS_FILE_BYTES = 1_048_576;
 const MAX_PARAMS_FILE_MB = String(MAX_PARAMS_FILE_BYTES / 1_048_576);
 export function parseRules(argv) {
+    const parsed = parseActionCommand(argv, RULES_SPEC);
+    return parsed.kind === "action" ? { kind: "rules", action: parsed.action, params: parsed.params, yes: parsed.yes } : parsed;
+}
+export function parseActionCommand(argv, spec) {
     let actionToken = null;
     let source = null;
     let yes = false;
@@ -28,24 +45,24 @@ export function parseRules(argv) {
             continue;
         }
         if (!optionsEnded && (token === "-h" || token === "--help")) {
-            return helpCommand(RULES_HELP);
+            return helpCommand(spec.help);
         }
         if (!optionsEnded && token === "--yes") {
             yes = true;
             continue;
         }
         if (!optionsEnded && token.startsWith("--yes=")) {
-            throw unexpectedFlagValue("--yes", token.slice("--yes=".length), RULES_USAGE);
+            throw unexpectedFlagValue("--yes", token.slice("--yes=".length), spec.usage);
         }
         const flag = !optionsEnded ? paramsFlag(token) : null;
         if (flag !== null) {
             if (source !== null) {
-                throw usageError("error: give the params once, with either --params or --params-file");
+                throw usageError("error: give the params once, with either --params or --params-file", spec);
             }
             const attached = token.length > flag.length;
             const value = attached ? token.slice(flag.length + 1) : argv[index + 1];
             if (value === undefined || value === "" || (!attached && value.length > 1 && value.startsWith("-"))) {
-                throw usageError(`error: a value is required for '${flag}' but none was supplied`);
+                throw usageError(`error: a value is required for '${flag}' but none was supplied`, spec);
             }
             source = flag === "--params" ? { flag, json: value } : { flag, path: value };
             index += attached ? 0 : 1;
@@ -55,26 +72,25 @@ export function parseRules(argv) {
             actionToken = token;
             continue;
         }
-        throw unexpectedArgument(token, RULES_USAGE);
+        throw unexpectedArgument(token, spec.usage);
     }
     if (actionToken === null) {
-        throw usageError("error: the following required arguments were not provided:\n  <ACTION>");
+        throw usageError("error: the following required arguments were not provided:\n  <ACTION>", spec);
     }
-    if (!isRuleAction(actionToken)) {
-        throw unknownAction(actionToken);
+    if (!spec.isAction(actionToken)) {
+        throw unknownAction(actionToken, spec);
     }
     const action = actionToken;
-    if (action === "describe" && source !== null) {
-        throw usageError("error: rules describe takes no params");
+    if (action === spec.describeAction && source !== null) {
+        throw usageError(`error: ${spec.name} ${spec.describeAction} takes no params`, spec);
     }
-    if (action === "delete" && !yes) {
-        throw usageError("error: deleting a rule can't be undone — its categories and tags come off every\n" +
-            "transaction it covers. To delete it, run the same command again with --yes.");
+    if (action === spec.deleteAction && !yes) {
+        throw usageError(spec.deleteNeedsYes, spec);
     }
-    if (action !== "delete" && yes) {
-        throw usageError("error: '--yes' only applies to rules delete");
+    if (action !== spec.deleteAction && yes) {
+        throw usageError(`error: '--yes' only applies to ${spec.name} ${spec.deleteAction}`, spec);
     }
-    return { kind: "rules", action, params: source === null ? {} : resolveParams(source), yes };
+    return { kind: "action", action, params: source === null ? {} : resolveParams(source, spec), yes };
 }
 // "--params", "--params=…", "--params-file", "--params-file=…" → the flag.
 function paramsFlag(token) {
@@ -85,13 +101,13 @@ function paramsFlag(token) {
     }
     return null;
 }
-function resolveParams(source) {
+function resolveParams(source, spec) {
     if (source.flag === "--params") {
-        return parseParamsObject(source.json, "--params", "\nFor JSON that's hard to quote in this shell, save it to a file and pass\n--params-file <PATH> instead.");
+        return parseParamsObject(source.json, "--params", "\nFor JSON that's hard to quote in this shell, save it to a file and pass\n--params-file <PATH> instead.", spec);
     }
-    return parseParamsObject(readParamsFile(source.path), "--params-file", "");
+    return parseParamsObject(readParamsFile(source.path, spec), "--params-file", "", spec);
 }
-function parseParamsObject(rawValue, flag, hint) {
+function parseParamsObject(rawValue, flag, hint, spec) {
     let parsed;
     try {
         parsed = JSON.parse(rawValue);
@@ -100,7 +116,7 @@ function parseParamsObject(rawValue, flag, hint) {
         parsed = null;
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw usageError(`error: invalid value for '${flag}':\n'${flag}' must be a JSON object, like '{"rule_ref":"rule_..."}'${hint}`);
+        throw usageError(`error: invalid value for '${flag}':\n'${flag}' must be a JSON object, like ${spec.exampleParams}${hint}`, spec);
     }
     return parsed;
 }
@@ -110,7 +126,7 @@ function parseParamsObject(rawValue, flag, hint) {
 // read). Special files are refused before they are opened, since opening a
 // FIFO blocks; on POSIX the open is also non-blocking, so a FIFO swapped in
 // after the check is refused by the fstat instead of hanging.
-function readParamsFile(path) {
+function readParamsFile(path, spec) {
     let bytes;
     try {
         if (!statSync(path).isFile()) {
@@ -119,10 +135,10 @@ function readParamsFile(path) {
         bytes = readAtMost(path, MAX_PARAMS_FILE_BYTES + 1);
     }
     catch (error) {
-        throw usageError(`error: couldn't read the --params-file: ${paramsFileProblem(error)}`);
+        throw usageError(`error: couldn't read the --params-file: ${paramsFileProblem(error)}`, spec);
     }
     if (bytes.length > MAX_PARAMS_FILE_BYTES) {
-        throw usageError(`error: couldn't read the --params-file: it's over ${MAX_PARAMS_FILE_MB} MB`);
+        throw usageError(`error: couldn't read the --params-file: it's over ${MAX_PARAMS_FILE_MB} MB`, spec);
     }
     return decodeParamsFile(bytes);
 }
@@ -172,11 +188,11 @@ function decodeParamsFile(bytes) {
     const text = bytes.toString("utf8");
     return text.startsWith("\uFEFF") ? text.slice(1) : text;
 }
-function unknownAction(token) {
-    const similar = didYouMean(token, RULE_ACTIONS);
+function unknownAction(token, spec) {
+    const similar = didYouMean(token, spec.actions);
     const tip = similar === undefined ? "" : `\n\n  tip: a similar action exists: '${similar}'`;
-    return usageError(`error: ${quotedForTerminal(token, 60)} isn't a rules action. Actions: ${RULE_ACTIONS.join(", ")}.${tip}`);
+    return usageError(`error: ${quotedForTerminal(token, 60)} isn't ${spec.article} ${spec.name} action. Actions: ${spec.actions.join(", ")}.${tip}`, spec);
 }
-function usageError(firstLines) {
-    return new CliError(`${firstLines}\n\n${RULES_USAGE}\n\nFor more information, try '--help'.`, 2);
+function usageError(firstLines, spec) {
+    return new CliError(`${firstLines}\n\n${spec.usage}\n\nFor more information, try '--help'.`, 2);
 }

package/dist/args-shared.js

@@ -4,6 +4,7 @@
 // terminal through an echoed argument, tip, or usage line.
 import { CliError } from "./cli-error.js";
 import {} from "./mcp-setup/known-client.js";
+import {} from "./items/item-actions.js";
 import {} from "./rules/rule-actions.js";
 import { sanitizeForTerminal } from "./terminal-text.js";
 export function helpCommand(text) {

package/dist/args.js

@@ -13,6 +13,7 @@ import { parseInit } from "./args-init.js";
 import { parseLogin } from "./args-login.js";
 import { parseMcpSetup } from "./args-mcp-setup.js";
 import { parseQuery } from "./args-query.js";
+import { parseItems } from "./args-items.js";
 import { parseRules } from "./args-rules.js";
 import { removeDashesTip, similarArgumentTip, unexpectedArgument, unexpectedFlagValue, } from "./args-shared.js";
 import { didYouMean } from "./clap-suggestions.js";
@@ -25,7 +26,7 @@ const MCP_USAGE = "Usage: npx driggsby@latest mcp <COMMAND>";
 const ROOT_LEVEL = {
     helpText: ROOT_HELP,
     usage: ROOT_USAGE,
-    subcommands: ["mcp", "login", "logout", "init", "dev", "deploy", "rollback", "versions", "delete", "query", "rules"],
+    subcommands: ["mcp", "login", "logout", "init", "dev", "deploy", "rollback", "versions", "delete", "query", "rules", "items"],
     longFlags: ["help", "version"],
     subcommandFlags: [
         { name: "mcp", longFlags: ["help"] },
@@ -39,6 +40,7 @@ const ROOT_LEVEL = {
         { name: "delete", longFlags: ["yes", "help"] },
         { name: "query", longFlags: ["sql", "params", "help"] },
         { name: "rules", longFlags: ["params", "params-file", "yes", "help"] },
+        { name: "items", longFlags: ["params", "params-file", "yes", "help"] },
     ],
     usagePrefix: "npx driggsby@latest",
     hasVersion: true,
@@ -110,6 +112,8 @@ function dispatchSubcommand(name, rest) {
             return parseQuery(rest);
         case "rules":
             return parseRules(rest);
+        case "items":
+            return parseItems(rest);
         case "setup":
             return parseMcpSetup(rest);
         default:

package/dist/dev/tool-allowlist.js

@@ -13,6 +13,7 @@ export const APP_TOOL_ALLOWLIST = new Set([
     "list_recurring_transactions",
     "query_cash_sql",
     "query_investment_sql",
+    "query_item_sql",
     "search_cash_transactions",
     "search_investment_activity",
 ]);

package/dist/help.js

@@ -22,6 +22,7 @@ Commands:
   delete    Permanently remove a deployed app.
   query     Run one Driggsby data tool and print its result as JSON.
   rules     Create, change, and delete your transaction rules.
+  items     Save and remove the items behind your charges.
 
 Options:
   -h, --help     Print help
@@ -38,6 +39,7 @@ Examples:
   npx driggsby@latest deploy
   npx driggsby@latest query get_overview
   npx driggsby@latest rules describe
+  npx driggsby@latest items describe
 `;
 export const INIT_HELP = `Create a new Driggsby app in a new folder.
 
@@ -61,8 +63,8 @@ export const LOGIN_HELP = `Sign in to Driggsby and save an app token on this mac
 
 This opens a Driggsby approval page in your browser. Approving it issues an
 app token that lets this machine read your Driggsby data, deploy Driggsby
-apps, and manage your transaction rules. The token is saved locally for
-other driggsby commands and is never printed.
+apps, and manage your transaction rules and items. The token is saved
+locally for other driggsby commands and is never printed.
 
 If you approve in a browser on another computer, the page shows a code
 instead. Paste it where login is waiting, or finish with --code.
@@ -180,8 +182,8 @@ Arguments:
 ${QUERY_TOOL_LINES}
 
 Options:
-      --sql <SQL>      The SQL for query_cash_sql or query_investment_sql.
-                       Overrides a sql key given in --params.
+      --sql <SQL>      The SQL for query_cash_sql, query_investment_sql, or
+                       query_item_sql. Overrides a sql key given in --params.
       --params <JSON>  Other params as a JSON object, for example
                        '{"history_type":"liabilities"}'.
   -h, --help           Print help
@@ -230,6 +232,43 @@ Examples:
   npx driggsby@latest rules tags
   npx driggsby@latest rules save --params-file answers.json
 `;
+export const ITEMS_HELP = `Save and remove the items behind your charges.
+
+An itemized charge carries what it bought: an order's or a receipt's items,
+each in a category, so Driggsby counts the charge by what was in it. Each
+action runs one Driggsby item tool and prints its result as JSON; the JSON
+goes to stdout and nothing else does. Start with describe: it prints the
+item format and the process. Read items back with
+npx driggsby@latest query query_item_sql --sql <SQL>.
+
+Sign in first with npx driggsby@latest login.
+
+Usage: npx driggsby@latest items <ACTION> [--params <JSON>] [--yes]
+
+Actions:
+  describe  Print the item format and the process.
+  save      Save the items of up to 25 charges. Saving a charge again
+            replaces its items.
+  delete    Remove the items of charges by transaction_ref. There is no
+            undo; needs --yes.
+
+Options:
+      --params <JSON>       The action's params as a JSON object, like
+                            '{"transaction_refs":["txn_..."]}'.
+      --params-file <PATH>  Read the params object from a JSON file instead.
+      --yes                 Confirm a delete.
+  -h, --help                Print help
+
+Each charge in a save is saved or refused on its own (items that don't add
+up to the charge, say): the JSON result reports each one, with the reason
+and the fix, and the command exits 0. Only a failure of the whole call puts
+its message on stderr and exits 1.
+
+Examples:
+  npx driggsby@latest items describe
+  npx driggsby@latest items save --params-file order.json
+  npx driggsby@latest items delete --params-file refs.json --yes
+`;
 export const MCP_HELP = `Set up Driggsby MCP clients.
 
 Usage: npx driggsby@latest mcp <COMMAND>

package/dist/init/template-styles.js

@@ -13,8 +13,8 @@
 export const STYLES_CSS = `/* Driggsby's console palette, so this page reads as part of the app it
    opens inside. Change these together if you re-theme (all but
    --font-sans, which stays as it is); keep --bg-app equal to the
-   "background" in driggsby.json. The status tones are the console's own,
-   for gains, losses, warnings, and a live dot. */
+   "background" in driggsby.json. The status tones are for gains, losses,
+   warnings, and a live dot. */
 :root {
   color-scheme: dark;
   --bg-app: #000000;
@@ -35,17 +35,14 @@ export const STYLES_CSS = `/* Driggsby's console palette, so this page reads as
   --ease: cubic-bezier(0.2, 0, 0, 1);
 }
 
-/* Inter, which Driggsby serves at /-/inter.woff2 on this app's own origin
-   (driggsby dev serves the same file there), so nothing loads from another
-   site. Inter is the only font a dashboard uses: set all text with
-   var(--font-sans), keep that stack as it is (the faces after Inter only
-   stand in if the font is slow or fails to load, or lacks a character),
-   and name no other font anywhere else. A <canvas> or a chart library's
-   font setting can't read var(): name "Inter" there, followed only by
-   sans-serif, and draw a canvas after document.fonts.ready. The page
-   loads its font from its own address, so it looks the same everywhere
-   it's shown. Text waits for the font (font-display: block, preloaded)
-   rather than flash another face first. */
+/* Inter, from this page's own address, so it looks the same everywhere
+   it's shown. Inter is the only font a dashboard uses: set all text with
+   var(--font-sans), keep that stack as it is, and name no other font
+   anywhere else. A <canvas> or a chart library's font setting can't read
+   var(): name "Inter" there, followed only by sans-serif, and draw a
+   canvas after document.fonts.ready. Text waits for the font
+   (font-display: block, preloaded) rather than flash another face
+   first. */
 @font-face {
   font-family: "Inter";
   src: url("/-/inter.woff2") format("woff2");
@@ -78,8 +75,7 @@ textarea {
 }
 
 /* A compact column: a few figures and a short list read best close
-   together. The console's own pages run wider (75rem); widen this as the
-   page grows. */
+   together. Widen it as the page grows. */
 main {
   max-width: 800px;
   margin: 0 auto;
@@ -104,8 +100,7 @@ h2 {
   letter-spacing: -0.02em;
 }
 
-/* The console's stat tiles: a card per figure, 16px apart, the row
-   capped at the console's 920px. */
+/* A card per figure, 16px apart. */
 .stat-grid {
   display: grid;
   grid-template-columns: repeat(4, minmax(0, 1fr));

package/dist/init/templates.js

@@ -111,12 +111,13 @@ export const APP_JS = `// Your app's code. Edit anything — driggsby dev reload
 //   list_recurring_transactions  subscriptions, bills, and paychecks
 //   query_cash_sql               SQL over cash transactions ({ sql: "..." })
 //   query_investment_sql         SQL over investment activity ({ sql: "..." })
+//   query_item_sql               SQL over the items in itemized charges
+//                                ({ sql: "..." })
 //   search_cash_transactions     bank and card transaction search
 //   search_investment_activity   trades, dividends, and transfers
 //
-// Params mirror Driggsby's public MCP tools of the same names, with one
-// simplification: those tools require a "reason" string, but a watch can
-// leave it out — Driggsby fills one in naming the dashboard.
+// Params mirror Driggsby's public MCP tools of the same names; a watch
+// needs no "reason".
 //
 // To see a tool's exact result shape before writing render code, run it
 // once from the terminal — the JSON it prints is what the callback gets:
@@ -236,9 +237,9 @@ function renderAccounts(result) {
     const displayName = asText(account.account_display_name);
     const institution = asText(account.institution_name);
     const mask = asText(account.account_mask_last4);
-    // The institution's initial on a round pill, the way Driggsby's own
-    // account rows draw it. Array.from keeps an emoji-leading name from
-    // breaking the render (it splits by whole character, not UTF-16 half).
+    // The institution's initial on a round pill. Array.from keeps an
+    // emoji-leading name from breaking the render (it splits by whole
+    // character, not UTF-16 half).
     const initialSource = (institution || displayName).trim();
     const initial = (Array.from(initialSource)[0] || "?").toUpperCase();
     const institutionLine = [institution, mask ? "····" + mask : ""].filter(Boolean).join(" ");
@@ -353,9 +354,8 @@ function settledRenderer(render) {
 
 // ---------------------------------------------------------------------------
 // When a call fails. A watch whose call fails never runs its callback; it
-// runs onError instead, with { message, kind }, once for each new failure —
-// after Driggsby has already retried a call that failed because it was busy
-// or slow. The section says why where its data would be: in place of its
+// runs onError instead, with { message, kind }, once for each new failure.
+// The section says why where its data would be: in place of its
 // skeleton, so a failure never looks like a page still loading, or under
 // the data it already shows, which stays. The watch asks again on its own
 // the next time your data changes, and the next good result repaints the

package/dist/items/item-actions.js

@@ -0,0 +1,11 @@
+// The items command's actions. Each maps to exactly one Driggsby item tool
+// (the same tools the Driggsby MCP server offers); describe reads those
+// tools' own descriptions instead of calling one.
+export const ITEM_ACTION_TOOLS = {
+    save: "save_transaction_items",
+    delete: "delete_transaction_items",
+};
+export const ITEM_ACTIONS = ["describe", "save", "delete"];
+export function isItemAction(value) {
+    return ITEM_ACTIONS.includes(value);
+}

package/dist/items/items-command.js

@@ -0,0 +1,97 @@
+// driggsby items: save and remove the items behind the signed-in person's
+// charges (what an order or a receipt actually bought). Each action is one
+// call to a Driggsby item tool (the same tools the Driggsby MCP server
+// offers); describe prints those tools' own descriptions, so the item format
+// is never copied into this CLI. stdout carries only JSON (the result, or a
+// refusal's own details) so an agent can pipe or save it; every message is a
+// CliError on stderr.
+import { apiBaseUrl } from "../api/base-url.js";
+import { CliError } from "../cli-error.js";
+import { defaultCredentialEnvironment } from "../credentials/store.js";
+import { deployFailure, requireDeploySession } from "../deploy/api-session.js";
+import { callRuleTool, listTools } from "../rules/rules-rpc.js";
+import { terminalSafeJson } from "../terminal-text.js";
+import { ITEM_ACTION_TOOLS, ITEM_ACTIONS } from "./item-actions.js";
+// The item tools take an optional short reason; when the caller gives none,
+// this names the CLI.
+export const ITEMS_REASON = "Itemizing charges from the driggsby CLI.";
+export const ITEMS_NOT_AVAILABLE_MESSAGE = "This sign-in can't save items. Sign in again and approve the request:\n" +
+    "  npx driggsby@latest login\n" +
+    "If items still aren't available after that, they aren't open to your account yet.";
+function defaultItemsIo() {
+    return {
+        out: (text) => {
+            process.stdout.write(text);
+        },
+    };
+}
+export async function runItems(options, environment = defaultCredentialEnvironment(), io = defaultItemsIo()) {
+    const { action, params } = options;
+    if (action === "delete" && options.yes !== true) {
+        throw new CliError("Removing a charge's items can't be undone, so it needs --yes.", 2);
+    }
+    const baseUrl = apiBaseUrl(environment.env);
+    const retryCommand = retryCommandFor(options);
+    try {
+        const session = await requireDeploySession(environment);
+        if (action === "describe") {
+            const tools = await listTools(session, new Set(Object.values(ITEM_ACTION_TOOLS)), ITEMS_NOT_AVAILABLE_MESSAGE);
+            io.out(`${terminalSafeJson(describePayload(tools))}\n`);
+            return 0;
+        }
+        const outcome = await callRuleTool(session, ITEM_ACTION_TOOLS[action], withReason(params));
+        if (outcome.kind === "ok") {
+            io.out(`${terminalSafeJson(outcome.result)}\n`);
+            return 0;
+        }
+        if (outcome.kind === "refused") {
+            io.out(`${terminalSafeJson(outcome.details)}\n`);
+        }
+        throw new CliError(outcome.message, 1);
+    }
+    catch (error) {
+        throw deployFailure(error, baseUrl, retryCommand);
+    }
+}
+// Each action's flags, keyed by action so a new action can't be left out.
+const ACTION_FLAGS = {
+    save: " --params <JSON>",
+    delete: " --params <JSON> --yes",
+};
+// What describe prints: the tools' own descriptions, plus the CLI command
+// that runs each tool the descriptions name.
+export function describePayload(tools) {
+    const howToRun = {};
+    for (const action of ITEM_ACTIONS) {
+        if (action !== "describe") {
+            howToRun[ITEM_ACTION_TOOLS[action]] = `npx driggsby@latest items ${action}${ACTION_FLAGS[action]}`;
+        }
+    }
+    // The two read tools the item descriptions send an agent to: finding the
+    // charges, and reading their items back.
+    howToRun.search_cash_transactions = "npx driggsby@latest query search_cash_transactions --params <JSON>";
+    howToRun.query_item_sql = "npx driggsby@latest query query_item_sql --sql <SQL>";
+    return {
+        how_to_run: howToRun,
+        notes: [
+            "--params is the tool's arguments object as JSON; --params-file <PATH> reads the same object from a file.",
+            "The CLI fills in reason when you leave it out.",
+        ],
+        tools,
+    };
+}
+function withReason(params) {
+    const reason = params.reason;
+    if (typeof reason === "string" && reason.trim() !== "") {
+        return params;
+    }
+    return { ...params, reason: ITEMS_REASON };
+}
+// The command to run again after a network blip. Params are never rebuilt
+// into a shell line (no quoting is right for every shell), so they are named
+// in a plain sentence under the command instead. A retried save is safe:
+// saving a charge again replaces its items rather than adding to them.
+function retryCommandFor(options) {
+    const command = `npx driggsby@latest items ${options.action}${options.action === "delete" ? " --yes" : ""}`;
+    return Object.keys(options.params).length === 0 ? command : `${command}\n  with the same params as before`;
+}

package/dist/main.js

@@ -11,6 +11,7 @@ import { runInit } from "./init/init-command.js";
 import { runRollback } from "./deploy/rollback-command.js";
 import { runVersions } from "./deploy/versions-command.js";
 import { runQuery } from "./query/query-command.js";
+import { runItems } from "./items/items-command.js";
 import { runRules } from "./rules/rules-command.js";
 import { runLogin, runLoginWithCode } from "./login/login.js";
 import { runLogout } from "./login/logout.js";
@@ -51,6 +52,8 @@ async function run(argv) {
             return await runQuery({ tool: command.tool, params: command.params });
         case "rules":
             return await runRules({ action: command.action, params: command.params, yes: command.yes });
+        case "items":
+            return await runItems({ action: command.action, params: command.params, yes: command.yes });
     }
 }
 try {

package/dist/rules/rules-rpc.js

@@ -1,4 +1,4 @@
-// The rules command's channel to Driggsby: one JSON-RPC POST to /mcp with
+// The rules and items commands' channel to Driggsby: one JSON-RPC POST to /mcp with
 // the saved sign-in. Unlike the dev preview's broker, a tool refusal keeps
 // its structured details (a blocking suggestion and its options, the
 // overlapping rule), because an agent needs them to answer and save again.
@@ -29,13 +29,17 @@ export async function callRuleTool(session, tool, toolArguments) {
 // this sign-in sees. None listed means the sign-in predates rules or rules
 // aren't open to the account; either way the next step is the same.
 export async function listRuleTools(session) {
+    return listTools(session, new Set(Object.values(RULE_ACTION_TOOLS)), RULES_NOT_AVAILABLE_MESSAGE);
+}
+// The wanted tools' own descriptions from this sign-in's tools/list (the
+// rules and items commands each describe their own tools this way).
+export async function listTools(session, wanted, notAvailableMessage) {
     const payload = await postMcp(session, { jsonrpc: "2.0", id: 1, method: "tools/list" });
     const tools = asRecord(asRecord(payload)?.result)?.tools;
     if (!Array.isArray(tools)) {
         throw new CliError(GENERIC_TOOL_TROUBLE, 1);
     }
     const listed = tools;
-    const wanted = new Set(Object.values(RULE_ACTION_TOOLS));
     const found = listed.flatMap((tool) => {
         const record = asRecord(tool);
         if (record === null ||
@@ -54,7 +58,7 @@ export async function listRuleTools(session) {
         ];
     });
     if (found.length === 0) {
-        throw new CliError(RULES_NOT_AVAILABLE_MESSAGE, 1);
+        throw new CliError(notAvailableMessage, 1);
     }
     return found;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driggsby",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "description": "Set up and build on Driggsby, the MCP server for personal finance.",
   "license": "Apache-2.0 AND OFL-1.1",
   "repository": {
@@ -30,7 +30,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@driggsby/deploy": "0.7.5",
-    "@driggsby/sdk": "0.7.5"
+    "@driggsby/deploy": "0.8.0",
+    "@driggsby/sdk": "0.8.0"
   }
 }