@go-labs-sg/bb 2.43.0 → 2.44.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

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",

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`.
 

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) {
@@ -8604,6 +8604,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 +8614,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 +9230,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 +9335,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) {
@@ -10903,6 +10916,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 +11002,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 +11571,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",
@@ -12219,6 +12280,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 +12293,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 +12322,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.44.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",