@posthog/wizard 1.36.1 → 2.0.0

package/dist/src/lib/constants.js

@@ -1,8 +1,13 @@
 "use strict";
+/**
+ * Shared constants for the PostHog wizard.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WIZARD_USER_AGENT = exports.WIZARD_REMARK_EVENT_NAME = exports.WIZARD_INTERACTION_EVENT_NAME = exports.OAUTH_PORT = exports.POSTHOG_OAUTH_URL = exports.POSTHOG_PROXY_CLIENT_ID = exports.POSTHOG_DEV_CLIENT_ID = exports.POSTHOG_EU_CLIENT_ID = exports.POSTHOG_US_CLIENT_ID = exports.DUMMY_PROJECT_API_KEY = exports.ANALYTICS_TEAM_TAG = exports.ANALYTICS_HOST_URL = exports.ANALYTICS_POSTHOG_PUBLIC_PROJECT_WRITE_KEY = exports.DEFAULT_HOST_URL = exports.ISSUES_URL = exports.DEFAULT_URL = exports.DEBUG = exports.IS_DEV = exports.Integration = void 0;
+exports.DETECTION_TIMEOUT_MS = exports.POSTHOG_FLAG_HEADER_PREFIX = exports.POSTHOG_PROPERTY_HEADER_PREFIX = exports.WIZARD_USER_AGENT = exports.WIZARD_VARIANTS = exports.WIZARD_VARIANT_FLAG_KEY = exports.WIZARD_REMARK_EVENT_NAME = exports.DUMMY_PROJECT_API_KEY = exports.POSTHOG_PROXY_CLIENT_ID = exports.POSTHOG_DEV_CLIENT_ID = exports.POSTHOG_EU_CLIENT_ID = exports.POSTHOG_US_CLIENT_ID = exports.OAUTH_PORT = exports.POSTHOG_OAUTH_URL = exports.ANALYTICS_TEAM_TAG = exports.ANALYTICS_HOST_URL = exports.ANALYTICS_POSTHOG_PUBLIC_PROJECT_WRITE_KEY = exports.ISSUES_URL = exports.DEFAULT_HOST_URL = exports.DEFAULT_URL = exports.DEBUG = exports.IS_DEV = exports.Integration = void 0;
+const version_1 = require("./version");
+// ── Integration / CLI ───────────────────────────────────────────────
 /**
- * Detection order matters: put framework-specific integrations BEFORE basic language fallbacks
+ * Detection order matters: put framework-specific integrations BEFORE basic language fallbacks.
  */
 var Integration;
 (function (Integration) {
@@ -25,34 +30,53 @@ var Integration;
     Integration["android"] = "android";
     Integration["rails"] = "rails";
     // Language fallbacks
+    Integration["javascript_web"] = "javascript_web";
     Integration["python"] = "python";
     Integration["ruby"] = "ruby";
     Integration["javascriptNode"] = "javascript_node";
-    Integration["javascript_web"] = "javascript_web";
 })(Integration || (exports.Integration = Integration = {}));
+// ── Environment ──────────────────────────────────────────────────────
 exports.IS_DEV = ['test', 'development'].includes(process.env.NODE_ENV ?? '');
 exports.DEBUG = false;
+// ── URLs ─────────────────────────────────────────────────────────────
 exports.DEFAULT_URL = exports.IS_DEV
     ? 'http://localhost:8010'
     : 'https://us.posthog.com';
-exports.ISSUES_URL = 'https://github.com/posthog/wizard/issues';
 exports.DEFAULT_HOST_URL = exports.IS_DEV
     ? 'http://localhost:8010'
     : 'https://us.i.posthog.com';
+exports.ISSUES_URL = 'https://github.com/posthog/wizard/issues';
+// ── Analytics (internal) ──────────────────────────────────────────────
 exports.ANALYTICS_POSTHOG_PUBLIC_PROJECT_WRITE_KEY = 'sTMFPsFhdP1Ssg';
 exports.ANALYTICS_HOST_URL = 'https://internal-j.posthog.com';
 exports.ANALYTICS_TEAM_TAG = 'docs-and-wizard';
-exports.DUMMY_PROJECT_API_KEY = '_YOUR_POSTHOG_PROJECT_API_KEY_';
-exports.POSTHOG_US_CLIENT_ID = 'c4Rdw8DIxgtQfA80IiSnGKlNX8QN00cFWF00QQhM';
-exports.POSTHOG_EU_CLIENT_ID = 'bx2C5sZRN03TkdjraCcetvQFPGH6N2Y9vRLkcKEy';
-exports.POSTHOG_DEV_CLIENT_ID = 'DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ';
-exports.POSTHOG_PROXY_CLIENT_ID = exports.POSTHOG_US_CLIENT_ID;
+// ── OAuth / Auth ────────────────────────────────────────────────────
 exports.POSTHOG_OAUTH_URL = exports.IS_DEV
     ? 'http://localhost:8010'
     : 'https://oauth.posthog.com';
 exports.OAUTH_PORT = 8239;
-exports.WIZARD_INTERACTION_EVENT_NAME = 'wizard interaction';
+exports.POSTHOG_US_CLIENT_ID = 'c4Rdw8DIxgtQfA80IiSnGKlNX8QN00cFWF00QQhM';
+exports.POSTHOG_EU_CLIENT_ID = 'bx2C5sZRN03TkdjraCcetvQFPGH6N2Y9vRLkcKEy';
+exports.POSTHOG_DEV_CLIENT_ID = 'DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ';
+exports.POSTHOG_PROXY_CLIENT_ID = exports.POSTHOG_US_CLIENT_ID;
+exports.DUMMY_PROJECT_API_KEY = '_YOUR_POSTHOG_PROJECT_API_KEY_';
+// ── Wizard run / variants ───────────────────────────────────────────
 exports.WIZARD_REMARK_EVENT_NAME = 'wizard remark';
-const version_1 = require("./version");
+/** Feature flag key whose value selects a variant from WIZARD_VARIANTS. */
+exports.WIZARD_VARIANT_FLAG_KEY = 'wizard-variant';
+/** Variant key -> metadata for wizard run (VARIANT flag selects which entry to use). */
+exports.WIZARD_VARIANTS = {
+    base: { VARIANT: 'base' },
+    subagents: { VARIANT: 'subagents' },
+};
+/** User-Agent for wizard HTTP requests and MCP server identification. */
 exports.WIZARD_USER_AGENT = `posthog/wizard; version: ${version_1.VERSION}`;
+// ── HTTP headers ─────────────────────────────────────────────────────
+/** Header prefix for PostHog properties (e.g. X-POSTHOG-PROPERTY-VARIANT). */
+exports.POSTHOG_PROPERTY_HEADER_PREFIX = 'X-POSTHOG-PROPERTY-';
+/** Header prefix for PostHog feature flags. */
+exports.POSTHOG_FLAG_HEADER_PREFIX = 'X-POSTHOG-FLAG-';
+// ── Timeouts ─────────────────────────────────────────────────────────
+/** Timeout for framework / project detection probes (ms). */
+exports.DETECTION_TIMEOUT_MS = 10_000;
 //# sourceMappingURL=constants.js.map

package/dist/src/lib/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/lib/constants.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,IAAY,WAyBX;AAzBD,WAAY,WAAW;IACrB,aAAa;IACb,gCAAiB,CAAA;IACjB,4BAAa,CAAA;IACb,0BAAW,CAAA;IACX,2CAA4B,CAAA;IAC5B,+CAAgC,CAAA;IAChC,iDAAkC,CAAA;IAClC,2CAA4B,CAAA;IAC5B,kCAAmB,CAAA;IACnB,8BAAe,CAAA;IACf,gCAAiB,CAAA;IACjB,8BAAe,CAAA;IACf,kCAAmB,CAAA;IACnB,kCAAmB,CAAA;IACnB,sCAAuB,CAAA;IACvB,8BAAe,CAAA;IACf,kCAAmB,CAAA;IACnB,8BAAe,CAAA;IAEf,qBAAqB;IACrB,gCAAiB,CAAA;IACjB,4BAAa,CAAA;IACb,iDAAkC,CAAA;IAClC,gDAAiC,CAAA;AACnC,CAAC,EAzBW,WAAW,2BAAX,WAAW,QAyBtB;AAMY,QAAA,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,QAAQ,CACpD,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAC3B,CAAC;AAEW,QAAA,KAAK,GAAG,KAAK,CAAC;AAEd,QAAA,WAAW,GAAG,cAAM;IAC/B,CAAC,CAAC,uBAAuB;IACzB,CAAC,CAAC,wBAAwB,CAAC;AAChB,QAAA,UAAU,GAAG,0CAA0C,CAAC;AACxD,QAAA,gBAAgB,GAAG,cAAM;IACpC,CAAC,CAAC,uBAAuB;IACzB,CAAC,CAAC,0BAA0B,CAAC;AAClB,QAAA,0CAA0C,GAAG,gBAAgB,CAAC;AAC9D,QAAA,kBAAkB,GAAG,gCAAgC,CAAC;AACtD,QAAA,kBAAkB,GAAG,iBAAiB,CAAC;AACvC,QAAA,qBAAqB,GAAG,gCAAgC,CAAC;AAEzD,QAAA,oBAAoB,GAAG,0CAA0C,CAAC;AAClE,QAAA,oBAAoB,GAAG,0CAA0C,CAAC;AAClE,QAAA,qBAAqB,GAAG,0CAA0C,CAAC;AACnE,QAAA,uBAAuB,GAAG,4BAAoB,CAAC;AAC/C,QAAA,iBAAiB,GAAG,cAAM;IACrC,CAAC,CAAC,uBAAuB;IACzB,CAAC,CAAC,2BAA2B,CAAC;AACnB,QAAA,UAAU,GAAG,IAAI,CAAC;AAElB,QAAA,6BAA6B,GAAG,oBAAoB,CAAC;AACrD,QAAA,wBAAwB,GAAG,eAAe,CAAC;AAExD,uCAAoC;AACvB,QAAA,iBAAiB,GAAG,4BAA4B,iBAAO,EAAE,CAAC","sourcesContent":["/**\n * Detection order matters: put framework-specific integrations BEFORE basic language fallbacks\n */\nexport enum Integration {\n  // Frameworks\n  nextjs = 'nextjs',\n  nuxt = 'nuxt',\n  vue = 'vue',\n  reactRouter = 'react-router',\n  tanstackStart = 'tanstack-start',\n  tanstackRouter = 'tanstack-router',\n  reactNative = 'react-native',\n  angular = 'angular',\n  astro = 'astro',\n  django = 'django',\n  flask = 'flask',\n  fastapi = 'fastapi',\n  laravel = 'laravel',\n  sveltekit = 'sveltekit',\n  swift = 'swift',\n  android = 'android',\n  rails = 'rails',\n\n  // Language fallbacks\n  python = 'python',\n  ruby = 'ruby',\n  javascriptNode = 'javascript_node',\n  javascript_web = 'javascript_web',\n}\nexport interface Args {\n  debug: boolean;\n  integration: Integration;\n}\n\nexport const IS_DEV = ['test', 'development'].includes(\n  process.env.NODE_ENV ?? '',\n);\n\nexport const DEBUG = false;\n\nexport const DEFAULT_URL = IS_DEV\n  ? 'http://localhost:8010'\n  : 'https://us.posthog.com';\nexport const ISSUES_URL = 'https://github.com/posthog/wizard/issues';\nexport const DEFAULT_HOST_URL = IS_DEV\n  ? 'http://localhost:8010'\n  : 'https://us.i.posthog.com';\nexport const ANALYTICS_POSTHOG_PUBLIC_PROJECT_WRITE_KEY = 'sTMFPsFhdP1Ssg';\nexport const ANALYTICS_HOST_URL = 'https://internal-j.posthog.com';\nexport const ANALYTICS_TEAM_TAG = 'docs-and-wizard';\nexport const DUMMY_PROJECT_API_KEY = '_YOUR_POSTHOG_PROJECT_API_KEY_';\n\nexport const POSTHOG_US_CLIENT_ID = 'c4Rdw8DIxgtQfA80IiSnGKlNX8QN00cFWF00QQhM';\nexport const POSTHOG_EU_CLIENT_ID = 'bx2C5sZRN03TkdjraCcetvQFPGH6N2Y9vRLkcKEy';\nexport const POSTHOG_DEV_CLIENT_ID = 'DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ';\nexport const POSTHOG_PROXY_CLIENT_ID = POSTHOG_US_CLIENT_ID;\nexport const POSTHOG_OAUTH_URL = IS_DEV\n  ? 'http://localhost:8010'\n  : 'https://oauth.posthog.com';\nexport const OAUTH_PORT = 8239;\n\nexport const WIZARD_INTERACTION_EVENT_NAME = 'wizard interaction';\nexport const WIZARD_REMARK_EVENT_NAME = 'wizard remark';\n\nimport { VERSION } from './version';\nexport const WIZARD_USER_AGENT = `posthog/wizard; version: ${VERSION}`;\n"]}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/lib/constants.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,uCAAoC;AAEpC,uEAAuE;AAEvE;;GAEG;AACH,IAAY,WAyBX;AAzBD,WAAY,WAAW;IACrB,aAAa;IACb,gCAAiB,CAAA;IACjB,4BAAa,CAAA;IACb,0BAAW,CAAA;IACX,2CAA4B,CAAA;IAC5B,+CAAgC,CAAA;IAChC,iDAAkC,CAAA;IAClC,2CAA4B,CAAA;IAC5B,kCAAmB,CAAA;IACnB,8BAAe,CAAA;IACf,gCAAiB,CAAA;IACjB,8BAAe,CAAA;IACf,kCAAmB,CAAA;IACnB,kCAAmB,CAAA;IACnB,sCAAuB,CAAA;IACvB,8BAAe,CAAA;IACf,kCAAmB,CAAA;IACnB,8BAAe,CAAA;IAEf,qBAAqB;IACrB,gDAAiC,CAAA;IACjC,gCAAiB,CAAA;IACjB,4BAAa,CAAA;IACb,iDAAkC,CAAA;AACpC,CAAC,EAzBW,WAAW,2BAAX,WAAW,QAyBtB;AAOD,wEAAwE;AAE3D,QAAA,MAAM,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,QAAQ,CACpD,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAC3B,CAAC;AACW,QAAA,KAAK,GAAG,KAAK,CAAC;AAE3B,wEAAwE;AAE3D,QAAA,WAAW,GAAG,cAAM;IAC/B,CAAC,CAAC,uBAAuB;IACzB,CAAC,CAAC,wBAAwB,CAAC;AAChB,QAAA,gBAAgB,GAAG,cAAM;IACpC,CAAC,CAAC,uBAAuB;IACzB,CAAC,CAAC,0BAA0B,CAAC;AAClB,QAAA,UAAU,GAAG,0CAA0C,CAAC;AAErE,yEAAyE;AAE5D,QAAA,0CAA0C,GAAG,gBAAgB,CAAC;AAC9D,QAAA,kBAAkB,GAAG,gCAAgC,CAAC;AACtD,QAAA,kBAAkB,GAAG,iBAAiB,CAAC;AAEpD,uEAAuE;AAE1D,QAAA,iBAAiB,GAAG,cAAM;IACrC,CAAC,CAAC,uBAAuB;IACzB,CAAC,CAAC,2BAA2B,CAAC;AACnB,QAAA,UAAU,GAAG,IAAI,CAAC;AAClB,QAAA,oBAAoB,GAAG,0CAA0C,CAAC;AAClE,QAAA,oBAAoB,GAAG,0CAA0C,CAAC;AAClE,QAAA,qBAAqB,GAAG,0CAA0C,CAAC;AACnE,QAAA,uBAAuB,GAAG,4BAAoB,CAAC;AAC/C,QAAA,qBAAqB,GAAG,gCAAgC,CAAC;AAEtE,uEAAuE;AAE1D,QAAA,wBAAwB,GAAG,eAAe,CAAC;AACxD,2EAA2E;AAC9D,QAAA,uBAAuB,GAAG,gBAAgB,CAAC;AACxD,wFAAwF;AAC3E,QAAA,eAAe,GAA2C;IACrE,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE;IACzB,SAAS,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;CACpC,CAAC;AACF,yEAAyE;AAC5D,QAAA,iBAAiB,GAAG,4BAA4B,iBAAO,EAAE,CAAC;AAEvE,wEAAwE;AAExE,8EAA8E;AACjE,QAAA,8BAA8B,GAAG,qBAAqB,CAAC;AACpE,+CAA+C;AAClC,QAAA,0BAA0B,GAAG,iBAAiB,CAAC;AAE5D,wEAAwE;AAExE,6DAA6D;AAChD,QAAA,oBAAoB,GAAG,MAAM,CAAC","sourcesContent":["/**\n * Shared constants for the PostHog wizard.\n */\n\nimport { VERSION } from './version';\n\n// ── Integration / CLI ───────────────────────────────────────────────\n\n/**\n * Detection order matters: put framework-specific integrations BEFORE basic language fallbacks.\n */\nexport enum Integration {\n  // Frameworks\n  nextjs = 'nextjs',\n  nuxt = 'nuxt',\n  vue = 'vue',\n  reactRouter = 'react-router',\n  tanstackStart = 'tanstack-start',\n  tanstackRouter = 'tanstack-router',\n  reactNative = 'react-native',\n  angular = 'angular',\n  astro = 'astro',\n  django = 'django',\n  flask = 'flask',\n  fastapi = 'fastapi',\n  laravel = 'laravel',\n  sveltekit = 'sveltekit',\n  swift = 'swift',\n  android = 'android',\n  rails = 'rails',\n\n  // Language fallbacks\n  javascript_web = 'javascript_web',\n  python = 'python',\n  ruby = 'ruby',\n  javascriptNode = 'javascript_node',\n}\n\nexport interface Args {\n  debug: boolean;\n  integration: Integration;\n}\n\n// ── Environment ──────────────────────────────────────────────────────\n\nexport const IS_DEV = ['test', 'development'].includes(\n  process.env.NODE_ENV ?? '',\n);\nexport const DEBUG = false;\n\n// ── URLs ─────────────────────────────────────────────────────────────\n\nexport const DEFAULT_URL = IS_DEV\n  ? 'http://localhost:8010'\n  : 'https://us.posthog.com';\nexport const DEFAULT_HOST_URL = IS_DEV\n  ? 'http://localhost:8010'\n  : 'https://us.i.posthog.com';\nexport const ISSUES_URL = 'https://github.com/posthog/wizard/issues';\n\n// ── Analytics (internal) ──────────────────────────────────────────────\n\nexport const ANALYTICS_POSTHOG_PUBLIC_PROJECT_WRITE_KEY = 'sTMFPsFhdP1Ssg';\nexport const ANALYTICS_HOST_URL = 'https://internal-j.posthog.com';\nexport const ANALYTICS_TEAM_TAG = 'docs-and-wizard';\n\n// ── OAuth / Auth ────────────────────────────────────────────────────\n\nexport const POSTHOG_OAUTH_URL = IS_DEV\n  ? 'http://localhost:8010'\n  : 'https://oauth.posthog.com';\nexport const OAUTH_PORT = 8239;\nexport const POSTHOG_US_CLIENT_ID = 'c4Rdw8DIxgtQfA80IiSnGKlNX8QN00cFWF00QQhM';\nexport const POSTHOG_EU_CLIENT_ID = 'bx2C5sZRN03TkdjraCcetvQFPGH6N2Y9vRLkcKEy';\nexport const POSTHOG_DEV_CLIENT_ID = 'DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ';\nexport const POSTHOG_PROXY_CLIENT_ID = POSTHOG_US_CLIENT_ID;\nexport const DUMMY_PROJECT_API_KEY = '_YOUR_POSTHOG_PROJECT_API_KEY_';\n\n// ── Wizard run / variants ───────────────────────────────────────────\n\nexport const WIZARD_REMARK_EVENT_NAME = 'wizard remark';\n/** Feature flag key whose value selects a variant from WIZARD_VARIANTS. */\nexport const WIZARD_VARIANT_FLAG_KEY = 'wizard-variant';\n/** Variant key -> metadata for wizard run (VARIANT flag selects which entry to use). */\nexport const WIZARD_VARIANTS: Record<string, Record<string, string>> = {\n  base: { VARIANT: 'base' },\n  subagents: { VARIANT: 'subagents' },\n};\n/** User-Agent for wizard HTTP requests and MCP server identification. */\nexport const WIZARD_USER_AGENT = `posthog/wizard; version: ${VERSION}`;\n\n// ── HTTP headers ─────────────────────────────────────────────────────\n\n/** Header prefix for PostHog properties (e.g. X-POSTHOG-PROPERTY-VARIANT). */\nexport const POSTHOG_PROPERTY_HEADER_PREFIX = 'X-POSTHOG-PROPERTY-';\n/** Header prefix for PostHog feature flags. */\nexport const POSTHOG_FLAG_HEADER_PREFIX = 'X-POSTHOG-FLAG-';\n\n// ── Timeouts ─────────────────────────────────────────────────────────\n\n/** Timeout for framework / project detection probes (ms). */\nexport const DETECTION_TIMEOUT_MS = 10_000;\n"]}

package/dist/src/lib/framework-config.d.ts

@@ -1,6 +1,24 @@
 import type { Integration } from './constants';
 import type { WizardOptions } from '../utils/types';
 import type { PackageManagerDetector } from './package-manager-detection';
+/**
+ * A setup question that the SetupScreen renders for framework disambiguation.
+ * If detect() returns a value, the question is auto-resolved and not shown.
+ */
+export interface SetupQuestion {
+    /** Stored in session.frameworkContext[key] */
+    key: string;
+    /** Displayed to user, e.g. "Which router are you using?" */
+    message: string;
+    /** Picker options */
+    options: Array<{
+        label: string;
+        value: string;
+        hint?: string;
+    }>;
+    /** Auto-detect; null = ask the user */
+    detect: (options: Pick<WizardOptions, 'installDir'>) => Promise<string | null>;
+}
 /**
  * Configuration interface for framework-specific agent integrations.
  * Each framework exports a FrameworkConfig that the universal runner uses.
@@ -46,6 +64,14 @@ export interface FrameworkMetadata<TContext extends Record<string, unknown> = Re
     additionalMcpServers?: Record<string, {
         url: string;
     }>;
+    /**
+     * Setup questions for framework disambiguation.
+     * The SetupScreen iterates unresolved questions and renders a PickerMenu for each.
+     * If all questions are auto-resolved (or none defined), the screen is skipped.
+     */
+    setup?: {
+        questions: SetupQuestion[];
+    };
 }
 /**
  * Framework detection and version handling

package/dist/src/lib/framework-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"framework-config.js","sourceRoot":"","sources":["../../../src/lib/framework-config.ts"],"names":[],"mappings":";;;AA0LA,8CAEC;AAhED;;;;GAIG;AACU,QAAA,4BAA4B,GACvC,wJAAwJ,CAAC;AAE9I,QAAA,2BAA2B,GACtC,8SAA8S,CAAC;AAkDjT;;GAEG;AACH,SAAgB,iBAAiB,CAAC,aAAqB;IACrD,OAAO,WAAW,aAAa,yBAAyB,CAAC;AAC3D,CAAC;AAED;;GAEG;AACU,QAAA,eAAe,GAC1B,mEAAmE,CAAC","sourcesContent":["import type { Integration } from './constants';\nimport type { WizardOptions } from '../utils/types';\nimport type { PackageManagerDetector } from './package-manager-detection';\n\n/**\n * Configuration interface for framework-specific agent integrations.\n * Each framework exports a FrameworkConfig that the universal runner uses.\n *\n * The TContext generic represents the framework-specific context gathered\n * before the agent runs (e.g., router type for Next.js, project type for Django).\n * The runner threads this opaquely — all framework-specific logic stays inside the config.\n */\nexport interface FrameworkConfig<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  metadata: FrameworkMetadata<TContext>;\n  detection: FrameworkDetection;\n  environment: EnvironmentConfig;\n  analytics: AnalyticsConfig<TContext>;\n  prompts: PromptConfig<TContext>;\n  ui: UIConfig<TContext>;\n}\n\n/**\n * Basic framework information and documentation\n */\nexport interface FrameworkMetadata<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  /** Display name (e.g., \"Next.js\", \"React\") */\n  name: string;\n\n  /** Integration type from constants */\n  integration: Integration;\n\n  /** URL to framework-specific PostHog docs */\n  docsUrl: string;\n\n  /**\n   * Optional URL to docs for users with unsupported framework versions.\n   * If not provided, defaults to docsUrl.\n   */\n  unsupportedVersionDocsUrl?: string;\n\n  /** If true, shows a beta notice before running the wizard. */\n  beta?: boolean;\n\n  /** Optional notice shown before the agent runs (e.g., \"Close Xcode before proceeding\"). */\n  preRunNotice?: string;\n\n  /**\n   * Optional function to gather framework-specific context before agent runs.\n   * For Next.js: detects router type\n   * For React Native: detects Expo vs bare\n   */\n  gatherContext?: (options: WizardOptions) => Promise<TContext>;\n\n  /** Optional additional MCP servers for this framework (e.g., Svelte MCP). */\n  additionalMcpServers?: Record<string, { url: string }>;\n}\n\n/**\n * Framework detection and version handling\n */\nexport interface FrameworkDetection {\n  /** Package name to check in package.json (e.g., \"next\", \"react\") */\n  packageName: string;\n\n  /** Human-readable name for error messages (e.g., \"Next.js\") */\n  packageDisplayName: string;\n\n  /** Extract version from package.json */\n  getVersion: (packageJson: unknown) => string | undefined;\n\n  /** Optional: Convert version to analytics bucket (e.g., \"15.x\") */\n  getVersionBucket?: (version: string) => string;\n\n  /**\n   * Whether this framework uses package.json (Node.js/JavaScript).\n   * If false, skips package.json checks (for Python, Go, etc.)\n   * Defaults to true if not specified.\n   */\n  usesPackageJson?: boolean;\n\n  /** Minimum supported version. If set, runner checks before proceeding. */\n  minimumVersion?: string;\n\n  /** Get the currently installed version. Called by runner for version check. */\n  getInstalledVersion?: (options: WizardOptions) => Promise<string | undefined>;\n\n  /** Detect whether this framework is present in the project. */\n  detect: (options: Pick<WizardOptions, 'installDir'>) => Promise<boolean>;\n\n  /** Detect the project's package manager(s). Used by the in-process MCP tool. */\n  detectPackageManager: PackageManagerDetector;\n}\n\n/**\n * Environment variable configuration\n */\nexport interface EnvironmentConfig {\n  /** Whether to upload env vars to hosting providers post-agent */\n  uploadToHosting: boolean;\n\n  /**\n   * Build the environment variables object for this framework.\n   * Returns the exact variable names and values to upload to hosting providers.\n   */\n  getEnvVars: (apiKey: string, host: string) => Record<string, string>;\n}\n\n/**\n * Analytics configuration\n */\nexport interface AnalyticsConfig<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  /** Generate tags from context (e.g., { 'nextjs-version': '15.x', 'router': 'app' }) */\n  getTags: (context: TContext) => Record<string, string>;\n\n  /** Optional: Additional event properties */\n  getEventProperties?: (context: TContext) => Record<string, string>;\n}\n\n/**\n * Default package installation instruction used when frameworks don't\n * provide their own. Frameworks with specific needs (e.g., Swift SPM,\n * Composer) override this in their config.\n */\nexport const DEFAULT_PACKAGE_INSTALLATION =\n  'Use the detect_package_manager tool to determine the package manager. Do not manually edit package.json; the package manager handles it automatically.';\n\nexport const PYTHON_PACKAGE_INSTALLATION =\n  'Use the detect_package_manager tool to determine the package manager. If the detected tool manages dependencies directly (e.g. uv add, poetry add), use it — it will update the manifest automatically. If using pip, you must also add the dependency to requirements.txt or the appropriate manifest file.';\n\n/**\n * Prompt configuration\n */\nexport interface PromptConfig<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  /**\n   * Optional: Additional context lines to append to base prompt\n   * For Next.js: \"- Router: app\"\n   * For React Native: \"- Platform: Expo\"\n   */\n  getAdditionalContextLines?: (context: TContext) => string[];\n\n  /**\n   * How to detect the project type for this framework.\n   * Included in the agent prompt as project context.\n   * e.g., \"Look for package.json and lockfiles\" or \"Look for requirements.txt and manage.py\"\n   */\n  projectTypeDetection: string;\n\n  /**\n   * How to install packages for this framework.\n   * Included in the agent prompt as project context.\n   * Defaults to DEFAULT_PACKAGE_INSTALLATION. Only override if the framework\n   * has specific installation guidance (e.g., Swift SPM, Composer).\n   */\n  packageInstallation?: string;\n}\n\n/**\n * UI messaging configuration\n */\nexport interface UIConfig<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  /** Success message when agent completes */\n  successMessage: string;\n\n  /** Estimated time for agent to complete (in minutes) */\n  estimatedDurationMinutes: number;\n\n  /** Generate \"What the agent did\" bullets from context */\n  getOutroChanges: (context: TContext) => string[];\n\n  /** Generate \"Next steps\" bullets from context */\n  getOutroNextSteps: (context: TContext) => string[];\n}\n\n/**\n * Generate welcome message from framework name\n */\nexport function getWelcomeMessage(frameworkName: string): string {\n  return `PostHog ${frameworkName} wizard (agent-powered)`;\n}\n\n/**\n * Shared spinner message for all frameworks\n */\nexport const SPINNER_MESSAGE =\n  'Writing your PostHog setup with events, error capture and more...';\n"]}
+{"version":3,"file":"framework-config.js","sourceRoot":"","sources":["../../../src/lib/framework-config.ts"],"names":[],"mappings":";;;AAoNA,8CAEC;AAhED;;;;GAIG;AACU,QAAA,4BAA4B,GACvC,wJAAwJ,CAAC;AAE9I,QAAA,2BAA2B,GACtC,8SAA8S,CAAC;AAkDjT;;GAEG;AACH,SAAgB,iBAAiB,CAAC,aAAqB;IACrD,OAAO,WAAW,aAAa,yBAAyB,CAAC;AAC3D,CAAC;AAED;;GAEG;AACU,QAAA,eAAe,GAC1B,mEAAmE,CAAC","sourcesContent":["import type { Integration } from './constants';\nimport type { WizardOptions } from '../utils/types';\nimport type { PackageManagerDetector } from './package-manager-detection';\n\n/**\n * A setup question that the SetupScreen renders for framework disambiguation.\n * If detect() returns a value, the question is auto-resolved and not shown.\n */\nexport interface SetupQuestion {\n  /** Stored in session.frameworkContext[key] */\n  key: string;\n  /** Displayed to user, e.g. \"Which router are you using?\" */\n  message: string;\n  /** Picker options */\n  options: Array<{ label: string; value: string; hint?: string }>;\n  /** Auto-detect; null = ask the user */\n  detect: (\n    options: Pick<WizardOptions, 'installDir'>,\n  ) => Promise<string | null>;\n}\n\n/**\n * Configuration interface for framework-specific agent integrations.\n * Each framework exports a FrameworkConfig that the universal runner uses.\n *\n * The TContext generic represents the framework-specific context gathered\n * before the agent runs (e.g., router type for Next.js, project type for Django).\n * The runner threads this opaquely — all framework-specific logic stays inside the config.\n */\nexport interface FrameworkConfig<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  metadata: FrameworkMetadata<TContext>;\n  detection: FrameworkDetection;\n  environment: EnvironmentConfig;\n  analytics: AnalyticsConfig<TContext>;\n  prompts: PromptConfig<TContext>;\n  ui: UIConfig<TContext>;\n}\n\n/**\n * Basic framework information and documentation\n */\nexport interface FrameworkMetadata<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  /** Display name (e.g., \"Next.js\", \"React\") */\n  name: string;\n\n  /** Integration type from constants */\n  integration: Integration;\n\n  /** URL to framework-specific PostHog docs */\n  docsUrl: string;\n\n  /**\n   * Optional URL to docs for users with unsupported framework versions.\n   * If not provided, defaults to docsUrl.\n   */\n  unsupportedVersionDocsUrl?: string;\n\n  /** If true, shows a beta notice before running the wizard. */\n  beta?: boolean;\n\n  /** Optional notice shown before the agent runs (e.g., \"Close Xcode before proceeding\"). */\n  preRunNotice?: string;\n\n  /**\n   * Optional function to gather framework-specific context before agent runs.\n   * For Next.js: detects router type\n   * For React Native: detects Expo vs bare\n   */\n  gatherContext?: (options: WizardOptions) => Promise<TContext>;\n\n  /** Optional additional MCP servers for this framework (e.g., Svelte MCP). */\n  additionalMcpServers?: Record<string, { url: string }>;\n\n  /**\n   * Setup questions for framework disambiguation.\n   * The SetupScreen iterates unresolved questions and renders a PickerMenu for each.\n   * If all questions are auto-resolved (or none defined), the screen is skipped.\n   */\n  setup?: {\n    questions: SetupQuestion[];\n  };\n}\n\n/**\n * Framework detection and version handling\n */\nexport interface FrameworkDetection {\n  /** Package name to check in package.json (e.g., \"next\", \"react\") */\n  packageName: string;\n\n  /** Human-readable name for error messages (e.g., \"Next.js\") */\n  packageDisplayName: string;\n\n  /** Extract version from package.json */\n  getVersion: (packageJson: unknown) => string | undefined;\n\n  /** Optional: Convert version to analytics bucket (e.g., \"15.x\") */\n  getVersionBucket?: (version: string) => string;\n\n  /**\n   * Whether this framework uses package.json (Node.js/JavaScript).\n   * If false, skips package.json checks (for Python, Go, etc.)\n   * Defaults to true if not specified.\n   */\n  usesPackageJson?: boolean;\n\n  /** Minimum supported version. If set, runner checks before proceeding. */\n  minimumVersion?: string;\n\n  /** Get the currently installed version. Called by runner for version check. */\n  getInstalledVersion?: (options: WizardOptions) => Promise<string | undefined>;\n\n  /** Detect whether this framework is present in the project. */\n  detect: (options: Pick<WizardOptions, 'installDir'>) => Promise<boolean>;\n\n  /** Detect the project's package manager(s). Used by the in-process MCP tool. */\n  detectPackageManager: PackageManagerDetector;\n}\n\n/**\n * Environment variable configuration\n */\nexport interface EnvironmentConfig {\n  /** Whether to upload env vars to hosting providers post-agent */\n  uploadToHosting: boolean;\n\n  /**\n   * Build the environment variables object for this framework.\n   * Returns the exact variable names and values to upload to hosting providers.\n   */\n  getEnvVars: (apiKey: string, host: string) => Record<string, string>;\n}\n\n/**\n * Analytics configuration\n */\nexport interface AnalyticsConfig<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  /** Generate tags from context (e.g., { 'nextjs-version': '15.x', 'router': 'app' }) */\n  getTags: (context: TContext) => Record<string, string>;\n\n  /** Optional: Additional event properties */\n  getEventProperties?: (context: TContext) => Record<string, string>;\n}\n\n/**\n * Default package installation instruction used when frameworks don't\n * provide their own. Frameworks with specific needs (e.g., Swift SPM,\n * Composer) override this in their config.\n */\nexport const DEFAULT_PACKAGE_INSTALLATION =\n  'Use the detect_package_manager tool to determine the package manager. Do not manually edit package.json; the package manager handles it automatically.';\n\nexport const PYTHON_PACKAGE_INSTALLATION =\n  'Use the detect_package_manager tool to determine the package manager. If the detected tool manages dependencies directly (e.g. uv add, poetry add), use it — it will update the manifest automatically. If using pip, you must also add the dependency to requirements.txt or the appropriate manifest file.';\n\n/**\n * Prompt configuration\n */\nexport interface PromptConfig<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  /**\n   * Optional: Additional context lines to append to base prompt\n   * For Next.js: \"- Router: app\"\n   * For React Native: \"- Platform: Expo\"\n   */\n  getAdditionalContextLines?: (context: TContext) => string[];\n\n  /**\n   * How to detect the project type for this framework.\n   * Included in the agent prompt as project context.\n   * e.g., \"Look for package.json and lockfiles\" or \"Look for requirements.txt and manage.py\"\n   */\n  projectTypeDetection: string;\n\n  /**\n   * How to install packages for this framework.\n   * Included in the agent prompt as project context.\n   * Defaults to DEFAULT_PACKAGE_INSTALLATION. Only override if the framework\n   * has specific installation guidance (e.g., Swift SPM, Composer).\n   */\n  packageInstallation?: string;\n}\n\n/**\n * UI messaging configuration\n */\nexport interface UIConfig<\n  TContext extends Record<string, unknown> = Record<string, unknown>,\n> {\n  /** Success message when agent completes */\n  successMessage: string;\n\n  /** Estimated time for agent to complete (in minutes) */\n  estimatedDurationMinutes: number;\n\n  /** Generate \"What the agent did\" bullets from context */\n  getOutroChanges: (context: TContext) => string[];\n\n  /** Generate \"Next steps\" bullets from context */\n  getOutroNextSteps: (context: TContext) => string[];\n}\n\n/**\n * Generate welcome message from framework name\n */\nexport function getWelcomeMessage(frameworkName: string): string {\n  return `PostHog ${frameworkName} wizard (agent-powered)`;\n}\n\n/**\n * Shared spinner message for all frameworks\n */\nexport const SPINNER_MESSAGE =\n  'Writing your PostHog setup with events, error capture and more...';\n"]}

package/dist/src/lib/health-checks/__tests__/health-checks.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tests for health-checks.ts
+ *
+ * Mock data is modelled on live Statuspage.io v2 API responses.
+ * Statuspage docs: https://metastatuspage.com/api
+ *
+ * status.json  – page-level rollup with indicator (none | minor | major | critical)
+ * summary.json – same rollup plus component list; component statuses:
+ *   operational | degraded_performance | partial_outage | major_outage | under_maintenance
+ *   https://support.atlassian.com/statuspage/docs/show-service-status-with-components
+ *
+ * LLM Gateway – FastAPI service, GET /_liveness returns {"status":"alive"} (200)
+ *   Source: posthog/services/llm-gateway/src/llm_gateway/api/health.py
+ *
+ * MCP – Cloudflare Worker, GET / returns an HTML landing page (200)
+ *   Source: posthog/services/mcp/src/index.ts
+ */
+export {};