@go-labs-sg/bb 1.20.0 → 2.0.0

package/dist/registry/generate-command-artifacts.js

@@ -0,0 +1,36 @@
+import { execFileSync } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { commandRegistry, createCommandManifest, globalCommandOptions, } from "./index.js";
+const packageRoot = process.cwd();
+const manifestPath = resolve(packageRoot, "command-manifest.json");
+const reference = [
+    "# Budget Builder CLI command reference",
+    "",
+    "This file is generated from the typed command registry. Do not edit it manually.",
+    "This catalog is not filtered by the authenticated user's role. The Budget Builder API authorizes every request using the current database role plus applicable resource, workflow-state, and pending-approver checks.",
+    "Command-specific arguments currently pass through the compatibility dispatcher; use `bb help --legacy` for their detailed transition reference.",
+    "",
+    "## Global options",
+    "",
+    ...globalCommandOptions.map((option) => `- \`${option.name}\`: ${option.description}`),
+    "",
+    ...commandRegistry.flatMap((command) => [
+        `## \`bb ${command.path.join(" ")}\``,
+        "",
+        command.summary,
+        "",
+        `Legacy aliases: ${command.legacyAliases.map((alias) => `\`${alias}\``).join(", ")}.`,
+        "",
+        `Effects: ${command.effects.length > 0 ? command.effects.join(", ") : "none"}.`,
+        "",
+    ]),
+].join("\n");
+await Promise.all([
+    writeFile(resolve(packageRoot, "command-reference.md"), reference),
+    writeFile(manifestPath, `${JSON.stringify(createCommandManifest(), null, "\t")}\n`),
+]);
+execFileSync(process.execPath, ["x", "biome", "format", "--write", manifestPath], {
+    cwd: packageRoot,
+    stdio: ["ignore", "ignore", "inherit"],
+});

package/dist/registry/index.js

@@ -0,0 +1,583 @@
+/**
+ * Declarative command catalogue for the Budget Builder CLI.
+ *
+ * The first v2 integration step uses `legacyTarget` to dispatch through the
+ * established command implementation. New command handlers can replace that
+ * target incrementally by supplying `load` instead.
+ */
+export const globalCommandOptions = [
+    { name: "--help", description: "Show help for this command." },
+    { name: "--quiet", description: "Suppress non-error diagnostics." },
+    { name: "--debug", description: "Emit sanitized diagnostic traces." },
+    {
+        name: "--api-url",
+        description: "Override the Budget Builder API base URL.",
+    },
+    {
+        name: "--allow-state-change",
+        description: "Allow a Budget Builder state change in non-interactive use.",
+    },
+    {
+        name: "--allow-email",
+        description: "Allow sending email in non-interactive use.",
+    },
+    {
+        name: "--allow-external-write",
+        description: "Allow writes to external systems in non-interactive use.",
+    },
+    {
+        name: "--allow-delete",
+        description: "Allow deleting data in non-interactive use.",
+    },
+    {
+        name: "--allow-financial-write",
+        description: "Allow financial-record changes in non-interactive use.",
+    },
+];
+const mutationPrefixes = [
+    "add-",
+    "approve-",
+    "attach-",
+    "cleanup-",
+    "complete-",
+    "create-",
+    "delete-",
+    "discard-",
+    "import-",
+    "mark-",
+    "patch-",
+    "reactivate-",
+    "reconcile-",
+    "reject-",
+    "remove-",
+    "rename-",
+    "reorder-",
+    "restore-",
+    "retry-",
+    "revoke-",
+    "send-",
+    "stage-",
+    "submit-",
+    "sync-",
+    "update-",
+    "upload-",
+    "void-",
+];
+const emailTargets = new Set([
+    "approve-bill",
+    "approve-budget",
+    "approve-customer-invoice",
+    "approve-supplier",
+    "create-bill",
+    "create-bill-approval",
+    "create-budget-approval",
+    "create-customer-invoice",
+    "create-supplier",
+    "reject-bill",
+    "reject-budget",
+    "reject-customer-invoice",
+    "reject-supplier",
+    "send-estimate-email",
+    "send-estimate-to-contact-person",
+    "send-customer-invoice-to-contact-person",
+    "update-bill-status",
+    "update-supplier",
+]);
+const externalWriteTargets = new Set([
+    "approve-bill",
+    "approve-customer-invoice",
+    "approve-supplier",
+    "complete-project",
+    "create-bill",
+    "create-company",
+    "create-estimate",
+    "create-placeholder-bill",
+    "create-customer-invoice",
+    "create-item",
+    "create-item-category",
+    "create-project",
+    "create-supplier",
+    "delete-bill",
+    "delete-budget",
+    "delete-company",
+    "delete-customer-invoice",
+    "delete-item",
+    "delete-project",
+    "delete-suppliers",
+    "discard-customer-invoice",
+    "import-qbo-project",
+    "mark-budget-items-not-utilized",
+    "mark-budget-won",
+    "mark-customer-invoice-paid",
+    "reconcile-project",
+    "reject-customer-invoice",
+    "reactivate-suppliers",
+    "restore-budget-item",
+    "restore-budget-version",
+    "retry-integration-operation",
+    "sync-customer-invoice",
+    "update-bill",
+    "update-budget-status",
+    "update-company",
+    "update-item",
+    "update-item-category",
+    "update-project",
+    "update-project-status",
+    "update-supplier",
+    "void-customer-invoice",
+]);
+const financialWriteTargets = new Set([
+    "approve-bill",
+    "approve-customer-invoice",
+    "complete-project",
+    "create-bill",
+    "create-customer-invoice",
+    "create-estimate",
+    "create-placeholder-bill",
+    "delete-budget-commission",
+    "delete-budget-discount",
+    "delete-bill",
+    "delete-budget",
+    "delete-customer-invoice",
+    "mark-budget-items-not-utilized",
+    "mark-budget-won",
+    "mark-customer-invoice-paid",
+    "patch-bill-payment",
+    "reject-customer-invoice",
+    "restore-budget-item",
+    "restore-budget-version",
+    "sync-customer-invoice",
+    "update-bill",
+    "update-bill-payment-evidence",
+    "update-bill-status",
+    "update-budget-commission",
+    "update-budget-discount",
+    "update-budget-status",
+    "update-project-status",
+    "void-customer-invoice",
+]);
+const deleteTargets = new Set([
+    "cleanup-staged-bill-attachments",
+    "cleanup-staged-quotation-attachments",
+    "discard-customer-invoice",
+    "complete-project",
+    "mark-budget-items-not-utilized",
+    "remove-budget-item",
+    "restore-budget-version",
+    "update-project-status",
+]);
+const effectsFor = (legacyTarget) => {
+    const effects = new Set();
+    if (mutationPrefixes.some((prefix) => legacyTarget.startsWith(prefix))) {
+        effects.add("state-change");
+    }
+    if (legacyTarget.startsWith("delete-") || deleteTargets.has(legacyTarget)) {
+        effects.add("delete");
+    }
+    if (emailTargets.has(legacyTarget))
+        effects.add("email");
+    if (externalWriteTargets.has(legacyTarget))
+        effects.add("external-write");
+    if (financialWriteTargets.has(legacyTarget))
+        effects.add("financial-write");
+    return [...effects];
+};
+const titleCase = (value) => value
+    .split("-")
+    .map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`)
+    .join(" ");
+const summaryFor = (legacyTarget) => {
+    if (legacyTarget === "whoami")
+        return "Show the active API-key identity.";
+    if (legacyTarget.startsWith("list-")) {
+        return `List ${legacyTarget.slice("list-".length).replaceAll("-", " ")}.`;
+    }
+    if (legacyTarget.startsWith("get-")) {
+        return `Get ${legacyTarget.slice("get-".length).replaceAll("-", " ")}.`;
+    }
+    return `${titleCase(legacyTarget)}.`;
+};
+const aliasesFor = (legacyTarget, aliases) => [
+    ...new Set([legacyTarget, ...aliases].flatMap((alias) => [
+        alias,
+        alias.replaceAll("-", "_"),
+    ])),
+];
+const legacyCommand = (legacyTarget, path, aliases = []) => ({
+    path,
+    legacyAliases: aliasesFor(legacyTarget, aliases),
+    summary: summaryFor(legacyTarget),
+    options: globalCommandOptions,
+    effects: effectsFor(legacyTarget),
+    legacyTarget,
+});
+const registry = [
+    legacyCommand("whoami", ["auth", "whoami"]),
+    legacyCommand("list-budgets", ["budget", "list"]),
+    legacyCommand("get-budget", ["budget", "get"]),
+    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-categories", ["budget", "category", "list"]),
+    legacyCommand("get-budget-versions", ["budget", "version", "list"]),
+    legacyCommand("rename-budget-version", ["budget", "version", "rename"]),
+    legacyCommand("restore-budget-version", ["budget", "version", "restore"]),
+    legacyCommand("update-budget-status", ["budget", "status", "update"]),
+    legacyCommand("create-budget-approval", ["budget", "approval", "create"]),
+    legacyCommand("create-estimate", ["budget", "estimate", "create"]),
+    legacyCommand("send-estimate-to-contact-person", ["budget", "estimate", "send"], ["send-estimate-email"]),
+    legacyCommand("create-budget", ["budget", "create"]),
+    legacyCommand("update-budget", ["budget", "update"]),
+    legacyCommand("delete-budget", ["budget", "delete"]),
+    legacyCommand("add-budget-items", ["budget", "item", "add"]),
+    legacyCommand("update-budget-item", ["budget", "item", "update"]),
+    legacyCommand("remove-budget-item", ["budget", "item", "remove"]),
+    legacyCommand("reorder-budget-items", ["budget", "item", "reorder"]),
+    legacyCommand("update-budget-item-supplier", [
+        "budget",
+        "item",
+        "supplier",
+        "update",
+    ]),
+    legacyCommand("create-budget-category", ["budget", "category", "create"]),
+    legacyCommand("update-budget-category", ["budget", "category", "update"]),
+    legacyCommand("delete-budget-category", ["budget", "category", "delete"]),
+    legacyCommand("update-budget-commission", ["budget", "commission", "update"]),
+    legacyCommand("update-budget-discount", ["budget", "discount", "update"]),
+    legacyCommand("delete-budget-commission", ["budget", "commission", "delete"]),
+    legacyCommand("delete-budget-discount", ["budget", "discount", "delete"]),
+    legacyCommand("mark-budget-items-not-utilized", [
+        "budget",
+        "item",
+        "mark-not-utilized",
+    ]),
+    legacyCommand("restore-budget-item", ["budget", "item", "restore"]),
+    legacyCommand("create-placeholder-bill", [
+        "budget",
+        "item",
+        "placeholder-bill",
+        "create",
+    ]),
+    legacyCommand("list-bills", ["bill", "list"]),
+    legacyCommand("list-claims", ["claim", "list"]),
+    legacyCommand("create-bill-approval", ["bill", "approval", "create"]),
+    legacyCommand("create-bill", ["bill", "create"]),
+    legacyCommand("validate-bill-selection", ["bill", "selection", "validate"]),
+    legacyCommand("update-bill", ["bill", "update"]),
+    legacyCommand("update-bill-payment-evidence", [
+        "bill",
+        "payment-evidence",
+        "update",
+    ]),
+    legacyCommand("delete-bill", ["bill", "delete"]),
+    legacyCommand("update-bill-status", ["bill", "status", "update"]),
+    legacyCommand("patch-bill-payment", ["bill", "payment", "patch"]),
+    legacyCommand("patch-bill-invoice-number", [
+        "bill",
+        "invoice-number",
+        "patch",
+    ]),
+    legacyCommand("get-bill-attachments", ["bill", "attachment", "list"]),
+    legacyCommand("stage-bill-attachment", ["bill", "attachment", "stage"]),
+    legacyCommand("cleanup-staged-bill-attachments", [
+        "bill",
+        "attachment",
+        "staged",
+        "cleanup",
+    ]),
+    legacyCommand("upload-bill-attachment", ["bill", "attachment", "upload"], ["attach-bill-attachment"]),
+    legacyCommand("attach-bill-payment-receipt", [
+        "bill",
+        "payment-receipt",
+        "attach",
+    ]),
+    legacyCommand("attach-bill-documents", ["bill", "document", "attach"]),
+    legacyCommand("get-bill-details", ["bill", "get"]),
+    legacyCommand("list-quotations", ["quotation", "list"]),
+    legacyCommand("get-quotation", ["quotation", "get"]),
+    legacyCommand("upload-quotation-attachment", [
+        "quotation",
+        "attachment",
+        "upload",
+    ]),
+    legacyCommand("cleanup-staged-quotation-attachments", [
+        "quotation",
+        "attachment",
+        "staged",
+        "cleanup",
+    ]),
+    legacyCommand("create-quotation", ["quotation", "create"]),
+    legacyCommand("update-quotation", ["quotation", "update"]),
+    legacyCommand("delete-quotation", ["quotation", "delete"]),
+    legacyCommand("submit-quotation", ["quotation", "submit"]),
+    legacyCommand("approve-quotation", ["quotation", "approve"]),
+    legacyCommand("reject-quotation", ["quotation", "reject"]),
+    legacyCommand("download-quotation-pdf", ["quotation", "pdf", "download"]),
+    legacyCommand("check-customer-invoice-readiness", [
+        "customer-invoice",
+        "readiness",
+        "check",
+    ]),
+    legacyCommand("list-eligible-customer-invoice-budgets", [
+        "customer-invoice",
+        "eligible-budget",
+        "list",
+    ]),
+    legacyCommand("list-customer-invoices", ["customer-invoice", "list"]),
+    legacyCommand("get-customer-invoice", ["customer-invoice", "get"]),
+    legacyCommand("get-customer-invoice-email-context", [
+        "customer-invoice",
+        "email-context",
+        "get",
+    ]),
+    legacyCommand("create-customer-invoice", ["customer-invoice", "create"]),
+    legacyCommand("discard-customer-invoice", ["customer-invoice", "discard"]),
+    legacyCommand("delete-customer-invoice", ["customer-invoice", "delete"]),
+    legacyCommand("void-customer-invoice", ["customer-invoice", "void"]),
+    legacyCommand("approve-customer-invoice", ["customer-invoice", "approve"]),
+    legacyCommand("reject-customer-invoice", ["customer-invoice", "reject"]),
+    legacyCommand("send-customer-invoice-to-contact-person", [
+        "customer-invoice",
+        "send",
+    ]),
+    legacyCommand("mark-customer-invoice-paid", [
+        "customer-invoice",
+        "payment",
+        "mark-paid",
+    ]),
+    legacyCommand("download-customer-invoice-payment-proof", [
+        "customer-invoice",
+        "payment-proof",
+        "download",
+    ]),
+    legacyCommand("download-customer-invoice-pdf", [
+        "customer-invoice",
+        "pdf",
+        "download",
+    ]),
+    legacyCommand("sync-customer-invoice", ["customer-invoice", "sync"]),
+    legacyCommand("list-approvals", ["approval", "list"], ["get-pending-approvals"]),
+    legacyCommand("approve-bill", ["bill", "approve"]),
+    legacyCommand("reject-bill", ["bill", "reject"]),
+    legacyCommand("approve-budget", ["budget", "approve"]),
+    legacyCommand("reject-budget", ["budget", "reject"]),
+    legacyCommand("approve-supplier", ["supplier", "approve"]),
+    legacyCommand("reject-supplier", ["supplier", "reject"]),
+    legacyCommand("get-supplier-details", ["supplier", "detail", "get"]),
+    legacyCommand("list-companies", ["company", "list"]),
+    legacyCommand("get-company", ["company", "get"]),
+    legacyCommand("create-company", ["company", "create"]),
+    legacyCommand("update-company", ["company", "update"]),
+    legacyCommand("delete-company", ["company", "delete"]),
+    legacyCommand("list-projects", ["project", "list"]),
+    legacyCommand("get-project", ["project", "get"]),
+    legacyCommand("create-project", ["project", "create"]),
+    legacyCommand("update-project", ["project", "update"]),
+    legacyCommand("delete-project", ["project", "delete"]),
+    legacyCommand("check-project-reconciliation", [
+        "project",
+        "reconciliation",
+        "check",
+    ]),
+    legacyCommand("reconcile-project", ["project", "reconcile"]),
+    legacyCommand("complete-project", ["project", "complete"]),
+    legacyCommand("import-qbo-project", ["project", "quickbooks", "import"]),
+    legacyCommand("update-project-status", ["project", "status", "update"]),
+    legacyCommand("list-contacts", ["contact", "list"]),
+    legacyCommand("create-contact-person", ["contact", "create"]),
+    legacyCommand("update-contact-person", ["contact", "update"]),
+    legacyCommand("list-suppliers", ["supplier", "list"]),
+    legacyCommand("create-supplier", ["supplier", "create"]),
+    legacyCommand("update-supplier", ["supplier", "update"]),
+    legacyCommand("delete-suppliers", ["supplier", "delete"]),
+    legacyCommand("reactivate-suppliers", ["supplier", "reactivate"]),
+    legacyCommand("create-certification", [
+        "supplier",
+        "certification",
+        "create",
+    ]),
+    legacyCommand("create-payment-method", [
+        "supplier",
+        "payment-method",
+        "create",
+    ]),
+    legacyCommand("create-supplier-role", ["supplier", "role", "create"]),
+    legacyCommand("create-supplier-tag", ["supplier", "tag", "create"]),
+    legacyCommand("get-supplier-analytics", ["supplier", "analytics", "get"]),
+    legacyCommand("list-items", ["item", "list"]),
+    legacyCommand("get-item", ["item", "get"]),
+    legacyCommand("create-item", ["item", "create"]),
+    legacyCommand("update-item", ["item", "update"]),
+    legacyCommand("delete-item", ["item", "delete"]),
+    legacyCommand("list-item-categories", ["item", "category", "list"]),
+    legacyCommand("create-item-category", ["item", "category", "create"]),
+    legacyCommand("update-item-category", ["item", "category", "update"]),
+    legacyCommand("delete-item-categories", ["item", "category", "delete"]),
+    legacyCommand("list-users", ["user", "list"]),
+    legacyCommand("create-user", ["user", "create"]),
+    legacyCommand("create-api-key", ["user", "api-key", "create"]),
+    legacyCommand("list-api-keys", ["user", "api-key", "list"]),
+    legacyCommand("revoke-api-key", ["user", "api-key", "revoke"]),
+    legacyCommand("get-user-performance", ["user", "performance", "get"]),
+    legacyCommand("get-dashboard", ["dashboard", "get"]),
+    legacyCommand("get-monthly-metrics", ["dashboard", "monthly-metrics", "get"]),
+    legacyCommand("get-system-overview", ["dashboard", "system-overview", "get"]),
+    legacyCommand("get-estimate-performance", [
+        "dashboard",
+        "estimate-performance",
+        "get",
+    ]),
+    legacyCommand("get-financial-overview", [
+        "dashboard",
+        "financial-overview",
+        "get",
+    ]),
+    legacyCommand("get-recent-errors", ["error", "recent", "list"]),
+    legacyCommand("get-error-metrics", ["error", "metrics", "get"]),
+    legacyCommand("list-integration-operations", [
+        "integration",
+        "operation",
+        "list",
+    ]),
+    legacyCommand("retry-integration-operation", [
+        "integration",
+        "operation",
+        "retry",
+    ]),
+    legacyCommand("get-approved-budgets", ["budget", "approved", "list"]),
+    legacyCommand("get-budget-category-benchmarks", [
+        "budget",
+        "category",
+        "benchmark",
+        "get",
+    ]),
+    legacyCommand("get-item-pricing-history", [
+        "item",
+        "pricing-history",
+        "list",
+    ]),
+    legacyCommand("get-supplier-pricing-history", [
+        "supplier",
+        "pricing-history",
+        "list",
+    ]),
+];
+const normalizeToken = (value) => value.replaceAll("_", "-");
+const normalizedPath = (path) => path.map(normalizeToken);
+const assertRegistry = (commands) => {
+    const paths = new Set();
+    const aliases = new Set();
+    for (const command of commands) {
+        const path = command.path.join(" ");
+        if (paths.has(path))
+            throw new Error(`Duplicate canonical command path: ${path}`);
+        paths.add(path);
+        const commandAliases = new Set();
+        for (const alias of command.legacyAliases) {
+            const normalizedAlias = normalizeToken(alias);
+            if (commandAliases.has(normalizedAlias))
+                continue;
+            commandAliases.add(normalizedAlias);
+            if (aliases.has(normalizedAlias)) {
+                throw new Error(`Duplicate legacy command alias: ${alias}`);
+            }
+            aliases.add(normalizedAlias);
+        }
+    }
+};
+assertRegistry(registry);
+export const commandRegistry = registry;
+export const resolveCommand = (argv) => {
+    const normalizedArgv = argv.map(normalizeToken);
+    const canonical = [...commandRegistry]
+        .sort((left, right) => right.path.length - left.path.length)
+        .find((command) => {
+        const path = normalizedPath(command.path);
+        return path.every((segment, index) => normalizedArgv[index] === segment);
+    });
+    if (canonical) {
+        return {
+            command: canonical,
+            argv: argv.slice(canonical.path.length),
+            invokedAs: argv.slice(0, canonical.path.length),
+            isLegacyAlias: false,
+        };
+    }
+    const rawAlias = argv[0];
+    if (!rawAlias)
+        return undefined;
+    const normalizedAlias = normalizeToken(rawAlias);
+    const legacy = commandRegistry.find((command) => command.legacyAliases.some((alias) => normalizeToken(alias) === normalizedAlias));
+    if (!legacy)
+        return undefined;
+    return {
+        command: legacy,
+        argv: argv.slice(1),
+        invokedAs: [rawAlias],
+        isLegacyAlias: true,
+    };
+};
+export const createCommandManifest = () => commandRegistry.map((command) => ({
+    path: command.path,
+    legacyAliases: command.legacyAliases,
+    summary: command.summary,
+    globalOptions: command.options,
+    argumentMode: "legacyTarget" in command ? "legacy-passthrough" : "typed",
+    effects: command.effects,
+    ...("legacyTarget" in command
+        ? { legacyTarget: command.legacyTarget }
+        : {}),
+}));
+export const createHumanHelp = () => {
+    const lines = commandRegistry.map((command) => {
+        const canonical = `bb ${command.path.join(" ")}`;
+        const aliases = command.legacyAliases
+            .filter((alias) => alias.includes("-"))
+            .map((alias) => `bb ${alias}`)
+            .join(", ");
+        return `  ${canonical}\n    ${command.summary}${aliases ? ` Legacy: ${aliases}.` : ""}`;
+    });
+    return [
+        "bb — Budget Builder CLI",
+        "",
+        "Usage: bb <resource> <operation> [options] [args]",
+        "",
+        "Global options",
+        ...globalCommandOptions.map((option) => `  ${option.name}\n    ${option.description}`),
+        "",
+        "Canonical commands",
+        ...lines,
+        "",
+        "Use `bb completion <shell>` to generate shell completion scripts.",
+    ].join("\n");
+};
+const completionWords = () => {
+    const words = new Set();
+    for (const command of commandRegistry) {
+        for (const segment of command.path)
+            words.add(segment);
+        for (const alias of command.legacyAliases)
+            words.add(alias);
+    }
+    words.add("help");
+    words.add("version");
+    words.add("completion");
+    return [...words].sort();
+};
+export const createCompletionScript = (shell) => {
+    const words = completionWords().join(" ");
+    switch (shell) {
+        case "bash":
+            return `# bash completion for bb\n_bb() {\n  COMPREPLY=( $(compgen -W '${words}' -- "${"$"}{COMP_WORDS[COMP_CWORD]}") )\n}\ncomplete -F _bb bb\n`;
+        case "zsh":
+            return `#compdef bb\n_bb() {\n  local -a commands\n  commands=(${words})\n  _describe 'bb command' commands\n}\ncompdef _bb bb\n`;
+        case "fish":
+            return completionWords()
+                .map((word) => `complete -c bb -f -a '${word}'`)
+                .join("\n")
+                .concat("\n");
+        case "powershell":
+            return `Register-ArgumentCompleter -Native -CommandName bb -ScriptBlock {\n  param($wordToComplete)\n  '${words}'.Split(' ') | Where-Object { $_ -like "$wordToComplete*" }\n}\n`;
+    }
+};