@funnelsgrove/cli 0.1.315 → 0.1.316

package/README.md

@@ -243,18 +243,22 @@ by Merchanto; the cost lines cover FunnelsGrove alerts for the whole project.
 The output never includes customer emails, names, phone numbers, IP addresses,
 card digits, network references or Stripe identifiers.
 
-Support a customer (workspace admins only): look them up by email or funnel
-user ID, refund chosen payments and cancel their subscription:
+Support a user (workspace admins only): find the projects they belong to,
+look them up by email or funnel user ID, refund chosen payments and cancel
+their subscription:
 
 ```bash
-fgrove customers lookup --project claimbee --email buyer@example.com --json   # users, live subscriptions, payments with refund eligibility
-fgrove customers refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456 --dry-run
-fgrove customers refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456
-fgrove customers cancel --project claimbee --user-id 8f1c2d   # at period end; --now cancels immediately without refunding the remainder
+fgrove users find --email buyer@example.com --json   # every project you administer where this user exists, each with its lookup
+fgrove users lookup --project claimbee --email buyer@example.com --json   # users, live subscriptions, payments with refund eligibility
+fgrove users refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456 --dry-run
+fgrove users refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456
+fgrove users cancel --project claimbee --user-id 8f1c2d   # at period end; --now cancels immediately without refunding the remainder
 ```
 
-Pass exactly one of `--email` or `--user-id`; `--env test` reads test-mode
-customers. Stripe charges and subscriptions come live from Stripe; Solidgate
+`customers` remains an alias of `users`. Pass exactly one of `--email` or `--user-id`; `--env test` reads test-mode
+users. `find` searches every workspace you belong to (narrow it with
+`--workspace`), lists workspaces where you are not an admin as not searched and
+exits 1 when a project could not be searched. Stripe charges and subscriptions come live from Stripe; Solidgate
 payments come from the FunnelsGrove ledger with refunded amounts read live from
 Solidgate. Refunds are full refunds of each payment's remaining amount, using
 the payment IDs printed by `lookup`. Each payment is refunded at most once,

package/dist/cli.js

@@ -20,7 +20,7 @@ import { executeFastDraftPatchSync, uploadDirectAssetWithFetch } from './draftPa
 import { updateCliInstallations } from './selfUpdate.js';
 import { executeExpensePublish, executeExpensePull } from './expenseCommands.js';
 import { buildAlertStatisticsReport, fetchAlertStatistics, fetchPreventSummary, formatAlertRows, formatAlertStatistics, formatPreventRows, formatPreventSummary, listAlerts, listPreventSearches, parseAlertMonth, toAlertJsonRow, } from './alertCommands.js';
-import { cancelCustomerSubscription, formatCustomerCancellation, formatCustomerLookup, formatCustomerRefunds, formatRefundPreview, lookupCustomer, parseCustomerSelector, previewRefund, refundCustomerPayments, } from './customerCommands.js';
+import { cancelUserSubscription, findUser, formatUserCancellation, formatUserFind, formatUserLookup, formatUserRefunds, formatRefundPreview, lookupUser, parseUserSelector, previewRefund, refundUserPayments, } from './userCommands.js';
 import { executeOfferSetPrices, executeOfferSetPublish, executeOfferSetPull, formatOfferSetPriceCatalogs, } from './offerSetCommands.js';
 import { executeEmailPull, executeEmailPush, executeEmailSend, executeEmailUpdateVariables, executeEmailSequenceAddStep, executeEmailSequenceCancel, executeEmailSequenceCreate, executeEmailSequencePublish, executeEmailSequenceSetActive, executeEmailLibraryAdd, executeEmailLibraryList, executeEmailTemplatePublish, executeEmailValidate, parseEmailVariablesJson, } from './emailCommands.js';
 import { formatGitHubConnectRows, formatGitHubJobRows, formatGitHubStatusRows, } from './githubOutput.js';
@@ -2285,71 +2285,99 @@ addAlertScopeOptions(preventCommand
     }
     printValueRows(formatPreventSummary(month, summary).map((line) => [line]));
 });
-const addCustomerOptions = (command) => command
+const addUserOptions = (command) => command
     .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
     .option('--project <id-or-slug-or-name>', 'Project id, slug, or name')
-    .option('--email <email>', 'Customer email (exact match, case-insensitive)')
+    .option('--email <email>', 'User email (exact match, case-insensitive)')
     .option('--user-id <id>', 'Funnel user ID (the SDK user ID)')
     .option('--env <environment>', 'test or live', 'live')
     .option('--json', 'Print machine-readable JSON');
-const resolveCustomerCommandScope = async (options) => {
-    const selector = parseCustomerSelector(options);
+const resolveUserCommandScope = async (options) => {
+    const selector = parseUserSelector(options);
     return { scope: await resolveProjectCommandScope(options), selector };
 };
-const customersCommand = addExamples(program.command('customers').description('Look up a customer\'s subscriptions and payments, refund payments and cancel subscriptions (workspace admins)'), [
-    'fgrove customers lookup --project claimbee --email buyer@example.com',
-    'fgrove customers refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456',
-    'fgrove customers cancel --project claimbee --user-id 8f1c... --now',
+const usersCommand = addExamples(program.command('users').alias('customers').description('Look up a user\'s subscriptions and payments, refund payments and cancel subscriptions (workspace admins)'), [
+    'fgrove users find --email buyer@example.com',
+    'fgrove users lookup --project claimbee --email buyer@example.com',
+    'fgrove users refund --project claimbee --email buyer@example.com --payment ch_123 --payment pay_456',
+    'fgrove users cancel --project claimbee --user-id 8f1c... --now',
 ]);
-addCustomerOptions(customersCommand
+usersCommand
+    .command('find')
+    .description('Find every project you administer where the user exists, with their subscriptions and payments')
+    .option('--workspace <id-or-slug-or-name>', 'Search only this workspace (default: every workspace you belong to)')
+    .option('--email <email>', 'User email (exact match, case-insensitive)')
+    .option('--user-id <id>', 'Funnel user ID (the SDK user ID)')
+    .option('--env <environment>', 'test or live', 'live')
+    .option('--json', 'Print machine-readable JSON')
+    .action(async (options) => {
+    const selector = parseUserSelector(options);
+    const token = await readAuthToken();
+    const workspaces = options.workspace
+        ? [await resolveWorkspace(token, options.workspace)]
+        : (await getCurrentUser(token)).workspaces;
+    const projects = (await Promise.all(workspaces.map(async (workspace) => ((await listProjects(token, workspace.id)).map((project) => ({
+        workspace: { id: workspace.id, name: workspace.name, slug: workspace.slug },
+        project: { id: project.id, name: project.name, slug: project.slug },
+    })))))).flat();
+    const found = await findUser({ callApi, token, projects }, selector);
+    if (found.skipped.some((skip) => skip.reason === 'failed'))
+        process.exitCode = 1;
+    if (options.json) {
+        console.log(JSON.stringify(found, null, 2));
+        return;
+    }
+    printValueRows(formatUserFind(found).map((line) => [line]));
+});
+addUserOptions(usersCommand
     .command('lookup')
-    .description('List the customer\'s funnel users, live provider subscriptions and payments with refund eligibility'))
+    .description('List the matching funnel users, their live provider subscriptions and payments with refund eligibility'))
     .action(async (options) => {
-    const { scope, selector } = await resolveCustomerCommandScope(options);
-    const lookup = await lookupCustomer(scope, selector);
+    const { scope, selector } = await resolveUserCommandScope(options);
+    const lookup = await lookupUser(scope, selector);
     if (options.json) {
         console.log(JSON.stringify(lookup, null, 2));
         return;
     }
-    printValueRows(formatCustomerLookup(lookup).map((line) => [line]));
+    printValueRows(formatUserLookup(lookup).map((line) => [line]));
 });
-addCustomerOptions(customersCommand
+addUserOptions(usersCommand
     .command('refund')
-    .description('Fully refund the remaining amount of each chosen payment (payment IDs from customers lookup)')
-    .requiredOption('--payment <id>', 'Payment ID from customers lookup; repeat for several', (value, previous = []) => [...previous, value])
+    .description('Fully refund the remaining amount of each chosen payment (payment IDs from users lookup)')
+    .requiredOption('--payment <id>', 'Payment ID from users lookup; repeat for several', (value, previous = []) => [...previous, value])
     .option('--dry-run', 'Show what would be refunded without refunding'))
     .action(async (options) => {
-    const { scope, selector } = await resolveCustomerCommandScope(options);
+    const { scope, selector } = await resolveUserCommandScope(options);
     if (options.dryRun) {
-        const preview = previewRefund(await lookupCustomer(scope, selector), options.payment);
+        const preview = previewRefund(await lookupUser(scope, selector), options.payment);
         console.log(options.json ? JSON.stringify({ dryRun: true, refunds: preview }, null, 2)
             : formatRefundPreview(preview).join('\n'));
         return;
     }
-    const { refunds } = await refundCustomerPayments(scope, selector, options.payment);
+    const { refunds } = await refundUserPayments(scope, selector, options.payment);
     if (refunds.some((refund) => refund.outcome === 'failed'))
         process.exitCode = 1;
     if (options.json) {
         console.log(JSON.stringify({ refunds }, null, 2));
         return;
     }
-    printValueRows(formatCustomerRefunds(refunds).map((line) => [line]));
+    printValueRows(formatUserRefunds(refunds).map((line) => [line]));
 });
-addCustomerOptions(customersCommand
+addUserOptions(usersCommand
     .command('cancel')
-    .description('Cancel the customer\'s billing subscription at period end, or immediately with --now')
+    .description('Cancel the user\'s billing subscription at period end, or immediately with --now')
     .option('--subscription <id>', 'Subscription ID; required when several subscriptions are still billing')
     .option('--now', 'Cancel immediately; the paid remainder is forfeited without a refund'))
     .action(async (options) => {
-    const { scope, selector } = await resolveCustomerCommandScope(options);
+    const { scope, selector } = await resolveUserCommandScope(options);
     if (options.now)
         console.error('Cancelling immediately: access ends now and the paid remainder is not refunded.');
-    const result = await cancelCustomerSubscription(scope, selector, { subscriptionId: options.subscription, now: options.now });
+    const result = await cancelUserSubscription(scope, selector, { subscriptionId: options.subscription, now: options.now });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
-    printValueRows(formatCustomerCancellation(result).map((line) => [line]));
+    printValueRows(formatUserCancellation(result).map((line) => [line]));
 });
 const funnelsCommand = addExamples(program.command('funnels').description('Manage funnels'), [
     'fgrove funnels list',

package/dist/{customerCommands.d.ts → userCommands.d.ts}

@@ -4,19 +4,19 @@ type CallApi = <T>(input: {
     data?: unknown;
     token?: string | null;
 }) => Promise<T>;
-export type CustomerCommandScope = {
+export type UserCommandScope = {
     callApi: CallApi;
     token: string;
     workspaceId: string;
     projectId: string;
 };
-export type CustomerSelector = {
+export type UserSelector = {
     environment: 'test' | 'live';
     email?: string;
     userId?: string;
 };
 type Provider = 'stripe' | 'solidgate';
-export type CustomerSubscription = {
+export type UserSubscription = {
     provider: Provider;
     paymentProfileId: string;
     subscriptionId: string;
@@ -31,7 +31,7 @@ export type CustomerSubscription = {
     interval: string | null;
     billing: boolean;
 };
-export type CustomerPayment = {
+export type UserPayment = {
     provider: Provider;
     paymentProfileId: string;
     paymentId: string | null;
@@ -45,7 +45,7 @@ export type CustomerPayment = {
     refundable: boolean;
     notRefundableReason: string | null;
 };
-export type CustomerLookup = {
+export type UserLookup = {
     environment: 'test' | 'live';
     users: Array<{
         funnelUserId: string;
@@ -54,8 +54,8 @@ export type CustomerLookup = {
         funnelId: string | null;
         createdAt: string;
     }>;
-    subscriptions: CustomerSubscription[];
-    payments: CustomerPayment[];
+    subscriptions: UserSubscription[];
+    payments: UserPayment[];
     sources: Array<{
         provider: string;
         paymentProfileId: string | null;
@@ -63,7 +63,7 @@ export type CustomerLookup = {
         detail?: string;
     }>;
 };
-export type CustomerRefund = {
+export type UserRefund = {
     paymentId: string;
     provider: Provider | null;
     outcome: 'refunded' | 'already_refunded' | 'processing' | 'failed';
@@ -72,7 +72,7 @@ export type CustomerRefund = {
     refundIds: string[];
     error?: string;
 };
-export type CustomerCancellation = {
+export type UserCancellation = {
     provider: Provider;
     paymentProfileId: string;
     subscriptionId: string;
@@ -84,21 +84,49 @@ export type CustomerCancellation = {
     paidDaysForfeited: number;
 };
 /** Exactly one of email or user ID; emails are matched trimmed and lowercased. */
-export declare const parseCustomerSelector: (options: {
+export declare const parseUserSelector: (options: {
     email?: string;
     userId?: string;
     env?: string;
-}) => CustomerSelector;
-export declare const lookupCustomer: (scope: CustomerCommandScope, selector: CustomerSelector) => Promise<CustomerLookup>;
-export declare const refundCustomerPayments: (scope: CustomerCommandScope, selector: CustomerSelector, paymentIds: string[]) => Promise<{
-    refunds: CustomerRefund[];
+}) => UserSelector;
+export declare const lookupUser: (scope: UserCommandScope, selector: UserSelector) => Promise<UserLookup>;
+export declare const refundUserPayments: (scope: UserCommandScope, selector: UserSelector, paymentIds: string[]) => Promise<{
+    refunds: UserRefund[];
 }>;
-export declare const cancelCustomerSubscription: (scope: CustomerCommandScope, selector: CustomerSelector, input: {
+export declare const cancelUserSubscription: (scope: UserCommandScope, selector: UserSelector, input: {
     subscriptionId?: string;
     now?: boolean;
-}) => Promise<CustomerCancellation>;
+}) => Promise<UserCancellation>;
+type NamedScope = {
+    id: string;
+    name: string;
+    slug: string;
+};
+export type UserSearchProject = {
+    workspace: NamedScope;
+    project: NamedScope;
+};
+export type UserFind = {
+    environment: 'test' | 'live';
+    searchedProjects: number;
+    matches: Array<UserSearchProject & {
+        lookup: UserLookup;
+    }>;
+    skipped: Array<UserSearchProject & {
+        reason: 'not-admin' | 'failed';
+        detail?: string;
+    }>;
+};
+/** Runs users lookup in every given project; projects where the user is unknown are left out. */
+export declare const findUser: (input: {
+    callApi: CallApi;
+    token: string;
+    projects: UserSearchProject[];
+    concurrency?: number;
+}, selector: UserSelector) => Promise<UserFind>;
+export declare const formatUserFind: (found: UserFind) => string[];
 /** Payments the refund would touch, in the order requested; unknown IDs are reported, not dropped. */
-export declare const previewRefund: (lookup: CustomerLookup, paymentIds: string[]) => ({
+export declare const previewRefund: (lookup: UserLookup, paymentIds: string[]) => ({
     paymentId: string;
     provider: Provider;
     amountMinor: number;
@@ -114,7 +142,7 @@ export declare const previewRefund: (lookup: CustomerLookup, paymentIds: string[
     reason: string;
 })[];
 export declare const formatRefundPreview: (preview: ReturnType<typeof previewRefund>) => string[];
-export declare const formatCustomerLookup: (lookup: CustomerLookup) => string[];
-export declare const formatCustomerRefunds: (refunds: CustomerRefund[]) => string[];
-export declare const formatCustomerCancellation: (result: CustomerCancellation) => string[];
+export declare const formatUserLookup: (lookup: UserLookup) => string[];
+export declare const formatUserRefunds: (refunds: UserRefund[]) => string[];
+export declare const formatUserCancellation: (result: UserCancellation) => string[];
 export {};

package/dist/{customerCommands.js → userCommands.js}

@@ -1,6 +1,7 @@
 import { formatMinor } from './alertCommands.js';
+import { TrpcApiError } from './apiClient.js';
 /** Exactly one of email or user ID; emails are matched trimmed and lowercased. */
-export const parseCustomerSelector = (options) => {
+export const parseUserSelector = (options) => {
     const email = options.email?.trim().toLowerCase();
     const userId = options.userId?.trim();
     if (Boolean(email) === Boolean(userId))
@@ -12,30 +13,74 @@ export const parseCustomerSelector = (options) => {
 const request = (scope, selector) => ({
     workspaceId: scope.workspaceId, projectId: scope.projectId, ...selector,
 });
-export const lookupCustomer = (scope, selector) => scope.callApi({
+export const lookupUser = (scope, selector) => scope.callApi({
     path: 'customers.lookup', type: 'query', token: scope.token, data: request(scope, selector),
 });
-export const refundCustomerPayments = (scope, selector, paymentIds) => (scope.callApi({
+export const refundUserPayments = (scope, selector, paymentIds) => (scope.callApi({
     path: 'customers.refund', type: 'mutation', token: scope.token, data: { ...request(scope, selector), paymentIds },
 }));
-export const cancelCustomerSubscription = (scope, selector, input) => scope.callApi({
+export const cancelUserSubscription = (scope, selector, input) => scope.callApi({
     path: 'customers.cancel',
     type: 'mutation',
     token: scope.token,
     data: { ...request(scope, selector), ...(input.subscriptionId ? { subscriptionId: input.subscriptionId } : {}), mode: input.now ? 'immediate' : 'period_end' },
 });
+/** Runs users lookup in every given project; projects where the user is unknown are left out. */
+export const findUser = async (input, selector) => {
+    const result = { environment: selector.environment, searchedProjects: input.projects.length, matches: [], skipped: [] };
+    const queue = [...input.projects];
+    const worker = async () => {
+        for (let target = queue.shift(); target; target = queue.shift()) {
+            const scope = { callApi: input.callApi, token: input.token, workspaceId: target.workspace.id, projectId: target.project.id };
+            try {
+                result.matches.push({ ...target, lookup: await lookupUser(scope, selector) });
+            }
+            catch (error) {
+                const code = error instanceof TrpcApiError ? error.code : null;
+                if (code === 'NOT_FOUND')
+                    continue;
+                result.skipped.push(code === 'FORBIDDEN'
+                    ? { ...target, reason: 'not-admin' }
+                    : { ...target, reason: 'failed', detail: error instanceof Error ? error.message : String(error) });
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(input.concurrency ?? 4, input.projects.length) }, worker));
+    const order = new Map(input.projects.map((target, index) => [target.project.id, index]));
+    const byInput = (a, b) => (order.get(a.project.id) ?? 0) - (order.get(b.project.id) ?? 0);
+    result.matches.sort(byInput);
+    result.skipped.sort(byInput);
+    return result;
+};
+export const formatUserFind = (found) => {
+    const lines = [`Environment\t${found.environment}`, `Searched\t${found.searchedProjects} projects`, `Found in\t${found.matches.length} projects`];
+    for (const match of found.matches) {
+        lines.push('', `== ${match.project.name} (${match.project.slug})\tworkspace ${match.workspace.name}`, ...formatUserLookup(match.lookup).slice(1));
+    }
+    const notAdmin = [...new Set(found.skipped.filter((skip) => skip.reason === 'not-admin').map((skip) => skip.workspace.name))];
+    const failed = found.skipped.filter((skip) => skip.reason === 'failed');
+    if (notAdmin.length || failed.length)
+        lines.push('');
+    if (notAdmin.length)
+        lines.push(`Not searched (not a workspace admin)\t${notAdmin.join(', ')}`);
+    for (const skip of failed)
+        lines.push(`Failed\t${skip.project.name} (${skip.project.slug})\t${skip.detail ?? ''}`);
+    if (failed.length)
+        lines.push('Incomplete: some projects did not answer; the user may also be in those projects.');
+    return lines;
+};
 /** Payments the refund would touch, in the order requested; unknown IDs are reported, not dropped. */
 export const previewRefund = (lookup, paymentIds) => paymentIds.map((paymentId) => {
     const payment = lookup.payments.find((candidate) => candidate.paymentId === paymentId);
     return payment
         ? { paymentId, provider: payment.provider, amountMinor: payment.amountMinor - payment.refundedMinor, currency: payment.currency, refundable: payment.refundable, reason: payment.notRefundableReason }
-        : { paymentId, provider: null, amountMinor: 0, currency: null, refundable: false, reason: 'Not found in customers lookup' };
+        : { paymentId, provider: null, amountMinor: 0, currency: null, refundable: false, reason: 'Not found in users lookup' };
 });
 export const formatRefundPreview = (preview) => preview.map((row) => [
     row.paymentId, row.refundable ? `would refund ${formatMinor(row.amountMinor, row.currency)}` : `skip: ${row.reason}`,
 ].join('\t'));
 const day = (value) => value?.slice(0, 10) ?? '';
-export const formatCustomerLookup = (lookup) => {
+export const formatUserLookup = (lookup) => {
     const lines = [`Environment\t${lookup.environment}`];
     for (const user of lookup.users)
         lines.push(`User\t${user.userId ?? ''}\t${user.email ?? ''}\tfunnel user ${user.funnelUserId}\tcreated ${day(user.createdAt)}`);
@@ -59,11 +104,11 @@ export const formatCustomerLookup = (lookup) => {
     }
     return lines;
 };
-export const formatCustomerRefunds = (refunds) => refunds.map((refund) => [
+export const formatUserRefunds = (refunds) => refunds.map((refund) => [
     refund.paymentId, refund.outcome.replace('_', ' '),
     refund.error ?? formatMinor(refund.amountMinor, refund.currency), refund.refundIds.join(','),
 ].join('\t'));
-export const formatCustomerCancellation = (result) => [
+export const formatUserCancellation = (result) => [
     `Subscription\t${result.subscriptionId} (${result.provider})`,
     `Status\t${result.status}${result.cancelAtPeriodEnd ? ', cancels at period end' : ''}`,
     `Access until\t${result.accessUntil ?? ''} (was ${result.accessUntilBefore ?? 'unknown'})`,

package/funnel-contract-compatibility.json

@@ -4,10 +4,10 @@
   "minimumCliVersion": "0.1.20",
   "entries": [
     {
-      "repositoryCliVersion": "0.1.315",
+      "repositoryCliVersion": "0.1.316",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.308",
+        "bundleVersion": "2.0.309",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -45,7 +45,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "c2b60e841dc59ee11dcfb6483b6b86433def59eb63019c4628a8f6e180a61a09"
+            "sha256": "ec9f9ffa1b9ba4d91ea391ad22f8aacabcc959172ec49c5e1cd7ecd57b233c02"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -145,16 +145,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "98d0552496075be689cd94d7f9ccd48db77d82e693da77ec2f922cf678607ee9"
+            "sha256": "a659665cdead3841cf23888bd46447b58f7c0c9eb6baff917f7235ac9b8d5d57"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.314",
+      "repositoryCliVersion": "0.1.315",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.307",
+        "bundleVersion": "2.0.308",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -192,7 +192,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "e3f9cd10ba6c481c4cc6a0477abb9729da10131ed0bd64994eeba13fa50041e7"
+            "sha256": "c2b60e841dc59ee11dcfb6483b6b86433def59eb63019c4628a8f6e180a61a09"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -292,16 +292,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "1edc6ee4d8cd0146d5a3d42f8e411015f8c3147117232fb2f80a1169b672b7a0"
+            "sha256": "98d0552496075be689cd94d7f9ccd48db77d82e693da77ec2f922cf678607ee9"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.313",
+      "repositoryCliVersion": "0.1.314",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.306",
+        "bundleVersion": "2.0.307",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -339,7 +339,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "4d9fa0b4846945524ec6d45562a8ee7cc48c64ce8f73510024445106db9e26ce"
+            "sha256": "e3f9cd10ba6c481c4cc6a0477abb9729da10131ed0bd64994eeba13fa50041e7"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -439,16 +439,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "61802de19c7144122977a735d98141b175d04e7880fa342e35a80bda6dfe966f"
+            "sha256": "1edc6ee4d8cd0146d5a3d42f8e411015f8c3147117232fb2f80a1169b672b7a0"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.312",
+      "repositoryCliVersion": "0.1.313",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.305",
+        "bundleVersion": "2.0.306",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -486,7 +486,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "2d1f917a42f99071709e3849d66d5434291bf899798cbb1c0094791cbedd8d96"
+            "sha256": "4d9fa0b4846945524ec6d45562a8ee7cc48c64ce8f73510024445106db9e26ce"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -586,16 +586,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "d9d21cbd6ecd576f37222e4f5c75808683709410452c34f2779d56b1d44fe445"
+            "sha256": "61802de19c7144122977a735d98141b175d04e7880fa342e35a80bda6dfe966f"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.311",
+      "repositoryCliVersion": "0.1.312",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.304",
+        "bundleVersion": "2.0.305",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -633,7 +633,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "95f7f9c522a98f16c42214f93747dc49d8f86b56ef5f56b202e29c7a2725d0f7"
+            "sha256": "2d1f917a42f99071709e3849d66d5434291bf899798cbb1c0094791cbedd8d96"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -733,16 +733,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "7677b66b8377a90463e559ce5817818e8ab396c0f4192882bc77f2792ab8db47"
+            "sha256": "d9d21cbd6ecd576f37222e4f5c75808683709410452c34f2779d56b1d44fe445"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.310",
+      "repositoryCliVersion": "0.1.311",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.303",
+        "bundleVersion": "2.0.304",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -780,7 +780,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "dfaf7e01284c3fed5334218cb24a3497acfb8a7a5dbc03a232d5f8a7ac468d6a"
+            "sha256": "95f7f9c522a98f16c42214f93747dc49d8f86b56ef5f56b202e29c7a2725d0f7"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -880,16 +880,16 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "4aae4fd505bfbfc8338354969920a08a46f64e0b1e843bdb20c9462d1327eef0"
+            "sha256": "7677b66b8377a90463e559ce5817818e8ab396c0f4192882bc77f2792ab8db47"
           }
         ]
       }
     },
     {
-      "repositoryCliVersion": "0.1.309",
+      "repositoryCliVersion": "0.1.310",
       "manifest": {
         "schemaVersion": 1,
-        "bundleVersion": "2.0.302",
+        "bundleVersion": "2.0.303",
         "stepContractVersion": 3,
         "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
         "managedFiles": [
@@ -927,7 +927,7 @@
           },
           {
             "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-            "sha256": "72d337fa007993d18455f281b9a784e2e15fb46e43038a2934ddfcc82d8c1d28"
+            "sha256": "dfaf7e01284c3fed5334218cb24a3497acfb8a7a5dbc03a232d5f8a7ac468d6a"
           },
           {
             "path": "docs/funnelsgrove/qa/analytics.md",
@@ -1027,7 +1027,7 @@
           },
           {
             "path": "funnel-docs.config.json",
-            "sha256": "e381723d48a0772419a5f8d757de1bb8fc9d7b3fd7838ad6fcde8ce0031d77c3"
+            "sha256": "4aae4fd505bfbfc8338354969920a08a46f64e0b1e843bdb20c9462d1327eef0"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.315",
+  "version": "0.1.316",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "repository": {
     "type": "git",

package/template_docs/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.308",
+  "bundleVersion": "2.0.309",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "c2b60e841dc59ee11dcfb6483b6b86433def59eb63019c4628a8f6e180a61a09"
+      "sha256": "ec9f9ffa1b9ba4d91ea391ad22f8aacabcc959172ec49c5e1cd7ecd57b233c02"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "98d0552496075be689cd94d7f9ccd48db77d82e693da77ec2f922cf678607ee9"
+      "sha256": "a659665cdead3841cf23888bd46447b58f7c0c9eb6baff917f7235ac9b8d5d57"
     }
   ]
 }

package/template_docs/docs/funnelsgrove/migrations/step-contract-v3.md

@@ -17,7 +17,7 @@ Supported read versions: `1`, `2`, `3`. Authoring and publish target version `3`
 
 ### Package release order
 
-Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.40.0`, then `@funnelsgrove/analytics` `0.23.0`, then `@funnelsgrove/payments` `0.57.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.315`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.40.0`, then `@funnelsgrove/analytics` `0.23.0`, then `@funnelsgrove/payments` `0.57.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.316`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
 <!-- funnelsgrove:generated:end contract-v3/migration/step-contract-v3 -->
 
 ## Version-last policy

package/template_docs/funnel-docs.config.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.308",
+  "bundleVersion": "2.0.309",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",

package/template_scaffold/.funnelsgrove-docs.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.308",
+  "bundleVersion": "2.0.309",
   "stepContractVersion": 3,
   "contractHash": "d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf",
   "managedFiles": [
@@ -38,7 +38,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "c2b60e841dc59ee11dcfb6483b6b86433def59eb63019c4628a8f6e180a61a09"
+      "sha256": "ec9f9ffa1b9ba4d91ea391ad22f8aacabcc959172ec49c5e1cd7ecd57b233c02"
     },
     {
       "path": "docs/funnelsgrove/qa/analytics.md",
@@ -138,7 +138,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "98d0552496075be689cd94d7f9ccd48db77d82e693da77ec2f922cf678607ee9"
+      "sha256": "a659665cdead3841cf23888bd46447b58f7c0c9eb6baff917f7235ac9b8d5d57"
     }
   ]
 }

package/template_scaffold/.funnelsgrove-scaffold.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
-  "sourceTreeHash": "578a4547e6d4d1d2127ba60ac824357712a86000f62c318d12db63725e7d78ba",
+  "sourceTreeHash": "0f06f46537d05d2af0ced343de96a011b4be326217de99d5f566ef90a1acea72",
   "stepContractVersion": 3,
-  "docsBundleVersion": "2.0.308",
+  "docsBundleVersion": "2.0.309",
   "files": [
     {
       "path": ".env.example",
@@ -16,7 +16,7 @@
     },
     {
       "path": ".funnelsgrove-docs.json",
-      "sha256": "a046775aa77fb7400960fbe3a4055f8dd3968c9edf8b9617344e4964f7dc5ecb",
+      "sha256": "5cdb7695c1f8627755689377bc15b3a33bf15cd254a0a590f58a83136b5498d3",
       "mode": "100644"
     },
     {
@@ -76,7 +76,7 @@
     },
     {
       "path": "docs/funnelsgrove/migrations/step-contract-v3.md",
-      "sha256": "c2b60e841dc59ee11dcfb6483b6b86433def59eb63019c4628a8f6e180a61a09",
+      "sha256": "ec9f9ffa1b9ba4d91ea391ad22f8aacabcc959172ec49c5e1cd7ecd57b233c02",
       "mode": "100644"
     },
     {
@@ -206,7 +206,7 @@
     },
     {
       "path": "funnel-docs.config.json",
-      "sha256": "98d0552496075be689cd94d7f9ccd48db77d82e693da77ec2f922cf678607ee9",
+      "sha256": "a659665cdead3841cf23888bd46447b58f7c0c9eb6baff917f7235ac9b8d5d57",
       "mode": "100644"
     },
     {

package/template_scaffold/docs/funnelsgrove/migrations/step-contract-v3.md

@@ -17,7 +17,7 @@ Supported read versions: `1`, `2`, `3`. Authoring and publish target version `3`
 
 ### Package release order
 
-Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.40.0`, then `@funnelsgrove/analytics` `0.23.0`, then `@funnelsgrove/payments` `0.57.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.315`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
+Release `@funnelsgrove/sdk` `0.4.0` first, then `@funnelsgrove/runtime` `0.40.0`, then `@funnelsgrove/analytics` `0.23.0`, then `@funnelsgrove/payments` `0.57.0`. The production deploy verifies the zero-traffic API candidate, publishes and verifies `@funnelsgrove/cli` `0.1.316`, and only then promotes the candidate to production traffic. The serving API must never advertise an unpublished preferred CLI. Publishing packages and deploying production remain separately approved operational actions.
 <!-- funnelsgrove:generated:end contract-v3/migration/step-contract-v3 -->
 
 ## Version-last policy

package/template_scaffold/funnel-docs.config.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "bundleVersion": "2.0.308",
+  "bundleVersion": "2.0.309",
   "contractSource": "funnelsgrove-repository://apps/funnel-runtime/contracts/step-contract-v2.json",
   "fullyGenerated": [
     ".funnelsgrove-docs.json",