@go-labs-sg/bb 1.20.0 → 2.0.0

package/dist/index.js

@@ -1,11 +1,16 @@
 #!/usr/bin/env node
 import "./load-env.js";
-import { 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, downloadCustomerInvoicePdf, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getCustomerInvoice, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, importQuickBooksProjectId, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listCustomerInvoices, listIntegrationOperations, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, 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, } from "./commands.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;
@@ -138,15 +143,24 @@ 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)
 
 Usage: bb <command> [options] [args]
 
+Identity: bb version — print the installed CLI package version and API target as JSON.
+
 Global: --quiet | -q | BB_CLI_QUIET=1 — hide action logs (default: log command + each tRPC call to stderr; stdout JSON unchanged).
 
-Auth: Set BB_API_KEY in the environment (same API key as MCP / Goracle).
+Auth: Create a key under API Keys in Budget Builder and set BB_API_KEY in the environment.
+
+Authorization: Run bb whoami before choosing commands. bb help lists the full
+catalog for every role; it does not prove the active key may call a command.
+The API evaluates whoami.role (USER, INSIDE_SALES, LEAD, ACCOUNTING_TEAM, or
+ADMIN) together with resource ownership/project assignment, current state, and
+pending-approver assignment. On FORBIDDEN, stop and report the identity, role,
+command, and target; do not switch keys or try a lower-level procedure.
 
 Sensitive workflow changes: approval decisions/requests, entity status updates,
 estimate emails, customer invoices, integration retries, mark-budget-won,
@@ -170,7 +184,7 @@ Budgets
     ESTIMATE_ACCEPTED requires win proof, auto-marks PITCH or LOST projects WON, requires --projectManagerId when the project has no PM, and auto-creates the Asana project/section when enabled.
     ESTIMATE_REJECTED requires --projectStatusOnCommercialRejection when rejecting the only accepted/closed budget on a commercial project.
     status: ${budgetStatusesForHelp.join(", ")}
-  mark-budget-won <budgetId> <filePath> [--projectManagerId <id>] [--markProjectWon true|false]   Upload signed quote/PO proof and set status to ESTIMATE_ACCEPTED; PITCH or LOST projects become WON automatically and require PM when none is assigned
+	mark-budget-won <budgetId> <filePath> [--projectManagerId <id>] [--invoiceSettings <json>]   Upload signed quote/PO proof and set status to ESTIMATE_ACCEPTED; first acceptance requires invoice settings when customer invoicing is enabled
   create-budget              --payload '<json>'  (budget.createBudget; Asana deal card is on the project)
   update-budget              --payload '<json>'  (budget.updateBudget; must include id)
   delete-budget <budgetId>
@@ -198,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)
@@ -235,16 +249,23 @@ Quotations
 
 Customer invoices
   check-customer-invoice-readiness <budgetId>
-  list-customer-invoices <budgetId> [--status CSV] [--search] [--sortBy createdAt|status|totalNetAmount|approvalExpiresAt] [--sortDir asc|desc] [--page] [--perPage]
+  list-eligible-customer-invoice-budgets <projectId>   Accepted budgets that are ready and still have invoice coverage remaining.
+  list-customer-invoices [budgetId] [--projectId <id>] [--companyIds CSV] [--projectIds CSV] [--budgetIds CSV] [--createdByIds CSV] [--status CSV] [--search] [--sortBy createdAt|status|totalNetAmount|approvalExpiresAt] [--sortDir asc|desc] [--page] [--perPage]
+    No scope flag lists invoices globally. --projectId uses the project scope. A positional budgetId is a backward-compatible shortcut for --budgetIds.
   get-customer-invoice <batchId>
+  get-customer-invoice-email-context <batchId>        Contact, required CC, budget, and project context for composing an invoice email.
   create-customer-invoice --payload '<json>'   budgetId + one split with label, percentage, and dueDate.
   discard-customer-invoice <batchId>           Discard a reserved CREATING batch with no created QBO invoices.
   delete-customer-invoice <batchId>            Delete QBO invoices and the local batch.
   void-customer-invoice <batchId>              Void the invoice batch in QuickBooks.
-  approve-customer-invoice <batchId>           Admin approval; notifies the creator.
+  approve-customer-invoice <batchId>           Admin approval; rejects voided invoices, notifies the creator, and closes the estimate at cumulative 100% coverage.
   reject-customer-invoice <batchId> --reason <text>   Admin rejection; voids QBO invoices and notifies the creator.
+  send-customer-invoice-to-contact-person --payload '<json>'   Same composer workflow as web; requires invoiceId, to, cc, replyTo, subject, HTML content, and HTML signature.
+  mark-customer-invoice-paid <invoiceId> --paymentDate YYYY-MM-DD --paymentProof <path> [--paymentReference <text>]
+    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.
+  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]
@@ -298,30 +319,31 @@ Suppliers & items
   update-item                --payload '<json>'  (item.updateItem; must include id)
   delete-item <id>
   get-supplier-details <supplierId>
-  get-supplier-analytics     [--name] [--page] [--perPage] [--timeFrame ALL|LAST_YEAR|…]
+  get-supplier-analytics     [--name] [--page] [--perPage] [--timeFrame ALL|LAST_YEAR|…]  (admin)
   list-items                 [--name] [--page] [--perPage]
   get-item <id>
   list-item-categories       [--page] [--perPage]
-  create-item-category       --name
-  update-item-category       --id --name
+  create-item-category       --name  (admin)
+  update-item-category       --id --name  (admin)
   delete-item-categories     --ids <csv>  (itemCategory.deleteItemCategories; admin; empty categories only)
 
 Dashboard & users
+  whoami                    Show the user identity and role for the active API key.
   list-users
   create-user                --email <email> [--name <name>] [--role ${userRolesForHelp.join("|")}]  (admin; API-only service identity with no Google sign-in)
-  create-api-key             --userId <userId> --name <label>  (admin; raw key is shown once)
-  list-api-keys              [--userId <userId>]  (admin; defaults to the caller)
-  revoke-api-key <apiKeyId>  [--userId <userId>]  (admin; --userId is required for another user's key)
-  get-user-performance       [--userId]
-  get-dashboard              [--userId] [--role BD|CREATOR|INSIDE_SALES|ALL] [--deals ALL|SUCCESSFUL|LOST] [--timeFrame] [--startDate] [--endDate]
-  get-monthly-metrics        [same optional flags as get-dashboard]  (dashboard.getMonthlyMetrics)
-  get-system-overview        [same optional flags as get-dashboard]  (dashboard.getSystemOverview)
-  get-estimate-performance   [same optional flags as get-dashboard]  (dashboard.getEstimatePerformance)
-  get-financial-overview     [same optional flags as dashboard; role uses BudgetRole enum]
+  create-api-key             --name <label> [--userId <userId>]  (defaults to the caller; admin required for another user; raw key is shown once)
+  list-api-keys              [--userId <userId>]  (defaults to the caller; admin required for another user)
+  revoke-api-key <apiKeyId>  [--userId <userId>]  (defaults to the caller; admin required for another user)
+  get-user-performance       [--userId]  (admin)
+  get-dashboard              [--userId] [--role BD|CREATOR|INSIDE_SALES|ALL] [--deals ALL|SUCCESSFUL|LOST] [--timeFrame] [--startDate] [--endDate]  (admin)
+  get-monthly-metrics        [same optional flags as get-dashboard]  (admin; dashboard.getMonthlyMetrics)
+  get-system-overview        [same optional flags as get-dashboard]  (admin; dashboard.getSystemOverview)
+  get-estimate-performance   [same optional flags as get-dashboard]  (admin; dashboard.getEstimatePerformance)
+  get-financial-overview     [same optional flags as dashboard; role uses BudgetRole enum]  (admin)
 
 Errors
-  get-recent-errors          [--page] [--perPage] [--severity] [--status]
-  get-error-metrics
+  get-recent-errors          [--page] [--perPage] [--severity] [--status]  (admin)
+  get-error-metrics          (admin)
 
 Automation (admin)
   list-integration-operations [--destination] [--status PENDING|PROCESSING|FAILED|COMPLETED] [--page] [--perPage]
@@ -343,21 +365,251 @@ 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"));
+    if (!packageJson.name || !packageJson.version) {
+        throw new Error("Could not read Budget Builder CLI package metadata.");
+    }
+    return { name: packageJson.name, version: packageJson.version };
+};
+const getVersionData = () => {
+    const metadata = getCliPackageMetadata();
+    return {
+        ...metadata,
+        apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
+    };
+};
 /** 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 || cmd === "help" || flags.help === true) {
-        printHelp();
-        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;
     }
-    requireApiKey();
+    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);
+    }
+    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({
@@ -369,7 +621,20 @@ 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();
+                break;
+            }
             case "list-budgets": {
                 const statusStr = getFlag(flags, "status");
                 const statuses = parseCommaSeparatedBudgetStatuses(statusStr !== undefined ? String(statusStr) : undefined);
@@ -415,6 +680,9 @@ async function main() {
                         ? String(getFlag(flags, "projectManagerId"))
                         : undefined,
                     markProjectWon: parseOptionalBoolFlag(flags, "markProjectWon"),
+                    projectInvoiceSettings: getFlag(flags, "invoiceSettings") !== undefined
+                        ? parseJsonFlag(String(getFlag(flags, "invoiceSettings")), "--invoiceSettings")
+                        : undefined,
                 });
                 break;
             }
@@ -474,6 +742,9 @@ async function main() {
                         : undefined,
                     markProjectWon: parseOptionalBoolFlag(flags, "markProjectWon"),
                     projectStatusOnCommercialRejection: parseCommercialRejectionProjectStatus(flags),
+                    projectInvoiceSettings: getFlag(flags, "invoiceSettings") !== undefined
+                        ? parseJsonFlag(String(getFlag(flags, "invoiceSettings")), "--invoiceSettings")
+                        : undefined,
                 });
                 break;
             }
@@ -1070,19 +1341,39 @@ async function main() {
                 await checkCustomerInvoiceReadiness(budgetId);
                 break;
             }
-            case "list-customer-invoices": {
-                const budgetId = positional[0];
-                if (!budgetId) {
-                    throw new Error("list-customer-invoices requires <budgetId>");
+            case "list-eligible-customer-invoice-budgets": {
+                const projectId = positional[0];
+                if (!projectId) {
+                    throw new Error("list-eligible-customer-invoice-budgets requires <projectId>");
                 }
+                await listEligibleCustomerInvoiceBudgets(projectId);
+                break;
+            }
+            case "list-customer-invoices": {
+                const positionalBudgetId = positional[0];
+                const projectId = getFlag(flags, "projectId");
+                const projectIds = parseCommaSeparatedIds(getFlag(flags, "projectIds"));
+                if (projectId && projectIds) {
+                    throw new Error("Use either --projectId for project scope or --projectIds for a global filter, not both.");
+                }
+                const budgetIds = [
+                    ...(positionalBudgetId ? [positionalBudgetId] : []),
+                    ...(parseCommaSeparatedIds(getFlag(flags, "budgetIds")) ?? []),
+                ];
                 const statusRaw = getFlag(flags, "status");
                 const sortDir = parseOptionalBillListSortDir(getFlag(flags, "sortDir"));
                 await listCustomerInvoices({
-                    budgetId,
+                    scope: projectId
+                        ? { type: "project", projectId }
+                        : { type: "global" },
                     page: parsePositiveIntFlag(getFlag(flags, "page"), "--page") ?? 1,
-                    perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage") ?? 12,
+                    perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage") ?? 20,
                     q: getFlag(flags, "search") ?? "",
                     statuses: parseCommaSeparatedCustomerInvoiceStatuses(statusRaw !== undefined ? String(statusRaw) : undefined),
+                    companyIds: parseCommaSeparatedIds(getFlag(flags, "companyIds")),
+                    projectIds,
+                    budgetIds: budgetIds.length > 0 ? [...new Set(budgetIds)] : undefined,
+                    createdByIds: parseCommaSeparatedIds(getFlag(flags, "createdByIds")),
                     sortBy: parseCustomerInvoiceSortBy(getFlag(flags, "sortBy")),
                     sortDir: sortDir ?? "desc",
                 });
@@ -1096,6 +1387,14 @@ async function main() {
                 await getCustomerInvoice(batchId);
                 break;
             }
+            case "get-customer-invoice-email-context": {
+                const batchId = positional[0];
+                if (!batchId) {
+                    throw new Error("get-customer-invoice-email-context requires <batchId>");
+                }
+                await getCustomerInvoiceEmailContext(batchId);
+                break;
+            }
             case "create-customer-invoice": {
                 const payloadRaw = getFlag(flags, "payload");
                 if (!payloadRaw) {
@@ -1145,6 +1444,37 @@ async function main() {
                 await rejectCustomerInvoice(batchId, String(reason));
                 break;
             }
+            case "send-customer-invoice-to-contact-person": {
+                const payloadRaw = getFlag(flags, "payload");
+                if (!payloadRaw) {
+                    throw new Error("send-customer-invoice-to-contact-person requires --payload '<json>'");
+                }
+                await sendCustomerInvoiceToContactPersonFromPayload(parseJsonFlag(String(payloadRaw), "--payload"));
+                break;
+            }
+            case "mark-customer-invoice-paid": {
+                const invoiceId = positional[0];
+                const paymentDate = getFlag(flags, "paymentDate");
+                const paymentProofPath = getFlag(flags, "paymentProof");
+                if (!invoiceId || !paymentDate || !paymentProofPath) {
+                    throw new Error("mark-customer-invoice-paid requires <invoiceId> --paymentDate YYYY-MM-DD --paymentProof <path> [--paymentReference <text>]");
+                }
+                await markCustomerInvoicePaidFromPath({
+                    invoiceId,
+                    paymentDate,
+                    paymentProofPath,
+                    paymentReference: getFlag(flags, "paymentReference"),
+                });
+                break;
+            }
+            case "download-customer-invoice-payment-proof": {
+                const invoiceId = positional[0];
+                if (!invoiceId) {
+                    throw new Error("download-customer-invoice-payment-proof requires <invoiceId> [--output <path>]");
+                }
+                await downloadCustomerInvoicePaymentProof(invoiceId, getFlag(flags, "output"));
+                break;
+            }
             case "download-customer-invoice-pdf": {
                 const invoiceId = positional[0];
                 if (!invoiceId) {
@@ -1601,8 +1931,8 @@ async function main() {
             case "create-api-key": {
                 const userId = getFlag(flags, "userId");
                 const name = getFlag(flags, "name");
-                if (!userId || !name) {
-                    throw new Error("create-api-key requires --userId <userId> --name <label>");
+                if (!name) {
+                    throw new Error("create-api-key requires --name <label> [--userId <userId>]");
                 }
                 await createApiKeyForUser({ userId, name });
                 break;
@@ -1737,6 +2067,8 @@ async function main() {
                 durationMs: Date.now() - t0,
             });
         }
+        clearActiveCliSession();
+        return 0;
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
@@ -1749,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;
+    }
+}
+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();
 }
-main();

package/dist/load-env.js

@@ -3,4 +3,4 @@
  */
 import path from "node:path";
 import { config } from "dotenv";
-config({ path: path.resolve(process.cwd(), ".env") });
+config({ path: path.resolve(process.cwd(), ".env"), quiet: true });

package/dist/parse-mutation-payload.js

@@ -42,24 +42,37 @@ const requiredEmail = (value, fieldLabel) => {
     }
     return email;
 };
+const parseContactPersonEmailPayload = (input, commandName) => {
+    if (!Array.isArray(input.cc)) {
+        throw new Error(`${commandName} payload.cc must be an email array.`);
+    }
+    return {
+        to: requiredEmail(input.to, `${commandName} payload.to`),
+        cc: input.cc.map((email, index) => requiredEmail(email, `${commandName} payload.cc[${index}]`)),
+        replyTo: requiredEmail(input.replyTo, `${commandName} payload.replyTo`),
+        subject: requiredString(input.subject, `${commandName} payload.subject`),
+        content: requiredString(input.content, `${commandName} payload.content`),
+        signature: requiredString(input.signature, `${commandName} payload.signature`),
+    };
+};
 /** Matches the web estimate composer (`email.sendEstimateToContactPerson`). */
 export const parseSendEstimateToContactPersonPayload = (raw) => {
     const input = requireObject(raw, "send-estimate-to-contact-person payload");
-    if (!Array.isArray(input.cc)) {
-        throw new Error("send-estimate-to-contact-person payload.cc must be an email array.");
-    }
     return {
-        to: requiredEmail(input.to, "send-estimate-to-contact-person payload.to"),
-        cc: input.cc.map((email, index) => requiredEmail(email, `send-estimate-to-contact-person payload.cc[${index}]`)),
-        replyTo: requiredEmail(input.replyTo, "send-estimate-to-contact-person payload.replyTo"),
-        subject: requiredString(input.subject, "send-estimate-to-contact-person payload.subject"),
-        content: requiredString(input.content, "send-estimate-to-contact-person payload.content"),
-        signature: requiredString(input.signature, "send-estimate-to-contact-person payload.signature"),
+        ...parseContactPersonEmailPayload(input, "send-estimate-to-contact-person"),
         estimateId: requiredString(input.estimateId, "send-estimate-to-contact-person payload.estimateId"),
         estimateDocNumber: optionalString(input.estimateDocNumber),
         budgetId: requiredString(input.budgetId, "send-estimate-to-contact-person payload.budgetId"),
     };
 };
+/** Matches the web customer-invoice email composer. */
+export const parseSendCustomerInvoiceToContactPersonPayload = (raw) => {
+    const input = requireObject(raw, "send-customer-invoice-to-contact-person payload");
+    return {
+        ...parseContactPersonEmailPayload(input, "send-customer-invoice-to-contact-person"),
+        invoiceId: requiredString(input.invoiceId, "send-customer-invoice-to-contact-person payload.invoiceId"),
+    };
+};
 /** Matches budget.createBudget — optional pipedriveDealId; Asana deal is project.asanaTaskId. */
 export function parseCreateBudgetPayload(raw) {
     const o = requireObject(raw, "create-budget payload");