@funnelsgrove/cli 0.1.14 → 0.1.18

package/template_scaffold/src/contract/golden/social_proof.fixture.ts

@@ -0,0 +1,27 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'member-results',
+  name: 'member-results',
+  path: '/member-results',
+  filePath: 'src/steps/step-member-results.tsx',
+  componentKey: 'stepMemberResults',
+  type: 'social_proof',
+  title: 'Member results',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'member-results',
+  name: 'member-results',
+  type: 'social_proof',
+  figmaNodeId: 'golden:social-proof',
+  title: 'Member results',
+  description: 'Show attributable testimonials and evidence.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'social_proof',
+  manifestStep,
+  componentMeta,
+  actionOwner: 'shared-shell',
+} as const;

package/template_scaffold/src/contract/golden/subscription_handoff.fixture.ts

@@ -0,0 +1,30 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'open-app',
+  name: 'open-app',
+  path: '/open-app',
+  filePath: 'src/steps/step-open-app.tsx',
+  componentKey: 'stepOpenApp',
+  type: 'subscription_handoff',
+  kind: 'subscription-handoff',
+  title: 'Continue in the app',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'open-app',
+  name: 'open-app',
+  type: 'subscription_handoff',
+  kind: 'subscription-handoff',
+  figmaNodeId: 'golden:subscription-handoff',
+  title: 'Continue in the app',
+  description: 'Continue through a non-terminal app handoff.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'subscription_handoff',
+  manifestStep,
+  componentMeta,
+  helper: 'runtime handoff helper',
+  isRegistrationCompletion: false,
+} as const;

package/template_scaffold/src/contract/golden/subscription_management.fixture.ts

@@ -0,0 +1,29 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'manage-subscription',
+  name: 'manage-subscription',
+  path: '/manage-subscription',
+  filePath: 'src/steps/step-manage-subscription.tsx',
+  componentKey: 'stepManageSubscription',
+  type: 'subscription_management',
+  kind: 'manage-subscription',
+  title: 'Manage subscription',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'manage-subscription',
+  name: 'manage-subscription',
+  type: 'subscription_management',
+  kind: 'manage-subscription',
+  figmaNodeId: 'golden:subscription-management',
+  title: 'Manage subscription',
+  description: 'Inspect and manage an existing subscription.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'subscription_management',
+  manifestStep,
+  componentMeta,
+  helper: 'runtime subscription helpers',
+} as const;

package/template_scaffold/src/contract/golden/summary_confirmation.fixture.ts

@@ -0,0 +1,27 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'review-plan',
+  name: 'review-plan',
+  path: '/review-plan',
+  filePath: 'src/steps/step-review-plan.tsx',
+  componentKey: 'stepReviewPlan',
+  type: 'summary_confirmation',
+  title: 'Review your plan',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'review-plan',
+  name: 'review-plan',
+  type: 'summary_confirmation',
+  figmaNodeId: 'golden:summary-confirmation',
+  title: 'Review your plan',
+  description: 'Review existing answers before continuing.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'summary_confirmation',
+  manifestStep,
+  componentMeta,
+  actionOwner: 'either',
+} as const;

package/template_scaffold/src/contract/golden/upsell_offer.fixture.ts

@@ -0,0 +1,29 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'premium-upgrade',
+  name: 'premium-upgrade',
+  path: '/premium-upgrade',
+  filePath: 'src/steps/step-premium-upgrade.tsx',
+  componentKey: 'stepPremiumUpgrade',
+  type: 'upsell_offer',
+  kind: 'upsell',
+  title: 'Add premium support',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'premium-upgrade',
+  name: 'premium-upgrade',
+  type: 'upsell_offer',
+  kind: 'upsell',
+  figmaNodeId: 'golden:upsell-offer',
+  title: 'Add premium support',
+  description: 'Offer an optional post-purchase upgrade.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'upsell_offer',
+  manifestStep,
+  componentMeta,
+  semanticHelpers: ['trackCheckoutStarted', 'trackPaymentInfoSubmitted', 'trackCheckoutCompleted'],
+} as const;

package/template_scaffold/src/contract/golden/value_prop_story.fixture.ts

@@ -0,0 +1,27 @@
+import type { FunnelManifestStep, FunnelStepMeta } from '@funnelsgrove/runtime';
+
+const manifestStep = {
+  id: 'your-plan',
+  name: 'your-plan',
+  path: '/your-plan',
+  filePath: 'src/steps/step-your-plan.tsx',
+  componentKey: 'stepYourPlan',
+  type: 'value_prop_story',
+  title: 'Your plan',
+} as const satisfies FunnelManifestStep;
+
+const componentMeta = {
+  id: 'your-plan',
+  name: 'your-plan',
+  type: 'value_prop_story',
+  figmaNodeId: 'golden:value-prop-story',
+  title: 'Your plan',
+  description: 'Narrative explanation of the product value.',
+} as const satisfies FunnelStepMeta;
+
+export const goldenFixture = {
+  stepType: 'value_prop_story',
+  manifestStep,
+  componentMeta,
+  actionOwner: 'shared-shell',
+} as const;

package/template_scaffold/src/contract/validate-funnel.cli.test.ts

@@ -0,0 +1,180 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  createFunnelContractDiagnostic,
+  CURRENT_STEP_CONTRACT_VERSION,
+  type FunnelContractDiagnostic,
+} from '@funnelsgrove/runtime';
+
+const execFileAsync = promisify(execFile);
+
+const loadCli = async () => {
+  return import('./validate-funnel.cli');
+};
+
+const diagnostic = createFunnelContractDiagnostic({
+  code: 'FG-PARITY-001',
+  file: 'src/steps/example.tsx',
+  stepId: 'example',
+  expected: { name: 'example' },
+  received: { name: 'renamed-example' },
+  reason: 'Manifest and component metadata differ.',
+  guide: 'docs/funnelsgrove/contracts/step-metadata.md',
+  repair: 'Restore exact metadata parity.',
+});
+
+type RunResult = {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+};
+
+const runWith = async (
+  diagnostics: readonly FunnelContractDiagnostic[],
+): Promise<RunResult> => {
+  const cli = await loadCli();
+  let stdout = '';
+  let stderr = '';
+  const exitCode = await cli.runValidateFunnelCli({
+    args: ['--json'],
+    loadValidation: async () => ({
+      contractVersion: cli.VALIDATOR_CONTRACT_VERSION,
+      diagnostics,
+    }),
+    writeStdout: (text: string) => {
+      stdout += text;
+    },
+    writeStderr: (text: string) => {
+      stderr += text;
+    },
+  });
+  return { exitCode, stdout, stderr };
+};
+
+describe('validate funnel CLI protocol', () => {
+  it('writes exactly one JSON object and exits zero for a valid project', async () => {
+    const result = await runWith([]);
+
+    expect(result).toEqual({
+      exitCode: 0,
+      stdout: `${JSON.stringify({
+        schemaVersion: 1,
+        contractVersion: CURRENT_STEP_CONTRACT_VERSION,
+        valid: true,
+        diagnostics: [],
+      })}\n`,
+      stderr: '',
+    });
+    expect(result.stdout.trim().split('\n')).toHaveLength(1);
+  });
+
+  it('preserves blocker diagnostics exactly and renders human detail to stderr', async () => {
+    const result = await runWith([diagnostic]);
+
+    expect(result.exitCode).toBe(1);
+    expect(JSON.parse(result.stdout)).toEqual({
+      schemaVersion: 1,
+      contractVersion: CURRENT_STEP_CONTRACT_VERSION,
+      valid: false,
+      diagnostics: [diagnostic],
+    });
+    expect(result.stderr).toContain('[FG-PARITY-001]');
+    expect(result.stderr).toContain('Manifest and component metadata differ.');
+    expect(result.stderr).toContain('src/steps/example.tsx');
+  });
+
+  it('keeps import log noise off stdout and maps malformed imports to exit two', async () => {
+    const cli = await loadCli();
+    let stdout = '';
+    let stderr = '';
+    const exitCode = await cli.runValidateFunnelCli({
+      args: ['--json'],
+      loadValidation: async () => {
+        process.stdout.write('project import noise\n');
+        throw new Error('malformed project import');
+      },
+      writeStdout: (text: string) => {
+        stdout += text;
+      },
+      writeStderr: (text: string) => {
+        stderr += text;
+      },
+    });
+
+    expect(exitCode).toBe(2);
+    expect(stdout).not.toContain('project import noise');
+    expect(stdout.trim().split('\n')).toHaveLength(1);
+    expect(JSON.parse(stdout)).toMatchObject({
+      schemaVersion: 1,
+      contractVersion: CURRENT_STEP_CONTRACT_VERSION,
+      valid: false,
+      diagnostics: [{
+        code: 'FG-CLIENT-001',
+        severity: 'error',
+      }],
+    });
+    expect(stderr).toContain('project import noise');
+    expect(stderr).toContain('malformed project import');
+  });
+
+  it('rejects unsupported arguments as a protocol error without running imports', async () => {
+    const cli = await loadCli();
+    let loaded = false;
+    let stdout = '';
+    let stderr = '';
+    const exitCode = await cli.runValidateFunnelCli({
+      args: ['--json', '--unknown'],
+      loadValidation: async () => {
+        loaded = true;
+        return { contractVersion: CURRENT_STEP_CONTRACT_VERSION, diagnostics: [] };
+      },
+      writeStdout: (text: string) => {
+        stdout += text;
+      },
+      writeStderr: (text: string) => {
+        stderr += text;
+      },
+    });
+
+    expect(exitCode).toBe(2);
+    expect(loaded).toBe(false);
+    expect(JSON.parse(stdout)).toMatchObject({
+      schemaVersion: 1,
+      contractVersion: CURRENT_STEP_CONTRACT_VERSION,
+      valid: false,
+    });
+    expect(stderr).toContain('Usage: validate-funnel.cli.ts [--json]');
+  });
+
+  it('runs through vite-node with one clean stdout protocol object', async () => {
+    const templateRoot = path.resolve(fileURLToPath(new URL('../..', import.meta.url)));
+    const viteNode = path.resolve(templateRoot, '../../node_modules/.bin/vite-node');
+    const script = path.resolve(templateRoot, 'src/contract/validate-funnel.cli.ts');
+
+    const result = await execFileAsync(viteNode, [
+      '--config',
+      'src/contract/funnel-validator.vite.config.ts',
+      script,
+      '--json',
+    ], {
+      cwd: templateRoot,
+      env: {
+        ...process.env,
+        VITE_CJS_IGNORE_WARNING: 'true',
+      },
+      timeout: 20_000,
+    });
+
+    expect(result.stderr).toBe('');
+    expect(result.stdout.trim().split('\n')).toHaveLength(1);
+    expect(JSON.parse(result.stdout)).toEqual({
+      schemaVersion: 1,
+      contractVersion: CURRENT_STEP_CONTRACT_VERSION,
+      valid: true,
+      diagnostics: [],
+    });
+  });
+});

package/template_scaffold/src/contract/validate-funnel.cli.ts

@@ -0,0 +1,199 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  CURRENT_STEP_CONTRACT_VERSION,
+  type FunnelContractDiagnostic,
+} from '@funnelsgrove/runtime';
+
+export const VALIDATOR_CONTRACT_VERSION = CURRENT_STEP_CONTRACT_VERSION;
+
+export type FunnelValidationProtocol = {
+  schemaVersion: 1;
+  contractVersion: number;
+  valid: boolean;
+  diagnostics: readonly FunnelContractDiagnostic[];
+};
+
+type LoadedValidation = {
+  contractVersion: number;
+  diagnostics: readonly FunnelContractDiagnostic[];
+};
+
+type TextWriter = (text: string) => void;
+
+export type RunValidateFunnelCliOptions = {
+  args?: readonly string[];
+  loadValidation?: () => Promise<LoadedValidation>;
+  writeStdout?: TextWriter;
+  writeStderr?: TextWriter;
+};
+
+export type FunnelValidationExitCode = 0 | 1 | 2;
+
+const internalDiagnostic = (): FunnelContractDiagnostic => ({
+  code: 'FG-CLIENT-001',
+  severity: 'error',
+  file: 'src/contract/validate-funnel.cli.ts',
+  stepId: null,
+  expected: 'loadable funnel project validation module',
+  received: 'internal validator failure',
+  reason: 'The funnel project validator could not load or run.',
+  guide: 'docs/funnelsgrove/qa/local.md',
+  repair: 'Fix project import errors, then rerun fgrove validate.',
+});
+
+const loadProjectValidation = async (): Promise<LoadedValidation> => {
+  const projectValidation = await import('./funnel-project.validation');
+  return {
+    contractVersion: projectValidation.FUNNEL_PROJECT_CONTRACT_VERSION,
+    diagnostics: projectValidation.validateFunnelProject(),
+  };
+};
+
+const describeUnknownError = (error: unknown): string => {
+  try {
+    if (error instanceof Error && error.message.trim()) {
+      return error.message;
+    }
+    return String(error);
+  } catch {
+    return 'unknown validator failure';
+  }
+};
+
+const renderValue = (value: unknown): string => {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return '[unserializable]';
+  }
+};
+
+const renderDiagnostic = (diagnostic: FunnelContractDiagnostic): string => {
+  const location = diagnostic.file
+    ? `${diagnostic.file}${diagnostic.stepId ? ` (${diagnostic.stepId})` : ''}`
+    : diagnostic.stepId ?? 'project';
+  return [
+    `[${diagnostic.code}] ${diagnostic.reason}`,
+    `  Location: ${location}`,
+    `  Expected: ${renderValue(diagnostic.expected)}`,
+    `  Received: ${renderValue(diagnostic.received)}`,
+    `  Repair: ${diagnostic.repair}`,
+    `  Guide: ${diagnostic.guide}`,
+  ].join('\n');
+};
+
+const invokeWithoutStdoutNoise = async <T>(
+  operation: () => Promise<T>,
+  writeStderr: TextWriter,
+): Promise<T> => {
+  const originalWrite = process.stdout.write;
+  let captured = '';
+  process.stdout.write = ((chunk: string | Uint8Array, ...args: unknown[]) => {
+    const encoding = typeof args[0] === 'string' ? args[0] as BufferEncoding : undefined;
+    captured += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString(encoding);
+    const callback = args.find((arg) => typeof arg === 'function');
+    if (typeof callback === 'function') {
+      callback();
+    }
+    return true;
+  }) as typeof process.stdout.write;
+
+  try {
+    return await operation();
+  } finally {
+    process.stdout.write = originalWrite;
+    if (captured) {
+      writeStderr(captured);
+      if (!captured.endsWith('\n')) {
+        writeStderr('\n');
+      }
+    }
+  }
+};
+
+const isLoadedValidation = (value: LoadedValidation): boolean => {
+  return value.contractVersion === VALIDATOR_CONTRACT_VERSION
+    && Array.isArray(value.diagnostics);
+};
+
+const emitProtocol = (
+  protocol: FunnelValidationProtocol,
+  writeStdout: TextWriter,
+): void => {
+  writeStdout(`${JSON.stringify(protocol)}\n`);
+};
+
+const protocolFor = (
+  diagnostics: readonly FunnelContractDiagnostic[],
+): FunnelValidationProtocol => ({
+  schemaVersion: 1,
+  contractVersion: VALIDATOR_CONTRACT_VERSION,
+  valid: diagnostics.length === 0,
+  diagnostics,
+});
+
+const usageError = (
+  json: boolean,
+  writeStdout: TextWriter,
+  writeStderr: TextWriter,
+): FunnelValidationExitCode => {
+  const diagnostic = internalDiagnostic();
+  writeStderr('Usage: validate-funnel.cli.ts [--json]\n');
+  if (json) {
+    emitProtocol(protocolFor([diagnostic]), writeStdout);
+  }
+  return 2;
+};
+
+export const runValidateFunnelCli = async (
+  options: RunValidateFunnelCliOptions = {},
+): Promise<FunnelValidationExitCode> => {
+  const args = options.args ?? process.argv.slice(2);
+  const writeStdout = options.writeStdout ?? ((text) => {
+    process.stdout.write(text);
+  });
+  const writeStderr = options.writeStderr ?? ((text) => {
+    process.stderr.write(text);
+  });
+  const json = args.includes('--json');
+  if (args.some((arg) => arg !== '--json') || args.filter((arg) => arg === '--json').length > 1) {
+    return usageError(json, writeStdout, writeStderr);
+  }
+
+  try {
+    const loaded = await invokeWithoutStdoutNoise(
+      options.loadValidation ?? loadProjectValidation,
+      writeStderr,
+    );
+    if (!isLoadedValidation(loaded)) {
+      throw new Error('The project validator returned an invalid protocol result.');
+    }
+
+    const protocol = protocolFor(loaded.diagnostics);
+    if (json) {
+      emitProtocol(protocol, writeStdout);
+    }
+    for (const diagnostic of loaded.diagnostics) {
+      writeStderr(`${renderDiagnostic(diagnostic)}\n`);
+    }
+    return protocol.valid ? 0 : 1;
+  } catch (error) {
+    const diagnostic = internalDiagnostic();
+    writeStderr(`Funnel validation failed internally: ${describeUnknownError(error)}\n`);
+    if (json) {
+      emitProtocol(protocolFor([diagnostic]), writeStdout);
+    }
+    return 2;
+  }
+};
+
+const isCliEntrypoint = (argv: readonly string[], modulePath: string): boolean => {
+  const resolvedModulePath = path.resolve(modulePath);
+  return path.basename(argv[1] ?? '') === 'vite-node'
+    || argv.slice(1).some((argument) => path.resolve(argument) === resolvedModulePath);
+};
+
+if (isCliEntrypoint(process.argv, fileURLToPath(import.meta.url))) {
+  process.exitCode = await runValidateFunnelCli();
+}

package/template_scaffold/src/runtime/checkout-runtime-config.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const ORIGINAL_ENV = { ...process.env };
+
+const resetClaimbeeCheckoutEnv = () => {
+  process.env = { ...ORIGINAL_ENV };
+  delete process.env.NEXT_PUBLIC_FUNNEL_PUBLISHABLE_KEY;
+  delete process.env.NEXT_PUBLIC_CLAIMBEE_TEST_STRIPE_PUBLISHABLE_KEY;
+  delete process.env.NEXT_PUBLIC_STRIPE_TEST_PUBLISHABLE_KEY;
+};
+
+describe('checkoutRuntimeConfig', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    resetClaimbeeCheckoutEnv();
+  });
+
+  afterEach(() => {
+    vi.resetModules();
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it('does not invent a checkout SDK publishable key from generic Stripe env', async () => {
+    process.env.NEXT_PUBLIC_STRIPE_TEST_PUBLISHABLE_KEY = 'pk_test_generic_runtime_value';
+
+    const { checkoutRuntimeConfig } = await import('./checkout-runtime-config');
+
+    expect(checkoutRuntimeConfig.funnelSdkPublishableKey).toBeNull();
+  });
+
+  it('prefers the funnel sdk publishable key when the project runtime provides one', async () => {
+    vi.doMock('@funnelsgrove/runtime', async () => {
+      const actual = await vi.importActual<typeof import('@funnelsgrove/runtime')>(
+        '@funnelsgrove/runtime',
+      );
+
+      return {
+        ...actual,
+        runtimePublicConfig: {
+          ...actual.runtimePublicConfig,
+          funnelSdkPublishableKey: 'sdk_pub_claimbee_project',
+        },
+      };
+    });
+
+    const { checkoutRuntimeConfig, resolveClaimbeeCheckoutMode } = await import('./checkout-runtime-config');
+
+    expect(checkoutRuntimeConfig.funnelSdkPublishableKey).toBe(
+      'sdk_pub_claimbee_project',
+    );
+    expect(resolveClaimbeeCheckoutMode('live')).toBe('live');
+  });
+
+  it('uses the server-provided runtime mode when no preview key is injected', async () => {
+    const { resolveClaimbeeCheckoutMode } = await import('./checkout-runtime-config');
+
+    expect(resolveClaimbeeCheckoutMode('live')).toBe('live');
+    expect(resolveClaimbeeCheckoutMode('test')).toBe('test');
+  });
+});

package/template_scaffold/src/runtime/checkout-runtime-config.ts

@@ -0,0 +1,26 @@
+import {
+  resolvePreviewPaymentPublishableKey,
+  runtimePublicConfig,
+  type RuntimeMode,
+} from '@funnelsgrove/runtime';
+
+const resolveCheckoutFunnelSdkPublishableKey = (): string | null => {
+  const trimmedCandidateKey = runtimePublicConfig.funnelSdkPublishableKey.trim();
+  if (trimmedCandidateKey) {
+    return resolvePreviewPaymentPublishableKey(trimmedCandidateKey) || null;
+  }
+
+  return null;
+};
+
+export const checkoutRuntimeConfig = {
+  apiBaseUrl: runtimePublicConfig.apiBaseUrl.trim() || null,
+  funnelId: runtimePublicConfig.funnelId.trim() || null,
+  funnelSdkPublishableKey: resolveCheckoutFunnelSdkPublishableKey(),
+} as const;
+
+export const resolveClaimbeeCheckoutMode = (
+  runtimeMode: RuntimeMode,
+): RuntimeMode => {
+  return runtimeMode;
+};

package/template_scaffold/src/runtime/funnel-runtime.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { funnelManifest } from '@/config/funnel.manifest';
+import {
+  defaultFunnelStepId,
+  resolveConfiguredNextStep,
+  resolveRuntimeInitialStepId,
+} from './funnel-runtime';
+
+describe('funnel runtime', () => {
+  it('falls back to the first manifest step when no valid step is requested', () => {
+    expect(funnelManifest.steps[0]?.id).toBe(defaultFunnelStepId);
+    expect(resolveRuntimeInitialStepId({ requestedStepId: null })).toBe(defaultFunnelStepId);
+    expect(resolveRuntimeInitialStepId({ requestedStepId: 'missing-step' })).toBe(defaultFunnelStepId);
+  });
+
+  it('resolves the normal edge after an experiment source route is active', () => {
+    expect(
+      resolveConfiguredNextStep('paywall', {
+        attributes: {},
+        ignoreExperiment: true,
+        resolveExperimentVariantKey: () => 'control',
+      }),
+    ).toBe('subscription-started');
+  });
+});