@go-labs-sg/bb 2.46.0 → 2.47.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
+```
 
-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.
+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: 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,7 @@ 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 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, delete audit snapshots, or establish measured RU savings.
 
 ### Link an existing QuickBooks invoice
 

package/dist/index.js

@@ -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) {
@@ -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.47.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",