driggsby 0.3.3 → 0.4.0

package/README.md

@@ -100,6 +100,18 @@ with Node.js 18 or newer.
 See the [GitHub repo](https://github.com/driggsby/driggsby) for
 tools, examples, and full documentation.
 
+## Transaction rules
+
+`npx driggsby@latest rules` reads and changes your transaction rules — your
+standing corrections to how Driggsby reads your transactions: a category, a
+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.
+
 ## License
 
 Apache-2.0

package/dist/args-rules.js

@@ -0,0 +1,182 @@
+// Argv parsing for `driggsby rules <ACTION> [--params <JSON> | --params-file
+// <PATH>] [--yes]`. --params is the rule tool's arguments object, verbatim;
+// --params-file reads the same object from a file, for rules too big or
+// too quote-heavy for a shell line. Usage errors exit 2; echoed argv is
+// sanitized by the shared builders. Help, the action, and the flag rules
+// are all checked before any params are parsed or any file is read.
+import { closeSync, constants, fstatSync, openSync, readSync, statSync } from "node:fs";
+import { helpCommand, unexpectedArgument, unexpectedFlagValue } from "./args-shared.js";
+import { didYouMean } from "./clap-suggestions.js";
+import { CliError } from "./cli-error.js";
+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]";
+// 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) {
+    let actionToken = null;
+    let source = null;
+    let yes = false;
+    let optionsEnded = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? "";
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && (token === "-h" || token === "--help")) {
+            return helpCommand(RULES_HELP);
+        }
+        if (!optionsEnded && token === "--yes") {
+            yes = true;
+            continue;
+        }
+        if (!optionsEnded && token.startsWith("--yes=")) {
+            throw unexpectedFlagValue("--yes", token.slice("--yes=".length), RULES_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");
+            }
+            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`);
+            }
+            source = flag === "--params" ? { flag, json: value } : { flag, path: value };
+            index += attached ? 0 : 1;
+            continue;
+        }
+        if (actionToken === null && (optionsEnded || !token.startsWith("-"))) {
+            actionToken = token;
+            continue;
+        }
+        throw unexpectedArgument(token, RULES_USAGE);
+    }
+    if (actionToken === null) {
+        throw usageError("error: the following required arguments were not provided:\n  <ACTION>");
+    }
+    if (!isRuleAction(actionToken)) {
+        throw unknownAction(actionToken);
+    }
+    const action = actionToken;
+    if (action === "describe" && source !== null) {
+        throw usageError("error: rules describe takes no params");
+    }
+    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 !== "delete" && yes) {
+        throw usageError("error: '--yes' only applies to rules delete");
+    }
+    return { kind: "rules", action, params: source === null ? {} : resolveParams(source), yes };
+}
+// "--params", "--params=…", "--params-file", "--params-file=…" → the flag.
+function paramsFlag(token) {
+    for (const flag of ["--params-file", "--params"]) {
+        if (token === flag || token.startsWith(`${flag}=`)) {
+            return flag;
+        }
+    }
+    return null;
+}
+function resolveParams(source) {
+    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(readParamsFile(source.path), "--params-file", "");
+}
+function parseParamsObject(rawValue, flag, hint) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawValue);
+    }
+    catch {
+        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}`);
+    }
+    return parsed;
+}
+// The path is the caller's own; neither it nor the contents are ever echoed
+// back. The read is bounded by bytes actually read, not by the size stat
+// reports (pseudo-files report 0, and a file can grow between stat and
+// 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) {
+    let bytes;
+    try {
+        if (!statSync(path).isFile()) {
+            throw new ParamsFileProblem("the path isn't a regular file");
+        }
+        bytes = readAtMost(path, MAX_PARAMS_FILE_BYTES + 1);
+    }
+    catch (error) {
+        throw usageError(`error: couldn't read the --params-file: ${paramsFileProblem(error)}`);
+    }
+    if (bytes.length > MAX_PARAMS_FILE_BYTES) {
+        throw usageError(`error: couldn't read the --params-file: it's over ${MAX_PARAMS_FILE_MB} MB`);
+    }
+    return decodeParamsFile(bytes);
+}
+class ParamsFileProblem extends Error {
+}
+function readAtMost(path, limit) {
+    const descriptor = openSync(path, process.platform === "win32" ? "r" : constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        if (!fstatSync(descriptor).isFile()) {
+            throw new ParamsFileProblem("the path isn't a regular file");
+        }
+        const buffer = Buffer.alloc(limit);
+        let length = 0;
+        while (length < limit) {
+            const read = readSync(descriptor, buffer, length, limit - length, null);
+            if (read === 0) {
+                break;
+            }
+            length += read;
+        }
+        return buffer.subarray(0, length);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function paramsFileProblem(error) {
+    if (error instanceof ParamsFileProblem) {
+        return error.message;
+    }
+    const code = error instanceof Error && "code" in error ? error.code : undefined;
+    if (code === "ENOENT") {
+        return "there's no file at that path";
+    }
+    if (code === "EACCES" || code === "EPERM") {
+        return "this account isn't allowed to read it";
+    }
+    return `it must be a readable JSON file under ${MAX_PARAMS_FILE_MB} MB`;
+}
+// Editors and shells on Windows often save "UTF-8" with a byte-order mark,
+// and Windows PowerShell 5.1's > writes UTF-16LE; both read as the JSON
+// they hold.
+function decodeParamsFile(bytes) {
+    if (bytes[0] === 0xff && bytes[1] === 0xfe) {
+        return bytes.subarray(2).toString("utf16le");
+    }
+    const text = bytes.toString("utf8");
+    return text.startsWith("\uFEFF") ? text.slice(1) : text;
+}
+function unknownAction(token) {
+    const similar = didYouMean(token, RULE_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}`);
+}
+function usageError(firstLines) {
+    return new CliError(`${firstLines}\n\n${RULES_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 "./rules/rule-actions.js";
 import { sanitizeForTerminal } from "./terminal-text.js";
 export function helpCommand(text) {
     return { kind: "print-help", text, stream: "stdout", exitCode: 0 };

package/dist/args.js

@@ -4,13 +4,15 @@
 // you mean" tips (via the ported Jaro similarity in clap-suggestions.ts),
 // "--" end-of-options, and short-flag cluster dispatch. Newer commands
 // (login, logout) keep the same behavior and exit codes without chasing
-// clap's byte-level quirks.
+// clap's byte-level quirks. One deliberate difference: a misplaced flag's
+// cross-level tip names only the subcommand actually typed.
 import { parseDeploy, parseRollback, parseVersions } from "./args-deploy.js";
 import { parseDev } from "./args-dev.js";
 import { parseDelete } from "./args-delete.js";
 import { parseInit } from "./args-init.js";
 import { parseMcpSetup } from "./args-mcp-setup.js";
 import { parseQuery } from "./args-query.js";
+import { parseRules } from "./args-rules.js";
 import { removeDashesTip, similarArgumentTip, unexpectedArgument, unexpectedFlagValue, } from "./args-shared.js";
 import { didYouMean } from "./clap-suggestions.js";
 import { CliError } from "./cli-error.js";
@@ -22,7 +24,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"],
+    subcommands: ["mcp", "login", "logout", "init", "dev", "deploy", "rollback", "versions", "delete", "query", "rules"],
     longFlags: ["help", "version"],
     subcommandFlags: [
         { name: "mcp", longFlags: ["help"] },
@@ -35,6 +37,7 @@ const ROOT_LEVEL = {
         { name: "versions", longFlags: ["help"] },
         { name: "delete", longFlags: ["yes", "help"] },
         { name: "query", longFlags: ["sql", "params", "help"] },
+        { name: "rules", longFlags: ["params", "params-file", "yes", "help"] },
     ],
     usagePrefix: "npx driggsby@latest",
     hasVersion: true,
@@ -104,6 +107,8 @@ function dispatchSubcommand(name, rest) {
             return parseVersions(rest);
         case "query":
             return parseQuery(rest);
+        case "rules":
+            return parseRules(rest);
         case "setup":
             return parseMcpSetup(rest);
         default:
@@ -167,18 +172,23 @@ function unknownLongFlagAtLevel(level, token, remainingArgs) {
     }
     // clap's cross-level fallback: when a LATER argv token names one of this
     // level's subcommands and that subcommand has a similar flag, point the
-    // user at the flag's real home ("tip: 'setup --print' exists").
-    for (const subcommand of level.subcommandFlags) {
-        if (!remainingArgs.includes(subcommand.name)) {
-            continue;
-        }
-        const subcommandSimilar = didYouMean(flagName, subcommand.longFlags);
-        if (subcommandSimilar !== undefined) {
-            return unexpectedArgument(shown, level.usage, `  tip: '${subcommand.name} --${subcommandSimilar}' exists`);
-        }
+    // user at the flag's real home ("tip: 'setup --print' exists"). The home
+    // is only ever the first subcommand actually typed (a flag's value never
+    // counts), so `--yes rules delete` is never pointed at the app-deleting
+    // `delete --yes`.
+    const typed = firstTypedSubcommand(level, remainingArgs);
+    const subcommand = level.subcommandFlags.find((entry) => entry.name === typed);
+    const subcommandSimilar = subcommand === undefined ? undefined : didYouMean(flagName, subcommand.longFlags);
+    if (subcommand !== undefined && subcommandSimilar !== undefined) {
+        return unexpectedArgument(shown, level.usage, `  tip: '${subcommand.name} --${subcommandSimilar}' exists`);
     }
     return unexpectedArgument(shown, level.usage);
 }
+// Flags anywhere in the tree whose next token is their value, not a word.
+const VALUE_FLAGS = new Set(["--params", "--params-file", "--sql", "--to", "-s", "--scope"]);
+function firstTypedSubcommand(level, args) {
+    return args.find((argument, index) => level.subcommands.includes(argument) && !VALUE_FLAGS.has(args[index - 1] ?? ""));
+}
 function unrecognizedSubcommand(level, subcommand) {
     const similar = didYouMean(subcommand, level.subcommands);
     const tip = similar === undefined ? "" : `  tip: a similar subcommand exists: '${similar}'\n\n`;

package/dist/help.js

@@ -21,6 +21,7 @@ Commands:
   versions  List your deployed app's versions.
   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.
 
 Options:
   -h, --help     Print help
@@ -36,6 +37,7 @@ Examples:
   npx driggsby@latest dev
   npx driggsby@latest deploy
   npx driggsby@latest query get_overview
+  npx driggsby@latest rules describe
 `;
 export const INIT_HELP = `Create a new Driggsby app in a new folder.
 
@@ -58,9 +60,9 @@ Options:
 export const LOGIN_HELP = `Sign in to Driggsby and save an app token on this machine.
 
 This opens a Driggsby approval page in your browser. Approving it issues an
-app token that lets this machine read your Driggsby data and deploy Driggsby
-apps. The token is saved locally for other driggsby commands and is never
-printed.
+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.
 
 Usage: npx driggsby@latest login
 
@@ -182,6 +184,45 @@ Examples:
   npx driggsby@latest query list_recurring_transactions
   npx driggsby@latest query query_cash_sql --sql "SELECT 1"
 `;
+export const RULES_HELP = `Create, change, and delete your transaction rules.
+
+A transaction rule is your standing correction to how Driggsby reads your
+transactions: a category, a counterparty's name, or tags on a set of
+transactions. Each action runs one Driggsby rule tool and prints its result
+as JSON; the JSON goes to stdout and nothing else does. Start with describe:
+it prints the rule format, the process, and worked examples.
+
+Sign in first with npx driggsby@latest login.
+
+Usage: npx driggsby@latest rules <ACTION> [--params <JSON>] [--yes]
+
+Actions:
+  describe  Print the rule format, the process, and examples.
+  list      List your rules. With {"rule_ref":"..."}, one rule in full.
+  tags      List your transaction tags.
+  preview   Show exactly what a rule would change. Saves nothing; returns
+            the confirm_token that save needs.
+  save      Create or change a rule with a preview's confirm_token, or
+            rename, pause, or resume one by rule_ref.
+  delete    Delete a rule by rule_ref. There is no undo; needs --yes.
+
+Options:
+      --params <JSON>       The action's params as a JSON object, like
+                            '{"rule_ref":"rule_..."}'.
+      --params-file <PATH>  Read the params object from a JSON file instead.
+      --yes                 Confirm a delete.
+  -h, --help                Print help
+
+If Driggsby refuses a change with details to act on (a question to answer,
+an overlapping rule), stdout carries those details as JSON. Any failure puts
+its message on stderr and exits 1.
+
+Examples:
+  npx driggsby@latest rules describe
+  npx driggsby@latest rules list
+  npx driggsby@latest rules tags
+  npx driggsby@latest rules save --params-file answers.json
+`;
 export const MCP_HELP = `Set up Driggsby MCP clients.
 
 Usage: npx driggsby@latest mcp <COMMAND>

package/dist/login/claim-client.js

@@ -5,7 +5,8 @@
 // an approval.
 import { CliError } from "../cli-error.js";
 import { sanitizeForTerminal } from "../terminal-text.js";
-const CLAIM_SCOPE = "driggsby.app_deploy";
+// The CLI's own sign-in: read, deploy, and the transaction-rule tools.
+const CLAIM_SCOPE = "driggsby.cli";
 const CLAIM_APP_NAME = "Driggsby CLI";
 const REQUEST_TIMEOUT_MS = 15_000;
 // The server names its own claim lifetime; this cap keeps a buggy or hostile

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 { runRules } from "./rules/rules-command.js";
 import { runLogin } from "./login/login.js";
 import { runLogout } from "./login/logout.js";
 import { runMcpSetup } from "./mcp-setup/setup.js";
@@ -48,6 +49,8 @@ async function run(argv) {
             return await runVersions({});
         case "query":
             return await runQuery({ tool: command.tool, params: command.params });
+        case "rules":
+            return await runRules({ action: command.action, params: command.params, yes: command.yes });
     }
 }
 try {

package/dist/query/query-command.js

@@ -10,7 +10,7 @@ import { McpBroker } from "../dev/mcp-broker.js";
 import { SQL_TOOLS } from "../args-query.js";
 import { APP_TOOL_ALLOWLIST } from "../dev/tool-allowlist.js";
 import { deployFailure, requireDeploySession, SIGN_IN_AGAIN_MESSAGE } from "../deploy/api-session.js";
-import { quotedForTerminal, wrapProse } from "../terminal-text.js";
+import { quotedForTerminal, terminalSafeJson, wrapProse } from "../terminal-text.js";
 // The Driggsby endpoint requires a short reason on most read tools; when
 // the caller gives none, this names the CLI rather than the dev preview.
 const QUERY_REASON = "Checking this tool's result shape from the driggsby CLI.";
@@ -52,7 +52,7 @@ export async function runQuery(options, environment = defaultCredentialEnvironme
                 : wrapProse(outcome.error.message);
             throw new CliError(message, 1);
         }
-        io.out(`${JSON.stringify(outcome.result, null, 2)}\n`);
+        io.out(`${terminalSafeJson(outcome.result)}\n`);
         return 0;
     }
     catch (error) {

package/dist/rules/rule-actions.js

@@ -0,0 +1,14 @@
+// The rules command's actions. Each maps to exactly one Driggsby
+// transaction-rule tool (the same tools the Driggsby MCP server offers);
+// describe reads those tools' own descriptions instead of calling one.
+export const RULE_ACTION_TOOLS = {
+    list: "list_transaction_rules",
+    tags: "list_transaction_tags",
+    preview: "preview_transaction_rule",
+    save: "save_transaction_rule",
+    delete: "delete_transaction_rule",
+};
+export const RULE_ACTIONS = ["describe", "list", "tags", "preview", "save", "delete"];
+export function isRuleAction(value) {
+    return RULE_ACTIONS.includes(value);
+}

package/dist/rules/rules-command.js

@@ -0,0 +1,96 @@
+// driggsby rules: read and change the signed-in person's transaction
+// rules. Each action is one call to a Driggsby transaction-rule tool (the
+// same tools the Driggsby MCP server offers); describe prints those tools'
+// own descriptions, so the rule 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 { terminalSafeJson } from "../terminal-text.js";
+import { RULE_ACTION_TOOLS, RULE_ACTIONS } from "./rule-actions.js";
+import { callRuleTool, listRuleTools } from "./rules-rpc.js";
+// Most rule tools require a short reason; when the caller gives none, this
+// names the CLI.
+export const RULES_REASON = "Managing transaction rules from the driggsby CLI.";
+function defaultRulesIo() {
+    return {
+        out: (text) => {
+            process.stdout.write(text);
+        },
+    };
+}
+export async function runRules(options, environment = defaultCredentialEnvironment(), io = defaultRulesIo()) {
+    const { action, params } = options;
+    if (action === "delete" && options.yes !== true) {
+        throw new CliError("Deleting a rule 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 listRuleTools(session);
+            io.out(`${terminalSafeJson(describePayload(tools))}\n`);
+            return 0;
+        }
+        const outcome = await callRuleTool(session, RULE_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 = {
+    list: " [--params <JSON>]",
+    tags: "",
+    preview: " --params <JSON>",
+    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 RULE_ACTIONS) {
+        if (action !== "describe") {
+            howToRun[RULE_ACTION_TOOLS[action]] = `npx driggsby@latest rules ${action}${ACTION_FLAGS[action]}`;
+        }
+    }
+    // The two read tools the rule descriptions send an agent to first.
+    howToRun.search_cash_transactions = "npx driggsby@latest query search_cash_transactions --params <JSON>";
+    howToRun.query_cash_sql = "npx driggsby@latest query query_cash_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: RULES_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: a
+// confirm token redeems once, so a save that already landed is refused, not
+// applied twice.
+function retryCommandFor(options) {
+    const command = `npx driggsby@latest rules ${options.action}${options.action === "delete" ? " --yes" : ""}`;
+    return Object.keys(options.params).length === 0 ? command : `${command}\n  with the same params as before`;
+}

package/dist/rules/rules-rpc.js

@@ -0,0 +1,132 @@
+// The rules command's 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.
+import { CliError } from "../cli-error.js";
+import { SIGN_IN_AGAIN_MESSAGE } from "../deploy/api-session.js";
+import { GENERIC_TOOL_TROUBLE } from "../dev/dev-servers.js";
+import { capForTerminal, sanitizeForTerminal } from "../terminal-text.js";
+import { RULE_ACTION_TOOLS } from "./rule-actions.js";
+// A preview replays the person's posted history; give it longer than a
+// dashboard read gets.
+export const RULES_CALL_TIMEOUT_MS = 60_000;
+// Server messages are hostile text: sanitized and bounded before they reach
+// the terminal. Generous, because a rule refusal explains itself.
+const MAX_SERVER_MESSAGE_CHARS = 1_000;
+export const RULES_NOT_AVAILABLE_MESSAGE = "This sign-in can't use transaction rules. Sign in again and approve the request:\n" +
+    "  npx driggsby@latest login\n" +
+    "If rules still aren't available after that, they aren't open to your account yet.";
+export async function callRuleTool(session, tool, toolArguments) {
+    const payload = await postMcp(session, {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: tool, arguments: toolArguments },
+    });
+    return interpretToolCall(payload);
+}
+// The rule tools' own descriptions and input schemas, from the tools/list
+// 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) {
+    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 ||
+            typeof record.name !== "string" ||
+            !wanted.has(record.name) ||
+            typeof record.description !== "string") {
+            return [];
+        }
+        return [
+            {
+                name: record.name,
+                title: typeof record.title === "string" ? record.title : null,
+                description: record.description,
+                inputSchema: record.inputSchema ?? null,
+            },
+        ];
+    });
+    if (found.length === 0) {
+        throw new CliError(RULES_NOT_AVAILABLE_MESSAGE, 1);
+    }
+    return found;
+}
+// Three shapes: a protocol error ({ error: { message } }), a tool refusal
+// (result.isError, details in structuredContent), and success.
+export function interpretToolCall(payload) {
+    const envelope = asRecord(payload);
+    if (envelope === null) {
+        return { kind: "error", message: GENERIC_TOOL_TROUBLE };
+    }
+    const error = asRecord(envelope.error);
+    if (error !== null) {
+        return { kind: "error", message: serverMessage(error.message) };
+    }
+    const result = asRecord(envelope.result);
+    if (result === null) {
+        return { kind: "error", message: GENERIC_TOOL_TROUBLE };
+    }
+    const structured = result.structuredContent ?? null;
+    if (result.isError === true) {
+        const message = asRecord(structured)?.error ?? firstText(result.content);
+        return { kind: "refused", message: serverMessage(message), details: structured };
+    }
+    return { kind: "ok", result: structured };
+}
+// A refusal's message lives in structuredContent.error; the MCP text
+// content is the fallback, the same one the dev preview's broker reads.
+function firstText(content) {
+    return Array.isArray(content) ? asRecord(content[0])?.text : undefined;
+}
+async function postMcp(session, body) {
+    // Bare headers on purpose: the Driggsby endpoint refuses anything that
+    // looks like a browser call (an Origin or Sec-Fetch-Site header), and
+    // Node's fetch sends neither on its own.
+    const response = await fetch(new URL("/mcp", session.baseUrl), {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${session.token}` },
+        body: JSON.stringify(body),
+        // The bearer token must never travel to a redirect target.
+        redirect: "error",
+        signal: AbortSignal.timeout(RULES_CALL_TIMEOUT_MS),
+    });
+    if (response.status === 401) {
+        throw new CliError(SIGN_IN_AGAIN_MESSAGE, 1);
+    }
+    if (!response.ok) {
+        throw new CliError(GENERIC_TOOL_TROUBLE, 1);
+    }
+    try {
+        const parsed = await response.json();
+        return parsed;
+    }
+    catch {
+        throw new CliError(GENERIC_TOOL_TROUBLE, 1);
+    }
+}
+// capForTerminal strips control and bidi bytes, then bounds the length.
+// Deliberately unwrapped: a server message can end in a command
+// (npx driggsby@latest login), and a hard wrap could split it; the terminal
+// soft-wraps a long line and copy-paste stays intact.
+function serverMessage(value) {
+    if (typeof value !== "string") {
+        return GENERIC_TOOL_TROUBLE;
+    }
+    const clean = sanitizeForTerminal(value).trim();
+    if (clean === "") {
+        return GENERIC_TOOL_TROUBLE;
+    }
+    return clean.length > MAX_SERVER_MESSAGE_CHARS ? `${capForTerminal(clean, MAX_SERVER_MESSAGE_CHARS - 1)}…` : clean;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}

package/dist/terminal-text.js

@@ -32,3 +32,14 @@ export function wrapNames(names, indent) {
     lines.push(line);
     return lines.join("\n");
 }
+// JSON.stringify escapes C0 controls but passes C1 controls, bidi
+// overrides, and invisible code points through raw; server data is hostile
+// (a counterparty's name comes from a bank), so escape those too, the same
+// class sanitizeForTerminal strips from prose. They can only sit inside JSON
+// strings, so the output stays valid JSON that parses to the same value.
+// Each UTF-16 unit is escaped on its own, so an astral code point (a tag
+// character) becomes a valid surrogate-pair escape.
+const TERMINAL_UNSAFE_IN_JSON = /[\u007f-\u009f\u2028\u2029\ufff9-\ufffb]|\p{Default_Ignorable_Code_Point}/gu;
+export function terminalSafeJson(value) {
+    return JSON.stringify(value ?? null, null, 2).replace(TERMINAL_UNSAFE_IN_JSON, (match) => Array.from({ length: match.length }, (_, index) => `\\u${match.charCodeAt(index).toString(16).padStart(4, "0")}`).join(""));
+}

package/package.json

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