@go-labs-sg/bb 2.46.0 → 2.48.0

package/README.md

@@ -1,10 +1,22 @@
 # bb
 
-Command-line interface for **Budget Builder**. Call budgets, bills, claims, approvals, suppliers, dashboard, and more from your terminal or from tools that don’t support MCP (e.g. some AI agents). Responses are JSON on stdout.
+Command-line interface for **Budget Builder**. Call budgets, bills, claims, approvals, suppliers, dashboard, and more from your terminal or from AI agents and automation. The CLI is the maintained integration surface; the former MCP server is deprecated. Responses are JSON on stdout.
 
-For AI agents: bills and claims are stored as the same underlying bill records. Use the `isClaimable` column/flag to distinguish them: `isClaimable=false` means a normal bill, while `isClaimable=true` means a reimbursable claim.
+## First step: update before use
+
+Before starting a task, **update to the latest published release first**, including when an AI agent runs this CLI:
+
+```bash
+bun add --global @go-labs-sg/bb@latest
+bb version
+bb --help
+```
+
+Run this sequence once per task, not before every command. Re-read the updated help before choosing commands or flags. If updating fails, stop and report the failure rather than silently using an outdated CLI. If the user explicitly requested a pinned version or a development/staging build, preserve that version instead of replacing it with the public release.
+
+New installation? Follow the runtime and installation instructions below to install Bun first, then return to this step.
 
-For AI agents using this CLI: always check whether a newer `@go-labs-sg/bb` version is available before running Budget Builder commands, then update the CLI if needed so command flags and API behavior stay current.
+For AI agents: bills and claims are stored as the same underlying bill records. Use the `isClaimable` column/flag to distinguish them: `isClaimable=false` means a normal bill, while `isClaimable=true` means a reimbursable claim.
 
 For AI agents using this CLI: run `bb auth whoami` before reading or changing Budget Builder data. The CLI displays every command regardless of the authenticated user's role, but the API authorizes each request using the current browser-authorized CLI user or automation API-key owner, resource ownership or project assignment, current workflow state, and approval assignment. See the [role-aware agent guide](./role-aware-agent-guide.md) before choosing commands.
 
@@ -14,11 +26,17 @@ For AI agents using this CLI: do not execute mutations until the user explicitly
 
 ## Bill and claim list summaries
 
-`bb bill list` / `bb claim list` (legacy `list-bills` / `list-claims`) now use `bill.getList`. Lists return summary fields, `isClaimable`, `lineItemCount` and `hasPendingApproval`, plus the existing pagination, counts and metrics envelope. Filters and sorting are unchanged. They no longer return attachment, detailed line-item or approval arrays, full supplier/budget/project/company records, or detail-only payment/integration/verification metadata.
+`bb bill list` / `bb claim list` (legacy `list-bills` / `list-claims`) use the updated summary-only `bill.getAll`. Lists return summary fields, `isClaimable`, `lineItemCount` and `hasPendingApproval`, plus the existing pagination, counts and metrics envelope. Filters, sorting and the CLI's existing summary output are unchanged. Lists do not return attachment, detailed line-item or approval arrays, full supplier/budget/project/company records, or detail-only payment/integration/verification metadata.
+
+**Breaking API migration:** `bill.getList` is removed completely, with no alias or fallback. Direct scripts reading the former rich `bill.getAll` response must adopt summaries and fetch selected bill/claim details with `bb get-bill-details <billId>`. Do not fetch details for every list row unless the task actually needs them. No rich-list flag or automatic detail expansion is added.
+
+Coordinate the matching API/web deployment and CLI release/installations. MCP is deprecated and is not a rollout or acceptance gate. Published CLI builds still calling `getList` receive `NOT_FOUND` after API rollout, so a mixed-revision deployment is not compatible. Update those installations to the matching CLI release. Budget-list options are unchanged. This source change does not publish the CLI or deploy the API.
+
+## Inventory list reads
 
-**Output migration:** scripts reading those removed fields must fetch the selected bill/claim with `bb get-bill-details <billId>`. Do not fetch details for every list row unless the task actually needs them. No rich-list flag or automatic detail expansion is added. Older clients can still call the existing `bill.getAll` API.
+`bb item list` / `bb list-items` now use the updated page-only `item.getItems` and separate `item.getItemCounts`. The JSON output remains `{ items, pageCount, counts }`; filters and pagination are unchanged. Neither request carries an acting-user cache ID. The server authenticates the CLI session or API-key owner as usual.
 
-Deploy the API containing `bill.getList` before publishing this CLI; there is no automatic fallback to the old rich list. Budget-list options are unchanged by this bill/claim migration.
+The existing `item.getItems` API is updated in place: it now returns an array rather than `{ items, pageCount, counts }`. There is no separate `getItemPage` procedure. Coordinate the API/web deployment and CLI release/installations: old clients expecting the combined response must be upgraded, and new clients require the revised response and separate counts. Direct integrations should fetch counts only when needed. This PR does not publish the CLI or deploy the API.
 
 ## Company discovery and reuse
 
@@ -165,7 +183,7 @@ The per-user lock directory contains only random ownership markers used to seria
 login, refresh, and logout. macOS/Linux enforce owner-only POSIX permissions there;
 Windows uses its native filesystem access controls rather than POSIX mode checks.
 
-Budget Builder API keys remain supported for MCP, CI, and non-interactive
+Budget Builder API keys remain supported for CI and non-interactive CLI
 automation. When `BB_API_KEY` is present it takes precedence over the interactive
 session for that process. Create and manage automation keys under **API Keys** or
 with the commands below:
@@ -276,7 +294,7 @@ Global options and command flags use `--key=value` or `--key value`. Run `bb hel
 
 Run `bb version` before agent-driven work to record the installed package version and production API target. This is read-only and does not require authentication.
 
-**Authoritative command list:** run `bb help` or inspect the generated `command-reference.md` / `command-manifest.json`. The catalog includes every canonical route, global option, and effect classification, but does not filter by the current `whoami` role. During the handler migration, command-specific arguments retain the compatibility dispatcher's validation and are explicitly marked `legacy-passthrough` in the manifest; use `bb help --legacy` for their detailed transition reference. Version 2 uses grouped, resource-first commands such as `bb budget list` and `bb bill attachment upload`. Flat commands such as `bb list-budgets` and their MCP-style `snake_case` aliases remain available during the v2 transition, with a deprecation notice and an equivalent grouped command in help. MCP exposes a subset of the same tRPC surface; the CLI additionally includes a few procedures mainly used by the web UI.
+**Authoritative command list:** run `bb help` or inspect the generated `command-reference.md` / `command-manifest.json`. The catalog includes every canonical route, global option, and effect classification, but does not filter by the current `whoami` role. During the handler migration, command-specific arguments retain the compatibility dispatcher's validation and are explicitly marked `legacy-passthrough` in the manifest; use `bb help --legacy` for their detailed transition reference. Version 2 uses grouped, resource-first commands such as `bb budget list` and `bb bill attachment upload`. Flat commands such as `bb list-budgets` and their legacy `snake_case` aliases remain available during the v2 transition, with a deprecation notice and an equivalent grouped command in help. The CLI calls the shared tRPC API, including procedures also used by the web UI.
 
 **Budget status automation:** Setting a budget to `ESTIMATE_ACCEPTED` requires a confirmed win-proof attachment. `--invoiceSettings '<json>'` remains available when the project needs saved delivery preferences, but invoice creation chooses its amount independently from those settings. If the parent project is `PITCH` or `LOST`, the API marks it `WON` automatically and runs enabled Asana automation. When rejecting the only accepted/closed budget on a commercial project, pass `--projectStatusOnCommercialRejection PITCH|LOST`.
 
@@ -483,7 +501,11 @@ bb budget version list <budgetId> --all
 - `--all` explicitly collects all visible history through sequential bounded requests. It cannot be combined with `--cursor`; `--limit` controls each request's size. It can still be expensive and retains the complete result in memory. A failed page aborts without emitting a successful partial export.
 - Pages preserve newest-first `createdAt`/`id` ordering, role visibility, and creator/version-group metadata. They are not a point-in-time database snapshot; versions added after traversal starts require a fresh first-page read, and concurrent changes to visibility can affect traversal.
 
-The backend must expose `budgetVersion.getBudgetVersionsPage`. The legacy unbounded tRPC `getBudgetVersions` remains available but deprecated for external compatibility; unknown external clients are not silently capped. Removing that endpoint requires a separate usage/compatibility review. This change does not publish the CLI, deploy the backend/MCP server, delete audit snapshots, or establish measured RU savings.
+The canonical backend procedure is `budgetVersion.getBudgetVersions`. It now accepts `{ budgetId, limit?, cursor? }` and returns `{ versions, nextCursor }`, with a default page size of 20 and maximum of 50. The former budgetId-only input remains valid, but returns the first page—not a complete-history array. **This response-shape and completeness change is breaking despite keeping the route name.** Older installed CLI builds and external scripts must consume `versions` and explicitly continue through `nextCursor`; otherwise they may fail or mistake partial history for a complete export. Deprecated MCP builds may also be incompatible, but they must not be updated or used as a rollout gate. Current CLI aliases `get-budget-versions` and `get_budget_versions` remain supported.
+
+For direct tRPC clients, call `getBudgetVersions.query({ budgetId, limit: 20, cursor })`, consume `versions`, and request the next page only when `nextCursor` is present. The intermediate `getBudgetVersionsPage` procedure is removed; migrate callers of that name to `getBudgetVersions` rather than retrying `NOT_FOUND`. A complete export must explicitly walk every page, abort on a failed page or repeated cursor, and emit success only after reaching the end; `bb budget version list <budgetId> --all` implements that traversal. Do not treat a first page as complete history. The existing missing/deleted-cursor behavior and non-snapshot traversal are unchanged; concurrent deletions or visibility changes can require restarting an export.
+
+Coordinate the backend and maintained client rollout: publish/use this CLI only against a backend with the paginated `getBudgetVersions` contract; an older backend returns an array under that same name. MCP is deprecated and frozen, so do not update or publish it. Existing builds that call `getBudgetVersionsPage` must also migrate before that route is removed, including cached web bundles. The residual requester is not yet attributed: server timing logs prove route usage but do not identify its client or installed version. Reusing the route name bounds its history result; it does not prove complete-history consumers migrated, that a periodic schedule stopped, or that measured RU savings occurred. This source change does not publish clients, deploy the backend, delete audit snapshots or change indexes.
 
 ### Link an existing QuickBooks invoice
 
@@ -584,17 +606,22 @@ A `.env` file in the **current working directory** is loaded automatically for a
 
 ## Developing in this repo
 
-From the monorepo root (after `bun install`):
+Follow the [development workflow](../../../docs/development-workflow.md#required-cli-coverage). App/API changes affecting `bb` must include CLI contracts, registry/help/docs and verification in the same change; do not update deprecated MCP.
+
+From the monorepo root, after isolated worktree setup and client generation:
 
 ```bash
-export BB_API_KEY=...
-bun run packages/budget-builder/cli/src/index.ts budget list
+bun --filter @go-labs-sg/bb typecheck
+bun --filter @go-labs-sg/bb build
+bun run packages/budget-builder/cli/src/index.ts help
 ```
 
+Use approved browser authorization or an existing automation API key for commands that access data. Help/build examples do not authorize production reads, mutations, email or financial writes.
+
 Or from `packages/budget-builder/cli`:
 
 ```bash
-bun run build          # emit dist/ via tsc
+bun run build          # generate command artifacts, then bundle dist/index.js with Bun
 bun run typecheck      # tsc --noEmit
 bun run src/index.ts budget list
 ```
@@ -606,7 +633,7 @@ bun run src/index.ts budget list
 
 ### Publish
 
-Build the package first, then create its publishable archive with Bun:
+Only prepare publication when authorized; building or packing is not permission to publish. From `packages/budget-builder/cli`, build the package first, then create its publishable archive with Bun:
 
 ```bash
 bun run build

package/dist/index.js

@@ -35,16 +35,16 @@ var __toESM = (mod, isNodeMode, target) => {
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __require = import.meta.require;
 
-// ../../../node_modules/.bun/dotenv@18.0.5/node_modules/dotenv/dist/index.cjs
+// ../../../node_modules/.bun/dotenv@18.0.6/node_modules/dotenv/dist/index.cjs
 var require_dist = __commonJS(function(exports, module) {
-  var I = (e, o) => () => {
+  var S = (e, o) => () => {
     try {
       return o || e((o = { exports: {} }).exports, o), o.exports;
     } catch (t) {
       throw o = 0, t;
     }
   };
-  var S = I((xe, U) => {
+  var j = S((xe, U) => {
     function G(e) {
       return typeof e == "string" ? !["false", "0", "no", "off", ""].includes(e.toLowerCase()) : !!e;
     }
@@ -58,8 +58,8 @@ var require_dist = __commonJS(function(exports, module) {
     }
     U.exports = { parseBoolean: G, optionsFromEnv: X };
   });
-  var N = I((ye, x) => {
-    var Y = __require("fs"), j = __require("path"), z = __require("os"), { URL: Z, fileURLToPath: ee } = __require("url"), { parseBoolean: k, optionsFromEnv: B } = S(), te = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg, b = new Uint8Array(256);
+  var N = S((ye, x) => {
+    var Y = __require("fs"), k = __require("path"), z = __require("os"), { URL: Z, fileURLToPath: ee } = __require("url"), { parseBoolean: $, optionsFromEnv: B } = j(), te = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg, b = new Uint8Array(256);
     for (let e = 48;e <= 57; e++)
       b[e] = 1;
     for (let e = 65;e <= 90; e++)
@@ -185,7 +185,7 @@ var require_dist = __commonJS(function(exports, module) {
       return o;
     }
     function ne(e, o) {
-      return o && k(o.fast) ? oe(e) : re(e);
+      return o && $(o.fast) ? oe(e) : re(e);
     }
     function T(e) {
       console.log(`\u2506 ${e}`);
@@ -194,16 +194,16 @@ var require_dist = __commonJS(function(exports, module) {
       console.error(`\u25C7 ${e}`);
     }
     function V(e) {
-      return e[0] === "~" ? j.join(z.homedir(), e.slice(1)) : e;
+      return e[0] === "~" ? k.join(z.homedir(), e.slice(1)) : e;
     }
     function ie(e = {}) {
       return { ...B(), ...e };
     }
     function ce(e) {
       e = ie(e);
-      let o = j.resolve(process.cwd(), ".env"), t = "utf8", n = process.env;
+      let o = k.resolve(process.cwd(), ".env"), t = "utf8", n = process.env;
       e && e.processEnv != null && (n = e.processEnv);
-      let r = k(e && e.debug);
+      let r = $(e && e.debug);
       e && e.encoding ? t = e.encoding : r && T("no encoding is specified (UTF-8 is used by default)");
       let s = [o];
       if (e && e.path)
@@ -222,12 +222,12 @@ var require_dist = __commonJS(function(exports, module) {
         } catch (a) {
           r && T(`failed to load ${c} ${a.message}`), i = a;
         }
-      let p = A.populate(n, l, e), f = k(Object.prototype.hasOwnProperty.call(e, "quiet") ? e.quiet : B(n).quiet);
+      let p = A.populate(n, l, e), f = $(Object.prototype.hasOwnProperty.call(e, "quiet") ? e.quiet : B(n).quiet);
       if (r || !f) {
         let c = Object.keys(p).length, a = [];
         for (let g of s)
           try {
-            let h = j.relative(process.cwd(), g instanceof Z ? ee(g) : g);
+            let h = k.relative(process.cwd(), g instanceof Z ? ee(g) : g);
             a.push(h);
           } catch (h) {
             r && T(`failed to load ${g} ${h.message}`), i = h;
@@ -240,7 +240,7 @@ var require_dist = __commonJS(function(exports, module) {
       return A.configDotenv(e);
     }
     function le(e, o, t = {}) {
-      let n = !!(t && t.debug), r = !!(t && t.override), s = {};
+      let n = $(t && t.debug), r = $(t && t.override), s = {};
       if (e === null || typeof e != "object" || o === null || typeof o != "object") {
         let i = new Error("OBJECT_REQUIRED: Please check the processEnv argument being passed to populate");
         throw i.code = "OBJECT_REQUIRED", i;
@@ -256,7 +256,7 @@ var require_dist = __commonJS(function(exports, module) {
     x.exports.populate = A.populate;
     x.exports = A;
   });
-  var M = I((Te, W) => {
+  var M = S((Te, W) => {
     var _ = __require("child_process"), fe = __require("fs"), L = __require("path");
     function ue(e) {
       let o = ['"'], t = 0;
@@ -309,9 +309,9 @@ var require_dist = __commonJS(function(exports, module) {
     }
     W.exports = pe;
   });
-  var K = I(($e, F) => {
-    var he = __require("fs"), ge = __require("os"), Q = __require("path"), me = __require("child_process"), ve = M(), R = N(), { optionsFromEnv: Ce } = S();
-    function $() {
+  var K = S(($e, F) => {
+    var he = __require("fs"), ge = __require("os"), Q = __require("path"), me = __require("child_process"), ve = M(), R = N(), { optionsFromEnv: Ce } = j();
+    function D() {
       console.log(["Usage: dotenv run [--help] [-q|--quiet] [--debug] [--override] [--fast] [-f|--file <paths>] [--] <command> [args...]", "", "Run a command with environment variables from a .env file.", "Place dotenv options before the command; all following arguments go to the command.", "", "Options:", "  -f, --file <paths>  .env paths, comma-separated or repeated (default: .env)", "  -q, --quiet suppress the injected env message", "  --debug     enable debug logging", "  --override  override existing environment variables", "  --fast      use the faster character-scanner parser", "", "Environment variables (DOTENV_CONFIG_* names remain as fallbacks):", "  DOTENV_PATH, DOTENV_ENCODING, DOTENV_QUIET,", "  DOTENV_DEBUG, DOTENV_OVERRIDE,", "  DOTENV_FAST"].join(`
 `));
     }
@@ -383,24 +383,24 @@ var require_dist = __commonJS(function(exports, module) {
     function J(e) {
       let o = e[0];
       if (o === "--help" || o === "-h") {
-        $();
+        D();
         return;
       }
       if (o !== "run") {
-        $(), process.exitCode = 1;
+        D(), process.exitCode = 1;
         return;
       }
       let t = we(e.slice(1));
       if (t.help) {
-        $();
+        D();
         return;
       }
       if (t.error) {
-        console.error(`dotenv: ${t.error}`), $(), process.exitCode = 1;
+        console.error(`dotenv: ${t.error}`), D(), process.exitCode = 1;
         return;
       }
       if (t.command.length === 0) {
-        $(), process.exitCode = 1;
+        D(), process.exitCode = 1;
         return;
       }
       let n = Ee(t);
@@ -456,13 +456,13 @@ var require_dist = __commonJS(function(exports, module) {
     F.exports = J;
     F === __require.main && J(process.argv.slice(2));
   });
-  var D = N();
+  var I = N();
   var Oe = K();
-  module.exports = D;
-  module.exports.config = D.config;
-  module.exports.configDotenv = D.configDotenv;
-  module.exports.parse = D.parse;
-  module.exports.populate = D.populate;
+  module.exports = I;
+  module.exports.config = I.config;
+  module.exports.configDotenv = I.configDotenv;
+  module.exports.parse = I.parse;
+  module.exports.populate = I.populate;
 });
 
 // src/load-env.ts
@@ -9024,7 +9024,7 @@ async function listBills(opts) {
     page: opts.page ?? 1,
     pageSize: opts.pageSize ?? 20
   };
-  const result = await api2.bill.getList.query(input);
+  const result = await api2.bill.getAll.query(input);
   out(result);
 }
 async function approveBill(billId, overBudgetOverrideReason) {
@@ -9576,7 +9576,7 @@ var getBudgetVersions = async (budgetId, options = {}) => {
   const seenCursors = new Set;
   let cursor = options.cursor;
   do {
-    const page = await api2.budgetVersion.getBudgetVersionsPage.query({
+    const page = await api2.budgetVersion.getBudgetVersions.query({
       budgetId,
       limit: options.limit,
       cursor
@@ -10611,13 +10611,16 @@ async function listContacts(companyId) {
   out(contacts);
 }
 async function listItems(opts) {
-  const result = await api2.item.getItems.query({
+  const filters = {
     includeQuickBooksDeactivationPending: opts.includeQuickBooksDeactivationPending,
-    page: opts.page ?? 1,
-    perPage: opts.perPage ?? 20,
     name: opts.name
-  });
-  out(result);
+  };
+  const perPage = opts.perPage ?? 20;
+  const [items, { total, counts }] = await Promise.all([
+    api2.item.getItems.query({ ...filters, page: opts.page ?? 1, perPage }),
+    api2.item.getItemCounts.query(filters)
+  ]);
+  out({ items, pageCount: Math.ceil(total / perPage), counts });
 }
 async function getItem(id) {
   const item = await api2.item.getItem.query({ id });
@@ -11801,9 +11804,12 @@ var resolveCommand = (argv) => {
     isLegacyAlias: true
   };
 };
+var updateBeforeUse = "First step before each task: update to the latest published release with 'bun add --global @go-labs-sg/bb@latest', then run 'bb version' and 'bb --help' before using commands. Update once per task. If updating fails, stop and report it. Preserve an explicitly requested pinned or development/staging version.";
 var createHumanHelp = (command) => {
   if (command) {
     return [
+      updateBeforeUse,
+      "",
       `Usage: bb ${command.path.join(" ")} [options] [args]`,
       "",
       command.summary,
@@ -11828,6 +11834,8 @@ var createHumanHelp = (command) => {
   return [
     "bb \u2014 Budget Builder CLI",
     "",
+    updateBeforeUse,
+    "",
     "Usage: bb <resource> <operation> [options] [args]",
     "",
     "Global options",
@@ -12023,6 +12031,8 @@ function printLegacyHelp(runtime) {
   const help = `
 bb \u2014 Budget Builder CLI for AI agents (parity with MCP tools)
 
+First step before each task: update to the latest published release with 'bun add --global @go-labs-sg/bb@latest', then run 'bb version' and 'bb --help' before using commands. Update once per task. If updating fails, stop and report it. Preserve an explicitly requested pinned or development/staging version.
+
 Usage: bb <command> [options] [args]
 
 Identity: bb version \u2014 print the installed CLI package version and API target as JSON.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.46.0",
+  "version": "2.48.0",
   "description": "Budget Builder CLI for AI agents — manage budgets, bills, claims, quotations, and customer invoices with explicit workflow previews for sensitive changes.",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   ],
   "dependencies": {
     "@trpc/client": "^11.19.0",
-    "dotenv": "^18.0.1",
+    "dotenv": "^18.0.6",
     "mime-types": "^3.0.2",
     "superjson": "^2.2.6"
   },