@posthog/wizard 2.8.0 → 2.9.0

package/README.md

@@ -33,6 +33,17 @@ npx @posthog/wizard mcp add
 npx @posthog/wizard mcp remove
 ```
 
+## Revenue Analytics
+
+Wire up an existing PostHog + Stripe project for revenue analytics:
+
+```bash
+npx @posthog/wizard revenue
+```
+
+Requires PostHog and Stripe SDKs already installed. Supports `--ci` with the
+same flags as the main wizard.
+
 # Options
 
 The following CLI arguments are available:

package/dist/bin.js

@@ -17,10 +17,10 @@ if (!(0, semver_1.satisfies)(process.version, NODE_VERSION_RANGE)) {
     (0, logging_1.red)(`PostHog wizard requires Node.js ${NODE_VERSION_RANGE}. You are using Node.js ${process.version}. Please upgrade your Node.js version.`);
     process.exit(1);
 }
-const run_1 = require("./src/run");
 const environment_1 = require("./src/utils/environment");
 const ui_1 = require("./src/ui");
 const logging_ui_1 = require("./src/ui/logging-ui");
+const workflow_registry_1 = require("./src/lib/workflows/workflow-registry");
 if (process.env.NODE_ENV === 'test') {
     void (async () => {
         try {
@@ -34,7 +34,35 @@ if (process.env.NODE_ENV === 'test') {
         }
     })();
 }
-(0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
+/** Shared yargs options for skill-based workflow subcommands. */
+const skillSubcommandOptions = {
+    debug: {
+        default: false,
+        describe: 'Enable verbose logging',
+        type: 'boolean',
+    },
+    'install-dir': {
+        describe: 'Directory to install in',
+        type: 'string',
+    },
+    'local-mcp': {
+        default: false,
+        describe: 'Use local MCP server',
+        type: 'boolean',
+    },
+    benchmark: {
+        default: false,
+        describe: 'Run in benchmark mode',
+        type: 'boolean',
+    },
+    'yara-report': {
+        default: false,
+        describe: 'Print YARA scanner summary',
+        type: 'boolean',
+        hidden: true,
+    },
+};
+const cli = (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     .env('POSTHOG_WIZARD')
     // global options
     .options({
@@ -76,10 +104,6 @@ if (process.env.NODE_ENV === 'test') {
         describe: 'PostHog project ID to use (optional; when not set, uses default from API key or OAuth)\nenv: POSTHOG_WIZARD_PROJECT_ID',
         type: 'string',
     },
-    email: {
-        describe: 'Email address for account creation (used with --signup)\nenv: POSTHOG_WIZARD_EMAIL',
-        type: 'string',
-    },
 })
     .command(['$0'], 'Run the PostHog setup wizard', (yargs) => {
     return yargs.options({
@@ -126,28 +150,71 @@ if (process.env.NODE_ENV === 'test') {
             type: 'boolean',
             hidden: true,
         },
+        skill: {
+            describe: 'Run a specific context-mill skill by ID\nenv: POSTHOG_WIZARD_SKILL',
+            type: 'string',
+        },
     });
 }, (argv) => {
     const options = { ...argv };
     // CI mode validation and TTY check
     if (options.ci) {
-        // Use LoggingUI for CI mode (no dependencies, no prompts)
-        (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
-        // Default region to 'us' if not specified
-        if (!options.region) {
+        if (!options.region)
             options.region = 'us';
-        }
         if (!options.apiKey) {
-            (0, ui_1.getUI)().intro(`PostHog Wizard`);
+            (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
+            (0, ui_1.getUI)().intro('PostHog Wizard');
             (0, ui_1.getUI)().log.error('CI mode requires --api-key (personal API key phx_xxx)');
             process.exit(1);
+            return;
         }
         if (!options.installDir) {
-            (0, ui_1.getUI)().intro(`PostHog Wizard`);
-            (0, ui_1.getUI)().log.error('CI mode requires --install-dir (directory to install PostHog in)');
+            (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
+            (0, ui_1.getUI)().intro('PostHog Wizard');
+            (0, ui_1.getUI)().log.error('CI mode requires --install-dir (directory to install in)');
             process.exit(1);
+            return;
         }
-        void (0, run_1.runWizard)(options);
+        void (async () => {
+            const { posthogIntegrationConfig } = await import('./src/lib/workflows/posthog-integration/index.js');
+            const { FRAMEWORK_REGISTRY } = await import('./src/lib/registry.js');
+            const { detectFramework, gatherFrameworkContext } = await import('./src/lib/detection/index.js');
+            const { analytics } = await import('./src/utils/analytics.js');
+            const { wizardAbort } = await import('./src/utils/wizard-abort.js');
+            // preRun: honor --integration, else auto-detect, then gather
+            // framework context. Bypasses onReady hooks by design.
+            runWizardCI(posthogIntegrationConfig, options, async (session) => {
+                const integration = session.integration ??
+                    (await detectFramework(session.installDir));
+                if (!integration) {
+                    await wizardAbort({
+                        message: 'Could not auto-detect your framework. Please specify --integration on the command line.',
+                    });
+                    return;
+                }
+                session.integration = integration;
+                analytics.setTag('integration', integration);
+                const frameworkConfig = FRAMEWORK_REGISTRY[integration];
+                session.frameworkConfig = frameworkConfig;
+                const context = await gatherFrameworkContext(frameworkConfig, {
+                    installDir: session.installDir,
+                    debug: session.debug,
+                    forceInstall: session.forceInstall,
+                    default: false,
+                    signup: session.signup,
+                    localMcp: session.localMcp,
+                    ci: true,
+                    menu: session.menu,
+                    benchmark: session.benchmark,
+                    yaraReport: session.yaraReport,
+                });
+                for (const [key, value] of Object.entries(context)) {
+                    if (!(key in session.frameworkContext)) {
+                        session.frameworkContext[key] = value;
+                    }
+                }
+            });
+        })();
     }
     else if ((0, environment_1.isNonInteractiveEnvironment)()) {
         // Non-interactive non-CI: error out
@@ -166,159 +233,32 @@ if (process.env.NODE_ENV === 'test') {
             startPlayground(WIZARD_VERSION);
         })();
     }
+    else if (options.skill) {
+        // Run a specific skill by ID
+        void (async () => {
+            const { createSkillWorkflow } = await import('./src/lib/workflows/agent-skill/index.js');
+            const skillId = options.skill;
+            const config = createSkillWorkflow({
+                skillId,
+                command: 'skill',
+                flowKey: 'agent-skill',
+                description: `Run skill: ${skillId}`,
+                integrationLabel: skillId,
+                successMessage: `${skillId} completed!`,
+                reportFile: `posthog-${skillId}-report.md`,
+                docsUrl: 'https://posthog.com/docs',
+                spinnerMessage: `Running ${skillId}...`,
+                estimatedDurationMinutes: 5,
+            });
+            runWizard(config, options);
+        })();
+    }
     else {
-        // Interactive TTY: launch the Ink TUI
+        // Interactive TTY: run core-integration through the unified workflow path.
+        // Same codepath as `npx @posthog/wizard integrate`.
         void (async () => {
-            try {
-                const { startTUI } = await import('./src/ui/tui/start-tui.js');
-                const { buildSession } = await import('./src/lib/wizard-session.js');
-                const tui = startTUI(WIZARD_VERSION);
-                // Build session from CLI args and attach to store
-                const session = buildSession({
-                    debug: options.debug,
-                    forceInstall: options.forceInstall,
-                    installDir: options.installDir,
-                    ci: false,
-                    signup: options.signup,
-                    localMcp: options.localMcp,
-                    apiKey: options.apiKey,
-                    email: options.email,
-                    menu: options.menu,
-                    integration: options.integration,
-                    benchmark: options.benchmark,
-                    yaraReport: options.yaraReport,
-                    projectId: options.projectId,
-                });
-                tui.store.session = session;
-                // Detect framework while IntroScreen shows its spinner.
-                // Runs concurrently — IntroScreen reacts when detection completes.
-                const { FRAMEWORK_REGISTRY } = (await import('./src/lib/registry.js'));
-                const { detectIntegration } = (await import('./src/run.js'));
-                const installDir = session.installDir ?? process.cwd();
-                const { DETECTION_TIMEOUT_MS } = (await import('./src/lib/constants.js'));
-                const detectedIntegration = await Promise.race([
-                    detectIntegration(installDir),
-                    new Promise((resolve) => setTimeout(() => resolve(undefined), DETECTION_TIMEOUT_MS)),
-                ]);
-                if (detectedIntegration) {
-                    const config = FRAMEWORK_REGISTRY[detectedIntegration];
-                    // Run gatherContext for the friendly variant label
-                    if (config.metadata.gatherContext) {
-                        try {
-                            const context = await Promise.race([
-                                config.metadata.gatherContext({
-                                    installDir,
-                                    debug: session.debug,
-                                    forceInstall: session.forceInstall,
-                                    default: false,
-                                    signup: session.signup,
-                                    localMcp: session.localMcp,
-                                    ci: session.ci,
-                                    menu: session.menu,
-                                    benchmark: session.benchmark,
-                                    yaraReport: session.yaraReport,
-                                }),
-                                new Promise((resolve) => setTimeout(() => resolve({}), DETECTION_TIMEOUT_MS)),
-                            ]);
-                            for (const [key, value] of Object.entries(context)) {
-                                if (!(key in session.frameworkContext)) {
-                                    tui.store.setFrameworkContext(key, value);
-                                }
-                            }
-                        }
-                        catch {
-                            // Detection failed — will show generic name
-                        }
-                    }
-                    tui.store.setFrameworkConfig(detectedIntegration, config);
-                    if (!session.detectedFrameworkLabel) {
-                        tui.store.setDetectedFramework(config.metadata.name);
-                    }
-                    // Early version check — surface on IntroScreen before user proceeds
-                    if (config.detection.minimumVersion &&
-                        config.detection.getInstalledVersion) {
-                        const semver = await import('semver');
-                        const version = await config.detection.getInstalledVersion({
-                            installDir,
-                            debug: session.debug,
-                            forceInstall: session.forceInstall,
-                            default: false,
-                            signup: session.signup,
-                            localMcp: session.localMcp,
-                            ci: session.ci,
-                            menu: session.menu,
-                            benchmark: session.benchmark,
-                            yaraReport: session.yaraReport,
-                        });
-                        if (version) {
-                            const coerced = semver.coerce(version);
-                            if (coerced &&
-                                semver.lt(coerced, config.detection.minimumVersion)) {
-                                tui.store.setUnsupportedVersion({
-                                    current: version,
-                                    minimum: config.detection.minimumVersion,
-                                    docsUrl: config.metadata.unsupportedVersionDocsUrl ??
-                                        config.metadata.docsUrl,
-                                });
-                            }
-                        }
-                    }
-                }
-                // Feature discovery — deterministic scan of package.json deps
-                try {
-                    const { readFileSync } = await import('fs');
-                    const pkgPath = require('path').join(installDir, 'package.json');
-                    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-                    const allDeps = {
-                        ...pkg.dependencies,
-                        ...pkg.devDependencies,
-                    };
-                    const depNames = Object.keys(allDeps);
-                    const { DiscoveredFeature } = await import('./src/lib/wizard-session.js');
-                    if (depNames.some((d) => ['stripe', '@stripe/stripe-js'].includes(d))) {
-                        tui.store.addDiscoveredFeature(DiscoveredFeature.Stripe);
-                    }
-                    // LLM SDK detection — sourced from PostHog LLM analytics skill
-                    const LLM_PACKAGES = [
-                        'openai',
-                        '@anthropic-ai/sdk',
-                        'ai',
-                        '@ai-sdk/openai',
-                        'langchain',
-                        '@langchain/openai',
-                        '@langchain/langgraph',
-                        '@google/generative-ai',
-                        '@google/genai',
-                        '@instructor-ai/instructor',
-                        '@mastra/core',
-                        'portkey-ai',
-                    ];
-                    if (depNames.some((d) => LLM_PACKAGES.includes(d))) {
-                        tui.store.addDiscoveredFeature(DiscoveredFeature.LLM);
-                    }
-                }
-                catch {
-                    // No package.json or parse error — skip feature discovery
-                }
-                // Signal detection is done — IntroScreen shows picker or results
-                tui.store.setDetectionComplete();
-                // Wait for IntroScreen confirmation
-                await tui.waitForSetup();
-                // Ensure health check has completed before starting the wizard.
-                // The flow gate on Intro (readinessResult !== null) keeps the
-                // TUI on IntroScreen until this resolves. If blocking, the
-                // outage overlay was already pushed in the .then() callback.
-                await tui.store.healthGateComplete;
-                await (0, run_1.runWizard)(options, tui.store.session);
-                // Keep the outro screen visible — let process.exit() handle cleanup
-            }
-            catch (err) {
-                // TUI unavailable (e.g., in test environment) — continue with default UI
-                if (process.env.DEBUG || process.env.POSTHOG_WIZARD_DEBUG) {
-                    console.error('TUI init failed:', err); // eslint-disable-line no-console
-                }
-                await (0, run_1.runWizard)(options);
-            }
+            const { posthogIntegrationConfig } = await import('./src/lib/workflows/posthog-integration/index.js');
+            runWizard(posthogIntegrationConfig, options);
         })();
     }
 })
@@ -408,10 +348,192 @@ if (process.env.NODE_ENV === 'test') {
     })
         .demandCommand(1, 'You must specify a subcommand (add or remove)')
         .help();
-})
+});
+// ── Skill-based workflow subcommands (derived from registry) ─────────
+for (const wfConfig of (0, workflow_registry_1.getSubcommandWorkflows)()) {
+    cli.command(wfConfig.command, wfConfig.description, (y) => y.options(skillSubcommandOptions), (argv) => {
+        const options = { ...argv };
+        if (options.ci) {
+            runWizardCI(wfConfig, options);
+        }
+        else {
+            runWizard(wfConfig, options);
+        }
+    });
+}
+cli
     .help()
     .alias('help', 'h')
     .version()
     .alias('version', 'v')
     .wrap(process.stdout.isTTY ? yargs_1.default.terminalWidth() : 80).argv;
+/**
+ * Run a full wizard workflow in the TUI. Handles the full lifecycle: start TUI,
+ * build session, run detection, wait for intro gate, execute the
+ * agent pipeline, wait for outro dismissal, then exit.
+ */
+function runWizard(config, options) {
+    void (async () => {
+        try {
+            const installDir = options.installDir || process.cwd();
+            const { startTUI } = await import('./src/ui/tui/start-tui.js');
+            const { buildSession } = await import('./src/lib/wizard-session.js');
+            // flowKey values match Flow enum values by convention
+            const tui = startTUI(WIZARD_VERSION, config.flowKey);
+            const session = buildSession({
+                debug: options.debug,
+                forceInstall: options.forceInstall,
+                localMcp: options.localMcp,
+                installDir,
+                ci: false,
+                signup: options.signup,
+                apiKey: options.apiKey,
+                projectId: options.projectId,
+                menu: options.menu,
+                integration: options.integration,
+                benchmark: options.benchmark,
+                yaraReport: options.yaraReport,
+            });
+            // Set workflow metadata for TUI display
+            session.workflowLabel = config.flowKey;
+            const runDef = typeof config.run === 'object' ? config.run : null;
+            session.skillId = runDef?.skillId ?? null;
+            tui.store.session = session;
+            await tui.store.runReadyHooks();
+            await tui.store.getGate('intro');
+            const { runAgent } = await import('./src/lib/agent/agent-runner.js');
+            await runAgent(config, tui.store.session);
+            tui.store.onEnterScreen('outro', () => {
+                // Screen is already outro — listen for dismissal
+            });
+            await new Promise((resolve) => {
+                const unsub = tui.store.subscribe(() => {
+                    if (tui.store.session.outroDismissed) {
+                        unsub();
+                        resolve();
+                    }
+                });
+                if (tui.store.session.outroDismissed) {
+                    unsub();
+                    resolve();
+                }
+            });
+            process.exit(0);
+        }
+        catch (err) {
+            if (process.env.DEBUG || process.env.POSTHOG_WIZARD_DEBUG) {
+                console.error('TUI init failed:', err); // eslint-disable-line no-console
+            }
+        }
+    })();
+}
+/**
+ * CI-mode pipeline shared by every non-interactive entry point.
+ *
+ * Validates flags, builds a `ci:true` session, runs `preRun` (or the
+ * workflow's `onReady` hooks by default), executes `runAgent`, and
+ * routes any failure through `wizardAbort`. `wizardAbort` owns all
+ * exits — never add a raw `process.exit` here.
+ */
+function runWizardCI(config, options, preRun) {
+    (0, ui_1.setUI)(new logging_ui_1.LoggingUI());
+    if (!options.region)
+        options.region = 'us';
+    if (!options.apiKey) {
+        (0, ui_1.getUI)().intro('PostHog Wizard');
+        (0, ui_1.getUI)().log.error('CI mode requires --api-key (personal API key phx_xxx)');
+        process.exit(1);
+    }
+    if (!options.installDir) {
+        (0, ui_1.getUI)().intro('PostHog Wizard');
+        (0, ui_1.getUI)().log.error('CI mode requires --install-dir (directory to install in)');
+        process.exit(1);
+    }
+    void (async () => {
+        const path = await import('path');
+        const { buildSession } = await import('./src/lib/wizard-session.js');
+        const { readEnvironment } = await import('./src/utils/environment.js');
+        const { readApiKeyFromEnv } = await import('./src/utils/env-api-key.js');
+        const { configureLogFileFromEnvironment, logToFile } = await import('./src/utils/debug.js');
+        const { wizardAbort, WizardError } = await import('./src/utils/wizard-abort.js');
+        configureLogFileFromEnvironment();
+        const env = readEnvironment();
+        const apiKey = options.apiKey ?? readApiKeyFromEnv() ?? undefined;
+        const installDir = path.isAbsolute(options.installDir)
+            ? options.installDir
+            : path.join(process.cwd(), options.installDir);
+        const session = buildSession({
+            debug: options.debug,
+            forceInstall: options.forceInstall,
+            installDir,
+            ci: true,
+            signup: options.signup,
+            localMcp: options.localMcp,
+            apiKey,
+            menu: options.menu,
+            integration: options.integration, // eslint-disable-line @typescript-eslint/no-explicit-any
+            projectId: options.projectId,
+            benchmark: options.benchmark,
+            yaraReport: options.yaraReport,
+            ...env,
+        });
+        session.workflowLabel = config.flowKey;
+        const runDef = typeof config.run === 'object' ? config.run : null;
+        session.skillId = runDef?.skillId ?? null;
+        (0, ui_1.getUI)().intro('Welcome to the PostHog setup wizard');
+        (0, ui_1.getUI)().log.info(`Running ${config.flowKey} in CI mode`);
+        try {
+            if (preRun) {
+                await preRun(session);
+            }
+            else {
+                // Run onReady hooks against a minimal store-less context.
+                const readyCtx = {
+                    session,
+                    setFrameworkContext: (key, value) => {
+                        session.frameworkContext[key] = value;
+                    },
+                    setFrameworkConfig: () => undefined,
+                    setDetectedFramework: () => undefined,
+                    setUnsupportedVersion: () => undefined,
+                    addDiscoveredFeature: () => undefined,
+                    setDetectionComplete: () => undefined,
+                };
+                for (const step of config.steps) {
+                    if (step.onReady) {
+                        await step.onReady(readyCtx);
+                    }
+                }
+                // Surface detectError written by the workflow's detect hook.
+                const detectError = session.frameworkContext.detectError;
+                if (detectError) {
+                    await wizardAbort({
+                        message: `Prerequisites not met: ${detectError.kind}\n\nSee ${runDef?.docsUrl ?? 'https://posthog.com/docs'}`,
+                        error: new WizardError(`${config.flowKey} prerequisites failed`, {
+                            integration: config.flowKey,
+                            detect_error_kind: detectError.kind,
+                        }),
+                    });
+                }
+            }
+            const { runAgent } = await import('./src/lib/agent/agent-runner.js');
+            await runAgent(config, session);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error && error.stack ? error.stack : undefined;
+            logToFile(`[bin.ts CI] ERROR: ${errorMessage}`);
+            if (errorStack)
+                logToFile(`[bin.ts CI] STACK: ${errorStack}`);
+            const debugInfo = session.debug && errorStack ? `\n\n${errorStack}` : '';
+            const docsUrl = session.frameworkConfig?.metadata.docsUrl ??
+                runDef?.docsUrl ??
+                'https://posthog.com/docs';
+            await wizardAbort({
+                message: `Something went wrong: ${errorMessage}\n\nYou can read the documentation at ${docsUrl} to set up manually.${debugInfo}`,
+                error: error,
+            });
+        }
+    })();
+}
 //# sourceMappingURL=bin.js.map