humanbehavior-js 0.7.0 → 0.8.0-beta.0

package/packages/wizard/dist/cli/auto-install.d.ts

@@ -9,9 +9,12 @@
  */
 interface CLIOptions {
     apiKey?: string;
+    apiKeyFile?: string;
+    reportJson?: string;
     projectPath?: string;
     yes?: boolean;
     dryRun?: boolean;
+    upgrade?: boolean;
 }
 declare class AutoInstallCLI {
     private options;
@@ -20,6 +23,7 @@ declare class AutoInstallCLI {
     private getApiKey;
     private confirmInstallation;
     private displayResults;
+    private writeReport;
 }
 export { AutoInstallCLI };
 //# sourceMappingURL=auto-install.d.ts.map

package/packages/wizard/dist/cli/auto-install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auto-install.d.ts","sourceRoot":"","sources":["../../src/cli/auto-install.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG;AAOH,UAAU,UAAU;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,cAAM,cAAc;IAClB,OAAO,CAAC,OAAO,CAAa;gBAEhB,OAAO,EAAE,UAAU;IAIzB,GAAG;YAyCK,SAAS;YAsBT,mBAAmB;IAQjC,OAAO,CAAC,cAAc;CA4BvB;AAsED,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"auto-install.d.ts","sourceRoot":"","sources":["../../src/cli/auto-install.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG;AAOH,UAAU,UAAU;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,cAAM,cAAc;IAClB,OAAO,CAAC,OAAO,CAAa;gBAEhB,OAAO,EAAE,UAAU;IAIzB,GAAG;YA6CK,SAAS;YA8BT,mBAAmB;IAQjC,OAAO,CAAC,cAAc;IA+CtB,OAAO,CAAC,WAAW;CAoBpB;AAkFD,OAAO,EAAE,cAAc,EAAE,CAAC"}

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

@@ -10,12 +10,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 +52,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 +66,10 @@ class AutoInstallationWizard {
                 framework: this.framework,
                 modifications,
                 errors: [],
-                nextSteps
+                nextSteps,
+                dryRun: this.options.dryRun,
+                installPlan,
+                agentPlan: this.options.agentPlan
             };
         }
         catch (error) {
@@ -67,7 +78,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 +256,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 +788,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 +848,6 @@ export class HumanBehavior {
   }
 }
 `;
-        if (!fs.existsSync(serviceDir)) {
-            fs.mkdirSync(serviceDir, { recursive: true });
-        }
         if (!fs.existsSync(servicePath)) {
             modifications.push({
                 filePath: servicePath,
@@ -681,11 +859,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 +1041,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 +1066,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 +1091,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',
@@ -1463,11 +1666,15 @@ class AutoInstallCLI {
             // Run installation
             const spinner = clack.spinner();
             spinner.start('🔍 Detecting framework and applying integration...');
-            const wizard = new AutoInstallationWizard(apiKey, projectPath);
+            const wizard = new AutoInstallationWizard(apiKey, projectPath, {
+                dryRun: this.options.dryRun,
+                upgrade: this.options.upgrade
+            });
             const result = await wizard.install();
-            spinner.stop('Installation complete!');
+            spinner.stop(this.options.dryRun ? 'Dry run complete!' : 'Installation complete!');
             // Display results
             this.displayResults(result);
+            this.writeReport(result);
         }
         catch (error) {
             clack.cancel(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
@@ -1478,6 +1685,12 @@ class AutoInstallCLI {
         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_...',
@@ -1500,13 +1713,27 @@ class AutoInstallCLI {
     }
     displayResults(result) {
         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');
             }
             // Display next steps
             if (result.nextSteps && result.nextSteps.length > 0) {
@@ -1520,6 +1747,25 @@ class AutoInstallCLI {
             }
         }
     }
+    writeReport(result) {
+        if (!this.options.reportJson)
+            return;
+        const report = {
+            schemaVersion: 1,
+            status: result.success ? (result.dryRun ? 'dry-run' : 'completed') : 'failed',
+            framework: result.framework,
+            dryRun: result.dryRun === true,
+            installPlan: result.installPlan,
+            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);
@@ -1539,10 +1785,19 @@ function parseArgs() {
             case '--dry-run':
                 options.dryRun = true;
                 break;
+            case '--upgrade':
+                options.upgrade = 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;
             default:
                 if (!options.apiKey && !arg.startsWith('-')) {
                     options.apiKey = arg;
@@ -1564,6 +1819,9 @@ 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
+  --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
 
 Examples: