driggsby 0.3.2 → 0.4.0

package/README.md

@@ -86,7 +86,9 @@ Every deploy after that uploads only the files that changed. Deploy with
 `--preview` to upload a version without
 changing what visitors see, `npx driggsby@latest versions` to list every
 kept version, and `npx driggsby@latest rollback` to switch which one is
-live — switching re-uploads nothing. `npx driggsby@latest query <tool>`
+live — switching re-uploads nothing. `npx driggsby@latest delete` removes
+a deployed app forever, after asking you to type its address name back
+(`--yes` for scripts). `npx driggsby@latest query <tool>`
 runs one read-only data tool and prints its result as JSON, the same
 shape a `driggsby.watch` callback receives, so you can see the data
 before writing any render code.
@@ -98,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-delete.js

@@ -0,0 +1,38 @@
+// Argv parsing for driggsby delete: one optional positional (the app's
+// address name), --yes for scripts and agents, help, and the shared
+// usage-error shape — usage errors exit 2, echoed argv is sanitized by the
+// shared builders.
+import { helpCommand, unexpectedArgument, unexpectedFlagValue, } from "./args-shared.js";
+import { DELETE_HELP } from "./help.js";
+const DELETE_USAGE = "Usage: npx driggsby@latest delete [APP-ADDRESS-NAME] [--yes]";
+export function parseDelete(argv) {
+    let slug = null;
+    let yes = false;
+    let optionsEnded = false;
+    for (const token of argv) {
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && (token === "-h" || token === "--help")) {
+            return helpCommand(DELETE_HELP);
+        }
+        if (!optionsEnded && token === "--yes") {
+            yes = true;
+            continue;
+        }
+        if (!optionsEnded && token.startsWith("--yes=")) {
+            throw unexpectedFlagValue("--yes", token.slice("--yes=".length), DELETE_USAGE);
+        }
+        // Any other flag-looking token is a mistake, not a name; after "--"
+        // everything is positional and the server refuses unknown names.
+        if (!optionsEnded && token.startsWith("-") && token !== "-") {
+            throw unexpectedArgument(token, DELETE_USAGE);
+        }
+        if (slug !== null) {
+            throw unexpectedArgument(token, DELETE_USAGE);
+        }
+        slug = token;
+    }
+    return { kind: "delete", slug, yes };
+}

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,12 +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";
@@ -21,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", "query"],
+    subcommands: ["mcp", "login", "logout", "init", "dev", "deploy", "rollback", "versions", "delete", "query", "rules"],
     longFlags: ["help", "version"],
     subcommandFlags: [
         { name: "mcp", longFlags: ["help"] },
@@ -32,7 +35,9 @@ const ROOT_LEVEL = {
         { name: "deploy", longFlags: ["preview", "help"] },
         { name: "rollback", longFlags: ["to", "help"] },
         { 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,
@@ -96,10 +101,14 @@ function dispatchSubcommand(name, rest) {
             return parseDeploy(rest);
         case "rollback":
             return parseRollback(rest);
+        case "delete":
+            return parseDelete(rest);
         case "versions":
             return parseVersions(rest);
         case "query":
             return parseQuery(rest);
+        case "rules":
+            return parseRules(rest);
         case "setup":
             return parseMcpSetup(rest);
         default:
@@ -163,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/deploy/delete-command.js

@@ -0,0 +1,125 @@
+// driggsby delete: permanently remove a deployed app — the app itself and
+// every version Driggsby kept for it. There is no undo, so this command
+// owns the "are you sure": interactively the person types the app's
+// address name back; in a script or agent run, --yes is required.
+import { access } from "node:fs/promises";
+import { join } from "node:path";
+import { deleteApp, readProjectConfig, slugProblem } from "@driggsby/deploy";
+import { apiBaseUrl } from "../api/base-url.js";
+import { CliError } from "../cli-error.js";
+import { defaultCredentialEnvironment, } from "../credentials/store.js";
+import { capForTerminal, quotedForTerminal, wrapProse } from "../terminal-text.js";
+import { MAX_SERVER_TEXT_CHARS, MAX_SERVER_URL_CHARS, deployFailure, requireDeploySession, } from "./api-session.js";
+import { fetchVersionList } from "./versions-command.js";
+const DELETE_RETRY_COMMAND = "npx driggsby@latest delete";
+// The success line is `✓ Deleted   ` (12 columns) plus the quoted name;
+// 12 + 2 quotes + 64 = 78 keeps it inside 80 whatever the server sends.
+const DELETED_LINE_NAME_CHARS = 64;
+// Once the name is known (and validated), the retry names it too, so a
+// retry from the wrong folder can't quietly target a different app.
+function retryCommandFor(slug) {
+    return slug === null ? DELETE_RETRY_COMMAND : `${DELETE_RETRY_COMMAND} ${slug}`;
+}
+function defaultDeleteIo() {
+    return {
+        out: (text) => {
+            process.stdout.write(text);
+        },
+        ask: async (question) => {
+            const { createInterface } = await import("node:readline/promises");
+            const readline = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await readline.question(question);
+            }
+            finally {
+                readline.close();
+            }
+        },
+        interactive: process.stdin.isTTY && process.stdout.isTTY,
+    };
+}
+export async function runDelete(options, environment = defaultCredentialEnvironment(), io = defaultDeleteIo()) {
+    const projectDirectory = options.projectDirectory ?? process.cwd();
+    const baseUrl = apiBaseUrl(environment.env);
+    let resolvedSlug = null;
+    try {
+        const slug = options.slug === null
+            ? await slugFromProjectFolder(projectDirectory)
+            : validatedArgvSlug(options.slug);
+        resolvedSlug = slug;
+        const session = await requireDeploySession(environment);
+        const api = { baseUrl: session.baseUrl, token: session.token };
+        // The look-before-you-leap read: it shows exactly what is about to
+        // go, and an unknown name stops here — with delete's own not-found,
+        // never the version list's "deploy it first" suggestion — before the
+        // DELETE is ever sent.
+        const list = await fetchVersionList(api, slug, appAlreadyGone);
+        const versionCount = list.versions.length;
+        const versionsLine = versionCount === 1 ? "1 deployed version" : `${versionCount} deployed versions`;
+        // The slug passed the strict pattern above (argv) or came from the
+        // validated project config, so it prints bare here.
+        io.out(`${wrapProse(`Deleting ${slug} removes it forever: ${versionsLine}, its page in Driggsby, and its address:`)}\n` +
+            `  ${capForTerminal(list.url, MAX_SERVER_URL_CHARS)}\n\n`);
+        if (!options.yes) {
+            await confirmOrStop(slug, io);
+        }
+        const deleted = await deleteApp(api, slug);
+        // The name is server text: quoted so it reads as a name, never as the
+        // CLI's own sentence, and capped tighter than usual (64) so the line
+        // stays inside 80 columns whatever the server sends. The preflight
+        // above already named the address, so the slug isn't repeated here.
+        io.out(`✓ Deleted   ${quotedForTerminal(deleted.appName, DELETED_LINE_NAME_CHARS)}\n\n`);
+        io.out(`${wrapProse("The app and its versions are gone, and its address now shows nothing. Deploying the app's folder again would create a new app at a new address.")}\n` +
+            "\nNext:\n" +
+            "  Start a new app with npx driggsby@latest init\n");
+        return 0;
+    }
+    catch (error) {
+        throw deployFailure(error, baseUrl, retryCommandFor(resolvedSlug));
+    }
+}
+// A name typed on the command line is shape-gated before it goes anywhere:
+// a typo gets the naming rules instead of a network round trip, nothing
+// unvalidated is ever echoed, and the empty string can't slip through to
+// match an empty confirmation answer.
+function validatedArgvSlug(slug) {
+    const problem = slugProblem(slug);
+    if (problem === null)
+        return slug;
+    const flatProblem = problem.replaceAll("\n", " ");
+    throw new CliError(wrapProse(`${quotedForTerminal(slug, MAX_SERVER_TEXT_CHARS)} doesn't look like an app's address name: ${flatProblem}. Copy the name from the app's driggsby.json ("slug"), or from npx driggsby@latest versions run in its folder.`), 2);
+}
+// The app already isn't there — for a delete that is closer to done than
+// to broken, and the one wrong suggestion would be "deploy it first".
+function appAlreadyGone(slug) {
+    return new CliError(wrapProse(`There's no app named ${quotedForTerminal(slug, MAX_SERVER_TEXT_CHARS)} on your Driggsby account — maybe it was already deleted. Nothing was changed.`), 1);
+}
+// With no name given, the app is the one this folder deploys. Only a
+// genuinely missing driggsby.json gets the "name it directly" guidance;
+// a present-but-broken config surfaces its own precise error, the same
+// one deploy and versions would show.
+async function slugFromProjectFolder(projectDirectory) {
+    try {
+        await access(join(projectDirectory, "driggsby.json"));
+    }
+    catch {
+        throw new CliError(`${wrapProse("This folder doesn't have a driggsby.json, so there's no app here to delete. Name the app directly — the \"slug\" in its driggsby.json:")}\n` +
+            "  npx driggsby@latest delete <APP-ADDRESS-NAME>", 1);
+    }
+    const config = await readProjectConfig(projectDirectory);
+    return config.slug;
+}
+// The person types the address name back. Anything else — including an
+// empty answer — deletes nothing and says so. Scripts and agents have no
+// one to ask, so they must say --yes explicitly.
+async function confirmOrStop(slug, io) {
+    if (!io.interactive) {
+        // Already shape-validated, so echoing it into a command line is safe.
+        throw new CliError(`${wrapProse("Deleting can't be undone, and this terminal can't ask you to confirm. Say it explicitly:")}\n` +
+            `  npx driggsby@latest delete ${slug} --yes`, 2);
+    }
+    const answer = (await io.ask("Type the app's address name to confirm: ")).trim();
+    if (answer !== slug) {
+        throw new CliError("That didn't match, so nothing was deleted.", 1);
+    }
+}

package/dist/deploy/versions-command.js

@@ -42,20 +42,25 @@ export async function runVersions(options, environment = defaultCredentialEnviro
         throw deployFailure(error, baseUrl, "npx driggsby@latest versions");
     }
 }
-// A 404 here means the app has never been deployed from this account, and
-// the fix is a deploy — not a retry.
-export async function fetchVersionList(api, slug) {
+// A 404 here means the app isn't on this account. For versions and
+// rollback the fix is a deploy; a caller whose right next step differs
+// (delete) passes its own notFound shape. The slug is quoted and capped
+// either way — delete hands this an argv string, not only config values.
+export async function fetchVersionList(api, slug, notFound = firstDeployCreatesIt) {
     try {
         return await listVersions(api, slug);
     }
     catch (error) {
         if (error instanceof DeployApiError && error.status === 404) {
-            throw new CliError(`${wrapProse(`There's no app named ${slug} on your Driggsby account yet. Its first deploy creates it:`)}\n` +
-                "  npx driggsby@latest deploy", 1);
+            throw notFound(slug);
         }
         throw error;
     }
 }
+function firstDeployCreatesIt(slug) {
+    return new CliError(`${wrapProse(`There's no app named ${quotedForTerminal(slug, MAX_SERVER_TEXT_CHARS)} on your Driggsby account yet. Its first deploy creates it:`)}\n` +
+        "  npx driggsby@latest deploy", 1);
+}
 export function renderVersionRows(list) {
     const rows = list.versions.map((version) => ({
         label: `v${version.number}`,

package/dist/help.js

@@ -19,7 +19,9 @@ Commands:
   deploy    Deploy the app in this directory to Driggsby.
   rollback  Switch which deployed version of your app is live.
   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
@@ -35,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.
 
@@ -57,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
 
@@ -128,6 +131,19 @@ Options:
                       npx driggsby@latest versions.
   -h, --help          Print help
 `;
+export const DELETE_HELP = `Permanently remove a deployed app.
+
+This deletes the app and every version Driggsby kept for it. There is no
+undo: the app's address shows nothing from that moment on. With no name,
+the app in this folder's driggsby.json is the one deleted. You'll be asked
+to type the name back to confirm; scripts and agents pass --yes instead.
+
+Usage: npx driggsby@latest delete [APP-ADDRESS-NAME] [--yes]
+
+Options:
+      --yes   Skip the confirmation question. For scripts and agents.
+  -h, --help  Print help
+`;
 export const VERSIONS_HELP = `List your deployed app's versions.
 
 Shows every version Driggsby has kept for the app in this directory, which
@@ -168,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

@@ -3,6 +3,7 @@
 import { homedir } from "node:os";
 import { parseArgv } from "./args.js";
 import { CliError } from "./cli-error.js";
+import { runDelete } from "./deploy/delete-command.js";
 import { runDeploy } from "./deploy/deploy-command.js";
 import { runDev } from "./dev/dev-command.js";
 import { runDevStop } from "./dev/dev-stop.js";
@@ -10,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";
@@ -39,12 +41,16 @@ async function run(argv) {
             return command.stop ? await runDevStop(homedir()) : await runDev();
         case "deploy":
             return await runDeploy({ preview: command.preview });
+        case "delete":
+            return await runDelete({ slug: command.slug, yes: command.yes });
         case "rollback":
             return await runRollback({ toVersion: command.toVersion });
         case "versions":
             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.2",
+  "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.2",
-    "@driggsby/sdk": "0.3.2"
+    "@driggsby/deploy": "0.4.0",
+    "@driggsby/sdk": "0.4.0"
   }
 }