@amplitude/wizard 1.0.0-beta.0

package/dist/package.json

@@ -0,0 +1,144 @@
+{
+    "name": "@amplitude/wizard",
+    "version": "1.0.0-beta.0",
+    "homepage": "https://github.com/amplitude/wizard",
+    "repository": "https://github.com/amplitude/wizard",
+    "description": "The Amplitude wizard helps you to configure your project",
+    "keywords": [
+        "amplitude",
+        "wizard",
+        "sdk",
+        "cli",
+        "project",
+        "setup",
+        "install",
+        "configure"
+    ],
+    "bin": {
+        "amplitude-wizard": "dist/bin.js"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "man": [
+        "man/amplitude-wizard.1"
+    ],
+    "files": [
+        "dist/bin.*",
+        "dist/src",
+        "man/",
+        "package.json",
+        "README.md"
+    ],
+    "main": "dist/index.js",
+    "typings": "dist/index.d.ts",
+    "typescript": {
+        "definition": "dist/index.d.ts"
+    },
+    "dependencies": {
+        "@amplitude/analytics-browser": "^2.0.0",
+        "@anthropic-ai/claude-agent-sdk": "0.2.7",
+        "@inkjs/ui": "^2.0.0",
+        "@inquirer/prompts": "^8.3.0",
+        "@langchain/core": "^1.1.33",
+        "@pavus/snake-game": "^1.1.1",
+        "axios": "1.13.5",
+        "chalk": "^2.4.1",
+        "client-oauth2": "^4.3.3",
+        "conf": "^15.1.0",
+        "dotenv": "^16.4.7",
+        "fast-glob": "^3.3.3",
+        "glob": "9.3.5",
+        "ink": "^6.8.0",
+        "inquirer": "^6.2.0",
+        "jsonc-parser": "^3.3.1",
+        "lodash": "^4.17.21",
+        "magicast": "^0.2.10",
+        "nanostores": "^1.1.1",
+        "opn": "^5.4.0",
+        "pkce-challenge": "^6.0.0",
+        "randomstring": "^1.3.1",
+        "react": "^19.2.4",
+        "read-env": "^1.3.0",
+        "recast": "^0.23.3",
+        "semver": "^7.5.3",
+        "uuid": "^11.1.0",
+        "xcode": "3.0.1",
+        "xml-js": "^1.6.11",
+        "yargs": "^16.2.0",
+        "zod": "^4.3.6",
+        "zod-to-json-schema": "^3.25.1"
+    },
+    "devDependencies": {
+        "@anthropic-ai/sdk": "^0.79.0",
+        "@cucumber/cucumber": "^12.7.0",
+        "@eslint/js": "^10.0.1",
+        "@types/chai": "^4.3.17",
+        "@types/glob": "^7.2.0",
+        "@types/inquirer": "^0.0.43",
+        "@types/lodash": "^4.17.15",
+        "@types/node": "^20.19.37",
+        "@types/opn": "5.1.0",
+        "@types/react": "^19.2.14",
+        "@types/rimraf": "^3.0.2",
+        "@types/semver": "^7.3.7",
+        "@types/yargs": "^16.0.9",
+        "@vitest/coverage-v8": "^4.0.18",
+        "eslint": "^9.39.4",
+        "eslint-config-prettier": "^9.1.2",
+        "globals": "^17.4.0",
+        "husky": "^9.1.7",
+        "lint-staged": "^15.5.1",
+        "msw": "^2.10.4",
+        "prettier": "^2.8.7",
+        "rimraf": "^6.1.3",
+        "ts-node": "^10.9.1",
+        "tsx": "^4.20.3",
+        "typescript": "^5.0.4",
+        "typescript-eslint": "^8.57.1",
+        "vitest": "^4.0.18"
+    },
+    "engines": {
+        "node": ">=20",
+        "npm": ">=3.10.7"
+    },
+    "packageManager": "pnpm@10.23.0+sha512.21c4e5698002ade97e4efe8b8b4a89a8de3c85a37919f957e7a0f30f38fbc5bbdd05980ffe29179b2fb6e6e691242e098d945d1601772cad0fef5fb6411e2a4b",
+    "scripts": {
+        "clean": "rm -rf ./dist",
+        "prebuild": "pnpm clean",
+        "build:watch": "pnpm tsc -w",
+        "build": "pnpm tsc",
+        "postbuild": "chmod +x ./dist/bin.js && pnpm test:smoke",
+        "test:smoke": "node -e \"require('./dist/bin.js')\" 2>&1 | head -5 | grep -q 'Amplitude Wizard' || (echo 'Smoke test failed: compiled binary crashed on load' && exit 1)",
+        "lint": "pnpm lint:prettier && pnpm lint:eslint",
+        "lint:prettier": "prettier --check \"{lib,src,test}/**/*.ts\"",
+        "lint:eslint": "eslint . --cache --format stylish",
+        "fix": "pnpm fix:eslint && pnpm fix:prettier",
+        "fix:prettier": "prettier --write \"{lib,src,test}/**/*.ts\"",
+        "fix:eslint": "eslint . --format stylish --fix",
+        "test": "vitest run",
+        "test:e2e": "pnpm build && ./e2e-tests/run.sh",
+        "test:e2e-record": "export RECORD_FIXTURES=true && pnpm build && ./e2e-tests/run.sh",
+        "try": "tsx bin.ts",
+        "proxy": "cd \"${JS_REPO:-../javascript}\"/server/packages/thunder && aws-sso exec --profile us-prod-dev -- pnpm debug",
+        "proxy:bypass": "cd \"${JS_REPO:-../javascript}\"/server/packages/thunder && WIZARD_PROXY_DEV_BYPASS=1 aws-sso exec --profile us-prod-dev -- pnpm debug",
+        "dev": "pnpm build && pnpm link --global && (trap 'kill 0' EXIT; pnpm proxy & pnpm build:watch)",
+        "test:watch": "vitest",
+        "prepare": "husky",
+        "flows": "node scripts/render-flows.mjs",
+        "test:bdd": "cucumber-js",
+        "test:bdd:watch": "cucumber-js --retry 0 2>&1 | npx nodemon --watch features --exec cucumber-js",
+        "test:proxy": "vitest run --config vitest.config.proxy.ts",
+        "test:proxy:smoke": "vitest run --config vitest.config.proxy.ts -t 'proxy:smoke'",
+        "skills:refresh": "bash scripts/refresh-instrumentation-skills.sh"
+    },
+    "lint-staged": {
+        "*.{js,ts,tsx,jsx}": "pnpm fix"
+    },
+    "author": "Amplitude",
+    "license": "MIT",
+    "volta": {
+        "node": "20.18.2",
+        "pnpm": "10.23.0"
+    }
+}

package/dist/src/frameworks/android/android-wizard-agent.d.ts

@@ -0,0 +1,6 @@
+import type { FrameworkConfig } from '../../lib/framework-config';
+type AndroidContext = {
+    language?: 'kotlin' | 'java';
+};
+export declare const ANDROID_AGENT_CONFIG: FrameworkConfig<AndroidContext>;
+export {};

package/dist/src/frameworks/android/android-wizard-agent.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANDROID_AGENT_CONFIG = void 0;
+const package_manager_detection_1 = require("../../lib/package-manager-detection");
+const constants_1 = require("../../lib/constants");
+const utils_1 = require("./utils");
+const ANDROID_PACKAGE_INSTALLATION = 'Use the detect_package_manager tool to determine the package manager. Add the Amplitude dependency to the app-level build.gradle (Groovy: `implementation \'com.amplitude:analytics-android:1.+\'`) or build.gradle.kts (Kotlin DSL: `implementation("com.amplitude:analytics-android:1.+")`), then sync the project.';
+exports.ANDROID_AGENT_CONFIG = {
+    metadata: {
+        name: 'Android',
+        integration: constants_1.Integration.android,
+        beta: true,
+        docsUrl: 'https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk',
+        gatherContext: async (options) => {
+            const language = await (0, utils_1.detectAndroidLanguage)(options);
+            return { language };
+        },
+    },
+    detection: {
+        packageName: 'com.amplitude:analytics-android',
+        packageDisplayName: 'Android',
+        usesPackageJson: false,
+        getVersion: () => undefined,
+        detect: utils_1.detectAndroidProject,
+        detectPackageManager: package_manager_detection_1.gradlePackageManager,
+    },
+    environment: {
+        // Android apps don't use .env files — the agent stores the key in gradle.properties or BuildConfig
+        uploadToHosting: false,
+        getEnvVars: () => ({}),
+    },
+    analytics: {
+        getTags: (context) => ({
+            language: context.language ?? 'unknown',
+        }),
+    },
+    prompts: {
+        projectTypeDetection: 'This is an Android project. Look for AndroidManifest.xml, build.gradle / build.gradle.kts, and settings.gradle to confirm.',
+        packageInstallation: ANDROID_PACKAGE_INSTALLATION,
+        getAdditionalContextLines: (context) => {
+            const lang = context.language ?? 'kotlin';
+            const initExample = lang === 'kotlin'
+                ? 'val amplitude = Amplitude(Configuration(apiKey = AMPLITUDE_API_KEY, context = applicationContext))'
+                : 'Amplitude amplitude = new Amplitude(new Configuration(AMPLITUDE_API_KEY, getApplicationContext()));';
+            return [
+                `Language: ${lang === 'kotlin' ? 'Kotlin' : 'Java'}`,
+                `Framework docs ID: android (use amplitude://docs/frameworks/android for documentation)`,
+                `SDK: com.amplitude:analytics-android — add to app-level build.gradle`,
+                `Initialization: ${initExample}`,
+                `Never hardcode the API key in source files — store it in gradle.properties or local.properties and read it via BuildConfig`,
+            ];
+        },
+    },
+    ui: {
+        successMessage: 'Amplitude integration complete',
+        estimatedDurationMinutes: 8,
+        getOutroChanges: (context) => {
+            const lang = context.language === 'java' ? 'Java' : 'Kotlin';
+            return [
+                `Analyzed your Android (${lang}) project structure`,
+                `Added the Amplitude analytics-android dependency to build.gradle`,
+                `Configured Amplitude initialization with autocapture`,
+            ];
+        },
+        getOutroNextSteps: () => [
+            'Sync your Gradle project and run the app on a device or emulator',
+            'Visit your Amplitude dashboard to see incoming events',
+            'Use amplitude.track("Event Name") for custom events',
+            'Use amplitude.setUserId("user@example.com") to associate events with users',
+        ],
+    },
+};

package/dist/src/frameworks/android/utils.d.ts

@@ -0,0 +1,11 @@
+import type { WizardOptions } from '../../utils/types';
+/**
+ * Returns true when the directory contains an Android project.
+ * Primary signal: AndroidManifest.xml (Android-specific; not present in pure JVM projects).
+ */
+export declare function detectAndroidProject(options: Pick<WizardOptions, 'installDir'>): Promise<boolean>;
+/**
+ * Returns the primary language used in the Android project.
+ * Presence of any .kt source file → Kotlin; otherwise assumes Java.
+ */
+export declare function detectAndroidLanguage(options: Pick<WizardOptions, 'installDir'>): Promise<'kotlin' | 'java'>;

package/dist/src/frameworks/android/utils.js

@@ -0,0 +1,32 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectAndroidProject = detectAndroidProject;
+exports.detectAndroidLanguage = detectAndroidLanguage;
+const fast_glob_1 = __importDefault(require("fast-glob"));
+/**
+ * Returns true when the directory contains an Android project.
+ * Primary signal: AndroidManifest.xml (Android-specific; not present in pure JVM projects).
+ */
+async function detectAndroidProject(options) {
+    const manifests = await (0, fast_glob_1.default)('**/AndroidManifest.xml', {
+        cwd: options.installDir,
+        ignore: ['**/node_modules/**', '**/build/**', '**/.gradle/**'],
+        deep: 6,
+    });
+    return manifests.length > 0;
+}
+/**
+ * Returns the primary language used in the Android project.
+ * Presence of any .kt source file → Kotlin; otherwise assumes Java.
+ */
+async function detectAndroidLanguage(options) {
+    const kotlinFiles = await (0, fast_glob_1.default)('**/*.kt', {
+        cwd: options.installDir,
+        ignore: ['**/node_modules/**', '**/build/**', '**/.gradle/**'],
+        deep: 8,
+    });
+    return kotlinFiles.length > 0 ? 'kotlin' : 'java';
+}

package/dist/src/frameworks/django/django-wizard-agent.d.ts

@@ -0,0 +1,8 @@
+import type { FrameworkConfig } from '../../lib/framework-config';
+import { DjangoProjectType } from './utils';
+type DjangoContext = {
+    projectType?: DjangoProjectType;
+    settingsFile?: string;
+};
+export declare const DJANGO_AGENT_CONFIG: FrameworkConfig<DjangoContext>;
+export {};

package/dist/src/frameworks/django/django-wizard-agent.js

@@ -0,0 +1,171 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DJANGO_AGENT_CONFIG = void 0;
+const framework_config_1 = require("../../lib/framework-config");
+const package_manager_detection_1 = require("../../lib/package-manager-detection");
+const constants_1 = require("../../lib/constants");
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const utils_1 = require("./utils");
+exports.DJANGO_AGENT_CONFIG = {
+    metadata: {
+        name: 'Django',
+        integration: constants_1.Integration.django,
+        beta: true,
+        docsUrl: 'https://amplitude.com/docs/sdks/analytics/python',
+        unsupportedVersionDocsUrl: 'https://amplitude.com/docs/sdks/analytics/python',
+        gatherContext: async (options) => {
+            const projectType = await (0, utils_1.getDjangoProjectType)(options);
+            const settingsFile = await (0, utils_1.findDjangoSettingsFile)(options);
+            return { projectType, settingsFile };
+        },
+    },
+    detection: {
+        packageName: 'django',
+        packageDisplayName: 'Django',
+        usesPackageJson: false,
+        getVersion: () => undefined,
+        getVersionBucket: utils_1.getDjangoVersionBucket,
+        minimumVersion: '3.0.0',
+        getInstalledVersion: (options) => (0, utils_1.getDjangoVersion)(options),
+        detect: async (options) => {
+            const { installDir } = options;
+            const managePyMatches = await (0, fast_glob_1.default)('**/manage.py', {
+                cwd: installDir,
+                ignore: ['**/venv/**', '**/.venv/**', '**/env/**', '**/.env/**'],
+            });
+            if (managePyMatches.length > 0) {
+                for (const match of managePyMatches) {
+                    try {
+                        const content = fs.readFileSync(path.join(installDir, match), 'utf-8');
+                        // Check for actual Django imports and usage
+                        if (content.includes('from django') ||
+                            content.includes('import django') ||
+                            content.includes('DJANGO_SETTINGS_MODULE') ||
+                            /execute_from_command_line/.test(content)) {
+                            return true;
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+            }
+            const requirementsFiles = await (0, fast_glob_1.default)(['**/requirements*.txt', '**/pyproject.toml', '**/setup.py'], {
+                cwd: installDir,
+                ignore: ['**/venv/**', '**/.venv/**', '**/env/**', '**/.env/**'],
+            });
+            for (const reqFile of requirementsFiles) {
+                try {
+                    const content = fs.readFileSync(path.join(installDir, reqFile), 'utf-8');
+                    // Match Django as a package requirement, not in comments or other text
+                    // Look for: django, django>=, django==, django~=, Django (capitalized)
+                    if (/^django([>=~!<\s]|$)/im.test(content) ||
+                        /["']django["']/i.test(content)) {
+                        return true;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            return false;
+        },
+        detectPackageManager: package_manager_detection_1.detectPythonPackageManagers,
+    },
+    environment: {
+        uploadToHosting: false,
+        getEnvVars: (apiKey, _host) => ({
+            AMPLITUDE_API_KEY: apiKey,
+        }),
+    },
+    analytics: {
+        getTags: (context) => ({
+            projectType: context.projectType || 'unknown',
+        }),
+    },
+    prompts: {
+        packageInstallation: framework_config_1.PYTHON_PACKAGE_INSTALLATION,
+        projectTypeDetection: 'This is a Python/Django project. Look for requirements.txt, pyproject.toml, setup.py, Pipfile, or manage.py to confirm.',
+        getAdditionalContextLines: (context) => {
+            const projectTypeName = context.projectType
+                ? (0, utils_1.getDjangoProjectTypeName)(context.projectType)
+                : 'unknown';
+            // Map project type to framework ID for MCP docs resource
+            const frameworkIdMap = {
+                [utils_1.DjangoProjectType.STANDARD]: 'django',
+                [utils_1.DjangoProjectType.DRF]: 'django',
+                [utils_1.DjangoProjectType.WAGTAIL]: 'django',
+                [utils_1.DjangoProjectType.CHANNELS]: 'django',
+            };
+            const frameworkId = context.projectType
+                ? frameworkIdMap[context.projectType]
+                : 'django';
+            const lines = [
+                `Project type: ${projectTypeName}`,
+                `Framework docs ID: ${frameworkId} (use amplitude://docs/frameworks/${frameworkId} for documentation)`,
+            ];
+            if (context.settingsFile) {
+                lines.push(`Settings file: ${context.settingsFile}`);
+            }
+            return lines;
+        },
+    },
+    ui: {
+        successMessage: 'Amplitude integration complete',
+        estimatedDurationMinutes: 5,
+        getOutroChanges: (context) => {
+            const projectTypeName = context.projectType
+                ? (0, utils_1.getDjangoProjectTypeName)(context.projectType)
+                : 'Django';
+            return [
+                `Analyzed your ${projectTypeName} project structure`,
+                `Installed the Amplitude Python package`,
+                `Configured Amplitude in your Django settings`,
+                `Added Amplitude middleware for event tracking`,
+            ];
+        },
+        getOutroNextSteps: () => [
+            'Start your Django development server to see Amplitude in action',
+            'Visit your Amplitude dashboard to see incoming events',
+            'Use amplitude.track() to capture events and amplitude.identify() for users',
+        ],
+    },
+};

package/dist/src/frameworks/django/utils.d.ts

@@ -0,0 +1,31 @@
+import type { WizardOptions } from '../../utils/types';
+export declare enum DjangoProjectType {
+    STANDARD = "standard",// Traditional Django project (django-admin startproject)
+    DRF = "drf",// Django REST Framework API
+    WAGTAIL = "wagtail",// Wagtail CMS
+    CHANNELS = "channels"
+}
+/**
+ * Get Django version bucket for analytics
+ */
+export declare const getDjangoVersionBucket: (version: string | undefined) => string;
+/**
+ * Extract Django version from requirements files or pyproject.toml
+ */
+export declare function getDjangoVersion(options: Pick<WizardOptions, 'installDir'>): Promise<string | undefined>;
+/**
+ * Detect Django project type
+ */
+export declare function getDjangoProjectType(options: WizardOptions): Promise<DjangoProjectType>;
+/**
+ * Get human-readable name for Django project type
+ */
+export declare function getDjangoProjectTypeName(projectType: DjangoProjectType): string;
+/**
+ * Find the main Django settings file
+ */
+export declare function findDjangoSettingsFile(options: Pick<WizardOptions, 'installDir'>): Promise<string | undefined>;
+/**
+ * Find the main Django urls.py file
+ */
+export declare function findDjangoUrlsFile(options: Pick<WizardOptions, 'installDir'>): Promise<string | undefined>;