feat: add PostHog error monitoring for CLI executions

[kfirstri]

Description

This PR implements comprehensive error monitoring and telemetry infrastructure for the CLI using PostHog. It introduces an ErrorReporter singleton that captures unhandled exceptions, controlled errors, and contextual information (command, user, app ID, agent detection). The implementation is optimized for short-running CLI tools with immediate event flushing, proper shutdown handling, and graceful degradation when telemetry is disabled via the BASE44_DISABLE_TELEMETRY environment variable.

Related Issue

Fixes #55

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• Created `src/cli/telemetry/` module with PostHog client integration and ErrorReporter singleton
• Implemented ErrorReporter class with session tracking, context accumulation, and exception capture
• Created `runCLI()` function to centralize CLI execution, error handling, and telemetry shutdown
• Refactored `bin/run.js` and `bin/dev.js` to use `createProgram()` + `runCLI()` pattern
• Integrated Commander.js hooks to capture command context (name, args, options) via preAction hook
• Added AI agent detection using @vercel/detect-agent for enhanced telemetry context
• Configured PostHog client for CLI usage (flushAt: 1, flushInterval: 0, 1s timeouts)
• Implemented process-level error handlers for uncaught exceptions and unhandled rejections
• Added BASE44_DISABLE_TELEMETRY environment variable to disable all telemetry
• Updated `runCommand()` to remove try-catch wrapper and add app context to error reporter
• Modified `initAppConfig()` to return app config for error reporter context
• Updated AGENTS.md documentation to reflect new error handling flow and telemetry architecture
• Converted all commands to factory pattern with dependency injection via CLIContext
• Added dependencies: posthog-node, nanoid@5, @vercel/detect-agent
• Updated test suite to disable telemetry and handle new error bubbling behavior

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (`npm test`)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated AGENTS.md if I made architectural changes

Additional Notes

The error reporter requires POSTHOG_API_KEY (configured in src/cli/telemetry/consts.ts) to function. Telemetry can be disabled via BASE44_DISABLE_TELEMETRY=1 environment variable. The implementation ensures all PostHog events are flushed before CLI exit through the runCLI() shutdown sequence using process.exitCode instead of process.exit() to allow the event loop to drain. The ErrorReporter displays error details (session ID, app ID, command, CLI version) to stderr for user support and debugging. CLIExitError instances (user cancellations) are not reported to PostHog.

---

_{🤖 Generated by Claude | 2026-01-31 09:33 UTC}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/[email protected]

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/[email protected]"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/[email protected]"
  }
}

• 📦 Preview Package: @base44-preview/[email protected]
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[claude]

Code Review

I've found a critical bug that will cause runtime errors.

---

Issue: Function signature mismatch in entry point files

Files affected:

• bin/dev.js (lines 10-11)
• bin/run.js (lines 10-11)

Problem:
The entry point files call createProgram() without arguments and pass the result to runCLI(program), but:

1. createProgram(context: CLIContext) requires a CLIContext parameter
2. runCLI() takes no parameters and creates everything internally

Current code in both files:

const program = createProgram();  // ❌ Missing required CLIContext parameter
await runCLI(program);             // ❌ runCLI doesn't accept parameters

Why this will fail:

• createProgram() will receive undefined for the context parameter
• When commands try to use context.errorReporter, they'll crash with: Cannot read property 'errorReporter' of undefined

Fix:
Remove both lines and replace with a single call to runCLI():

await runCLI();

The runCLI() function handles everything internally:

• Creates the ErrorReporter
• Creates the CLIContext
• Calls createProgram(context) with proper context
• Parses commands and handles errors