@funnelsgrove/cli 0.1.7 → 0.1.9

package/README.md

@@ -7,24 +7,25 @@ npm install -g @funnelsgrove/cli
 fgrove login
 ```
 
-Set the active project and funnel:
+Sync a funnel into its own local folder:
 
 ```bash
-fgrove use --project claimbee --funnel claimbee-ios
-fgrove status
+fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios
+cd ./claimbee-ios
 ```
 
 Common workflow:
 
 ```bash
-fgrove sync down --dir ./claimbee-ios
-cd ./claimbee-ios
+fgrove status
 fgrove docs
 fgrove sync up --message 'Update funnel copy'
 fgrove publish --env preview
 ```
 
-Use `fgrove env pull --dir <local-dir>` to refresh only the ignored local `.env` file after project settings change, without replacing source files.
+Inside a synced folder, `fgrove` reads `.funnelsgrove-sync.json` first, so you do not need to run `fgrove use` when switching between local funnel directories. Use `fgrove use` only when you want a global fallback context for commands outside a synced folder.
+
+Use `fgrove env pull` from a synced folder to refresh only the ignored local `.env` file after project settings change, without replacing source files.
 
 GitHub sync workflow:
 

package/dist/cli.d.ts

@@ -1,2 +1,15 @@
 #!/usr/bin/env node
+import { type ActiveContext } from './authStore.js';
+import { type SyncManifest } from './localSync.js';
+type SyncTargetIdInput = {
+    explicitWorkspaceId?: string;
+    explicitFunnelId?: string;
+    manifest?: Pick<SyncManifest, 'workspaceId' | 'funnelId'> | null;
+    active?: Pick<ActiveContext, 'workspaceId' | 'funnelId'> | null;
+    defaultWorkspaceId?: string;
+};
+export declare function resolveSyncTargetIds(input: SyncTargetIdInput): {
+    workspaceId: string;
+    funnelId?: string;
+};
 export {};

package/dist/cli.js

@@ -35,6 +35,21 @@ const resolveTemplatePath = (slug) => path.resolve(__dirname, '..', '..', '..',
 const resolveTemplateDocsPath = () => path.resolve(__dirname, '..', TEMPLATE_DOCS_DIR);
 const DEFAULT_API_URL = 'https://api.funnelsgrove.com/trpc';
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PUBLISH_POLL_INTERVAL_MS = 2_000;
+const PUBLISH_WAIT_TIMEOUT_MS = 30 * 60_000;
+export function resolveSyncTargetIds(input) {
+    const workspaceId = input.explicitWorkspaceId ||
+        input.manifest?.workspaceId ||
+        input.active?.workspaceId ||
+        input.defaultWorkspaceId;
+    if (!workspaceId) {
+        throw new Error('No workspace found for this account.');
+    }
+    return {
+        workspaceId,
+        funnelId: input.explicitFunnelId || input.manifest?.funnelId || input.active?.funnelId,
+    };
+}
 const getApiUrl = () => {
     const options = program.opts();
     return options.apiUrl || process.env.FUNNELSGROVE_API_URL || DEFAULT_API_URL;
@@ -59,6 +74,40 @@ const callApi = async (input) => {
         token: input.token,
     });
 };
+const sleep = async (ms) => {
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+};
+const isTerminalDeploymentState = (state) => {
+    return ['ready', 'failed', 'expired', 'canceled'].includes(state.trim().toLowerCase());
+};
+const waitForPublishDeployment = async (input) => {
+    const deadline = Date.now() + PUBLISH_WAIT_TIMEOUT_MS;
+    while (Date.now() <= deadline) {
+        const detail = await callApi({
+            path: 'funnels.detail',
+            type: 'query',
+            token: input.token,
+            data: {
+                workspaceId: input.workspaceId,
+                funnelId: input.funnelId,
+            },
+        });
+        const deployment = detail.deployments.find((item) => item.id === input.deploymentId);
+        if (deployment && isTerminalDeploymentState(deployment.state)) {
+            if (deployment.state === 'failed') {
+                throw new Error(deployment.qa_summary || 'Publish deployment failed.');
+            }
+            if (deployment.state === 'expired' || deployment.state === 'canceled') {
+                throw new Error(`Publish deployment ${deployment.state}.`);
+            }
+            return deployment;
+        }
+        await sleep(PUBLISH_POLL_INTERVAL_MS);
+    }
+    throw new Error(`Timed out waiting for publish deployment ${input.deploymentId}.`);
+};
 const readCodeFromStdin = async () => {
     const rl = createInterface({
         input: process.stdin,
@@ -182,18 +231,24 @@ const resolveSyncTarget = async (input) => {
     const sourceDir = path.resolve(process.cwd(), input.dir || '.');
     const manifest = await readSyncManifest(sourceDir);
     const active = await loadActiveContext(getConfigPath());
-    const workspaceId = input.workspace
-        ? await resolveWorkspaceId(input.token, input.workspace)
-        : manifest?.workspaceId || active?.workspaceId || await resolveWorkspaceId(input.token);
-    const funnelId = input.funnel
-        ? await resolveFunnelId(input.token, workspaceId, input.funnel)
-        : manifest?.funnelId || active?.funnelId;
-    if (!funnelId) {
-        throw new Error('No active funnel. Run `fgrove use --funnel <id-or-slug>` or pass `--funnel`.');
+    const explicitWorkspaceId = input.workspace ? await resolveWorkspaceId(input.token, input.workspace) : undefined;
+    const fallbackWorkspaceId = explicitWorkspaceId || manifest?.workspaceId || active?.workspaceId || await resolveWorkspaceId(input.token);
+    const explicitFunnelId = input.funnel
+        ? await resolveFunnelId(input.token, fallbackWorkspaceId, input.funnel)
+        : undefined;
+    const resolved = resolveSyncTargetIds({
+        explicitWorkspaceId,
+        explicitFunnelId,
+        manifest,
+        active,
+        defaultWorkspaceId: fallbackWorkspaceId,
+    });
+    if (!resolved.funnelId) {
+        throw new Error('No synced funnel found. Run from a synced funnel directory, pass `--funnel`, or set a fallback with `fgrove use --funnel <id-or-slug>`.');
     }
     return {
-        workspaceId,
-        funnelId,
+        workspaceId: resolved.workspaceId,
+        funnelId: resolved.funnelId,
         sourceDir,
         manifest,
     };
@@ -241,8 +296,8 @@ program
     .option('--config <path>', 'Auth config path', process.env.FUNNELSGROVE_CONFIG || getDefaultAuthConfigPath());
 addExamples(program, [
     'fgrove login',
-    'fgrove use --project claimbee --funnel claimbee-ios',
-    'fgrove sync down --dir ./claimbee-ios',
+    'fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios',
+    'cd ./claimbee-ios && fgrove status',
     'fgrove publish --env preview',
 ]);
 addExamples(program
@@ -336,9 +391,9 @@ addExamples(program
     console.log(`user\t${me.user.email || me.user.id}`);
     console.log(`api\t${getApiUrl()}`);
     console.log(`config\t${getConfigPath()}`);
-    console.log(`workspace\t${active?.workspaceName || active?.workspaceSlug || active?.workspaceId || me.workspace?.name || 'Not set'}`);
-    console.log(`project\t${active?.projectName || active?.projectSlug || active?.projectId || 'Not set'}`);
-    console.log(`funnel\t${active?.funnelName || active?.funnelSlug || active?.funnelId || 'Not set'}`);
+    console.log(`workspace\t${manifest?.workspaceId || active?.workspaceName || active?.workspaceSlug || active?.workspaceId || me.workspace?.name || 'Not set'}`);
+    console.log(`project\t${manifest ? 'Not set' : active?.projectName || active?.projectSlug || active?.projectId || 'Not set'}`);
+    console.log(`funnel\t${manifest?.funnelId || active?.funnelName || active?.funnelSlug || active?.funnelId || 'Not set'}`);
     if (manifest) {
         console.log(`localWorkspace\t${manifest.workspaceId}`);
         console.log(`localFunnel\t${manifest.funnelId}`);
@@ -405,7 +460,7 @@ addExamples(funnelsCommand
     console.log(`${result.funnel.id}\t${result.funnel.name}\t${result.funnel.slug}`);
 });
 const syncCommand = addExamples(program.command('sync').description('Sync funnel source'), [
-    'fgrove sync down --dir ./claimbee-ios',
+    'fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios',
     'fgrove sync up --message "Update copy"',
 ]);
 addExamples(syncCommand
@@ -414,7 +469,6 @@ addExamples(syncCommand
     .option('--workspace <id-or-slug-or-name>', 'Workspace id, slug, or name')
     .option('--funnel <id-or-slug>', 'Funnel id or slug')
     .requiredOption('--dir <path>', 'Local target directory'), [
-    'fgrove sync down --dir ./claimbee-ios',
     'fgrove sync down --funnel claimbee-ios --dir ./claimbee-ios',
 ])
     .action(async (options) => {
@@ -608,7 +662,13 @@ addExamples(program
             domains: publishEnv === 'production' && options.domain ? [options.domain] : undefined,
         },
     });
-    console.log(`${result.deploymentUrl}\tv${result.publishedVersionSeq}\t${result.publishedVersionId}`);
+    const readyDeployment = await waitForPublishDeployment({
+        token,
+        workspaceId: target.workspaceId,
+        funnelId: target.funnelId,
+        deploymentId: result.deploymentId,
+    });
+    console.log(`${readyDeployment.deployment_url || result.deploymentUrl}\tv${result.publishedVersionSeq}\t${result.publishedVersionId}`);
 });
 const githubCommand = addExamples(program.command('github').description('Manage GitHub funnel sync'), [
     'fgrove github status --funnel claimbee-general',
@@ -785,7 +845,9 @@ addExamples(program
     console.log('  npm install');
     console.log('  npm run dev');
 });
-program.parseAsync().catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
-});
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    program.parseAsync().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelsgrove/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "FunnelsGrove command-line tools for editing, syncing, and publishing funnels",
   "type": "module",
   "bin": {

package/template_docs/docs/editing-flow.md

@@ -7,7 +7,9 @@ Flow is product logic. The source of truth is `src/config/funnel.manifest.ts`; r
 The manifest defines:
 
 - `viewport`: the designed shell size, usually `430 x 932`.
-- `assets`: preloaded image metadata used by runtime/build tooling.
+- `assets`: image metadata used by runtime/build tooling. Funnel shells may use
+  this data to warm likely next-step images, but first-viewport images should
+  still use the framework's normal priority/preload mechanism.
 - `steps`: every routable step with `id`, `path`, `filePath`, `componentKey`, `type`, optional `kind`, and optional `assetIds`.
 - `edgesByStepId`: graph edges between steps.
 - `experiments`: optional variant routing.

package/template_docs/docs/payment-plans-and-discounts.md

@@ -48,12 +48,16 @@ Runtime config should come from `runtimePublicConfig` through a local `src/runti
 
 Subscription paywalls with on-page wallet buttons should share one `useStripeSubscriptionCheckoutSession(...)` instance across the manual card checkout and wallet checkout. Do not build funnel-local Stripe PaymentIntent or Express Checkout flows.
 
+- Keep funnel-specific checkout orchestration local when it includes product layout, analytics callbacks, return URL branching, or email prompt copy. The shared UI boundary is `SharedStripeCheckoutV2Dialog`; do not add another shared wrapper that duplicates a funnel's paywall composition.
 - Use `SharedStripeCheckoutV2Dialog` for the manual/card checkout modal. Open it from the paywall CTA after the checkout session has an `activeClientSecret` and `stripePromise`.
 - Render real wallet slots on the paywall with `ApplePaySubscriptionCheckoutSlot` and `GooglePaySubscriptionCheckoutSlot`, usually above the manual/card CTA. Pass the same checkout session, selected plan amount, return URL, customer details, summary label, success handler, and any `beforeConfirm` logic used to finalize email or analytics metadata.
 - Use `usePlatformWalletPaymentMethods()` to decide which slots to render. Desktop web can show Apple Pay and Google Pay; iOS shows Apple Pay; Android shows Google Pay.
 - Track each slot's `onAvailabilityChange` result by the current `checkoutSession.intentKey`. When opening `SharedStripeCheckoutV2Dialog`, derive `initialWalletAvailable` from the current intent's confirmed wallet availability and pass it into the dialog so checkout can show the wallet tab immediately when a wallet is already known to be available.
 - Treat unknown wallet availability as `null`, not `false`. Only hide/fallback from a wallet after Stripe or the shared slot reports that wallet unavailable.
+- Treat Checkout Session/API preparation failures as retryable checkout failures, not wallet unavailability. A failed `prepareWalletCheckout()` should leave the wallet slot in unknown availability and show the real clickable fallback placeholder after loading stops; only Stripe readiness/availability reports should mark a wallet unavailable.
 - Suspend paywall wallet slots while the shared checkout dialog or another blocking offer modal is open, so two Stripe Express Checkout elements do not compete for the same active checkout session.
+- If checkout starts without a known customer email, first try to resolve it from a known `user_id` or `stripe_customer_id`. Only show an email prompt when there is no known identity to fetch from, or that lookup returns no email.
+- Before publishing payment changes, run the shared wallet smoke helper from `@funnelsgrove/payments` against local and preview paywall URLs. The package script is `npm run smoke:wallet --workspace @funnelsgrove/payments -- --url <paywall-url>` and accepts selector overrides through CLI flags or `WALLET_SMOKE_*` env vars.
 
 ## Paywall Identity Handoff
 

package/template_docs/docs/sdk-api-endpoints.md

@@ -50,6 +50,8 @@ Always pass runtime checkout config so published funnels, preview funnels, and l
 
 Checkout endpoints receive `user_id` and `customerEmail` when available. Stripe metadata and `client_reference_id` rely on these values for webhook reconciliation, analytics, and project user support links.
 
+When a funnel sends a configured Stripe `providerPlanId`, public checkout APIs validate that price id against Stripe and fail with a client-visible error if it is missing. Do not silently replace configured price ids with generated `price_data`; dynamic price fallback is only for legacy/catalog entries that have no provider price id.
+
 ## Subscription APIs
 
 Use the runtime service methods instead of calling the endpoints directly: