@amplitude/wizard 1.0.0-beta.0

package/dist/src/lib/middleware/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Middleware system types for wizard agent runs.
+ *
+ * Middleware receives lifecycle events (messages, phase transitions, finalize)
+ * and can publish data to a shared store for downstream middleware to read.
+ */
+import type { SpinnerHandle } from '../../ui';
+/** Token usage reported by the SDK on assistant messages */
+export interface SDKUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_creation?: {
+        ephemeral_5m_input_tokens?: number;
+        ephemeral_1h_input_tokens?: number;
+    };
+    total_cost_usd?: number;
+}
+export interface SDKContentBlock {
+    type: string;
+    text?: string;
+    name?: string;
+    input?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface SDKModelUsageEntry {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+}
+export interface SDKCompactMetadata {
+    pre_tokens?: number;
+    trigger?: string;
+}
+/** SDK message received from the agent runner */
+export interface SDKMessage {
+    type: string;
+    subtype?: string;
+    message?: {
+        id?: string;
+        usage?: SDKUsage;
+        content?: SDKContentBlock[];
+        [key: string]: unknown;
+    };
+    compact_metadata?: SDKCompactMetadata;
+    is_error?: boolean;
+    result?: string;
+    errors?: string[];
+    model?: string;
+    tools?: unknown[];
+    mcp_servers?: {
+        name: string;
+        status: string;
+    }[];
+    usage?: SDKUsage;
+    total_cost_usd?: number;
+    num_turns?: number;
+    modelUsage?: Record<string, SDKModelUsageEntry>;
+    [key: string]: unknown;
+}
+/** Read-only shared state available to all middleware */
+export interface MiddlewareContext {
+    /** Current detected phase name */
+    readonly currentPhase: string;
+    /** Whether the current phase started with fresh context (new query) */
+    readonly currentPhaseFreshContext: boolean;
+    /** Read a value from the shared store (published by upstream middleware) */
+    get<T>(key: string): T | undefined;
+}
+/** Write handle for middleware to publish data to the shared store */
+export interface MiddlewareStore {
+    set(key: string, value: unknown): void;
+}
+/** Lifecycle hooks a middleware can implement */
+export interface Middleware {
+    /** Unique name for this middleware (used in config and store keys) */
+    readonly name: string;
+    /** Called once when the pipeline initializes */
+    onInit?(ctx: MiddlewareContext): void;
+    /** Called for every SDK message */
+    onMessage?(message: SDKMessage, ctx: MiddlewareContext, store: MiddlewareStore): void;
+    /** Called when a phase transition is detected */
+    onPhaseTransition?(fromPhase: string, toPhase: string, ctx: MiddlewareContext, store: MiddlewareStore): void;
+    /** Called at the end of the agent run. Return value from last middleware is used. */
+    onFinalize?(resultMessage: SDKMessage, totalDurationMs: number, ctx: MiddlewareContext, store: MiddlewareStore): unknown;
+}
+/** Options bag passed to middleware factories during construction */
+export interface MiddlewareFactoryOptions {
+    spinner?: SpinnerHandle;
+    outputPath?: string;
+    phased?: boolean;
+}

package/dist/src/lib/middleware/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Middleware system types for wizard agent runs.
+ *
+ * Middleware receives lifecycle events (messages, phase transitions, finalize)
+ * and can publish data to a shared store for downstream middleware to read.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/lib/package-manager-detection.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Cross-ecosystem package manager detection.
+ *
+ * Provides a common interface (PackageManagerDetector) that each FrameworkConfig
+ * implements, plus shared helpers for Node.js, Python, PHP, and Swift ecosystems.
+ * The MCP tool in wizard-tools.ts delegates to whatever detector the
+ * current framework supplies.
+ */
+/** Structured package manager info the agent can act on */
+export interface DetectedPackageManager {
+    name: string;
+    label: string;
+    installCommand: string;
+    runCommand?: string;
+}
+/** Result returned by every detector */
+export interface PackageManagerInfo {
+    detected: DetectedPackageManager[];
+    primary: DetectedPackageManager | null;
+    recommendation: string;
+}
+/** Signature each framework implements */
+export type PackageManagerDetector = (installDir: string) => Promise<PackageManagerInfo>;
+/**
+ * Detect Node.js package managers via lockfiles.
+ * Wraps the existing detectAllPackageManagers() from utils/package-manager.ts.
+ */
+export declare function detectNodePackageManagers(installDir: string): Promise<PackageManagerInfo>;
+/**
+ * Detect Python package managers via lockfiles and config files.
+ * Wraps the existing detectPackageManager() from python/utils.ts.
+ */
+export declare function detectPythonPackageManagers(installDir: string): Promise<PackageManagerInfo>;
+export declare function composerPackageManager(): Promise<PackageManagerInfo>;
+export declare function swiftPackageManager(): Promise<PackageManagerInfo>;
+export declare function detectJavaPackageManagers(installDir: string): Promise<PackageManagerInfo>;
+export declare function flutterPackageManager(): Promise<PackageManagerInfo>;
+export declare function goPackageManager(): Promise<PackageManagerInfo>;
+export declare function unityPackageManager(): Promise<PackageManagerInfo>;
+export declare function unrealPackageManager(): Promise<PackageManagerInfo>;
+export declare function bundlerPackageManager(): Promise<PackageManagerInfo>;
+export declare function gradlePackageManager(): Promise<PackageManagerInfo>;

package/dist/src/lib/package-manager-detection.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * Cross-ecosystem package manager detection.
+ *
+ * Provides a common interface (PackageManagerDetector) that each FrameworkConfig
+ * implements, plus shared helpers for Node.js, Python, PHP, and Swift ecosystems.
+ * The MCP tool in wizard-tools.ts delegates to whatever detector the
+ * current framework supplies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectNodePackageManagers = detectNodePackageManagers;
+exports.detectPythonPackageManagers = detectPythonPackageManagers;
+exports.composerPackageManager = composerPackageManager;
+exports.swiftPackageManager = swiftPackageManager;
+exports.detectJavaPackageManagers = detectJavaPackageManagers;
+exports.flutterPackageManager = flutterPackageManager;
+exports.goPackageManager = goPackageManager;
+exports.unityPackageManager = unityPackageManager;
+exports.unrealPackageManager = unrealPackageManager;
+exports.bundlerPackageManager = bundlerPackageManager;
+exports.gradlePackageManager = gradlePackageManager;
+const package_manager_1 = require("../utils/package-manager");
+const utils_1 = require("../frameworks/python/utils");
+// ---------------------------------------------------------------------------
+// Node.js helper
+// ---------------------------------------------------------------------------
+function serializeNodePM(pm) {
+    return {
+        name: pm.name,
+        label: pm.label,
+        installCommand: pm.installCommand,
+        runCommand: pm.runScriptCommand,
+    };
+}
+/**
+ * Detect Node.js package managers via lockfiles.
+ * Wraps the existing detectAllPackageManagers() from utils/package-manager.ts.
+ */
+function detectNodePackageManagers(installDir) {
+    const detected = (0, package_manager_1.detectAllPackageManagers)({ installDir }).map(serializeNodePM);
+    if (detected.length === 0) {
+        return Promise.resolve({
+            detected: [],
+            primary: null,
+            recommendation: 'No lockfile found. Default to npm (npm add, npm run).',
+        });
+    }
+    const primary = detected[0];
+    return Promise.resolve({
+        detected,
+        primary,
+        recommendation: detected.length === 1
+            ? `Use ${primary.label} (${primary.installCommand}).`
+            : `Multiple package managers detected. Prefer ${primary.label} (${primary.installCommand}).`,
+    });
+}
+// ---------------------------------------------------------------------------
+// Python helper
+// ---------------------------------------------------------------------------
+const PYTHON_PM_INFO = {
+    [utils_1.PythonPackageManager.UV]: {
+        name: 'uv',
+        label: 'uv',
+        installCommand: 'uv add',
+        runCommand: 'uv run',
+    },
+    [utils_1.PythonPackageManager.POETRY]: {
+        name: 'poetry',
+        label: 'Poetry',
+        installCommand: 'poetry add',
+        runCommand: 'poetry run',
+    },
+    [utils_1.PythonPackageManager.PDM]: {
+        name: 'pdm',
+        label: 'PDM',
+        installCommand: 'pdm add',
+        runCommand: 'pdm run',
+    },
+    [utils_1.PythonPackageManager.HATCH]: {
+        name: 'hatch',
+        label: 'Hatch',
+        installCommand: 'hatch add',
+        runCommand: 'hatch run',
+    },
+    [utils_1.PythonPackageManager.RYE]: {
+        name: 'rye',
+        label: 'Rye',
+        installCommand: 'rye add',
+        runCommand: 'rye run',
+    },
+    [utils_1.PythonPackageManager.PIPENV]: {
+        name: 'pipenv',
+        label: 'Pipenv',
+        installCommand: 'pipenv install',
+        runCommand: 'pipenv run',
+    },
+    [utils_1.PythonPackageManager.CONDA]: {
+        name: 'conda',
+        label: 'Conda',
+        installCommand: 'conda install',
+        runCommand: 'conda run',
+    },
+    [utils_1.PythonPackageManager.PIP]: {
+        name: 'pip',
+        label: 'pip',
+        installCommand: 'pip install',
+    },
+    [utils_1.PythonPackageManager.UNKNOWN]: {
+        name: 'pip',
+        label: 'pip (default)',
+        installCommand: 'pip install',
+    },
+};
+/**
+ * Detect Python package managers via lockfiles and config files.
+ * Wraps the existing detectPackageManager() from python/utils.ts.
+ */
+async function detectPythonPackageManagers(installDir) {
+    const pm = await (0, utils_1.detectPackageManager)({
+        installDir,
+    });
+    const info = PYTHON_PM_INFO[pm];
+    return {
+        detected: [info],
+        primary: info,
+        recommendation: `Use ${info.label} (${info.installCommand}).`,
+    };
+}
+// ---------------------------------------------------------------------------
+// PHP (Composer) helper
+// ---------------------------------------------------------------------------
+const COMPOSER = {
+    name: 'composer',
+    label: 'Composer',
+    installCommand: 'composer require',
+};
+function composerPackageManager() {
+    return Promise.resolve({
+        detected: [COMPOSER],
+        primary: COMPOSER,
+        recommendation: 'Use Composer (composer require).',
+    });
+}
+// ---------------------------------------------------------------------------
+// Swift (SPM) helper
+// ---------------------------------------------------------------------------
+const SPM = {
+    name: 'spm',
+    label: 'Swift Package Manager',
+    installCommand: 'swift package add-dependency',
+};
+function swiftPackageManager() {
+    return Promise.resolve({
+        detected: [SPM],
+        primary: SPM,
+        recommendation: 'Use Swift Package Manager. Add the dependency to Package.swift or via Xcode.',
+    });
+}
+// ---------------------------------------------------------------------------
+// Java (Maven / Gradle) helper
+// ---------------------------------------------------------------------------
+const MAVEN = {
+    name: 'maven',
+    label: 'Maven',
+    installCommand: 'mvn',
+    runCommand: 'mvn exec:java',
+};
+const GRADLE_JAVA = {
+    name: 'gradle',
+    label: 'Gradle',
+    installCommand: 'gradle',
+    runCommand: 'gradle run',
+};
+async function detectJavaPackageManagers(installDir) {
+    const fs = await import('node:fs');
+    const nodePath = await import('node:path');
+    const hasMaven = fs.existsSync(nodePath.join(installDir, 'pom.xml'));
+    const hasGradle = fs.existsSync(nodePath.join(installDir, 'build.gradle')) ||
+        fs.existsSync(nodePath.join(installDir, 'build.gradle.kts'));
+    if (hasMaven) {
+        return {
+            detected: [MAVEN],
+            primary: MAVEN,
+            recommendation: 'Use Maven: add the dependency to pom.xml and run mvn install.',
+        };
+    }
+    if (hasGradle) {
+        return {
+            detected: [GRADLE_JAVA],
+            primary: GRADLE_JAVA,
+            recommendation: 'Use Gradle: add the implementation dependency to build.gradle and sync.',
+        };
+    }
+    return {
+        detected: [MAVEN],
+        primary: MAVEN,
+        recommendation: 'No build file detected. Defaulting to Maven.',
+    };
+}
+// ---------------------------------------------------------------------------
+// Flutter (pub) helper
+// ---------------------------------------------------------------------------
+const FLUTTER_PUB = {
+    name: 'flutter',
+    label: 'Flutter pub',
+    installCommand: 'flutter pub add',
+    runCommand: 'flutter pub run',
+};
+function flutterPackageManager() {
+    return Promise.resolve({
+        detected: [FLUTTER_PUB],
+        primary: FLUTTER_PUB,
+        recommendation: 'Use Flutter pub (flutter pub add).',
+    });
+}
+// ---------------------------------------------------------------------------
+// Go (modules) helper
+// ---------------------------------------------------------------------------
+const GO_MODULES = {
+    name: 'go',
+    label: 'Go modules',
+    installCommand: 'go get',
+    runCommand: 'go run',
+};
+function goPackageManager() {
+    return Promise.resolve({
+        detected: [GO_MODULES],
+        primary: GO_MODULES,
+        recommendation: 'Use Go modules (go get).',
+    });
+}
+// ---------------------------------------------------------------------------
+// Unity (UPM) helper
+// ---------------------------------------------------------------------------
+const UNITY_UPM = {
+    name: 'unity',
+    label: 'Unity Package Manager',
+    installCommand: 'Add to Packages/manifest.json dependencies: "com.amplitude.unity-plugin": "https://github.com/amplitude/unity-plugin.git?path=/Assets"',
+};
+function unityPackageManager() {
+    return Promise.resolve({
+        detected: [UNITY_UPM],
+        primary: UNITY_UPM,
+        recommendation: 'Use Unity Package Manager: add the git URL dependency to Packages/manifest.json.',
+    });
+}
+// ---------------------------------------------------------------------------
+// Unreal Engine helper
+// ---------------------------------------------------------------------------
+const UNREAL_MANUAL = {
+    name: 'unreal',
+    label: 'Manual plugin install',
+    installCommand: 'Download AmplitudeUnreal.zip from https://github.com/amplitude/Amplitude-Unreal/releases/latest and extract into Plugins/AmplitudeUnreal/',
+};
+function unrealPackageManager() {
+    return Promise.resolve({
+        detected: [UNREAL_MANUAL],
+        primary: UNREAL_MANUAL,
+        recommendation: 'Unreal Engine uses manual plugin installation. Download the zip from GitHub releases and extract it into the project Plugins/ directory.',
+    });
+}
+// ---------------------------------------------------------------------------
+// Ruby (Bundler) helper
+// ---------------------------------------------------------------------------
+const BUNDLER = {
+    name: 'bundler',
+    label: 'Bundler',
+    installCommand: 'bundle add',
+    runCommand: 'bundle exec',
+};
+function bundlerPackageManager() {
+    return Promise.resolve({
+        detected: [BUNDLER],
+        primary: BUNDLER,
+        recommendation: 'Use Bundler (bundle add). Run commands with bundle exec.',
+    });
+}
+// ---------------------------------------------------------------------------
+// Android (Gradle) helper
+// ---------------------------------------------------------------------------
+const GRADLE = {
+    name: 'gradle',
+    label: 'Gradle',
+    installCommand: 'implementation',
+};
+function gradlePackageManager() {
+    return Promise.resolve({
+        detected: [GRADLE],
+        primary: GRADLE,
+        recommendation: 'Add dependencies to build.gradle(.kts) using implementation().',
+    });
+}

package/dist/src/lib/registry.d.ts

@@ -0,0 +1,3 @@
+import type { FrameworkConfig } from './framework-config';
+import { Integration } from './constants';
+export declare const FRAMEWORK_REGISTRY: Record<Integration, FrameworkConfig>;

package/dist/src/lib/registry.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRAMEWORK_REGISTRY = void 0;
+const constants_1 = require("./constants");
+const nextjs_wizard_agent_1 = require("../frameworks/nextjs/nextjs-wizard-agent");
+const vue_wizard_agent_1 = require("../frameworks/vue/vue-wizard-agent");
+const react_router_wizard_agent_1 = require("../frameworks/react-router/react-router-wizard-agent");
+const django_wizard_agent_1 = require("../frameworks/django/django-wizard-agent");
+const flask_wizard_agent_1 = require("../frameworks/flask/flask-wizard-agent");
+const fastapi_wizard_agent_1 = require("../frameworks/fastapi/fastapi-wizard-agent");
+const swift_wizard_agent_1 = require("../frameworks/swift/swift-wizard-agent");
+const react_native_wizard_agent_1 = require("../frameworks/react-native/react-native-wizard-agent");
+const android_wizard_agent_1 = require("../frameworks/android/android-wizard-agent");
+const flutter_wizard_agent_1 = require("../frameworks/flutter/flutter-wizard-agent");
+const go_wizard_agent_1 = require("../frameworks/go/go-wizard-agent");
+const java_wizard_agent_1 = require("../frameworks/java/java-wizard-agent");
+const unreal_wizard_agent_1 = require("../frameworks/unreal/unreal-wizard-agent");
+const unity_wizard_agent_1 = require("../frameworks/unity/unity-wizard-agent");
+const python_wizard_agent_1 = require("../frameworks/python/python-wizard-agent");
+const javascript_node_wizard_agent_1 = require("../frameworks/javascript-node/javascript-node-wizard-agent");
+const javascript_web_wizard_agent_1 = require("../frameworks/javascript-web/javascript-web-wizard-agent");
+const generic_wizard_agent_1 = require("../frameworks/generic/generic-wizard-agent");
+exports.FRAMEWORK_REGISTRY = {
+    [constants_1.Integration.nextjs]: nextjs_wizard_agent_1.NEXTJS_AGENT_CONFIG,
+    [constants_1.Integration.vue]: vue_wizard_agent_1.VUE_AGENT_CONFIG,
+    [constants_1.Integration.reactRouter]: react_router_wizard_agent_1.REACT_ROUTER_AGENT_CONFIG,
+    [constants_1.Integration.django]: django_wizard_agent_1.DJANGO_AGENT_CONFIG,
+    [constants_1.Integration.flask]: flask_wizard_agent_1.FLASK_AGENT_CONFIG,
+    [constants_1.Integration.fastapi]: fastapi_wizard_agent_1.FASTAPI_AGENT_CONFIG,
+    [constants_1.Integration.swift]: swift_wizard_agent_1.SWIFT_AGENT_CONFIG,
+    [constants_1.Integration.reactNative]: react_native_wizard_agent_1.REACT_NATIVE_AGENT_CONFIG,
+    [constants_1.Integration.android]: android_wizard_agent_1.ANDROID_AGENT_CONFIG,
+    [constants_1.Integration.flutter]: flutter_wizard_agent_1.FLUTTER_AGENT_CONFIG,
+    [constants_1.Integration.go]: go_wizard_agent_1.GO_AGENT_CONFIG,
+    [constants_1.Integration.java]: java_wizard_agent_1.JAVA_AGENT_CONFIG,
+    [constants_1.Integration.unreal]: unreal_wizard_agent_1.UNREAL_AGENT_CONFIG,
+    [constants_1.Integration.unity]: unity_wizard_agent_1.UNITY_AGENT_CONFIG,
+    [constants_1.Integration.python]: python_wizard_agent_1.PYTHON_AGENT_CONFIG,
+    [constants_1.Integration.javascriptNode]: javascript_node_wizard_agent_1.JAVASCRIPT_NODE_AGENT_CONFIG,
+    [constants_1.Integration.javascript_web]: javascript_web_wizard_agent_1.JAVASCRIPT_WEB_AGENT_CONFIG,
+    [constants_1.Integration.generic]: generic_wizard_agent_1.GENERIC_AGENT_CONFIG,
+};

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

@@ -0,0 +1,2 @@
+export declare const LINTING_TOOLS: string[];
+export type LintingTool = (typeof LINTING_TOOLS)[number];