firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/billing-usage.js

@@ -0,0 +1,227 @@
+import { api, openBrowser } from './auth.js';
+import { APP_ORIGIN, CliError } from './http.js';
+import { selectedWorkspace } from './world-access.js';
+import { selectOne, terminalText } from './prompts.js';
+import { creditAmount as credits } from './credit-format.js';
+const actions = new Set(['credits', 'credit-help', 'usage', 'credit-ledger', 'credit-allocations', 'credit-work', 'credit-purchases', 'credit-purchase', 'recharge', 'credit-settings']);
+const exact = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const invalid = () => new CliError('billing_response_unconfirmed', 'The credit response could not be confirmed. Reopen Billing or retry this read.');
+const uid = (value) => typeof value === 'string' && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value);
+const boundedText = (value, limit) => typeof value === 'string' && value.length <= limit && !/[\u0000-\u001f\u007f]/.test(value);
+const retainedCreditUnit = (row) => typeof row.denomination === 'string'
+    && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,31}$/.test(row.denomination) && exact(row.credit_scale)
+    && row.credit_scale >= 1 && /^10*$/.test(String(row.credit_scale));
+const retainedCreditAmount = (row) => retainedCreditUnit(row)
+    ? `${credits(row.units, row.credit_scale)} credits` : 'Credit amount unavailable';
+function creditGuideUrl(scope) {
+    if (!uid(scope.workspace))
+        throw invalid();
+    const url = new URL('/settings/billing/credits', APP_ORIGIN);
+    url.searchParams.set('workspace', scope.workspace);
+    return url.href;
+}
+async function showCreditGuide(scope, options, output, open = false) {
+    options.signal.throwIfAborted();
+    const help_url = creditGuideUrl(scope);
+    const opened = open && options.openBrowser && !options.json ? await openBrowser(help_url) : false;
+    options.signal.throwIfAborted();
+    output('billing_credit_help', { workspace_id: scope.workspace, help_url, opened }, `${opened ? 'Opened How credits work' : 'How credits work'}\n${help_url}`);
+}
+function scoped(value, scope) {
+    if (!object(value) || value.actor_id !== scope.owner || value.workspace_id !== scope.workspace
+        || !uid(value.organization_id) || !uid(value.account_id))
+        throw invalid();
+    return value;
+}
+async function summary(scope, options) {
+    const raw = scoped(await api(`/api/workspaces/${scope.workspace}/billing/credits`, {
+        actor: scope.owner, workspace: scope.workspace, signal: options.signal
+    }), scope);
+    if (raw.schema !== 'firedrill.credit-summary.v1' || !object(raw.policy) || typeof raw.policy.enabled !== 'boolean'
+        || raw.policy.help_path !== '/settings/billing/credits' || typeof raw.can_manage !== 'boolean')
+        throw invalid();
+    if (raw.policy.enabled && (!object(raw.balance) || !exact(raw.balance.available_units) || !exact(raw.balance.reserved_units)
+        || !exact(raw.balance.credit_scale) || !object(raw.balance.by_source)
+        || Object.values(raw.balance.by_source).some(one => !exact(one))))
+        throw invalid();
+    return raw;
+}
+async function summaryWithGuide(scope, options, output) {
+    try {
+        return await summary(scope, options);
+    }
+    catch (error) {
+        if (!options.signal.aborted)
+            await showCreditGuide(scope, options, output);
+        throw error;
+    }
+}
+export function isCreditBillingAction(action) { return !!action && actions.has(action); }
+export async function creditBillingCommand(args, options, output, selected) {
+    const action = args[0] ?? 'credits';
+    const detail = ['credit-work', 'credit-purchase'].includes(action);
+    if (!actions.has(action) || args.length > 2 || detail && !uid(args[1]) || !detail && args[1]
+        || options.page !== undefined && (!/^[1-9][0-9]{0,8}$/.test(options.page) || !['usage', 'credit-ledger', 'credit-allocations', 'credit-purchases'].includes(action))
+        || options.search !== undefined || options.kind !== undefined && !['credit-ledger', 'credit-allocations'].includes(action)
+        || options.status !== undefined && !['usage', 'credit-purchases'].includes(action)
+        || (options.from !== undefined || options.to !== undefined) && !['usage', 'credit-ledger'].includes(action))
+        throw new CliError('arguments_invalid', 'Use billing credits, credit-help, usage, credit-ledger, credit-allocations, credit-work <id>, credit-purchases, credit-purchase <id> or recharge.', 2);
+    const scope = selected ?? await selectedWorkspace({ ...options, interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY });
+    if (action === 'credit-help') {
+        await showCreditGuide(scope, options, output, true);
+        return;
+    }
+    if (action === 'recharge' || action === 'credit-settings') {
+        const url = new URL('/settings/billing', APP_ORIGIN);
+        url.searchParams.set('workspace', scope.workspace);
+        const result = { action: 'browser_approval_required', url: url.href, workspace_id: scope.workspace };
+        output('billing_browser_handoff', result, 'Open Billing to review credits, event codes, subscriptions and payment settings. Automatic top-ups require the billing owner to approve the pack, threshold, monthly cash cap and saved card.\n' + url.href);
+        if (options.openBrowser && !options.json)
+            await openBrowser(url.href);
+        return;
+    }
+    // Historical work/payments carry their own frozen identity and scale. A
+    // current tariff read is not a prerequisite for those independent reads or
+    // for the explicit browser-owned financial recovery ceremony above.
+    const row = ['credits', 'credit-ledger', 'credit-allocations'].includes(action) ? await summaryWithGuide(scope, options, output) : null;
+    if (row && (!row.policy.enabled || !row.balance)) {
+        const help_url = creditGuideUrl(scope);
+        output('billing_credit_policy_pending', { workspace_id: scope.workspace, configured: false,
+            help_url }, 'Resource-credit rates are not configured for this platform. No free-runtime or fixed-cost assumption was made.\nHow credits work\n' + help_url);
+        return;
+    }
+    if (action === 'credits') {
+        if (!row?.balance)
+            throw invalid();
+        output('billing_credits', row, `${credits(row.balance.available_units, row.balance.credit_scale)} credits available\n`
+            + `${credits(row.balance.reserved_units, row.balance.credit_scale)} reserved\n`
+            + Object.entries(row.balance.by_source).map(([source, value]) => `${terminalText(source)}: ${credits(value, row.balance.credit_scale)}`).join('\n')
+            + '\nCredits cover preparation, actual authorized execution resources and standalone tool runtime.');
+        await showCreditGuide(scope, options, output);
+        return;
+    }
+    if (action === 'credit-purchases' || action === 'credit-purchase') {
+        const states = ['pending', 'preparing', 'awaiting_payment', 'paid', 'failed', 'uncertain', 'reconciliation_required', 'expired', 'reversed', 'requires_action', 'requires_confirmation', 'canceled'];
+        if (options.status !== undefined && !states.includes(options.status))
+            throw new CliError('arguments_invalid', 'Choose a supported credit purchase status.', 2);
+        const suffix = action === 'credit-purchase' ? `/${args[1]}` : `?${new URLSearchParams({ page: options.page ?? '1', state: options.status ?? '' })}`;
+        const value = scoped(await api(`/api/workspaces/${scope.workspace}/billing/credits/purchases${suffix}`, {
+            actor: scope.owner, workspace: scope.workspace, signal: options.signal
+        }), scope);
+        const read = (raw) => {
+            if (!object(raw) || !uid(raw.id) || !['topup', 'automatic_topup'].includes(String(raw.kind)) || !boundedText(raw.state, 48) || !raw.state
+                || raw.request_state !== null && !boundedText(raw.request_state, 48)
+                || !exact(raw.units) || !exact(raw.amount_cents) || raw.currency !== 'usd'
+                || !(raw.denomination === null || typeof raw.denomination === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,31}$/.test(raw.denomination))
+                || !(raw.credit_scale === null ? raw.url === null : retainedCreditUnit(raw))
+                || raw.message !== undefined && !boundedText(raw.message, 512))
+                throw invalid();
+            return raw;
+        };
+        const state = (row) => !['paid', 'reversed'].includes(String(row.state))
+            && ['uncertain', 'failed', 'reconciliation_required'].includes(String(row.request_state)) ? String(row.request_state) : String(row.state);
+        const money = (cents) => new Intl.NumberFormat(undefined, { style: 'currency', currency: 'USD' }).format(cents / 100);
+        if (action === 'credit-purchase') {
+            const purchase = read(value.purchase);
+            if (purchase.id !== args[1])
+                throw invalid();
+            const url = new URL('/settings/billing', APP_ORIGIN);
+            url.searchParams.set('workspace', scope.workspace);
+            url.searchParams.set('credit_history_purchase', purchase.id);
+            // Hosted payment capabilities stay in the explicit browser ceremony.
+            const { url: _hosted, ...metadata } = purchase;
+            output('billing_credit_purchase', { ...value, purchase: metadata, browser_url: url.href }, `${retainedCreditAmount(purchase)} · ${money(purchase.amount_cents)}\n${terminalText(state(purchase)).replaceAll('_', ' ')}`
+                + (purchase.message ? `\n${terminalText(purchase.message)}` : '') + `\nReview this original payment in Billing:\n${url.href}`);
+            return;
+        }
+        if (!exact(value.count) || !exact(value.page) || value.page !== Number(options.page ?? '1') || !exact(value.page_size)
+            || value.page_size < 1 || value.page_size > 100 || !Array.isArray(value.results) || value.results.length > value.page_size)
+            throw invalid();
+        const purchases = value.results.map(read);
+        if (purchases.some(row => row.url !== null || options.status && state(row) !== options.status))
+            throw invalid();
+        output('billing_credit_purchases', value, (purchases.map(purchase => `${purchase.id}\t${retainedCreditAmount(purchase)}\t${money(purchase.amount_cents)}\t${terminalText(state(purchase)).replaceAll('_', ' ')}`).join('\n') || 'No credit purchases.')
+            + `\nPage ${value.page}; ${value.count} purchases.` + (value.page * value.page_size < value.count ? `\nNext: firedrill billing credit-purchases --page ${value.page + 1}` : ''));
+        return;
+    }
+    const path = action === 'credit-work' ? `/usage/works/${args[1]}` : action === 'usage' ? '/usage/works'
+        : action === 'credit-ledger' ? '/credits/ledger' : '/credits/allocations';
+    const params = new URLSearchParams();
+    if (options.page)
+        params.set('page', options.page);
+    if (options.kind) {
+        const kinds = action === 'credit-ledger' ? ['grant', 'reserved', 'consumed', 'released', 'expired', 'revoked', 'refunded']
+            : ['included', 'purchased', 'sponsored', 'adjustment'];
+        if (!kinds.includes(options.kind))
+            throw new CliError('arguments_invalid', 'Choose a supported credit history kind.', 2);
+        params.set('kind', options.kind);
+    }
+    if (options.status) {
+        if (!['reserved', 'measured', 'budget_exhausted', 'usage_pending', 'settled', 'released'].includes(options.status))
+            throw new CliError('arguments_invalid', 'Choose a supported work usage status.', 2);
+        params.set('state', options.status);
+    }
+    for (const [key, value] of [['from', options.from], ['to', options.to]])
+        if (value !== undefined) {
+            if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) || !Number.isFinite(Date.parse(value)))
+                throw new CliError('arguments_invalid', 'Use an ISO timestamp with an explicit timezone for --from or --to.', 2);
+            params.set(key, new Date(value).toISOString());
+        }
+    const raw = await api(`/api/workspaces/${scope.workspace}/billing${path}${params.size ? '?' + params : ''}`, {
+        actor: scope.owner, workspace: scope.workspace, signal: options.signal
+    });
+    if (action === 'credit-work') {
+        const work = scoped(raw, scope);
+        if (work.id !== args[1]
+            || !exact(work.estimated_units) || !exact(work.maximum_units) || !exact(work.consumed_units) || !exact(work.credit_scale)
+            || work.measured_units !== null && !exact(work.measured_units)
+            || typeof work.state !== 'string' || typeof work.measurement_complete !== 'boolean')
+            throw invalid();
+        output('billing_credit_work', work, `Work: ${terminalText(String(work.id))}\n${terminalText(work.state)}\n`
+            + `Estimate: ${credits(work.estimated_units, work.credit_scale)} credits\nBudget: ${credits(work.maximum_units, work.credit_scale)} credits\n`
+            + `Recorded use: ${work.measured_units === null ? 'Not yet observed' : credits(work.measured_units, work.credit_scale) + ' credits' + (work.measurement_complete ? '' : ' so far')}\n`
+            + (['settled', 'released'].includes(work.state) ? `Charged: ${credits(work.consumed_units, work.credit_scale)} credits` : 'Final charge pending'));
+        return;
+    }
+    const page = scoped(raw, scope);
+    if (!exact(page.count) || !exact(page.page_size) || page.page_size < 1 || !Array.isArray(page.results) || page.results.length > 100)
+        throw invalid();
+    for (const entry of page.results)
+        if (!object(entry) || !uid(entry.id))
+            throw invalid();
+    output('billing_credit_history', page, `${page.count} records, page ${options.page ?? '1'}\n`
+        + (page.results.length ? page.results.map((entry) => {
+            const label = typeof entry.description === 'string' ? entry.description : `${entry.activity ?? entry.kind ?? 'Allocation'} ${entry.state ?? ''}`;
+            // Work history can include a previous tariff/denomination. Never apply
+            // today's display scale to another retained quote's actual charge.
+            const scale = action === 'usage' ? entry.credit_scale : row.balance.credit_scale;
+            if (!exact(scale) || scale < 1 || !/^10*$/.test(String(scale)))
+                throw invalid();
+            if (action === 'usage' && entry.measured_units !== null && !exact(entry.measured_units))
+                throw invalid();
+            const amount = action === 'usage' ? entry.measured_units : entry.units ?? entry.available_units;
+            if (amount !== undefined && amount !== null && (typeof amount !== 'number' || !Number.isSafeInteger(amount)))
+                throw invalid();
+            const formatted = amount === null ? 'Not yet observed' : amount === undefined ? '' : amount < 0 ? '-' + credits(-amount, scale) : credits(amount, scale);
+            return `${entry.id}\t${terminalText(label)}\t${formatted}`;
+        }).join('\n') : 'No matching records.')
+        + (Number(options.page ?? 1) * page.page_size < page.count ? `\nNext page: firedrill billing ${action} --page ${Number(options.page ?? 1) + 1}` : ''));
+}
+/** Preserve a single organization scope when upgrading the normal billing flow. */
+export async function useResourceCreditSummary(scope, options, output) {
+    const row = await summaryWithGuide(scope, options, output);
+    if (!row.policy.enabled) {
+        await creditBillingCommand(['credits'], options, output, scope);
+        return true;
+    }
+    await creditBillingCommand(['credits'], options, output, scope);
+    if (!options.json && process.stdin.isTTY && process.stderr.isTTY) {
+        const choice = await selectOne('Billing', [{ value: 'usage', label: 'Work usage' }, { value: 'credit-ledger', label: 'Credit history' },
+            { value: 'credit-allocations', label: 'Allocations and expiry' }, { value: 'credit-help', label: 'How credits work' }, ...(row.can_manage ? [{ value: 'credit-purchases', label: 'Credit purchase history' }, { value: 'recharge', label: 'Payment and top-up settings in browser' }] : []),
+            { value: 'done', label: 'Back' }], options.signal);
+        if (choice !== 'done')
+            await creditBillingCommand([choice], options, output, scope);
+    }
+    return true;
+}

package/dist/cli/src/billing-wallet-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/billing-wallet-contracts.js';

package/dist/cli/src/billing.js

@@ -0,0 +1,170 @@
+import { api, openBrowser } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { creditBillingCommand, isCreditBillingAction, useResourceCreditSummary } from './billing-usage.js';
+import { billingWalletRead, billingSummaryMatches } from './billing-wallet-contracts.js';
+import { billingCommerceRead, billingOptionsMatch, billingPurchaseMatches, billingPurchasesMatch, billingInvoiceMatches, billingInvoicesMatch, billingInvoiceLinesMatch } from './billing-commerce-contracts.js';
+const interactive = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const auth = (scope, options) => ({ actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+const prefix = (scope) => `/api/workspaces/${scope.workspace}/billing`;
+const money = (cents) => Number.isSafeInteger(cents)
+    ? new Intl.NumberFormat(undefined, { style: 'currency', currency: 'USD' }).format(cents / 100) : 'Amount unavailable';
+const purchaseStates = { paid: 'Payment recorded', pending: 'Preparing hosted page', preparing: 'Preparing hosted page',
+    awaiting_payment: 'Awaiting payment', portal_ready: 'Hosted management ready', uncertain: 'Request status unconfirmed',
+    reconciliation_required: 'Payment needs review', failed: 'Request not completed', expired: 'Request expired', reversed: 'Payment adjusted' };
+const effectiveState = (row) => !['paid', 'reversed'].includes(row.state)
+    && ['uncertain', 'failed', 'reconciliation_required'].includes(row.request_state ?? '') ? row.request_state : row.state;
+const purchaseName = (row) => row.kind === 'portal' ? row.offer ? `Change to ${row.offer} (${row.interval})` : 'Payment details and cancellation'
+    : `${row.offer} subscription (${row.interval})`;
+const purchaseUnitUnavailable = (row) => !(row.kind === 'portal' && row.units === 0 && row.amount_cents === 0
+    && row.denomination === null && !row.offer && !row.interval)
+    && !(typeof row.denomination === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,31}$/.test(row.denomination)
+        && typeof row.credit_scale === 'number' && Number.isSafeInteger(row.credit_scale) && row.credit_scale >= 1 && /^10*$/.test(String(row.credit_scale)));
+const invoiceId = (value) => {
+    if (!/^in_[A-Za-z0-9_]{1,120}$/.test(value))
+        throw new CliError('invoice_required', 'Choose an invoice from billing invoices.', 2);
+    return value;
+};
+function showPurchase(row, output) {
+    const { url: _url, ...publicRow } = row;
+    output('billing_purchase', publicRow, `${purchaseName(row)}\n${purchaseStates[effectiveState(row)] ?? 'Status unavailable'}\n`
+        + (row.kind === 'portal' ? '' : `${money(row.amount_cents)} before any Checkout discount. Recorded payment details are in invoices.\n`)
+        + (row.kind === 'portal' && row.offer ? 'Confirm the selected change and any proration in Stripe. Opening this page does not confirm a change or payment.\n' : '')
+        + `Request: ${row.id}\nRecorded: ${row.created_at}` + (row.message ? `\n${row.message}` : '')
+        + (row.url && !purchaseUnitUnavailable(row) ? `\nOpen the hosted page: firedrill billing open ${row.id}` : ''));
+}
+async function purchaseAction(action, id, scope, options, output) {
+    const selected = identifier(id), path = `${prefix(scope)}/purchases/${selected}`;
+    const row = await api(path, action === 'refresh-purchase'
+        ? { ...auth(scope, options), method: 'POST', body: {} } : auth(scope, options));
+    billingCommerceRead(row, billingPurchaseMatches(row, scope.workspace, { id: selected }));
+    if (action === 'refresh-purchase') {
+        showPurchase(row, output);
+        output('billing_refresh', { id: selected, scheduled: true }, 'A read of this original payment or subscription was requested. No new payment or plan change was created.');
+        return;
+    }
+    if (action !== 'open') {
+        showPurchase(row, output);
+        return;
+    }
+    let link;
+    try {
+        if (purchaseUnitUnavailable(row) || !row.url || !row.expires_at || !['awaiting_payment', 'portal_ready'].includes(row.state)
+            || !Number.isFinite(Date.parse(row.expires_at)) || Date.parse(row.expires_at) <= Date.now())
+            throw new Error();
+        link = new URL(row.url);
+        if (link.protocol !== 'https:' || link.host !== (row.kind === 'portal' ? 'billing.stripe.com' : 'checkout.stripe.com')
+            || link.username || link.password)
+            throw new Error();
+    }
+    catch {
+        throw new CliError('billing_link_unavailable', 'No current hosted link is available. Inspect this original payment request before starting another.', 2);
+    }
+    const opened = !options.json && options.openBrowser && await openBrowser(link.href);
+    output('billing_hosted_page', { id: row.id, opened, ...(opened ? {} : { url: link.href }), expires_at: row.expires_at }, opened ? 'Opened the hosted payment page. No payment is implied.' : `Open the hosted payment page: ${link.href}`);
+}
+async function invoiceAction(action, id, scope, options, output) {
+    const row = await api(`${prefix(scope)}/invoices/${invoiceId(id)}`, action === 'refresh-invoice'
+        ? { ...auth(scope, options), method: 'POST', body: {} } : auth(scope, options));
+    billingCommerceRead(row, billingInvoiceMatches(row, scope.workspace, id));
+    output('billing_invoice', row, `${row.id}\n${row.status} · ${money(row.total_cents)} total · ${money(row.paid_cents)} paid\n`
+        + `${money(row.discount_cents)} discount\nRecorded: ${row.created_at}\nReconciliation: ${row.reconciliation}`
+        + (row.service_starts_at ? `\nService period: ${row.service_starts_at} to ${row.service_ends_at}` : '')
+        + (action === 'refresh-invoice' ? '\nA current invoice read was requested. No payment was changed.' : `\nInspect line items: firedrill billing lines ${row.id}`));
+}
+async function history(action, id, scope, options, output) {
+    let page = Number(options.page ?? '1');
+    while (true) {
+        const query = new URLSearchParams({ page: String(page) });
+        if (options.status)
+            query.set('status', options.status);
+        const path = action === 'lines' ? `/invoices/${invoiceId(id)}/lines` : `/${action}`;
+        let rows, labels;
+        if (action === 'purchases') {
+            const value = await api(`${prefix(scope)}${path}?${query}`, auth(scope, options));
+            rows = billingCommerceRead(value, billingPurchasesMatch(value, scope.workspace, options.status ?? '', page));
+            labels = value.results.map(item => `${purchaseName(item)} · ${purchaseStates[effectiveState(item)] ?? 'Status unavailable'} · ${item.id}`);
+        }
+        else if (action === 'invoices') {
+            const value = await api(`${prefix(scope)}${path}?${query}`, auth(scope, options));
+            rows = billingCommerceRead(value, billingInvoicesMatch(value, scope.workspace, options.status ?? '', page));
+            labels = value.results.map(item => `${money(item.total_cents)} · ${item.status} · ${item.id}`);
+        }
+        else {
+            const value = await api(`${prefix(scope)}${path}?${query}`, auth(scope, options));
+            rows = billingCommerceRead(value, billingInvoiceLinesMatch(value, scope.workspace, id, page));
+            labels = value.results.map(item => `${item.plan}, ${item.interval} · ${money(item.amount_cents)}${item.prorated ? ' · Prorated' : ''} · ${item.service_starts_at} to ${item.service_ends_at}`);
+        }
+        output(`billing_${action}`, rows, (labels.join('\n') || 'No matching records.') + `\nPage ${rows.page} · ${rows.count} records`
+            + (action === 'lines' && 'collection_complete' in rows && !rows.collection_complete ? '\nInvoice line collection is incomplete. These are the items recorded so far.' : '')
+            + (rows.next ? `\nNext: firedrill billing ${action}${id ? ` ${id}` : ''} --workspace ${scope.workspace} --page ${page + 1}${options.status ? ` --status ${options.status}` : ''}` : ''));
+        if (!interactive(options))
+            return;
+        const selected = await selectOne('Billing history', [
+            ...(['purchases', 'invoices'].includes(action) ? rows.results.map((item, index) => ({ value: item.id, label: terminalText(labels[index]) })) : []),
+            ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : []),
+            ...(rows.next ? [{ value: 'next', label: 'Next page' }] : []), { value: 'done', label: 'Back' }
+        ], options.signal);
+        if (selected === 'done')
+            return;
+        if (selected === 'previous') {
+            page -= 1;
+            continue;
+        }
+        if (selected === 'next') {
+            page += 1;
+            continue;
+        }
+        if (action === 'purchases')
+            await purchaseAction('purchase', selected, scope, options, output);
+        else
+            await invoiceAction('invoice', selected, scope, options, output);
+    }
+}
+export async function billingCommand(args, options, output) {
+    const action = args[0] ?? 'summary';
+    if (isCreditBillingAction(action)) {
+        await creditBillingCommand(args, options, output);
+        return;
+    }
+    const financial = ['subscribe', 'change', 'topup', 'portal', 'redeem'];
+    const withId = ['purchase', 'open', 'refresh-purchase', 'invoice', 'lines', 'refresh-invoice'];
+    const listing = ['purchases', 'invoices', 'lines'];
+    if (!['summary', 'options', ...financial, ...withId, ...listing].includes(action) || args.length > 2
+        || withId.includes(action) && !args[1] || args[1] && !withId.includes(action)
+        || options.from !== undefined || options.to !== undefined || options.kind !== undefined || options.search !== undefined
+        || options.page !== undefined && (!listing.includes(action) || !/^[1-9][0-9]{0,8}$/.test(options.page))
+        || options.status !== undefined && (!['purchases', 'invoices'].includes(action)
+            || !(action === 'purchases' ? Object.keys(purchaseStates) : ['draft', 'open', 'paid', 'void', 'uncollectible']).includes(options.status)))
+        throw new CliError('arguments_invalid', 'Use billing credits, usage, credit-ledger, credit-allocations, options, purchases or invoices. Review subscription, payment and event-code changes in Billing.', 2);
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) });
+    if (action === 'summary') {
+        await useResourceCreditSummary(scope, options, output);
+        return;
+    }
+    if (financial.includes(action)) {
+        await creditBillingCommand(['credit-settings'], options, output, scope);
+        return;
+    }
+    if (withId.includes(action)) {
+        if (action === 'lines')
+            await history('lines', args[1], scope, options, output);
+        else if (action === 'invoice' || action === 'refresh-invoice')
+            await invoiceAction(action, args[1], scope, options, output);
+        else
+            await purchaseAction(action, args[1], scope, options, output);
+        return;
+    }
+    if (action === 'purchases' || action === 'invoices') {
+        await history(action, undefined, scope, options, output);
+        return;
+    }
+    const summary = await api(prefix(scope), auth(scope, options));
+    billingWalletRead(summary, billingSummaryMatches(summary, scope.workspace, scope.owner));
+    const offers = summary.can_manage ? await api(`${prefix(scope)}/options`, auth(scope, options)) : null;
+    if (offers)
+        billingCommerceRead(offers, billingOptionsMatch(offers, scope.workspace, scope.owner, summary.organization_id));
+    output('billing_options', { catalog: summary.catalog, offers, can_manage: summary.can_manage }, JSON.stringify({ catalog: summary.catalog, offers, can_manage: summary.can_manage }, null, 2));
+}

package/dist/cli/src/bootstrap-process-lock.js

@@ -0,0 +1,136 @@
+import { createHash } from 'node:crypto';
+import { lstat } from 'node:fs/promises';
+import { createServer } from 'node:net';
+import { dirname, isAbsolute } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { CliError } from './http.js';
+const unavailable = () => new CliError('bootstrap_operation_owned', 'This sign-in or helper setup is already owned, a prior lock needs inspection, or local coordination is unavailable. No pending request was repeated.');
+/** Before a trusted Python exists, Node's exclusive loopback binding supplies
+ * process-lifetime coordination only. No protocol, credentials or requests are
+ * served. A deterministic port collision is a refusal, never another lock slot.
+ * This is not proof of account identity or a security boundary against local
+ * denial of service. All product/refresh journals retain their original fences.
+ */
+class BindCollision extends Error {
+}
+export async function bootstrapProcessLock(path, options = {}) {
+    const waitMs = options.waitMs ?? 0;
+    if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 30000)
+        throw unavailable();
+    const deadline = performance.now() + waitMs;
+    for (;;) {
+        options.signal?.throwIfAborted();
+        try {
+            return await acquireProcessLock(path);
+        }
+        catch (error) {
+            // Only an OS bind collision may wait. No old directory lock, failed
+            // ownership check, provider request or persisted refresh is retried.
+            if (!(error instanceof BindCollision))
+                throw error;
+            const remaining = deadline - performance.now();
+            if (remaining <= 0)
+                throw unavailable();
+            await delay(Math.min(remaining, 100 + Math.floor(Math.random() * 150)), undefined, { signal: options.signal });
+        }
+    }
+}
+async function acquireProcessLock(path) {
+    if (!isAbsolute(path))
+        throw unavailable();
+    const directory = await lstat(dirname(path));
+    if (!directory.isDirectory() || directory.isSymbolicLink()
+        || process.getuid && directory.uid !== process.getuid()
+        || process.platform !== 'win32' && directory.mode & 0o077)
+        throw unavailable();
+    // Preserve any old directory-based owner, including an ambiguous dead owner.
+    // Never infer safety from its PID or unlink it to get a different lock.
+    try {
+        await lstat(path);
+        throw unavailable();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const port = 16384 + createHash('sha256').update('firedrill.bootstrap-lock.v1\0').update(path).digest().readUInt32BE(0) % 49152;
+    const controller = new AbortController();
+    const server = createServer(socket => socket.destroy());
+    server.maxConnections = 1;
+    let held = false, closing = false, closePromise;
+    const lost = () => { held = false; if (!closing)
+        controller.abort(); };
+    server.on('error', lost);
+    server.on('close', lost);
+    server.on('listening', () => { if (closing)
+        server.close(); });
+    try {
+        await new Promise((resolve, reject) => {
+            let finished = false;
+            const fail = (error) => finish(error?.code === 'EADDRINUSE' ? new BindCollision() : unavailable());
+            const finish = (error) => {
+                if (finished)
+                    return;
+                finished = true;
+                clearTimeout(timer);
+                server.off('error', fail);
+                server.off('listening', ready);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const ready = () => { held = true; finish(); };
+            const timer = setTimeout(fail, 10000);
+            server.once('error', fail);
+            server.once('listening', ready);
+            try {
+                server.listen({ host: '127.0.0.1', port, exclusive: true, backlog: 1 });
+            }
+            catch {
+                finish(unavailable());
+            }
+        });
+    }
+    catch (error) {
+        closing = true;
+        try {
+            server.close();
+        }
+        catch { /* A failed bind may never have opened. */ }
+        throw error;
+    }
+    const close = () => closePromise ??= new Promise((resolve, reject) => {
+        closing = true;
+        held = false;
+        const timer = setTimeout(() => { controller.abort(); reject(unavailable()); }, 5000);
+        server.close(error => {
+            clearTimeout(timer);
+            if (error) {
+                controller.abort();
+                reject(unavailable());
+            }
+            else
+                resolve();
+        });
+    });
+    return { signal: controller.signal, assertHeld: () => {
+            if (!held || !server.listening || controller.signal.aborted || closing)
+                throw unavailable();
+        }, close };
+}
+export async function withBootstrapProcessLock(path, signal, work) {
+    signal.throwIfAborted();
+    const lock = await bootstrapProcessLock(path), active = AbortSignal.any([signal, lock.signal]);
+    try {
+        lock.assertHeld();
+        active.throwIfAborted();
+        const value = await work(active, lock.signal);
+        lock.assertHeld();
+        active.throwIfAborted();
+        return value;
+    }
+    finally {
+        await lock.close();
+    }
+}

package/dist/cli/src/browser-links.js

@@ -0,0 +1,14 @@
+import { APP_ORIGIN, CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+/** Browser and native workspace selections are independent authenticated state. */
+export function workspaceLink(workspace, path, parameters = {}) {
+    if (!path.startsWith('/') || path.startsWith('//'))
+        throw new CliError('browser_link_invalid', 'Open this record from its workspace.', 2);
+    const url = new URL(path, APP_ORIGIN);
+    if (url.origin !== new URL(APP_ORIGIN).origin)
+        throw new CliError('browser_link_invalid', 'Open this record from its workspace.', 2);
+    for (const [key, value] of Object.entries(parameters))
+        url.searchParams.set(key, value);
+    url.searchParams.set('workspace', identifier(workspace));
+    return url.href;
+}