@go-labs-sg/bb 1.21.0 → 2.0.0

package/dist/api-client.js

@@ -1,7 +1,18 @@
-import { createTRPCProxyClient, httpBatchLink, loggerLink } from "@trpc/client";
+import { createTRPCProxyClient, httpBatchLink, loggerLink, } from "@trpc/client";
 import SuperJSON from "superjson";
 import { sanitizeValueForTrace, shouldLogCliActions } from "./cli-trace.js";
-export const BUDGET_BUILDER_API_BASE_URL = "https://budget-builder.getout.events";
+export const DEFAULT_BUDGET_BUILDER_API_BASE_URL = "https://budget-builder.getout.events";
+const normalizeApiBaseUrl = (value) => {
+    const url = new URL(value);
+    const isLocalHttp = url.protocol === "http:" &&
+        (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+    if (url.protocol !== "https:" && !isLocalHttp) {
+        throw new Error("Budget Builder API URL must use HTTPS, except for localhost development.");
+    }
+    url.pathname = url.pathname.replace(/\/$/, "");
+    return url.toString().replace(/\/$/, "");
+};
+export let BUDGET_BUILDER_API_BASE_URL = DEFAULT_BUDGET_BUILDER_API_BASE_URL;
 function getAuthHeader() {
     const key = process.env.BB_API_KEY;
     if (!key?.trim())
@@ -17,7 +28,7 @@ const containsRawApiKey = (value, seen = new WeakSet()) => {
     return Object.entries(value).some(([key, nestedValue]) => (key.toLowerCase() === "apikey" && typeof nestedValue === "string") ||
         containsRawApiKey(nestedValue, seen));
 };
-export const api = createTRPCProxyClient({
+export const createBudgetBuilderClient = (apiBaseUrl = BUDGET_BUILDER_API_BASE_URL) => createTRPCProxyClient({
     links: [
         loggerLink({
             enabled: (opts) => shouldLogCliActions() &&
@@ -31,7 +42,7 @@ export const api = createTRPCProxyClient({
             },
         }),
         httpBatchLink({
-            url: `${BUDGET_BUILDER_API_BASE_URL}/api/trpc`,
+            url: `${apiBaseUrl}/api/trpc`,
             transformer: SuperJSON,
             headers: () => {
                 const headers = {
@@ -45,13 +56,38 @@ export const api = createTRPCProxyClient({
         }),
     ],
 });
+let activeClient = createBudgetBuilderClient();
+export const configureBudgetBuilderApiBaseUrl = (value) => {
+    const normalized = normalizeApiBaseUrl(value);
+    BUDGET_BUILDER_API_BASE_URL = normalized;
+    activeClient = createBudgetBuilderClient(normalized);
+    return normalized;
+};
+/**
+ * Stable facade used by command handlers. Tests can replace the transport without
+ * teaching commands about tRPC or process-wide authentication.
+ */
+export const api = new Proxy({}, {
+    get: (_target, property, receiver) => Reflect.get(activeClient, property, receiver),
+});
+export const setBudgetBuilderClientForTesting = (client) => {
+    const previous = activeClient;
+    activeClient = client;
+    return () => {
+        activeClient = previous;
+    };
+};
+export class MissingApiKeyError extends Error {
+    code = "AUTHENTICATION";
+    constructor() {
+        super("BB_API_KEY is required. Set it in the environment.");
+        this.name = "MissingApiKeyError";
+    }
+}
 export function requireApiKey() {
     const key = process.env.BB_API_KEY?.trim();
     if (!key) {
-        console.error(JSON.stringify({
-            error: "BB_API_KEY is required. Set it in the environment.",
-        }));
-        process.exit(1);
+        throw new MissingApiKeyError();
     }
     return key;
 }

package/dist/commands.js

@@ -9,6 +9,7 @@ import { billStatusesForApi, } from "./parse-cli-enums.js";
 import { parseBudgetDiscountPayload, parseCompanyUpdatePayload, parseContactCreatePayload, parseContactUpdatePayload, parseCreateBillPayload, parseCreateBudgetPayload, parseCreateCustomerInvoicePayload, parseCreateQuotationPayload, parseItemCreatePayload, parseItemUpdatePayload, parseSendCustomerInvoiceToContactPersonPayload, parseSendEstimateToContactPersonPayload, parseSupplierCreatePayload, parseSupplierUpdatePayload, parseUpdateBillPayload, parseUpdateBillPaymentEvidencePayload, parseUpdateBudgetCommissionPayload, parseUpdateBudgetPayload, parseUpdateProjectPayload, parseUpdateQuotationPayload, parseValidateBillSelectionPayload, } from "./parse-mutation-payload.js";
 import { BillStatus, BudgetStatus, ProjectStatus } from "./prisma-enums.js";
 import { createRichTextFromPlainText } from "./rich-text.js";
+import { confirmCurrentCommand, emitCommandResult, getActiveCliSession, } from "./runtime/index.js";
 const BUDGET = "BUDGET";
 const BILL = "BILL";
 const SUPPLIER = "SUPPLIER";
@@ -52,7 +53,7 @@ function isPendingRequest(n) {
     return n.notificationType === "request" && n.status === "PENDING_APPROVAL";
 }
 const out = (data) => {
-    console.log(JSON.stringify(data, null, 2));
+    emitCommandResult(data);
 };
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const stringField = (record, key) => {
@@ -311,6 +312,14 @@ export const buildSensitiveWorkflowPreview = ({ action, entity, details, }) => {
     ].join("\n");
 };
 const assertSensitiveWorkflowConfirmed = async (input) => {
+    if (getActiveCliSession()?.invocation.legacy !== true) {
+        await confirmCurrentCommand({
+            action: input.action,
+            target: input.entity,
+            details: input.details,
+        });
+        return;
+    }
     const expected = "CONFIRM";
     const preview = buildSensitiveWorkflowPreview(input);
     if (!process.stdin.isTTY || !process.stderr.isTTY) {
@@ -335,6 +344,15 @@ const assertLockedBudgetChangeConfirmed = async ({ budget, action, }) => {
         return;
     }
     const statusLabel = lockedBudgetStatusLabel(budget.status);
+    if (getActiveCliSession()?.invocation.legacy !== true) {
+        await confirmCurrentCommand({
+            action,
+            target: `budget ${budget.id}`,
+            details: `Changes locked budget "${budget.name}" in status ${statusLabel}.`,
+            effects: ["state-change"],
+        });
+        return;
+    }
     if (!process.stdin.isTTY || !process.stderr.isTTY) {
         throw new Error(`${action} would change locked budget "${budget.name}" (${budget.id}) with status ${statusLabel}. Run this command in an interactive terminal and type "yes" to confirm.`);
     }
@@ -1407,7 +1425,7 @@ export const syncCustomerInvoice = async (invoiceId) => {
     await assertSensitiveWorkflowConfirmed({
         action: "Sync customer invoice from QuickBooks",
         entity: `invoice ${invoiceId}`,
-        details: "refreshes local status, QuickBooks metadata, balance, and history; a QBO-voided invoice becomes VOIDED locally and may reopen its estimate",
+        details: "refreshes local status, QuickBooks metadata, balance, and history; QBO Paid or a zero balance becomes PAID, a reversed payment restores the delivery or approval status, and a QBO void becomes VOIDED",
     });
     const result = await api.customerInvoice.syncInvoiceStatus.mutate({
         invoiceId,

package/dist/index.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import "./load-env.js";
-import { readFileSync } from "node:fs";
-import { BUDGET_BUILDER_API_BASE_URL, requireApiKey } from "./api-client.js";
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { BUDGET_BUILDER_API_BASE_URL, configureBudgetBuilderApiBaseUrl, DEFAULT_BUDGET_BUILDER_API_BASE_URL, requireApiKey, } from "./api-client.js";
 import { consumeCliQuietFlags, logCliAction, sanitizeFlagsForTrace, setCliQuiet, shouldLogCliActions, } from "./cli-trace.js";
 import { addBudgetItems, approveBill, approveBudget, approveCustomerInvoice, approveQuotation, approveSupplier, checkCustomerInvoiceReadiness, checkProjectReconciliation, cleanupStagedBillAttachments, cleanupStagedQuotationAttachments, completeProject, createApiKeyForUser, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createCustomerInvoice, createEstimate, createItemCategory, createItemFromPayload, createPlaceholderBillForBudgetItem, createProject, createQuotationFromPayload, createSupplierCertification, createSupplierFromPayload, createSupplierPaymentMethod, createSupplierRoleOption, createSupplierTagOption, createUser, deleteBillById, deleteBudgetById, deleteBudgetCategory, deleteBudgetCommission, deleteBudgetDiscount, deleteCompanyById, deleteCustomerInvoice, deleteItemById, deleteItemCategoriesByIds, deleteProjectById, deleteQuotationById, deleteSuppliersByIds, discardCreatingCustomerInvoice, downloadCustomerInvoicePaymentProof, downloadCustomerInvoicePdf, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getCustomerInvoice, getCustomerInvoiceEmailContext, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, importQuickBooksProjectId, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listCustomerInvoices, listEligibleCustomerInvoiceBudgets, listIntegrationOperations, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, markCustomerInvoicePaidFromPath, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, sendCustomerInvoiceToContactPersonFromPayload, sendEstimateToContactPersonFromPayload, setBudgetItemsNotUtilized, stageBillAttachmentsFromPaths, submitQuotation, syncCustomerInvoice, updateBillFromPayload, updateBillPaymentEvidenceFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateQuotationFromPayload, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBillAttachmentsFromPaths, uploadBillDocumentsFromPaths, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, validateBillSelectionFromPayload, voidCustomerInvoice, whoAmI, } from "./commands.js";
 import { getFlag, parseArgs } from "./parse-args.js";
 import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedCustomerInvoiceStatuses, parseCommaSeparatedIds, parseCommaSeparatedQuotationStatuses, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, parseUserRole, projectStatusesForHelp, userRolesForHelp, } from "./parse-cli-enums.js";
 import { parseJsonFlag, parseOptionalNumber as parseOptNum, } from "./parse-json-flag.js";
+import { createCompletionScript, createHumanHelp, resolveCommand, } from "./registry/index.js";
+import { CliRuntimeError, clearActiveCliSession, confirmCurrentCommand, createProcessRuntime, emitCommandError, emitCommandResult, setActiveCliSession, } from "./runtime/index.js";
 function parsePositiveIntFlag(value, flagName) {
     if (value === undefined)
         return undefined;
@@ -139,7 +143,7 @@ function parseDashboardQueryFlags(flags) {
         endDate: getFlag(flags, "endDate"),
     };
 }
-function printHelp() {
+function printLegacyHelp(runtime) {
     const help = `
 bb — Budget Builder CLI for AI agents (parity with MCP tools)
 
@@ -208,10 +212,10 @@ Bills
   list-bills                 [--projectId] [--budgetId] [--status CSV] [--search <text>] [--isClaimable true|false] [--createdByIds <csv>] [--sortBy createdAt|amount|status] [--sortDir asc|desc] [--page] [--pageSize]
   list-claims                same flags as list-bills; only reimbursable claims (ignores --isClaimable)
     isClaimable differentiates the shared bill/claim records: false = bill, true = claim.
-    New supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage for each non-legacy line item.
+    Non-legacy supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage for every selected line item, including already-paid bills.
   create-bill-approval <billId>       (also sends approval request emails)
   create-bill                --payload '<json>'  (bill.create; payload.isClaimable false = bill, true = claim)
-  validate-bill-selection    --payload '<json>'  Check projectId, supplierId, budgetItemIds, and optional alreadyPaid before creation.
+  validate-bill-selection    --payload '<json>'  Check projectId, supplierId, and budgetItemIds before creation; alreadyPaid never bypasses quotation checks.
   stage-bill-attachment <projectId> <filePath...> [--file <path>] [--files <csv>]   Upload files before create-bill; returns attachment JSON for attachments/paymentProofAttachments
   cleanup-staged-bill-attachments <projectId> --keys <csv>   Delete unattached staged bill/claim uploads.
   update-bill                --payload '<json>'  (bill.update; must include id)
@@ -261,7 +265,7 @@ Customer invoices
     Admin-only. Uploads proof, creates a QBO Payment for the live balance when needed, attaches proof in QBO when possible, and records payment history in BB.
   download-customer-invoice-payment-proof <invoiceId> [--output <path>]
   download-customer-invoice-pdf <invoiceId> [--output <path>]
-  sync-customer-invoice <invoiceId>             Refresh local status and balance from QuickBooks; QBO voids can reopen a closed estimate.
+  sync-customer-invoice <invoiceId>             Refresh local status and balance from QuickBooks; paid invoices become PAID, reversals restore delivery/approval, and QBO voids can reopen an estimate.
 
 Approvals
   list-approvals | get-pending-approvals   [--type budget|supplier|bill|quotation|customer_invoice|all]
@@ -361,7 +365,7 @@ Note: MCP also exposes a Prisma schema resource; the CLI has no equivalent.
 
 Not covered vs MCP get_budget: "get-budget" also fetches line items in one call.
 `.trim();
-    console.log(help);
+    runtime.stdout.write(`${help}\n`);
 }
 const getCliPackageMetadata = () => {
     const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -370,30 +374,242 @@ const getCliPackageMetadata = () => {
     }
     return { name: packageJson.name, version: packageJson.version };
 };
-const printVersion = () => {
+const getVersionData = () => {
     const metadata = getCliPackageMetadata();
-    console.log(JSON.stringify({
+    return {
         ...metadata,
         apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
-    }, null, 2));
+    };
 };
 /** MCP registers tools with snake_case; CLI commands are kebab-case. */
 function normalizeCliCommand(raw) {
     return raw.replace(/_/g, "-");
 }
-async function main() {
-    const { command, positional, flags } = parseArgs(process.argv);
-    setCliQuiet(consumeCliQuietFlags(flags));
-    const cmd = normalizeCliCommand(command ?? "");
-    if (cmd === "version" || flags.version === true) {
-        printVersion();
-        process.exit(0);
+const booleanFlagValues = new Set(["true", "false", "1", "0"]);
+const isEnabledFlag = (argv, flag) => {
+    for (let index = 0; index < argv.length; index++) {
+        const value = argv[index];
+        if (value === `${flag}=true` || value === `${flag}=1`)
+            return true;
+        if (value?.startsWith(`${flag}=`))
+            return false;
+        if (value !== flag)
+            continue;
+        const next = argv[index + 1];
+        if (next !== undefined && booleanFlagValues.has(next)) {
+            return next === "true" || next === "1";
+        }
+        return true;
     }
-    if (!cmd || cmd === "help" || flags.help === true) {
-        printHelp();
-        process.exit(0);
+    return false;
+};
+const runtimeOnlyFlags = [
+    "--allow-state-change",
+    "--allow-email",
+    "--allow-external-write",
+    "--allow-delete",
+    "--allow-financial-write",
+    "--debug",
+    "--quiet",
+    "--api-url",
+];
+const isRuntimeOnlyArgument = (value) => runtimeOnlyFlags.some((flag) => value === flag || value.startsWith(`${flag}=`)) || value === "-q";
+const parseRootArguments = (argv) => {
+    const commandArgv = [];
+    let apiBaseUrl;
+    for (let index = 0; index < argv.length; index++) {
+        const value = argv[index];
+        if (value === undefined)
+            continue;
+        if (value.startsWith("--api-url=")) {
+            apiBaseUrl = value.slice("--api-url=".length);
+            continue;
+        }
+        if (value === "--api-url") {
+            const next = argv[index + 1];
+            if (next === undefined || next.startsWith("-")) {
+                throw new CliRuntimeError("USAGE", "--api-url requires a URL.");
+            }
+            apiBaseUrl = next;
+            index++;
+            continue;
+        }
+        if (isRuntimeOnlyArgument(value)) {
+            const next = argv[index + 1];
+            if (next !== undefined && booleanFlagValues.has(next))
+                index++;
+            continue;
+        }
+        commandArgv.push(value);
     }
-    requireApiKey();
+    return { apiBaseUrl, commandArgv };
+};
+const effectPermissionsFromArgv = (argv) => ({
+    allowStateChange: isEnabledFlag(argv, "--allow-state-change"),
+    allowEmail: isEnabledFlag(argv, "--allow-email"),
+    allowExternalWrite: isEnabledFlag(argv, "--allow-external-write"),
+    allowDelete: isEnabledFlag(argv, "--allow-delete"),
+    allowFinancialWrite: isEnabledFlag(argv, "--allow-financial-write"),
+});
+const isCompletionShell = (value) => value === "bash" ||
+    value === "zsh" ||
+    value === "fish" ||
+    value === "powershell";
+const legacyArgvForCommand = (argv, resolvedCommand) => {
+    const legacyTarget = resolvedCommand.command.legacyTarget;
+    if (legacyTarget === undefined) {
+        throw new CliRuntimeError("INTERNAL", `Command ${resolvedCommand.command.path.join(" ")} has no dispatcher target.`);
+    }
+    return [
+        argv[0] ?? "node",
+        argv[1] ?? "bb",
+        legacyTarget,
+        ...resolvedCommand.argv.filter((value) => !isRuntimeOnlyArgument(value)),
+    ];
+};
+const normalizeDispatcherError = (error) => {
+    if (!(error instanceof Error))
+        return error;
+    if (/\brequires\b|\bmust be\b|\bmust include\b|^Invalid\b|^Missing\b|^--/.test(error.message)) {
+        return new CliRuntimeError("VALIDATION", error.message);
+    }
+    return error;
+};
+const commandConfirmationTarget = (resolvedCommand) => {
+    const positionalTarget = resolvedCommand.argv.find((value) => value !== "--" && !value.startsWith("-"));
+    if (positionalTarget !== undefined &&
+        !positionalTarget.startsWith("{") &&
+        !positionalTarget.startsWith("[")) {
+        return positionalTarget;
+    }
+    return resolvedCommand.command.path.join(" ");
+};
+export async function runCli(argv = process.argv, runtime = createProcessRuntime()) {
+    const rawArgv = argv.slice(2);
+    const metadata = getCliPackageMetadata();
+    const quiet = isEnabledFlag(rawArgv, "--quiet") ||
+        rawArgv.includes("-q") ||
+        runtime.env.BB_CLI_QUIET === "1";
+    const debug = isEnabledFlag(rawArgv, "--debug");
+    let rootArguments;
+    try {
+        rootArguments = parseRootArguments(rawArgv);
+        const apiBaseUrl = rootArguments.apiBaseUrl ?? runtime.env.BB_API_URL?.trim();
+        configureBudgetBuilderApiBaseUrl(apiBaseUrl || DEFAULT_BUDGET_BUILDER_API_BASE_URL);
+    }
+    catch (error) {
+        setActiveCliSession({
+            runtime,
+            invocation: {
+                command: "startup",
+                cliVersion: metadata.version,
+                apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
+                quiet,
+                debug,
+            },
+            effects: [],
+            permissions: {},
+        });
+        const message = error instanceof Error ? error.message : String(error);
+        const exitCode = emitCommandError(error instanceof CliRuntimeError
+            ? error
+            : new CliRuntimeError("USAGE", `Invalid API URL: ${message}`));
+        clearActiveCliSession();
+        return exitCode;
+    }
+    const { commandArgv } = rootArguments;
+    if (commandArgv.length === 0 ||
+        commandArgv[0] === "help" ||
+        isEnabledFlag(commandArgv, "--help") ||
+        commandArgv.includes("-h")) {
+        if (commandArgv.includes("--legacy")) {
+            printLegacyHelp(runtime);
+        }
+        else {
+            runtime.stdout.write(`${createHumanHelp()}\n`);
+        }
+        return 0;
+    }
+    if (commandArgv[0] === "completion") {
+        const shell = commandArgv[1];
+        if (shell === undefined || !isCompletionShell(shell)) {
+            setActiveCliSession({
+                runtime,
+                invocation: {
+                    command: "completion",
+                    cliVersion: metadata.version,
+                    apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
+                    quiet,
+                    debug,
+                },
+                effects: [],
+                permissions: {},
+            });
+            const exitCode = emitCommandError(new CliRuntimeError("USAGE", "completion requires bash, zsh, fish, or powershell."));
+            clearActiveCliSession();
+            return exitCode;
+        }
+        runtime.stdout.write(createCompletionScript(shell));
+        return 0;
+    }
+    if (commandArgv[0] === "version" ||
+        isEnabledFlag(commandArgv, "--version") ||
+        commandArgv.includes("-v")) {
+        setActiveCliSession({
+            runtime,
+            invocation: {
+                command: "version",
+                cliVersion: metadata.version,
+                apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
+                quiet,
+                debug,
+            },
+            effects: [],
+            permissions: {},
+        });
+        emitCommandResult(getVersionData());
+        clearActiveCliSession();
+        return 0;
+    }
+    const resolvedCommand = resolveCommand(commandArgv);
+    if (resolvedCommand === undefined) {
+        setActiveCliSession({
+            runtime,
+            invocation: {
+                command: commandArgv[0] ?? "unknown",
+                cliVersion: metadata.version,
+                apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
+                quiet,
+                debug,
+            },
+            effects: [],
+            permissions: {},
+        });
+        const exitCode = emitCommandError(new CliRuntimeError("USAGE", `Unknown command: ${commandArgv.join(" ")}. Run 'bb help'.`));
+        clearActiveCliSession();
+        return exitCode;
+    }
+    const effectiveArgv = legacyArgvForCommand(argv, resolvedCommand);
+    const { command, positional, flags } = parseArgs(effectiveArgv);
+    consumeCliQuietFlags(flags);
+    setCliQuiet(resolvedCommand.isLegacyAlias ? quiet : quiet || !debug);
+    setActiveCliSession({
+        runtime,
+        invocation: {
+            command: resolvedCommand.command.path.join(" "),
+            cliVersion: metadata.version,
+            apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
+            legacy: resolvedCommand.isLegacyAlias,
+            quiet,
+            debug,
+        },
+        effects: resolvedCommand.command.effects,
+        permissions: effectPermissionsFromArgv(rawArgv),
+    });
+    if (resolvedCommand.isLegacyAlias && !quiet) {
+        runtime.stderr.write(`[bb] Deprecated command "${resolvedCommand.invokedAs.join(" ")}"; use "bb ${resolvedCommand.command.path.join(" ")}".\n`);
+    }
+    const cmd = normalizeCliCommand(command ?? "");
     const t0 = Date.now();
     if (shouldLogCliActions()) {
         logCliAction({
@@ -405,6 +621,15 @@ async function main() {
         });
     }
     try {
+        requireApiKey();
+        if (!resolvedCommand.isLegacyAlias &&
+            resolvedCommand.command.effects.length > 0) {
+            await confirmCurrentCommand({
+                action: resolvedCommand.command.path.join(" "),
+                target: commandConfirmationTarget(resolvedCommand),
+                details: "Canonical v2 mutation. Supply every effect-specific --allow-* flag for non-interactive execution.",
+            });
+        }
         switch (cmd) {
             case "whoami": {
                 await whoAmI();
@@ -1842,6 +2067,8 @@ async function main() {
                 durationMs: Date.now() - t0,
             });
         }
+        clearActiveCliSession();
+        return 0;
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -1854,8 +2081,21 @@ async function main() {
                 error: message,
             });
         }
-        console.error(JSON.stringify({ error: message }));
-        process.exit(1);
+        const exitCode = emitCommandError(normalizeDispatcherError(err));
+        clearActiveCliSession();
+        return exitCode;
     }
 }
-main();
+const resolveExecutablePath = (value) => {
+    try {
+        return realpathSync(value);
+    }
+    catch {
+        return resolve(value);
+    }
+};
+const isDirectExecution = process.argv[1] !== undefined &&
+    resolveExecutablePath(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isDirectExecution) {
+    process.exitCode = await runCli();
+}

package/dist/registry/generate-command-artifacts.js

@@ -0,0 +1,36 @@
+import { execFileSync } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { commandRegistry, createCommandManifest, globalCommandOptions, } from "./index.js";
+const packageRoot = process.cwd();
+const manifestPath = resolve(packageRoot, "command-manifest.json");
+const reference = [
+    "# Budget Builder CLI command reference",
+    "",
+    "This file is generated from the typed command registry. Do not edit it manually.",
+    "This catalog is not filtered by the authenticated user's role. The Budget Builder API authorizes every request using the current database role plus applicable resource, workflow-state, and pending-approver checks.",
+    "Command-specific arguments currently pass through the compatibility dispatcher; use `bb help --legacy` for their detailed transition reference.",
+    "",
+    "## Global options",
+    "",
+    ...globalCommandOptions.map((option) => `- \`${option.name}\`: ${option.description}`),
+    "",
+    ...commandRegistry.flatMap((command) => [
+        `## \`bb ${command.path.join(" ")}\``,
+        "",
+        command.summary,
+        "",
+        `Legacy aliases: ${command.legacyAliases.map((alias) => `\`${alias}\``).join(", ")}.`,
+        "",
+        `Effects: ${command.effects.length > 0 ? command.effects.join(", ") : "none"}.`,
+        "",
+    ]),
+].join("\n");
+await Promise.all([
+    writeFile(resolve(packageRoot, "command-reference.md"), reference),
+    writeFile(manifestPath, `${JSON.stringify(createCommandManifest(), null, "\t")}\n`),
+]);
+execFileSync(process.execPath, ["x", "biome", "format", "--write", manifestPath], {
+    cwd: packageRoot,
+    stdio: ["ignore", "ignore", "inherit"],
+});