@amplitude/wizard 1.0.0-beta.0

package/dist/src/lib/safe-tools.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINTING_TOOLS = void 0;
+exports.LINTING_TOOLS = [
+    // All (general purpose)
+    'codespell',
+    'cspell',
+    'git-diff-check',
+    'gitleaks',
+    'trufflehog',
+    // Amazon States Language
+    'asl-validator',
+    // Ansible
+    'ansible-lint',
+    // Apex, Java
+    'pmd',
+    // Astro, CSS, GraphQL, GritQL, HTML, JavaScript, JSON, JSONC, JSON5, JSX, TSX, Svelte, TypeScript, Vue
+    'biome',
+    // AWS CloudFormation templates
+    'cfn-lint',
+    'cfnlint',
+    // AWS CloudFormation, Azure ARM, Dockerfile, Helm, Kubernetes, Security, Terraform
+    'checkov',
+    // AWS CloudFormation, Azure ARM, Dockerfile, Kubernetes, Secrets, Security, Terraform, Vulnerabilities
+    'trivy',
+    // Azure Resource Manager (ARM)
+    'test-aztemplate',
+    // Bash / Shell
+    'shellcheck',
+    'shfmt',
+    // Bazel, Starlark
+    'buildifier',
+    // C, C++
+    'cpplint',
+    'clang-format',
+    'clang-tidy',
+    'cmake-format',
+    'iwyu',
+    'pragma-once',
+    // C#, Dotnet (.NET)
+    'dotnet-format',
+    // CircleCI Config
+    'circleci',
+    // Clojure
+    'clj-kondo',
+    // CoffeeScript
+    'coffeelint',
+    // Commit messages
+    'commitlint',
+    // Copy/paste detection
+    'jscpd',
+    // CSS, SCSS, Sass
+    'stylelint',
+    // CSS, GraphQL, HTML, JavaScript, JSON, JSONC, JSON5, JSX, TSX, Markdown, TypeScript, Vue, YAML
+    'prettier',
+    // Cue
+    'cue-fmt',
+    // Dart
+    'dart',
+    // Dockerfile / Docker
+    'hadolint',
+    // Dotenv
+    'dotenv-linter',
+    // EditorConfig
+    'editorconfig-checker',
+    // GitHub Actions
+    'actionlint',
+    'zizmor',
+    // Go
+    'gofmt',
+    'gofumpt',
+    'goimports',
+    'gokart',
+    'golangci-lint',
+    'golines',
+    // Go, Java, JavaScript, JSON, Python, Ruby, TypeScript, YAML
+    'semgrep',
+    // GoReleaser
+    'goreleaser',
+    // GraphQL
+    'graphql-schema-linter',
+    // Groovy
+    'npm-groovy-lint',
+    // HAML
+    'haml-lint',
+    // HTML
+    'htmlhint',
+    // HTML Templates
+    'djlint',
+    // Java
+    'checkstyle',
+    'google-java-format',
+    // JavaScript, JSON, TypeScript
+    'eslint',
+    // Next.js
+    'next lint',
+    // JavaScript, JSON, Markdown, TypeScript
+    'deno',
+    // JavaScript, TypeScript
+    'rome',
+    // JSON, JSONC, JSON5
+    'eslint-plugin-jsonc',
+    'eslint-plugin-json',
+    // JSX, TSX
+    'eslint-plugin-jsx-a11y',
+    'eslint-plugin-react',
+    // Jupyter Notebook
+    'nbqa',
+    // Kotlin
+    'detekt',
+    'ktlint',
+    // Kubernetes
+    'kubeconform',
+    'kube-linter',
+    // LaTeX
+    'chktex',
+    // Lua
+    'luacheck',
+    'stylua',
+    // Markdown
+    'markdownlint',
+    'markdownlint-cli2',
+    'markdown-link-check',
+    'markdown-table-prettify',
+    'remark-lint',
+    // Natural language / Prose
+    'textlint',
+    'vale',
+    // Nix
+    'nixpkgs-fmt',
+    // OpenAPI
+    'spectral',
+    // package.json
+    'sort-package-json',
+    // Perl
+    'perlcritic',
+    'perltidy',
+    // PHP
+    'php-cs-fixer',
+    'phpcs',
+    'phpstan',
+    'psalm',
+    // PNG
+    'oxipng',
+    // PowerShell
+    'psscriptanalyzer',
+    // Prisma
+    'prisma',
+    // Protocol Buffers (Protobuf)
+    'protolint',
+    'buf',
+    // Python
+    'pylint',
+    'flake8',
+    'isort',
+    'ruff',
+    'black',
+    'autopep8',
+    'bandit',
+    'mypy',
+    'pyright',
+    'sourcery',
+    'yapf',
+    // R
+    'lintr',
+    // Rego
+    'opa',
+    'regal',
+    // Ruby
+    'rubocop',
+    'brakeman',
+    'rufo',
+    'standardrb',
+    // Rust
+    'clippy',
+    'rustfmt',
+    // Scala
+    'scalafmt',
+    // Security, Vulnerabilities
+    'osv-scanner',
+    // Security, Terraform
+    'terrascan',
+    'tfsec',
+    // Snakemake
+    'snakemake --lint',
+    'snakefmt',
+    // SQL
+    'sqlfluff',
+    'sql-formatter',
+    'sqlfmt',
+    'squawk',
+    // SVG
+    'svgo',
+    // Swift
+    'stringslint',
+    'swiftformat',
+    'swiftlint',
+    // Terraform
+    'tflint',
+    'terraform',
+    'tofu',
+    // Terragrunt
+    'terragrunt',
+    // Textproto
+    'txtpbfmt',
+    // TOML
+    'taplo',
+    // Vue
+    'eslint-plugin-vue',
+    // XML
+    'xmllint',
+    // YAML
+    'yamllint',
+];

package/dist/src/lib/wizard-session.d.ts

@@ -0,0 +1,220 @@
+/**
+ * WizardSession — single source of truth for every decision the wizard needs.
+ *
+ * Populated in layers:
+ *   CLI args / env vars  →  populate fields directly
+ *   Auto-detection       →  framework, typescript, package manager
+ *   TUI screens          →  region, framework disambiguation, etc.
+ *   OAuth                →  credentials
+ *
+ * Business logic reads from the session. Never calls a prompt.
+ */
+import type { Integration } from './constants';
+import type { FrameworkConfig } from './framework-config';
+export type CloudRegion = 'us' | 'eu';
+/** Lifecycle phase of the main work (agent run, MCP install, etc.) */
+export declare const RunPhase: {
+    /** Still gathering input (intro, setup screens) */
+    readonly Idle: "idle";
+    /** Main work is in progress */
+    readonly Running: "running";
+    /** Main work finished successfully */
+    readonly Completed: "completed";
+    /** Main work finished with an error */
+    readonly Error: "error";
+};
+export type RunPhase = (typeof RunPhase)[keyof typeof RunPhase];
+/** Features discovered by the feature-discovery subagent */
+export declare const DiscoveredFeature: {
+    readonly Stripe: "stripe";
+    readonly LLM: "llm";
+};
+export type DiscoveredFeature = (typeof DiscoveredFeature)[keyof typeof DiscoveredFeature];
+/** Additional features the agent can integrate after the main setup */
+export declare const AdditionalFeature: {
+    readonly LLM: "llm";
+};
+export type AdditionalFeature = (typeof AdditionalFeature)[keyof typeof AdditionalFeature];
+/** Human-readable labels for additional features (used in TUI progress) */
+export declare const ADDITIONAL_FEATURE_LABELS: Record<AdditionalFeature, string>;
+/** Agent prompts for each additional feature, injected via the stop hook */
+export declare const ADDITIONAL_FEATURE_PROMPTS: Record<AdditionalFeature, string>;
+/** Outcome of the MCP server installation step */
+export declare const McpOutcome: {
+    readonly NoClients: "no_clients";
+    readonly Skipped: "skipped";
+    readonly Installed: "installed";
+    readonly Failed: "failed";
+};
+export type McpOutcome = (typeof McpOutcome)[keyof typeof McpOutcome];
+/** Outcome of the Slack integration setup step */
+export declare const SlackOutcome: {
+    readonly Skipped: "skipped";
+    readonly Configured: "configured";
+};
+export type SlackOutcome = (typeof SlackOutcome)[keyof typeof SlackOutcome];
+/** Outcome kind for the outro screen */
+export declare const OutroKind: {
+    readonly Success: "success";
+    readonly Error: "error";
+    readonly Cancel: "cancel";
+};
+export type OutroKind = (typeof OutroKind)[keyof typeof OutroKind];
+export interface OutroData {
+    kind: OutroKind;
+    message?: string;
+    changes?: string[];
+    docsUrl?: string;
+    continueUrl?: string;
+    promptLogin?: boolean;
+    canRestart?: boolean;
+}
+export interface WizardSession {
+    debug: boolean;
+    verbose: boolean;
+    forceInstall: boolean;
+    installDir: string;
+    ci: boolean;
+    signup: boolean;
+    localMcp: boolean;
+    apiKey?: string;
+    menu: boolean;
+    benchmark: boolean;
+    projectId?: number;
+    setupConfirmed: boolean;
+    integration: Integration | null;
+    frameworkContext: Record<string, unknown>;
+    typescript: boolean;
+    /** Human-readable label for the detected framework variant (e.g., "Django with Wagtail CMS") */
+    detectedFrameworkLabel: string | null;
+    /** True once framework detection has run (whether it found something or not) */
+    detectionComplete: boolean;
+    /**
+     * Whether the currently selected project has existing event data.
+     * null = not yet checked (shown as DataSetup screen)
+     * false = no data → route to Framework Detection
+     * true = has data → route to Options menu
+     */
+    projectHasData: boolean | null;
+    /**
+     * Activation level determined by the API check.
+     * null  = not yet checked
+     * 'none'    = 0 events, snippet not configured → Framework Detection
+     * 'partial' = 1–49 events or snippet installed but limited events → ActivationOptions
+     * 'full'    = well-established data (50+ events) → Options
+     */
+    activationLevel: 'none' | 'partial' | 'full' | null;
+    /** True once the user has responded to the ActivationOptions screen. */
+    activationOptionsComplete: boolean;
+    /** Whether the SDK snippet is installed in the project (set by DataSetupScreen). */
+    snippetConfigured: boolean;
+    /**
+     * Amplitude data-center region chosen by the user.
+     * null = not yet selected (shown as RegionSelect screen)
+     * 'us' = US region (api.amplitude.com)
+     * 'eu' = EU region (api.eu.amplitude.com)
+     */
+    region: CloudRegion | null;
+    /**
+     * True when the /region slash command forces RegionSelect to re-appear.
+     * Cleared once the user picks a region. After re-selection, projectHasData
+     * is reset to null so the data setup step re-runs for the new region.
+     */
+    regionForced: boolean;
+    /**
+     * Orgs available after OAuth completes, before the user selects one.
+     * null = OAuth not yet done (AuthScreen shows spinner)
+     * [...] = OAuth done, AuthScreen showing org/workspace/key selection
+     */
+    pendingOrgs: Array<{
+        id: string;
+        name: string;
+        workspaces: Array<{
+            id: string;
+            name: string;
+        }>;
+    }> | null;
+    /** OAuth id_token held during SUSI account-setup steps. */
+    pendingAuthIdToken: string | null;
+    /** OAuth access_token held during SUSI — used for Hydra-validated proxy auth. */
+    pendingAuthAccessToken: string | null;
+    /** Cloud region detected from the OAuth token. Drives RegionSelect auto-skip. */
+    pendingAuthCloudRegion: CloudRegion | null;
+    /** Org selected during SUSI (written to ampli.json). */
+    selectedOrgId: string | null;
+    selectedOrgName: string | null;
+    /** Workspace selected during SUSI (written to ampli.json). */
+    selectedWorkspaceId: string | null;
+    selectedWorkspaceName: string | null;
+    /**
+     * Notice shown on the API key entry step of AuthScreen.
+     * Set when auto-fetch fails (e.g. user is not an org admin) so the user
+     * understands why manual entry is required.
+     */
+    apiKeyNotice: string | null;
+    credentials: {
+        accessToken: string;
+        /** id_token from OAuth — used for Amplitude Data API / Thunder calls */
+        idToken?: string;
+        projectApiKey: string;
+        host: string;
+        projectId: number;
+    } | null;
+    runPhase: RunPhase;
+    loginUrl: string | null;
+    discoveredFeatures: DiscoveredFeature[];
+    llmOptIn: boolean;
+    /** True once the user has clicked Continue on the IntroScreen. */
+    introConcluded: boolean;
+    mcpComplete: boolean;
+    mcpOutcome: McpOutcome | null;
+    mcpInstalledClients: string[];
+    slackComplete: boolean;
+    slackOutcome: SlackOutcome | null;
+    serviceStatus: {
+        description: string;
+        statusPageUrl: string;
+    } | null;
+    settingsOverrideKeys: string[] | null;
+    outroData: OutroData | null;
+    additionalFeatureQueue: AdditionalFeature[];
+    frameworkConfig: FrameworkConfig | null;
+    /**
+     * True when the agent run was skipped because Amplitude was already
+     * detected in the project via static analysis. Set in bin.ts before
+     * runPhase is set to Completed.
+     */
+    amplitudePreDetected: boolean;
+    /**
+     * True once the activation check confirms events are flowing into the project.
+     * Set immediately if activationLevel is already 'full', otherwise set after
+     * the DataIngestionCheckScreen detects events via the API.
+     */
+    dataIngestionConfirmed: boolean;
+    /** Checklist item: whether the user's first chart has been created. */
+    checklistChartComplete: boolean;
+    /** Checklist item: whether the user's first dashboard has been created. */
+    checklistDashboardComplete: boolean;
+    /**
+     * True once the user has dismissed the checklist (either all items done,
+     * or they chose to continue without completing everything).
+     */
+    checklistComplete: boolean;
+}
+/**
+ * Build a WizardSession from CLI args, pre-populating whatever is known.
+ */
+export declare function buildSession(args: {
+    debug?: boolean;
+    verbose?: boolean;
+    forceInstall?: boolean;
+    installDir?: string;
+    ci?: boolean;
+    signup?: boolean;
+    localMcp?: boolean;
+    apiKey?: string;
+    menu?: boolean;
+    integration?: Integration;
+    benchmark?: boolean;
+    projectId?: string;
+}): WizardSession;

package/dist/src/lib/wizard-session.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * WizardSession — single source of truth for every decision the wizard needs.
+ *
+ * Populated in layers:
+ *   CLI args / env vars  →  populate fields directly
+ *   Auto-detection       →  framework, typescript, package manager
+ *   TUI screens          →  region, framework disambiguation, etc.
+ *   OAuth                →  credentials
+ *
+ * Business logic reads from the session. Never calls a prompt.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutroKind = exports.SlackOutcome = exports.McpOutcome = exports.ADDITIONAL_FEATURE_PROMPTS = exports.ADDITIONAL_FEATURE_LABELS = exports.AdditionalFeature = exports.DiscoveredFeature = exports.RunPhase = void 0;
+exports.buildSession = buildSession;
+function parseProjectIdArg(value) {
+    if (value === undefined || value === '')
+        return undefined;
+    const n = Number(value);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+/** Lifecycle phase of the main work (agent run, MCP install, etc.) */
+exports.RunPhase = {
+    /** Still gathering input (intro, setup screens) */
+    Idle: 'idle',
+    /** Main work is in progress */
+    Running: 'running',
+    /** Main work finished successfully */
+    Completed: 'completed',
+    /** Main work finished with an error */
+    Error: 'error',
+};
+/** Features discovered by the feature-discovery subagent */
+exports.DiscoveredFeature = {
+    Stripe: 'stripe',
+    LLM: 'llm',
+};
+/** Additional features the agent can integrate after the main setup */
+exports.AdditionalFeature = {
+    LLM: 'llm',
+};
+/** Human-readable labels for additional features (used in TUI progress) */
+exports.ADDITIONAL_FEATURE_LABELS = {
+    [exports.AdditionalFeature.LLM]: 'LLM analytics',
+};
+/** Agent prompts for each additional feature, injected via the stop hook */
+exports.ADDITIONAL_FEATURE_PROMPTS = {
+    [exports.AdditionalFeature.LLM]: `Now integrate LLM analytics with Amplitude. Use the Amplitude MCP server to find the appropriate LLM analytics skill, install it, and follow its workflow. Amplitude basics are already installed. Update the setup report markdown file when complete with additions from this task. `,
+};
+/** Outcome of the MCP server installation step */
+exports.McpOutcome = {
+    NoClients: 'no_clients',
+    Skipped: 'skipped',
+    Installed: 'installed',
+    Failed: 'failed',
+};
+/** Outcome of the Slack integration setup step */
+exports.SlackOutcome = {
+    Skipped: 'skipped',
+    Configured: 'configured',
+};
+/** Outcome kind for the outro screen */
+exports.OutroKind = {
+    Success: 'success',
+    Error: 'error',
+    Cancel: 'cancel',
+};
+/**
+ * Build a WizardSession from CLI args, pre-populating whatever is known.
+ */
+function buildSession(args) {
+    return {
+        debug: args.debug ?? false,
+        verbose: args.verbose ?? false,
+        forceInstall: args.forceInstall ?? false,
+        installDir: args.installDir ?? process.cwd(),
+        ci: args.ci ?? false,
+        signup: args.signup ?? false,
+        localMcp: args.localMcp ?? false,
+        apiKey: args.apiKey,
+        menu: args.menu ?? false,
+        benchmark: args.benchmark ?? false,
+        projectId: parseProjectIdArg(args.projectId),
+        setupConfirmed: false,
+        integration: args.integration ?? null,
+        frameworkContext: {},
+        typescript: false,
+        detectedFrameworkLabel: null,
+        detectionComplete: false,
+        projectHasData: null,
+        activationLevel: null,
+        activationOptionsComplete: false,
+        snippetConfigured: false,
+        region: null,
+        regionForced: false,
+        runPhase: exports.RunPhase.Idle,
+        discoveredFeatures: [],
+        llmOptIn: false,
+        mcpComplete: false,
+        mcpOutcome: null,
+        mcpInstalledClients: [],
+        slackComplete: false,
+        slackOutcome: null,
+        pendingOrgs: null,
+        pendingAuthIdToken: null,
+        pendingAuthAccessToken: null,
+        pendingAuthCloudRegion: null,
+        selectedOrgId: null,
+        selectedOrgName: null,
+        selectedWorkspaceId: null,
+        selectedWorkspaceName: null,
+        loginUrl: null,
+        credentials: null,
+        apiKeyNotice: null,
+        serviceStatus: null,
+        settingsOverrideKeys: null,
+        outroData: null,
+        introConcluded: false,
+        additionalFeatureQueue: [],
+        frameworkConfig: null,
+        amplitudePreDetected: false,
+        dataIngestionConfirmed: false,
+        checklistChartComplete: false,
+        checklistDashboardComplete: false,
+        checklistComplete: false,
+    };
+}

package/dist/src/lib/wizard-tools.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Unified in-process MCP server for the Amplitude wizard.
+ *
+ * Provides tools that run locally (secret values never leave the machine):
+ * - check_env_keys: Check which env var keys exist in a .env file
+ * - set_env_values: Create/update env vars in a .env file
+ * - detect_package_manager: Detect the project's package manager(s)
+ */
+import type { PackageManagerDetector } from './package-manager-detection';
+export type SkillEntry = {
+    id: string;
+    name: string;
+    downloadUrl: string;
+};
+export interface SkillMenu {
+    categories: Record<string, SkillEntry[]>;
+}
+/**
+ * Fetch the skill menu from a remote skills server (GitHub Releases).
+ * Returns parsed data on success, `null` on failure.
+ */
+export declare function fetchSkillMenu(skillsBaseUrl: string): Promise<SkillMenu | null>;
+/**
+ * Download and extract a skill from a remote URL.
+ * Installs to `<installDir>/.claude/skills/<id>/`.
+ */
+export declare function downloadSkill(skillEntry: SkillEntry, installDir: string): {
+    success: boolean;
+    error?: string;
+};
+/**
+ * Build skill menu from bundled skill directories.
+ * Scans skills/<category>/ subdirectories for folders containing SKILL.md.
+ * Each subdirectory of skills/ becomes a category (e.g. integration, instrumentation).
+ */
+export declare function loadBundledSkillMenu(): SkillMenu;
+/**
+ * Install a bundled skill by copying it to the project's .claude/skills/ dir.
+ * Searches across all category subdirectories under skills/.
+ */
+export declare function installBundledSkill(skillId: string, installDir: string): {
+    success: boolean;
+    error?: string;
+};
+export interface WizardToolsOptions {
+    /** Root directory of the project being analyzed */
+    workingDirectory: string;
+    /** Framework-specific package manager detector */
+    detectPackageManager: PackageManagerDetector;
+    /**
+     * Remote skills server URL (e.g. GitHub Releases base URL).
+     * When set, skills are fetched from this URL instead of bundled files.
+     * Set via SKILLS_URL env var or pass directly.
+     * Example: https://github.com/amplitude/context-hub/releases/latest/download
+     */
+    skillsBaseUrl?: string;
+}
+/**
+ * Resolve filePath relative to workingDirectory, rejecting path traversal.
+ */
+export declare function resolveEnvPath(workingDirectory: string, filePath: string): string;
+/**
+ * Ensure the given env file basename is covered by .gitignore in the working directory.
+ * Creates .gitignore if it doesn't exist; appends the entry if missing.
+ */
+export declare function ensureGitignoreCoverage(workingDirectory: string, envFileName: string): void;
+/**
+ * Parse a .env file's content and return the set of defined key names.
+ */
+export declare function parseEnvKeys(content: string): Set<string>;
+/**
+ * Merge key-value pairs into existing .env content.
+ * Updates existing keys in-place, appends new keys at the end.
+ */
+export declare function mergeEnvValues(content: string, values: Record<string, string>): string;
+/**
+ * Create the unified in-process MCP server with all wizard tools.
+ * Must be called asynchronously because the SDK is an ESM module loaded via dynamic import.
+ */
+export declare function createWizardToolsServer(options: WizardToolsOptions): Promise<unknown>;
+/** Tool names exposed by the wizard-tools server, for use in allowedTools */
+export declare const WIZARD_TOOL_NAMES: string[];