humanbehavior-js 0.7.0 → 0.8.0-beta.0

package/packages/wizard/dist/cli/ai-auto-install.js

@@ -2,6 +2,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
+import { query } from '@anthropic-ai/claude-agent-sdk';
 import * as clack from '@clack/prompts';
 
 /**
@@ -10,12 +11,18 @@ import * as clack from '@clack/prompts';
  * This wizard automatically detects the user's framework and modifies their codebase
  * to integrate the SDK with minimal user intervention.
  */
+const MIN_SUPPORTED_SDK_VERSION = '0.7.0';
+const TESTED_SDK_VERSION = '0.7.0';
 class AutoInstallationWizard {
-    constructor(apiKey, projectRoot = process.cwd()) {
+    constructor(apiKey, projectRoot = process.cwd(), options = {}) {
         this.framework = null;
         this.manualNotes = [];
         this.apiKey = apiKey;
-        this.projectRoot = projectRoot;
+        this.projectRoot = path.resolve(projectRoot);
+        this.options = options;
+    }
+    setAgentPlan(agentPlan) {
+        this.options.agentPlan = agentPlan;
     }
     /**
      * Simple version comparison utility
@@ -46,11 +53,13 @@ class AutoInstallationWizard {
         try {
             // Step 1: Detect framework
             this.framework = await this.detectFramework();
-            // Step 2: Install package
-            await this.installPackage();
+            // Step 2: Plan and optionally install package
+            const installPlan = await this.installPackage();
             // Step 3: Generate and apply code modifications
             const modifications = await this.generateModifications();
-            await this.applyModifications(modifications);
+            if (!this.options.dryRun) {
+                await this.applyModifications(modifications);
+            }
             // Step 4: Generate next steps
             const nextSteps = this.generateNextSteps();
             return {
@@ -58,7 +67,10 @@ class AutoInstallationWizard {
                 framework: this.framework,
                 modifications,
                 errors: [],
-                nextSteps
+                nextSteps,
+                dryRun: this.options.dryRun,
+                installPlan,
+                agentPlan: this.options.agentPlan
             };
         }
         catch (error) {
@@ -67,7 +79,9 @@ class AutoInstallationWizard {
                 framework: this.framework || { name: 'unknown', type: 'vanilla' },
                 modifications: [],
                 errors: [error instanceof Error ? error.message : 'Unknown error'],
-                nextSteps: []
+                nextSteps: [],
+                dryRun: this.options.dryRun,
+                agentPlan: this.options.agentPlan
             };
         }
     }
@@ -243,38 +257,212 @@ class AutoInstallationWizard {
         else if (dependencies.rollup) {
             framework.bundler = 'rollup';
         }
-        // Detect package manager
-        if (fs.existsSync(path.join(this.projectRoot, 'yarn.lock'))) {
-            framework.packageManager = 'yarn';
-        }
-        else if (fs.existsSync(path.join(this.projectRoot, 'pnpm-lock.yaml'))) {
-            framework.packageManager = 'pnpm';
-        }
-        else {
-            framework.packageManager = 'npm';
-        }
+        framework.packageManager = this.detectPackageManager(this.projectRoot);
         return framework;
     }
     /**
      * Install the SDK package with latest version range
      */
     async installPackage() {
-        // Build base command with latest version range
-        let command = this.framework?.packageManager === 'yarn'
-            ? 'yarn add humanbehavior-js@latest'
-            : this.framework?.packageManager === 'pnpm'
-                ? 'pnpm add humanbehavior-js@latest'
-                : 'npm install humanbehavior-js@latest';
-        // Add legacy peer deps flag for npm to handle dependency conflicts
-        if (this.framework?.packageManager !== 'yarn' && this.framework?.packageManager !== 'pnpm') {
-            command += ' --legacy-peer-deps';
+        const plan = this.planPackageInstall();
+        if (!plan.shouldInstall || this.options.skipInstall || this.options.dryRun) {
+            return plan;
         }
         try {
-            execSync(command, { cwd: this.projectRoot, stdio: 'inherit' });
+            execSync(plan.command, { cwd: plan.cwd, stdio: 'inherit' });
         }
         catch (error) {
             throw new Error(`Failed to install humanbehavior-js: ${error}`);
         }
+        return plan;
+    }
+    planPackageInstall() {
+        const packageManager = this.framework?.packageManager || this.detectPackageManager(this.projectRoot);
+        const workspaceRoot = this.findWorkspaceRoot(this.projectRoot);
+        const packageJson = this.readPackageJson(this.projectRoot);
+        const packageName = packageJson?.name;
+        const installedVersion = this.getInstalledSDKVersion(packageJson);
+        const alreadyInstalled = installedVersion !== undefined;
+        const versionStatus = this.getSDKVersionStatus(installedVersion);
+        const isWorkspace = workspaceRoot !== this.projectRoot;
+        const targetRef = packageName || path.relative(workspaceRoot, this.projectRoot);
+        const sdkPackage = 'humanbehavior-js@latest';
+        const shouldInstall = !alreadyInstalled ||
+            (versionStatus === 'stale' && this.options.upgrade === true);
+        const command = this.buildInstallCommand(packageManager, sdkPackage, {
+            isWorkspace,
+            targetRef
+        });
+        return {
+            packageName: 'humanbehavior-js',
+            packageManager,
+            command,
+            cwd: isWorkspace ? workspaceRoot : this.projectRoot,
+            targetPackagePath: this.projectRoot,
+            workspaceRoot,
+            isWorkspace,
+            alreadyInstalled,
+            installedVersion,
+            minimumSupportedVersion: MIN_SUPPORTED_SDK_VERSION,
+            testedVersion: TESTED_SDK_VERSION,
+            versionStatus,
+            shouldInstall,
+            reason: this.getInstallPlanReason({
+                alreadyInstalled,
+                installedVersion,
+                versionStatus,
+                shouldInstall,
+                isWorkspace,
+                targetRef
+            })
+        };
+    }
+    getInstallPlanReason(options) {
+        if (options.alreadyInstalled) {
+            switch (options.versionStatus) {
+                case 'compatible':
+                    return `humanbehavior-js is already compatible (${options.installedVersion})`;
+                case 'stale':
+                    return options.shouldInstall
+                        ? `humanbehavior-js ${options.installedVersion} is below ${MIN_SUPPORTED_SDK_VERSION}; upgrade requested`
+                        : `humanbehavior-js ${options.installedVersion} is below ${MIN_SUPPORTED_SDK_VERSION}; rerun with --upgrade to update`;
+                case 'newer':
+                    return `humanbehavior-js ${options.installedVersion} is newer than tested ${TESTED_SDK_VERSION}; keeping existing version`;
+                case 'unknown':
+                    return `humanbehavior-js is already declared with a non-semver range (${options.installedVersion}); keeping existing version`;
+            }
+        }
+        return options.isWorkspace
+            ? `Install scoped to workspace package ${options.targetRef}`
+            : 'Install in selected project package';
+    }
+    buildInstallCommand(packageManager, sdkPackage, options) {
+        if (options.isWorkspace) {
+            switch (packageManager) {
+                case 'pnpm':
+                    return `pnpm --filter ${this.shellQuote(options.targetRef)} add ${sdkPackage}`;
+                case 'yarn':
+                    return `yarn workspace ${this.shellQuote(options.targetRef)} add ${sdkPackage}`;
+                case 'bun':
+                    return `bun add ${sdkPackage} --cwd ${this.shellQuote(options.targetRef)}`;
+                case 'npm':
+                default:
+                    return `npm install ${sdkPackage} --workspace ${this.shellQuote(options.targetRef)} --legacy-peer-deps`;
+            }
+        }
+        switch (packageManager) {
+            case 'pnpm':
+                return `pnpm add ${sdkPackage}`;
+            case 'yarn':
+                return `yarn add ${sdkPackage}`;
+            case 'bun':
+                return `bun add ${sdkPackage}`;
+            case 'npm':
+            default:
+                return `npm install ${sdkPackage} --legacy-peer-deps`;
+        }
+    }
+    detectPackageManager(startDir) {
+        const root = this.findWorkspaceRoot(startDir);
+        const lockfileChecks = [
+            ['pnpm-lock.yaml', 'pnpm'],
+            ['yarn.lock', 'yarn'],
+            ['bun.lockb', 'bun'],
+            ['bun.lock', 'bun'],
+            ['package-lock.json', 'npm'],
+            ['npm-shrinkwrap.json', 'npm']
+        ];
+        for (const dir of [startDir, root]) {
+            for (const [lockfile, packageManager] of lockfileChecks) {
+                if (fs.existsSync(path.join(dir, lockfile))) {
+                    return packageManager;
+                }
+            }
+        }
+        const packageJson = this.readPackageJson(root) || this.readPackageJson(startDir);
+        const packageManager = packageJson?.packageManager;
+        if (typeof packageManager === 'string') {
+            if (packageManager.startsWith('pnpm@'))
+                return 'pnpm';
+            if (packageManager.startsWith('yarn@'))
+                return 'yarn';
+            if (packageManager.startsWith('bun@'))
+                return 'bun';
+            if (packageManager.startsWith('npm@'))
+                return 'npm';
+        }
+        return 'npm';
+    }
+    findWorkspaceRoot(startDir) {
+        let current = path.resolve(startDir);
+        let bestRoot = current;
+        while (true) {
+            const packageJson = this.readPackageJson(current);
+            const hasWorkspacePackageJson = !!packageJson &&
+                (Array.isArray(packageJson.workspaces) ||
+                    (packageJson.workspaces && Array.isArray(packageJson.workspaces.packages)));
+            const hasPnpmWorkspace = fs.existsSync(path.join(current, 'pnpm-workspace.yaml'));
+            if (hasWorkspacePackageJson || hasPnpmWorkspace) {
+                bestRoot = current;
+            }
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        return bestRoot;
+    }
+    readPackageJson(dir) {
+        const packageJsonPath = path.join(dir, 'package.json');
+        if (!fs.existsSync(packageJsonPath))
+            return null;
+        try {
+            return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    getInstalledSDKVersion(packageJson) {
+        if (!packageJson)
+            return undefined;
+        const dependencyFields = [
+            'dependencies',
+            'devDependencies',
+            'peerDependencies',
+            'optionalDependencies'
+        ];
+        for (const field of dependencyFields) {
+            const version = packageJson[field]?.['humanbehavior-js'];
+            if (typeof version === 'string') {
+                return version;
+            }
+        }
+        return undefined;
+    }
+    getSDKVersionStatus(installedVersion) {
+        if (!installedVersion)
+            return 'not-installed';
+        const normalized = this.extractSemver(installedVersion);
+        if (!normalized)
+            return 'unknown';
+        if (this.compareVersions(normalized, MIN_SUPPORTED_SDK_VERSION) < 0) {
+            return 'stale';
+        }
+        if (this.compareVersions(normalized, TESTED_SDK_VERSION) > 0) {
+            return 'newer';
+        }
+        return 'compatible';
+    }
+    extractSemver(versionRange) {
+        const match = versionRange.match(/\d+\.\d+\.\d+/);
+        return match ? match[0] : null;
+    }
+    shellQuote(value) {
+        if (/^[A-Za-z0-9_@./:-]+$/.test(value)) {
+            return value;
+        }
+        return `'${value.replace(/'/g, "'\\''")}'`;
     }
     /**
      * Generate code modifications based on framework
@@ -601,20 +789,14 @@ export function useHumanBehavior() {
   return { tracker: null }
 }
 `;
-        try {
-            if (!fs.existsSync(composableDir)) {
-                fs.mkdirSync(composableDir, { recursive: true });
-            }
-            if (!fs.existsSync(composablePath)) {
-                modifications.push({
-                    filePath: composablePath,
-                    action: 'create',
-                    content: composableContent,
-                    description: 'Created Vue composable useHumanBehavior'
-                });
-            }
+        if (!fs.existsSync(composablePath)) {
+            modifications.push({
+                filePath: composablePath,
+                action: 'create',
+                content: composableContent,
+                description: 'Created Vue composable useHumanBehavior'
+            });
         }
-        catch { }
         if (mainFile) {
             const content = fs.readFileSync(mainFile, 'utf8');
             const modifiedContent = this.injectVuePlugin(content);
@@ -667,9 +849,6 @@ export class HumanBehavior {
   }
 }
 `;
-        if (!fs.existsSync(serviceDir)) {
-            fs.mkdirSync(serviceDir, { recursive: true });
-        }
         if (!fs.existsSync(servicePath)) {
             modifications.push({
                 filePath: servicePath,
@@ -681,11 +860,6 @@ export class HumanBehavior {
         // Handle Angular environment files (proper Angular way)
         const envFile = path.join(this.projectRoot, 'src', 'environments', 'environment.ts');
         const envProdFile = path.join(this.projectRoot, 'src', 'environments', 'environment.prod.ts');
-        // Create environments directory if it doesn't exist
-        const envDir = path.dirname(envFile);
-        if (!fs.existsSync(envDir)) {
-            fs.mkdirSync(envDir, { recursive: true });
-        }
         // Create or update development environment
         if (fs.existsSync(envFile)) {
             const content = fs.readFileSync(envFile, 'utf8');
@@ -868,8 +1042,15 @@ export const onClientEntry = () => {
      * Apply modifications to the codebase
      */
     async applyModifications(modifications) {
-        for (const modification of modifications) {
-            try {
+        const snapshots = modifications.map((modification) => ({
+            filePath: modification.filePath,
+            existed: fs.existsSync(modification.filePath),
+            content: fs.existsSync(modification.filePath)
+                ? fs.readFileSync(modification.filePath, 'utf8')
+                : null
+        }));
+        try {
+            for (const modification of modifications) {
                 const dir = path.dirname(modification.filePath);
                 if (!fs.existsSync(dir)) {
                     fs.mkdirSync(dir, { recursive: true });
@@ -886,8 +1067,24 @@ export const onClientEntry = () => {
                         break;
                 }
             }
-            catch (error) {
-                throw new Error(`Failed to apply modification to ${modification.filePath}: ${error}`);
+        }
+        catch (error) {
+            this.rollbackModifications(snapshots);
+            throw new Error(`Failed to apply modifications; rolled back file changes: ${error}`);
+        }
+    }
+    rollbackModifications(snapshots) {
+        for (const snapshot of snapshots.reverse()) {
+            try {
+                if (snapshot.existed && snapshot.content !== null) {
+                    fs.writeFileSync(snapshot.filePath, snapshot.content);
+                }
+                else if (!snapshot.existed && fs.existsSync(snapshot.filePath)) {
+                    fs.rmSync(snapshot.filePath, { force: true });
+                }
+            }
+            catch {
+                // Best-effort rollback. The original apply error is more actionable.
             }
         }
     }
@@ -895,6 +1092,13 @@ export const onClientEntry = () => {
      * Generate next steps for the user
      */
     generateNextSteps() {
+        if (this.options.dryRun) {
+            return [
+                'Dry run complete. No packages were installed and no files were changed.',
+                'Review the planned install command and file modifications.',
+                'Run again without --dry-run to apply these changes.'
+            ];
+        }
         const steps = [
             '✅ SDK installed and configured automatically!',
             '🚀 Your app is now tracking user behavior',
@@ -1638,8 +1842,8 @@ class RemoteAIService {
  * Useful when auto-detection fails or users want more control.
  */
 class ManualFrameworkInstallationWizard extends AutoInstallationWizard {
-    constructor(apiKey, projectRoot = process.cwd(), framework) {
-        super(apiKey, projectRoot);
+    constructor(apiKey, projectRoot = process.cwd(), framework, options = {}) {
+        super(apiKey, projectRoot, options);
         this.selectedFramework = framework.toLowerCase();
         this.framework = this.createFrameworkInfo(this.selectedFramework);
     }
@@ -1669,10 +1873,12 @@ class ManualFrameworkInstallationWizard extends AutoInstallationWizard {
                 };
             }
             // Step 4: Install package
-            await this.installPackage();
+            const installPlan = await this.installPackage();
             // Step 5: Generate and apply code modifications
             const modifications = await this.generateModifications();
-            await this.applyModifications(modifications);
+            if (!this.options.dryRun) {
+                await this.applyModifications(modifications);
+            }
             // Step 6: Generate next steps
             const nextSteps = this.generateManualNextSteps();
             return {
@@ -1681,6 +1887,8 @@ class ManualFrameworkInstallationWizard extends AutoInstallationWizard {
                 modifications,
                 errors: [],
                 nextSteps,
+                dryRun: this.options.dryRun,
+                installPlan,
                 selectedFramework: this.selectedFramework,
                 manualMode: true
             };
@@ -1692,6 +1900,7 @@ class ManualFrameworkInstallationWizard extends AutoInstallationWizard {
                 modifications: [],
                 errors: [error instanceof Error ? error.message : 'Unknown error'],
                 nextSteps: [],
+                dryRun: this.options.dryRun,
                 selectedFramework: this.selectedFramework,
                 manualMode: true
             };
@@ -1812,6 +2021,14 @@ class ManualFrameworkInstallationWizard extends AutoInstallationWizard {
      * Generate next steps with manual mode info
      */
     generateManualNextSteps() {
+        if (this.options.dryRun) {
+            return [
+                'Dry run complete. No packages were installed and no files were changed.',
+                `Selected framework: ${this.framework?.name || 'unknown'}`,
+                'Review the planned install command and file modifications.',
+                'Run again without --dry-run to apply these changes.'
+            ];
+        }
         return [
             '✅ Manual framework installation completed!',
             `🎯 Selected framework: ${this.framework?.name || 'unknown'}`,
@@ -1840,6 +2057,232 @@ class ManualFrameworkInstallationWizard extends AutoInstallationWizard {
     }
 }
 
+const AGENT_PLAN_SCHEMA = {
+    type: 'object',
+    properties: {
+        summary: { type: 'string' },
+        targetPackagePath: { type: 'string' },
+        framework: { type: 'string' },
+        packageManager: { type: 'string' },
+        recommendedChecks: {
+            type: 'array',
+            items: { type: 'string' }
+        },
+        risks: {
+            type: 'array',
+            items: { type: 'string' }
+        },
+        confidence: {
+            type: 'number',
+            minimum: 0,
+            maximum: 1
+        }
+    },
+    required: ['summary', 'recommendedChecks', 'risks', 'confidence'],
+    additionalProperties: false
+};
+async function runClaudeAgentInstaller(options) {
+    const prompt = `You are the HumanBehavior setup wizard agent.
+
+Inspect this repository in read-only planning mode and produce a JSON setup plan.
+Do not edit files. Do not install packages. Do not include API keys or secrets.
+
+Known deterministic install plan:
+- Target package path: ${options.installPlan.targetPackagePath}
+- Workspace root: ${options.installPlan.workspaceRoot}
+- Package manager: ${options.installPlan.packageManager}
+- Install command: ${options.installPlan.command}
+- Framework guess: ${options.framework}
+- Dry run: ${options.dryRun === true}
+
+Return only the structured JSON matching the requested schema. Focus on:
+1. Whether the target package looks correct.
+2. Which files should be instrumented.
+3. Which checks should run after deterministic mutation.
+4. Risks or ambiguities the deterministic wizard should surface.`;
+    let resultText = '';
+    for await (const message of query({
+        prompt,
+        options: {
+            cwd: options.projectRoot,
+            permissionMode: 'plan',
+            allowedTools: ['Read', 'Glob', 'Grep', 'LS'],
+            disallowedTools: ['Edit', 'MultiEdit', 'Write', 'NotebookEdit', 'Bash'],
+            maxTurns: 6,
+            outputFormat: {
+                type: 'json_schema',
+                schema: AGENT_PLAN_SCHEMA
+            },
+            persistSession: false
+        }
+    })) {
+        if (message.type === 'result' && message.subtype === 'success') {
+            resultText = message.result || '';
+        }
+    }
+    return validateAgentPlan(resultText);
+}
+async function runClaudeAgentFullFlow(options) {
+    const snapshot = snapshotProject(options.projectRoot);
+    try {
+        const prompt = `You are the HumanBehavior setup wizard agent.
+
+Run the full setup flow for this app:
+1. Scan the codebase.
+2. Install the SDK using exactly this command if install is needed: ${options.installPlan.command}
+3. Instrument the client entrypoint using HumanBehavior SDK best practices.
+4. Use environment-variable based API key access only. Never write a raw API key.
+5. Run safe local checks if package scripts exist.
+6. Return a concise JSON summary matching the requested schema.
+
+Hard constraints:
+- Work only in this target package: ${options.installPlan.targetPackagePath}
+- Do not edit files outside the target package.
+- Do not run destructive commands.
+- Do not include secrets in output.
+- If unsure, stop and report risks instead of guessing.
+
+Framework guess: ${options.framework}
+Package manager: ${options.installPlan.packageManager}
+Workspace root: ${options.installPlan.workspaceRoot}`;
+        let resultText = '';
+        for await (const message of query({
+            prompt,
+            options: {
+                cwd: options.installPlan.targetPackagePath,
+                permissionMode: 'acceptEdits',
+                allowedTools: ['Read', 'Glob', 'Grep', 'LS', 'Edit', 'Bash'],
+                disallowedTools: ['Write', 'NotebookEdit', 'MultiEdit'],
+                maxTurns: 12,
+                outputFormat: {
+                    type: 'json_schema',
+                    schema: AGENT_PLAN_SCHEMA
+                },
+                persistSession: false,
+                canUseTool: async (toolName, input) => {
+                    if (toolName === 'Bash') {
+                        const command = String(input.command || '');
+                        return isAllowedBash(command, options.installPlan.command)
+                            ? { behavior: 'allow' }
+                            : { behavior: 'deny', message: `Command is outside setup wizard allowlist: ${command}` };
+                    }
+                    return { behavior: 'allow' };
+                }
+            }
+        })) {
+            if (message.type === 'result') {
+                if (message.subtype === 'success') {
+                    resultText = message.result || '';
+                }
+                else {
+                    throw new Error(message.subtype);
+                }
+            }
+        }
+        const agentPlan = validateAgentPlan(resultText);
+        return {
+            success: true,
+            agentPlan,
+            result: resultText,
+            rolledBack: false
+        };
+    }
+    catch (error) {
+        restoreProject(options.projectRoot, snapshot);
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+            rolledBack: true
+        };
+    }
+}
+function validateAgentPlan(rawResult) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawResult);
+    }
+    catch {
+        throw new Error('Claude agent did not return valid JSON');
+    }
+    if (typeof parsed.summary !== 'string') {
+        throw new Error('Claude agent plan missing summary');
+    }
+    if (!Array.isArray(parsed.recommendedChecks) || !parsed.recommendedChecks.every((item) => typeof item === 'string')) {
+        throw new Error('Claude agent plan has invalid recommendedChecks');
+    }
+    if (!Array.isArray(parsed.risks) || !parsed.risks.every((item) => typeof item === 'string')) {
+        throw new Error('Claude agent plan has invalid risks');
+    }
+    if (typeof parsed.confidence !== 'number' || parsed.confidence < 0 || parsed.confidence > 1) {
+        throw new Error('Claude agent plan has invalid confidence');
+    }
+    return {
+        summary: parsed.summary,
+        targetPackagePath: typeof parsed.targetPackagePath === 'string' ? parsed.targetPackagePath : undefined,
+        framework: typeof parsed.framework === 'string' ? parsed.framework : undefined,
+        packageManager: typeof parsed.packageManager === 'string' ? parsed.packageManager : undefined,
+        recommendedChecks: parsed.recommendedChecks,
+        risks: parsed.risks,
+        confidence: parsed.confidence,
+        rawResult
+    };
+}
+function isAllowedBash(command, installCommand) {
+    if (!command)
+        return false;
+    const trimmed = command.trim();
+    if (trimmed === installCommand)
+        return true;
+    if (/^(npm|pnpm|yarn|bun) run (build|test|lint|typecheck|check)(\s|$)/.test(trimmed))
+        return true;
+    if (/^(npm|pnpm|yarn|bun) (test|lint)(\s|$)/.test(trimmed))
+        return true;
+    return false;
+}
+function snapshotProject(root) {
+    const snapshot = new Map();
+    for (const filePath of listProjectFiles(root)) {
+        snapshot.set(filePath, fs.readFileSync(filePath, 'utf8'));
+    }
+    return snapshot;
+}
+function restoreProject(root, snapshot) {
+    const currentFiles = new Set(listProjectFiles(root));
+    for (const filePath of currentFiles) {
+        if (!snapshot.has(filePath)) {
+            fs.rmSync(filePath, { force: true });
+        }
+    }
+    for (const [filePath, content] of snapshot.entries()) {
+        if (content !== null) {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, content);
+        }
+    }
+}
+function listProjectFiles(root) {
+    const out = [];
+    const ignored = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.nuxt', '.svelte-kit']);
+    const walk = (dir) => {
+        if (!fs.existsSync(dir))
+            return;
+        for (const entry of fs.readdirSync(dir)) {
+            if (ignored.has(entry))
+                continue;
+            const fullPath = path.join(dir, entry);
+            const stat = fs.statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+            }
+            else if (stat.isFile() && stat.size <= 1024 * 1024) {
+                out.push(fullPath);
+            }
+        }
+    };
+    walk(root);
+    return out;
+}
+
 /**
  * AI-Enhanced HumanBehavior SDK Auto-Installation CLI
  *
@@ -1880,11 +2323,52 @@ class AIAutoInstallCLI {
             // Run installation
             const spinner = clack.spinner();
             spinner.start('🔍 Analyzing your project with AI...');
-            const wizard = new ManualFrameworkInstallationWizard(apiKey, projectPath, framework);
+            const wizard = new ManualFrameworkInstallationWizard(apiKey, projectPath, framework, {
+                dryRun: this.options.dryRun,
+                upgrade: this.options.upgrade
+            });
+            if (this.options.agent) {
+                const detected = await wizard.detectFramework();
+                const installPlan = wizard.planPackageInstall();
+                const agentResult = this.options.agentApply && !this.options.dryRun
+                    ? await runClaudeAgentFullFlow({
+                        projectRoot: projectPath,
+                        installPlan,
+                        framework: detected.name,
+                        dryRun: this.options.dryRun
+                    })
+                    : { success: true, agentPlan: await runClaudeAgentInstaller({
+                            projectRoot: projectPath,
+                            installPlan,
+                            framework: detected.name,
+                            dryRun: this.options.dryRun
+                        }), rolledBack: false };
+                if (agentResult.success && agentResult.agentPlan) {
+                    wizard.setAgentPlan(agentResult.agentPlan);
+                    if (this.options.agentApply && !this.options.dryRun) {
+                        clack.outro('Claude agent completed setup successfully.');
+                        this.writeReport({
+                            success: true,
+                            framework: detected,
+                            modifications: [],
+                            errors: [],
+                            nextSteps: agentResult.agentPlan.recommendedChecks,
+                            dryRun: false,
+                            installPlan,
+                            agentPlan: agentResult.agentPlan
+                        }, framework);
+                        return;
+                    }
+                }
+                else {
+                    clack.note(`${agentResult.error || 'Unknown agent error'}\nRolled back: ${agentResult.rolledBack ? 'yes' : 'no'}\nContinuing with deterministic fallback.`, 'Claude Agent Fallback');
+                }
+            }
             const result = await wizard.install();
-            spinner.stop('Analysis complete!');
+            spinner.stop(this.options.dryRun ? 'Dry run complete!' : 'Analysis complete!');
             // Display results
             this.displayResults(result, framework);
+            this.writeReport(result, framework);
         }
         catch (error) {
             clack.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -1895,6 +2379,12 @@ class AIAutoInstallCLI {
         if (this.options.apiKey) {
             return this.options.apiKey;
         }
+        if (this.options.apiKeyFile) {
+            return fs.readFileSync(this.options.apiKeyFile, 'utf8').trim();
+        }
+        if (process.env.HB_API_KEY) {
+            return process.env.HB_API_KEY;
+        }
         const apiKey = await clack.text({
             message: 'Enter your HumanBehavior API key:',
             placeholder: 'hb_...',
@@ -1915,6 +2405,9 @@ class AIAutoInstallCLI {
         return confirmed;
     }
     async chooseFramework() {
+        if (this.options.framework) {
+            return this.options.framework;
+        }
         const framework = await clack.select({
             message: 'Select your framework:',
             options: [
@@ -1934,13 +2427,39 @@ class AIAutoInstallCLI {
     }
     displayResults(result, framework) {
         if (result.success) {
-            clack.outro('🎉 Installation completed successfully!');
+            clack.outro(result.dryRun
+                ? 'Dry run completed successfully. No packages were installed and no files were changed.'
+                : '🎉 Installation completed successfully!');
             // Display framework info
             clack.note(`Framework detected: ${result.framework.name} (${result.framework.type})`, 'Framework Info');
             // Display modifications
+            if (result.installPlan) {
+                clack.note([
+                    `Command: ${result.installPlan.command}`,
+                    `Run from: ${result.installPlan.cwd}`,
+                    `Target package: ${result.installPlan.targetPackagePath}`,
+                    `Workspace: ${result.installPlan.isWorkspace ? 'yes' : 'no'}`,
+                    `Version status: ${result.installPlan.versionStatus}`,
+                    result.installPlan.alreadyInstalled
+                        ? `Already installed: ${result.installPlan.installedVersion}`
+                        : `Reason: ${result.installPlan.reason}`
+                ].join('\n'), result.dryRun ? 'Planned Package Install' : 'Package Install');
+            }
             if (result.modifications && result.modifications.length > 0) {
                 const modifications = result.modifications.map((mod) => `${mod.action}: ${mod.filePath} - ${mod.description}`);
-                clack.note(modifications.join('\n'), 'Files Modified');
+                clack.note(modifications.join('\n'), result.dryRun ? 'Planned File Changes' : 'Files Modified');
+            }
+            if (result.agentPlan) {
+                clack.note([
+                    result.agentPlan.summary,
+                    `Confidence: ${Math.round(result.agentPlan.confidence * 100)}%`,
+                    result.agentPlan.recommendedChecks.length
+                        ? `Checks: ${result.agentPlan.recommendedChecks.join(', ')}`
+                        : 'Checks: none',
+                    result.agentPlan.risks.length
+                        ? `Risks: ${result.agentPlan.risks.join(', ')}`
+                        : 'Risks: none'
+                ].join('\n'), 'Claude Agent Plan');
             }
             // Display next steps
             if (result.nextSteps && result.nextSteps.length > 0) {
@@ -1961,6 +2480,37 @@ class AIAutoInstallCLI {
             }
         }
     }
+    writeReport(result, selectedFramework) {
+        if (!this.options.reportJson)
+            return;
+        const report = {
+            schemaVersion: 1,
+            status: result.success ? (result.dryRun ? 'dry-run' : 'completed') : 'failed',
+            selectedFramework,
+            framework: result.framework,
+            dryRun: result.dryRun === true,
+            installPlan: result.installPlan,
+            agentPlan: result.agentPlan
+                ? {
+                    summary: result.agentPlan.summary,
+                    targetPackagePath: result.agentPlan.targetPackagePath,
+                    framework: result.agentPlan.framework,
+                    packageManager: result.agentPlan.packageManager,
+                    recommendedChecks: result.agentPlan.recommendedChecks,
+                    risks: result.agentPlan.risks,
+                    confidence: result.agentPlan.confidence
+                }
+                : undefined,
+            modifications: (result.modifications || []).map((mod) => ({
+                filePath: mod.filePath,
+                action: mod.action,
+                description: mod.description
+            })),
+            errors: result.errors || [],
+            nextSteps: result.nextSteps || []
+        };
+        fs.writeFileSync(this.options.reportJson, JSON.stringify(report, null, 2));
+    }
 }
 function parseArgs() {
     const args = process.argv.slice(2);
@@ -1980,20 +2530,34 @@ function parseArgs() {
             case '--dry-run':
                 options.dryRun = true;
                 break;
+            case '--upgrade':
+                options.upgrade = true;
+                break;
+            case '--agent':
+                options.agent = true;
+                break;
+            case '--agent-apply':
+                options.agent = true;
+                options.agentApply = true;
+                break;
             case '--project':
             case '-p':
                 options.projectPath = args[++i];
                 break;
+            case '--api-key-file':
+                options.apiKeyFile = args[++i];
+                break;
+            case '--report-json':
+                options.reportJson = args[++i];
+                break;
             case '--framework':
             case '-f':
                 options.framework = args[++i];
                 break;
             case 'init':
-                if (!args[i + 1] || args[i + 1].startsWith('-')) {
-                    showInitHelp();
-                    process.exit(1);
+                if (args[i + 1] && !args[i + 1].startsWith('-')) {
+                    options.apiKey = args[++i];
                 }
-                options.apiKey = args[++i];
                 break;
             default:
                 if (!options.apiKey && !arg.startsWith('-')) {
@@ -2014,7 +2578,12 @@ Options:
   -h, --help              Show this help message
   -y, --yes               Skip all prompts and use defaults
   --dry-run               Show what would be changed without making changes
+  --upgrade               Upgrade stale existing SDK versions
+  --agent                 Use Claude Agent SDK to inspect and plan before deterministic changes
+  --agent-apply           Let Claude attempt guarded install/edit/check before deterministic fallback
 
+  --api-key-file <path>   Read API key from a local file
+  --report-json <path>    Write a structured install report without file contents
   -p, --project <path>    Specify project directory
   -f, --framework <name>  Specify framework manually
 
@@ -2025,24 +2594,15 @@ Examples:
   npx humanbehavior-js ai-auto-install --framework react --yes
 `);
 }
-function showInitHelp() {
-    console.log(`
-Usage: npx humanbehavior-js init <api-key>
-
-Arguments:
-  api-key    Your HumanBehavior API key (required, starts with "hb_")
-
-Examples:
-  npx humanbehavior-js init hb_your_api_key_here
-`);
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+    const options = parseArgs();
+    const cli = new AIAutoInstallCLI(options);
+    cli.run().catch((error) => {
+        clack.cancel(`Unexpected error: ${error.message}`);
+        process.exit(1);
+    });
 }
-// Main execution
-const options = parseArgs();
-const cli = new AIAutoInstallCLI(options);
-cli.run().catch((error) => {
-    clack.cancel(`Unexpected error: ${error.message}`);
-    process.exit(1);
-});
 
 export { AIAutoInstallCLI };
 //# sourceMappingURL=ai-auto-install.js.map