@go-labs-sg/bb 2.43.0 → 2.45.0

package/README.md

@@ -63,7 +63,7 @@ See the [supplier review and rollout policy](../api/docs/supplier-edit-review.md
 
 ## Runtime and installation
 
-The CLI requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer and a Budget Builder account with any active user role.
+The same CLI package supports macOS and Windows. It requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer and a Budget Builder account with any active user role. Windows users can run the commands below in native PowerShell; Bash and `export PATH=...` are not required.
 
 Check whether a compatible Bun version is already available:
 
@@ -106,6 +106,25 @@ Or run without installing:
 bunx @go-labs-sg/bb <command>
 ```
 
+### Historical budget reads (Admin only)
+
+Budget reads are active-only by default. The API enforces the historical-read permission; the CLI does not grant access based on the flag alone.
+
+```bash
+# Active budgets only (default)
+bb list-budgets
+bb get-budget <budget-id>
+
+# Include inactive budgets; each form requires an ADMIN identity
+bb list-budgets --active false
+bb list-budgets --active all
+bb get-budget <budget-id> --includeInactive
+bb get-budget-items <budget-id> --includeInactive
+bb get-budget-details <budget-id> --includeInactive
+```
+
+`--active false` lists inactive budgets only. `--active all` lists active and inactive budgets. `--includeInactive` allows the three budget/detail/item commands to read inactive history. If the authenticated identity is not an Admin, the API rejects the historical request before reading budget data. For `get-budget`, the CLI requests the budget and its line items concurrently; each API read independently enforces the same active-only default and Admin-only historical opt-in.
+
 ## Authentication
 
 Interactive users authorize the CLI through Budget Builder's normal Google-backed
@@ -123,6 +142,11 @@ credentials through `Bun.secrets`. It never stores Google credentials. Use
 `bb auth logout` to revoke the interactive session. For SSH or containers, pass
 `--no-browser` and open the printed URL on another device.
 
+Credentials use macOS Keychain or Windows Credential Manager, not plaintext files.
+The per-user lock directory contains only random ownership markers used to serialize
+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
 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
@@ -484,6 +508,8 @@ Project and budget query payloads keep the Asana identities explicit: `asanaTask
 
 Bill, claim, and quotation mutations accept only suppliers whose approval status is `APPROVED`. An active supplier that is `PENDING_APPROVAL`, `REJECTED`, or `SUPERSEDED` must be approved before it can be used.
 
+Admin/Lead users can run `bb supplier approve <supplierId>` to directly re-approve a `REJECTED` supplier even when no pending approval request exists. This appends a new approval record and activity entry with the current responder/time, retains earlier approval and rejection history unchanged, and synchronizes QuickBooks; it does not send a requester reply email. Non-interactive direct re-approval requires `--allow-state-change --allow-external-write`, without `--allow-email`. An archived supplier remains archived and also needs Admin reactivation (`bb supplier reactivate --ids <supplierId>`) before new use. Reactivating alone does not change approval status. For a pending supplier, the command still resolves the current user's assigned request and queues the existing reply email.
+
 | Area | Legacy handler labels (reference only; non-exhaustive) |
 | --- | --- |
 | **Budgets** | `list-budgets` (full payload by default; `--summary` or `--includeDetails false` for slim list), `get-budget`, `get-budget-items`, `get-budget-details`, `get-budget-categories`, `get-budget-versions`, `rename-budget-version`, `restore-budget-version`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates an Asana Event Ops section from Prompt 5 tasks when enabled; Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date; `--projectStatusOnCommercialRejection PITCH\|LOST` is required when rejecting the only accepted/closed budget on a commercial project), `mark-budget-won` (`<budgetId>` + proof file path; `PITCH` or `LOST` projects become `WON` automatically), `create-budget` / `update-budget` (`--payload`; cloned unavailable lines require `unavailableItemReviewAcknowledged: true`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `create-estimate`, `send-estimate-to-contact-person` (same contact-person email workflow as web), `add-budget-items`, `update-budget-item`, `replace-budget-item`, `approve-unavailable-item-exception` (Lead/Admin), `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `mark-budget-items-not-utilized`, `restore-budget-item`, `create-placeholder-bill` (admin recovery), `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `delete-budget-commission`, `update-budget-discount`, `delete-budget-discount` (`--payload` where noted), `upload-budget-attachment` (`<budgetId>` + local file path; uses `attachment.requestBudgetAttachmentUpload` + PUT + `attachment.confirmBudgetAttachment`) |

package/command-manifest.json

@@ -199,7 +199,7 @@
 	{
 		"path": ["budget", "list"],
 		"legacyAliases": ["list-budgets", "list_budgets"],
-		"summary": "List budgets.",
+		"summary": "List budgets. Omit --active for active budgets only; use --active false or --active all for Admin-only historical reads.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -240,6 +240,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--active <true|false|all>",
+				"description": "Omit for active budgets only; false or all requires Admin access."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -249,7 +253,7 @@
 	{
 		"path": ["budget", "get"],
 		"legacyAliases": ["get-budget", "get_budget"],
-		"summary": "Get budget.",
+		"summary": "Get a budget by ID. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -290,6 +294,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--includeInactive",
+				"description": "Include inactive historical budgets; Admin only."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -399,7 +407,7 @@
 	{
 		"path": ["budget", "item", "list"],
 		"legacyAliases": ["get-budget-items", "get_budget_items"],
-		"summary": "Get budget items.",
+		"summary": "Get line items for a budget. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -440,6 +448,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--includeInactive",
+				"description": "Include inactive historical budgets; Admin only."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -449,7 +461,7 @@
 	{
 		"path": ["budget", "detail", "get"],
 		"legacyAliases": ["get-budget-details", "get_budget_details"],
-		"summary": "Get budget details.",
+		"summary": "Get budget details. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -490,6 +502,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--includeInactive",
+				"description": "Include inactive historical budgets; Admin only."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -4779,7 +4795,7 @@
 	{
 		"path": ["supplier", "approve"],
 		"legacyAliases": ["approve-supplier", "approve_supplier"],
-		"summary": "Approve Supplier.",
+		"summary": "Approve a pending supplier request and send a requester reply email, or directly re-approve a rejected supplier as Admin/Lead without a pending request or email. QuickBooks is synchronized; archived suppliers remain archived. Argument: <supplierId>.",
 		"globalOptions": [
 			{
 				"name": "--help",

package/command-reference.md

@@ -51,7 +51,7 @@ Effects: none.
 
 ## `bb budget list`
 
-List budgets.
+List budgets. Omit --active for active budgets only; use --active false or --active all for Admin-only historical reads.
 
 Legacy aliases: `list-budgets`, `list_budgets`.
 
@@ -59,7 +59,7 @@ Effects: none.
 
 ## `bb budget get`
 
-Get budget.
+Get a budget by ID. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.
 
 Legacy aliases: `get-budget`, `get_budget`.
 
@@ -83,7 +83,7 @@ Effects: state-change, external-write, financial-write.
 
 ## `bb budget item list`
 
-Get budget items.
+Get line items for a budget. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.
 
 Legacy aliases: `get-budget-items`, `get_budget_items`.
 
@@ -91,7 +91,7 @@ Effects: none.
 
 ## `bb budget detail get`
 
-Get budget details.
+Get budget details. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.
 
 Legacy aliases: `get-budget-details`, `get_budget_details`.
 
@@ -833,7 +833,7 @@ Effects: state-change, email.
 
 ## `bb supplier approve`
 
-Approve Supplier.
+Approve a pending supplier request and send a requester reply email, or directly re-approve a rejected supplier as Admin/Lead without a pending request or email. QuickBooks is synchronized; archived suppliers remain archived. Argument: <supplierId>.
 
 Legacy aliases: `approve-supplier`, `approve_supplier`.
 

package/dist/index.js

@@ -6071,7 +6071,7 @@ var ensurePrivateCredentialLockDirectory = async () => {
     return directoryStat;
   };
   const directoryStat = await inspectDirectory();
-  if ((directoryStat.mode & 63) !== 0) {
+  if (process.platform !== "win32" && (directoryStat.mode & 63) !== 0) {
     await chmod(directory, 448);
     const securedDirectoryStat = await inspectDirectory();
     if ((securedDirectoryStat.mode & 63) !== 0) {
@@ -8504,7 +8504,8 @@ var assertSensitiveWorkflowConfirmed = async (input) => {
     await confirmCurrentCommand({
       action: input.action,
       target: input.entity,
-      details: input.details
+      details: input.details,
+      effects: input.effects
     });
     return;
   }
@@ -8604,6 +8605,7 @@ async function listBudgets(opts) {
     createdBy: opts.createdBy,
     dateFrom: opts.dateFrom,
     dateTo: opts.dateTo,
+    active: opts.active,
     sortBy: opts.sortBy,
     sortDir: opts.sortDir,
     page: opts.page ?? 1,
@@ -8613,10 +8615,16 @@ async function listBudgets(opts) {
   const result = await api2.budget.getAllBudgets.query(input);
   out(result);
 }
-async function getBudget(id) {
+async function getBudget(id, opts) {
   const [budget, items] = await Promise.all([
-    api2.budget.getBudget.query({ id }),
-    api2.budget.getBudgetItems.query({ budgetId: id })
+    api2.budget.getBudget.query({
+      id,
+      includeInactive: opts?.includeInactive ?? false
+    }),
+    api2.budget.getBudgetItems.query({
+      budgetId: id,
+      includeInactive: opts?.includeInactive ?? false
+    })
   ]);
   out({ budget, items });
 }
@@ -9223,8 +9231,11 @@ async function getBillDetails(id) {
   const result = await api2.bill.getById.query({ id });
   out(result);
 }
-async function getBudgetItemsOnly(budgetId) {
-  const items = await api2.budget.getBudgetItems.query({ budgetId });
+async function getBudgetItemsOnly(budgetId, opts) {
+  const items = await api2.budget.getBudgetItems.query({
+    budgetId,
+    includeInactive: opts?.includeInactive ?? false
+  });
   out(items);
 }
 async function addBudgetItems(opts) {
@@ -9325,8 +9336,11 @@ var sendEstimateToContactPersonFromPayload = async (raw) => {
   const result = await api2.email.sendEstimateToContactPerson.mutate(input);
   out(result);
 };
-async function getBudgetDetails(budgetId) {
-  const detail = await api2.budget.getBudgetDetail.query({ id: budgetId });
+async function getBudgetDetails(budgetId, opts) {
+  const detail = await api2.budget.getBudgetDetail.query({
+    id: budgetId,
+    includeInactive: opts?.includeInactive ?? false
+  });
   out(detail);
 }
 async function createBudgetFromPayload(raw) {
@@ -9940,6 +9954,17 @@ async function getSupplierDetails(supplierId) {
   });
 }
 async function approveSupplier(supplierId) {
+  const supplier = await api2.supplier.getSupplierById.query({ id: supplierId });
+  if (supplier.status === ExtendedApprovalStatus.REJECTED) {
+    await assertSensitiveWorkflowConfirmed({
+      action: "Re-approve supplier",
+      entity: `supplier ${supplierId}`,
+      effects: ["state-change", "external-write"],
+      details: supplier.active ? "and sync its details with QuickBooks; append a new approval and retain earlier history; no requester reply email is sent" : "and sync its details with QuickBooks; append a new approval and retain earlier history; it remains archived and no requester reply email is sent"
+    });
+    out(await api2.supplier.reapproveSupplier.mutate({ supplierId }));
+    return;
+  }
   await assertSensitiveWorkflowConfirmed({
     action: "Approve supplier",
     entity: `supplier ${supplierId}`,
@@ -10881,6 +10906,8 @@ var effectsFor = (legacyTarget) => {
 };
 var titleCase = (value) => value.split("-").map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`).join(" ");
 var summaryFor = (legacyTarget) => {
+  if (legacyTarget === "approve-supplier")
+    return "Approve a pending supplier request and send a requester reply email, or directly re-approve a rejected supplier as Admin/Lead without a pending request or email. QuickBooks is synchronized; archived suppliers remain archived. Argument: <supplierId>.";
   if (legacyTarget === "search-existing-companies")
     return "Search BB and QuickBooks companies without writes. --query <name> [--page <number>].";
   if (legacyTarget === "use-existing-company")
@@ -10903,6 +10930,18 @@ var summaryFor = (legacyTarget) => {
   }
   if (legacyTarget === "whoami")
     return "Show the active API-key identity.";
+  if (legacyTarget === "list-budgets") {
+    return "List budgets. Omit --active for active budgets only; use --active false or --active all for Admin-only historical reads.";
+  }
+  if (legacyTarget === "get-budget") {
+    return "Get a budget by ID. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.";
+  }
+  if (legacyTarget === "get-budget-items") {
+    return "Get line items for a budget. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.";
+  }
+  if (legacyTarget === "get-budget-details") {
+    return "Get budget details. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.";
+  }
   if (legacyTarget === "create-bill") {
     return "Create a bill or claim with an approved supplier. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.";
   }
@@ -10977,12 +11016,32 @@ var registry2 = [
   authCommand("status", "Show the active CLI authentication method and session status."),
   authCommand("logout", "Revoke the interactive CLI session and remove its local credential."),
   legacyCommand("whoami", ["auth", "whoami"]),
-  legacyCommand("list-budgets", ["budget", "list"]),
-  legacyCommand("get-budget", ["budget", "get"]),
+  legacyCommand("list-budgets", ["budget", "list"], [], [
+    {
+      name: "--active <true|false|all>",
+      description: "Omit for active budgets only; false or all requires Admin access."
+    }
+  ]),
+  legacyCommand("get-budget", ["budget", "get"], [], [
+    {
+      name: "--includeInactive",
+      description: "Include inactive historical budgets; Admin only."
+    }
+  ]),
   legacyCommand("upload-budget-attachment", ["budget", "attachment", "upload"]),
   legacyCommand("mark-budget-won", ["budget", "won", "mark"]),
-  legacyCommand("get-budget-items", ["budget", "item", "list"]),
-  legacyCommand("get-budget-details", ["budget", "detail", "get"]),
+  legacyCommand("get-budget-items", ["budget", "item", "list"], [], [
+    {
+      name: "--includeInactive",
+      description: "Include inactive historical budgets; Admin only."
+    }
+  ]),
+  legacyCommand("get-budget-details", ["budget", "detail", "get"], [], [
+    {
+      name: "--includeInactive",
+      description: "Include inactive historical budgets; Admin only."
+    }
+  ]),
   legacyCommand("get-budget-categories", ["budget", "category", "list"]),
   legacyCommand("get-budget-versions", ["budget", "version", "list"]),
   legacyCommand("rename-budget-version", ["budget", "version", "rename"]),
@@ -11526,6 +11585,22 @@ function parseOptionalBoolFlag(flags, key) {
     return false;
   throw new Error(`--${key} must be true or false.`);
 }
+function parseBudgetActiveFlag(flags) {
+  const raw = flags.active;
+  if (raw === undefined)
+    return;
+  if (raw === true) {
+    throw new Error("--active requires true, false, or all.");
+  }
+  const value = String(raw).toLowerCase();
+  if (value === "all")
+    return "all";
+  if (value === "true" || value === "1")
+    return true;
+  if (value === "false" || value === "0")
+    return false;
+  throw new Error("--active must be true, false, or all.");
+}
 var CUSTOMER_INVOICE_SORT_FIELDS = [
   "createdAt",
   "status",
@@ -11762,7 +11837,7 @@ Approvals
   reject-bill <billId> --reason <text> (also sends requester reply email)
   approve-budget <budgetId>           (also sends requester reply email)
   reject-budget <budgetId> --reason <text> (also sends requester reply email)
-  approve-supplier <supplierId>       (also sends requester reply email)
+  approve-supplier <supplierId>       (approve a pending request, or Admin/Lead re-approve a rejected supplier)
   reject-supplier <supplierId> --reason <text> (also sends requester reply email)
 
 Companies & projects
@@ -12197,7 +12272,7 @@ Waiting for approval\u2026
       }
       configureAccessToken(accessToken);
     }
-    if (!resolvedCommand.isLegacyAlias && cmd !== "create-bill" && cmd !== "import-qbo-customer-invoice" && resolvedCommand.command.effects.length > 0) {
+    if (!resolvedCommand.isLegacyAlias && cmd !== "create-bill" && cmd !== "import-qbo-customer-invoice" && cmd !== "approve-supplier" && resolvedCommand.command.effects.length > 0) {
       await confirmCurrentCommand({
         action: resolvedCommand.command.path.join(" "),
         target: commandConfirmationTarget(resolvedCommand),
@@ -12219,6 +12294,7 @@ Waiting for approval\u2026
           createdBy: getFlag(flags, "createdBy"),
           dateFrom: getFlag(flags, "dateFrom"),
           dateTo: getFlag(flags, "dateTo"),
+          active: parseBudgetActiveFlag(flags),
           sortBy: getFlag(flags, "sortBy"),
           sortDir: getFlag(flags, "sortDir"),
           page: parsePositiveIntFlag(getFlag(flags, "page"), "--page"),
@@ -12231,7 +12307,9 @@ Waiting for approval\u2026
         const id = positional[0];
         if (!id)
           throw new Error("get-budget requires <id>");
-        await getBudget(id);
+        await getBudget(id, {
+          includeInactive: flags.includeInactive === true ? true : parseOptionalBoolFlag(flags, "includeInactive") ?? false
+        });
         break;
       }
       case "upload-budget-attachment": {
@@ -12258,14 +12336,18 @@ Waiting for approval\u2026
         const id = positional[0];
         if (!id)
           throw new Error("get-budget-items requires <budgetId>");
-        await getBudgetItemsOnly(id);
+        await getBudgetItemsOnly(id, {
+          includeInactive: flags.includeInactive === true ? true : parseOptionalBoolFlag(flags, "includeInactive") ?? false
+        });
         break;
       }
       case "get-budget-details": {
         const id = positional[0];
         if (!id)
           throw new Error("get-budget-details requires <budgetId>");
-        await getBudgetDetails(id);
+        await getBudgetDetails(id, {
+          includeInactive: flags.includeInactive === true ? true : parseOptionalBoolFlag(flags, "includeInactive") ?? false
+        });
         break;
       }
       case "get-budget-categories": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.43.0",
+  "version": "2.45.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",

package/role-aware-agent-guide.md

@@ -25,7 +25,7 @@ The Budget Builder API, not the CLI, makes the final decision. A request may nee
 2. A sufficient current database role: `USER`, `INSIDE_SALES`, `LEAD`, `ACCOUNTING_TEAM`, or `ADMIN`. Pending approval assignment does not preserve decision authority after a role change.
 3. Access to the specific resource, commonly through creator ownership or project assignment as Business Development, Inside Sales, or Project Manager.
 4. A compatible resource state, such as a bill being `DRAFT` or `REJECTED` before editing.
-5. A pending approval record assigned to the current user for approval decisions.
+5. A pending approval record assigned to the current user for request decisions. Direct Admin/Lead re-approval of a rejected supplier does not require a pending request.
 6. Required evidence and consistent related records, such as payment proof, approved quotation coverage, or matching project/budget IDs.
 
 Therefore, two users with the same role can receive different results for the same command and different resource IDs.
@@ -95,7 +95,8 @@ This table highlights the role-sensitive command groups an agent is most likely
 | `bb project hub status`, `bb project hub setup`, and `bb project hub sync` | `ADMIN`, project creator, or project assignment as Business Development, Inside Sales, or Project Manager. Setup and sync also enforce Project Hub lifecycle/readiness checks. |
 | `bb supplier update`, `bb item update`, `bb item category update` | Any active authenticated role. Normal-user supplier edits are submitted for approval by the shared API; item/category edits apply immediately. Human review and provider synchronization can temporarily block further supplier edits/new usage. |
 | Edit/delete a bill or quotation | Usually creator or `ADMIN`, with a supported status. |
-| `bb budget approve`, `bb budget reject`, `bb supplier approve`, and `bb supplier reject` | Current user must be the pending approver and currently have role `LEAD` or `ADMIN`. |
+| `bb budget approve`, `bb budget reject`, and `bb supplier reject` | Current user must be the pending approver and currently have role `LEAD` or `ADMIN`. |
+| `bb supplier approve` | `LEAD` or `ADMIN`. Pending suppliers require an assigned pending request; rejected suppliers can be directly re-approved without one. Re-approval preserves archive state and does not send a requester email. |
 | `bb bill approve` and `bb bill reject` | Current user must be the pending approver and currently have role `ACCOUNTING_TEAM` for the finance/check stage or `ADMIN` for the final approval stage. |
 | `bb quotation approve` and `bb quotation reject` | Current user must be the pending approver and currently have role `ADMIN`; a normal submitter cannot decide the quotation. |
 | `bb bill status update ... CHECKED` | `ACCOUNTING_TEAM` or `ADMIN`. |