@jetstart/core 1.6.0 → 2.0.0

package/README.md

@@ -1,124 +1,239 @@
-# @jetstart/core
+# @jetstart/core
 
-Core build server and orchestration for JetStart.
+Central build server and real-time orchestration layer for JetStart.
 
 ## Overview
 
-The Core package is the central hub of JetStart, responsible for:
+`@jetstart/core` is the engine that powers `jetstart`. It runs three networked services and orchestrates the complete hot reload pipeline — from detecting a file change to having new code running on a physical Android device in under 100ms.
 
-- 🏗️ **Build Management** - Compiling Kotlin/Compose projects
-- 🌐 **HTTP Server** - Serving APKs and REST API
-- 🔌 **WebSocket Server** - Real-time communication with clients
-- 📦 **Build Caching** - Faster incremental builds
-- 👀 **File Watching** - Auto-rebuild on changes
-- 🔐 **Session Management** - Secure device pairing
+```
+src/
+├── build/
+│   ├── kotlin-compiler.ts    # Invokes kotlinc, builds classpath from SDK + Gradle caches
+│   ├── dex-generator.ts      # Runs d8 to convert .class files to classes.dex
+│   ├── override-generator.ts # Generates $Override companion classes (InstantRun-style)
+│   ├── hot-reload-service.ts # Orchestrates compile → override → dex pipeline
+│   ├── gradle.ts             # GradleExecutor + AdbHelper for full builds
+│   ├── gradle-injector.ts    # Injects JetStart plugin config into build.gradle
+│   ├── watcher.ts            # chokidar-based file watcher with debounce
+│   ├── builder.ts            # High-level build manager
+│   ├── cache.ts              # Incremental build cache
+│   ├── parser.ts             # Gradle output parser
+│   ├── dsl-parser.ts         # Compose DSL parser
+│   └── js-compiler-service.ts # kotlinc-js → ES module for web emulator
+├── server/
+│   ├── http.ts               # Express HTTP server setup
+│   ├── routes.ts             # REST API routes
+│   └── middleware.ts         # Request middleware
+├── websocket/
+│   ├── manager.ts            # Connection registry, session routing
+│   ├── handler.ts            # Message dispatch + session/token validation
+│   └── index.ts
+├── utils/
+│   ├── logger.ts             # Colored terminal logger
+│   ├── qr.ts                 # QR code generation
+│   └── session.ts            # Session creation and lifecycle
+└── types/
+    └── index.ts              # ServerSession, QRCodeOptions
+```
+
+---
+
+## Architecture
+
+```
+File change detected  (chokidar — watches *.kt, *.xml, *.gradle, 300ms debounce)
+  │
+  ├─► KotlinCompiler
+  │     kotlinc + Compose compiler plugin (bundled in Kotlin 2.0+, or Gradle cache fallback)
+  │     Classpath: android.jar + Gradle module cache + transforms-3 cache + project build outputs
+  │     Uses @argfile to avoid Windows command-line length limits
+  │     → .class files in a temp directory
+  │
+  ├─► OverrideGenerator
+  │     Generates $Override companion classes for each modified class (InstantRun pattern)
+  │     Compiles override source files back through KotlinCompiler
+  │     Falls back to direct class reload if override generation fails
+  │
+  ├─► DexGenerator
+  │     Runs d8 from $ANDROID_HOME/build-tools/<latest>
+  │     --min-api 24  (Android 7.0+)
+  │     → classes.dex
+  │
+  └─► WebSocketHandler.sendDexReload()
+        Broadcasts base64-encoded DEX + class name list to all authenticated Android clients
+        Android runtime loads classes via custom ClassLoader — no reinstall needed
+```
+
+For the web emulator, a parallel path compiles via `kotlinc-js` to an ES module and broadcasts it as `core:js-update`.
+
+---
 
 ## Usage
 
-### As a Library
 ```typescript
 import { JetStartServer } from '@jetstart/core';
 
 const server = new JetStartServer({
   httpPort: 8765,
   wsPort: 8766,
-  host: '0.0.0.0',
+  host: '0.0.0.0',           // Bind to all interfaces
+  displayHost: '192.168.1.5', // LAN IP used in QR code and terminal output
+  projectPath: '/path/to/my-app',
+  projectName: 'my-app',
+  // For Android emulators — host is reachable at 10.0.2.2 inside the AVD
+  emulatorHost: '10.0.2.2',
 });
 
-await server.start();
-```
+const session = await server.start();
+// session.id and session.token are embedded in the QR code
+
+server.on('build:complete', (result) => {
+  console.log('APK ready:', result.apkPath);
+});
 
-### As a Standalone Server
-```bash
-npm run start
+await server.stop();
 ```
 
-## API Endpoints
+---
 
-### HTTP REST API
+## HTTP API
 
-**Health Check**
-```
-GET /health
-Response: { status: 'ok', version: '0.1.0', uptime: 123 }
-```
+All endpoints are served on the HTTP port (default `8765`).
 
-**Create Session**
-```
-POST /session/create
-Body: { projectName: 'MyApp', projectPath: '/path/to/project' }
-Response: { session: {...}, qrCode: 'data:image/png;base64,...' }
-```
+### `GET /`
+Redirects to `https://web.jetstart.site` with the active session's connection parameters (`host`, `port`, `wsPort`, `sessionId`, `token`, `version`, `projectName`) as query parameters, so the web emulator connects automatically. Returns a plain status page if no session is active.
 
-**Get Session**
+### `GET /health`
+```json
+{ "status": "ok", "version": "0.1.0", "uptime": 42.3 }
 ```
-GET /session/:sessionId
-Response: { id, token, projectName, ... }
+
+### `GET /version`
+```json
+{ "version": "0.1.0" }
 ```
 
-**Download APK**
+### `POST /session/create`
+Creates a new dev session and returns a base64 QR code PNG.
+
+Request body:
+```json
+{ "projectName": "my-app", "projectPath": "/abs/path/to/my-app" }
 ```
-GET /download/:sessionId/:filename
-Response: APK file download
+
+Response:
+```json
+{
+  "session": { "id": "abc123", "token": "xyz789", "projectName": "my-app", "createdAt": 1711900000000 },
+  "qrCode": "data:image/png;base64,..."
+}
 ```
 
-### WebSocket Messages
+### `GET /session/:sessionId`
+Returns the session object (404 if not found).
 
-**Client → Core:**
-- `client:connect` - Initial connection with session
-- `client:status` - Status update
-- `client:log` - Log message
-- `client:heartbeat` - Keep-alive ping
+### `GET /download/:filename`
+Streams the most recently built APK as a file download.
 
-**Core → Client:**
-- `core:connected` - Connection confirmed
-- `core:build-start` - Build started
-- `core:build-status` - Build progress update
-- `core:build-complete` - Build finished
-- `core:build-error` - Build failed
-- `core:reload` - Trigger app reload
+---
 
-## Build System
-```typescript
-import { BuildManager } from '@jetstart/core';
+## WebSocket Protocol
+
+The WebSocket server runs on port `8766`. Every client must send `client:connect` with the matching `sessionId` and `token` (both embedded in the QR code). Mismatched connections are closed immediately:
+
+- Close code `4001` — session mismatch (device built against a different session, rescan QR)
+- Close code `4002` — token mismatch
 
-const buildManager = new BuildManager();
+### Messages: device/browser → core
 
-const result = await buildManager.build({
+| Type | Key fields | Description |
+|---|---|---|
+| `client:connect` | `sessionId`, `token`, `deviceInfo` | Authenticate with session credentials |
+| `client:status` | `status` | Send a `SessionStatus` update |
+| `client:log` | `log: LogEntry` | Forward a device log entry to the server |
+| `client:heartbeat` | — | Keep-alive ping |
+| `client:disconnect` | `reason?` | Graceful disconnect |
+| `client:click` | `action`, `elementType`, `elementText?` | UI interaction from web emulator |
+
+### Messages: core → device/browser
+
+| Type | Key fields | Description |
+|---|---|---|
+| `core:connected` | `projectName` | Authentication accepted |
+| `core:build-start` | — | Gradle build has begun |
+| `core:build-status` | `status: BuildStatus` | Mid-build progress update |
+| `core:build-complete` | `apkInfo`, `downloadUrl` | APK ready for download/install |
+| `core:build-error` | `error`, `details?` | Build failed |
+| `core:dex-reload` | `dexBase64`, `classNames[]` | Hot reload DEX patch for Android devices |
+| `core:js-update` | `jsBase64`, `sourceFile`, `byteSize` | ES module update for the web emulator |
+| `core:log` | `log: LogEntry` | Device log broadcast to dashboard clients |
+| `core:disconnect` | `reason` | Server shutting down |
+
+---
+
+## File Watcher
+
+```typescript
+import { FileWatcher } from '@jetstart/core';
+
+const watcher = new FileWatcher({
   projectPath: '/path/to/project',
-  outputPath: './build',
-  buildType: 'debug',
-  debuggable: true,
-  minifyEnabled: false,
-  versionCode: 1,
-  versionName: '1.0.0',
-  applicationId: 'com.example.app',
+  callback: (changedFiles) => { /* handle changes */ },
+  debounceMs: 300,
 });
 
-console.log(result.success, result.apkPath);
+watcher.watch('/path/to/project');
+// Watches **/*.kt, **/*.xml, **/*.gradle, **/*.gradle.kts
+// Ignores: node_modules, build, .gradle, .git, dist
+
+watcher.stop();
 ```
 
-## File Watching
+---
+
+## Hot Reload Service
+
 ```typescript
-import { FileWatcher } from '@jetstart/core';
+import { HotReloadService } from '@jetstart/core';
 
-const watcher = new FileWatcher('/path/to/project');
+const service = new HotReloadService('/path/to/project');
 
-watcher.start(() => {
-  console.log('Files changed, rebuilding...');
-});
+// Check that kotlinc and d8 are available
+const env = await service.checkEnvironment();
+if (!env.ready) console.log(env.issues);
 
-// Later
-watcher.stop();
+// Compile a changed file and get the DEX payload
+const result = await service.hotReload('/path/to/project/app/src/main/java/com/example/MainActivity.kt');
+if (result.success) {
+  console.log(`Done in ${result.compileTime + result.dexTime}ms`);
+  // result.dexBase64 — send this to the device
+  // result.classNames — fully-qualified class names patched
+}
 ```
 
+---
+
+## Gradle & ADB
+
+`GradleExecutor` runs full Gradle builds (debug or release). It prefers system Gradle over the project `gradlew` wrapper for speed, auto-creates `local.properties` if the Android SDK is found but not configured, and supports Gradle build flags `--parallel --build-cache --configure-on-demand --daemon`.
+
+`AdbHelper` handles wireless ADB connections with retry logic (up to 5 attempts, escalating delays) to account for user-approval timing on the device, and polls for device readiness after `adb connect` since the device may transition through `connecting` → `offline` → `device` states.
+
+---
+
 ## Environment Variables
 
-- `PORT` - HTTP server port (default: 8765)
-- `WS_PORT` - WebSocket server port (default: 8766)
-- `HOST` - Server host (default: 0.0.0.0)
-- `DEBUG` - Enable debug logging
+| Variable | Description |
+|---|---|
+| `ANDROID_HOME` / `ANDROID_SDK_ROOT` | Android SDK path — required for hot reload and Gradle builds |
+| `KOTLIN_HOME` | Kotlin installation path — used to find `kotlinc` |
+| `JAVA_HOME` | JDK path |
+| `DEBUG` | Enable verbose logging |
+
+---
 
 ## License
 
-Apache-2.0
+MIT
+

package/dist/build/dex-generator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DEX Generator Service
+ * Converts .class files to .dex using d8 (Android DEX compiler)
+ */
+export interface DexResult {
+    success: boolean;
+    dexPath: string;
+    dexBytes: Buffer | null;
+    errors: string[];
+}
+export declare class DexGenerator {
+    private static readonly TAG;
+    private d8Path;
+    /**
+     * Find d8 executable in Android SDK
+     */
+    findD8(): Promise<string | null>;
+    /**
+     * Convert .class files to a single .dex file
+     */
+    generateDex(classFiles: string[], outputDir?: string): Promise<DexResult>;
+    /**
+     * Run a command and return result
+     */
+    private runCommand;
+}
+//# sourceMappingURL=dex-generator.d.ts.map

package/dist/build/dex-generator.js

@@ -0,0 +1,202 @@
+"use strict";
+/**
+ * DEX Generator Service
+ * Converts .class files to .dex using d8 (Android DEX compiler)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DexGenerator = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
+const logger_1 = require("../utils/logger");
+class DexGenerator {
+    static TAG = 'DexGenerator';
+    d8Path = null;
+    /**
+     * Find d8 executable in Android SDK
+     */
+    async findD8() {
+        if (this.d8Path)
+            return this.d8Path;
+        // Check multiple locations for Android SDK
+        let androidHome = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
+        // Fallback to common Windows locations
+        if (!androidHome) {
+            const commonLocations = [
+                'C:\\Android',
+                path.join(os.homedir(), 'AppData', 'Local', 'Android', 'Sdk'),
+                'C:\\Users\\Public\\Android\\Sdk',
+            ];
+            for (const loc of commonLocations) {
+                if (fs.existsSync(path.join(loc, 'build-tools'))) {
+                    androidHome = loc;
+                    (0, logger_1.log)(`Found Android SDK at: ${loc}`);
+                    break;
+                }
+            }
+        }
+        if (!androidHome) {
+            (0, logger_1.error)('ANDROID_HOME or ANDROID_SDK_ROOT not set');
+            return null;
+        }
+        // d8 is in build-tools
+        const buildToolsDir = path.join(androidHome, 'build-tools');
+        if (!fs.existsSync(buildToolsDir)) {
+            (0, logger_1.error)('Android build-tools not found');
+            return null;
+        }
+        // Find latest build-tools version
+        const versions = fs.readdirSync(buildToolsDir)
+            .filter(v => /^\d+\.\d+\.\d+$/.test(v))
+            .sort((a, b) => {
+            const aParts = a.split('.').map(Number);
+            const bParts = b.split('.').map(Number);
+            for (let i = 0; i < 3; i++) {
+                if (aParts[i] !== bParts[i])
+                    return bParts[i] - aParts[i];
+            }
+            return 0;
+        });
+        if (versions.length === 0) {
+            (0, logger_1.error)('No Android build-tools version found');
+            return null;
+        }
+        const d8Name = os.platform() === 'win32' ? 'd8.bat' : 'd8';
+        const d8Path = path.join(buildToolsDir, versions[0], d8Name);
+        if (!fs.existsSync(d8Path)) {
+            (0, logger_1.error)(`d8 not found at: ${d8Path}`);
+            return null;
+        }
+        this.d8Path = d8Path;
+        (0, logger_1.log)(`Found d8 at: ${d8Path} (build-tools ${versions[0]})`);
+        return d8Path;
+    }
+    /**
+     * Convert .class files to a single .dex file
+     */
+    async generateDex(classFiles, outputDir) {
+        const d8 = await this.findD8();
+        if (!d8) {
+            return {
+                success: false,
+                dexPath: '',
+                dexBytes: null,
+                errors: ['d8 not found - Android SDK build-tools not installed']
+            };
+        }
+        if (classFiles.length === 0) {
+            return {
+                success: false,
+                dexPath: '',
+                dexBytes: null,
+                errors: ['No class files provided']
+            };
+        }
+        // Create output directory
+        const dexOutputDir = outputDir || path.join(os.tmpdir(), 'jetstart-dex', Date.now().toString());
+        fs.mkdirSync(dexOutputDir, { recursive: true });
+        (0, logger_1.log)(`Generating DEX from ${classFiles.length} class files...`);
+        // Build d8 arguments
+        const args = [
+            '--output', dexOutputDir,
+            '--min-api', '24',
+            ...classFiles
+        ];
+        const result = await this.runCommand(d8, args);
+        if (!result.success) {
+            return {
+                success: false,
+                dexPath: '',
+                dexBytes: null,
+                errors: [result.stderr || 'DEX generation failed']
+            };
+        }
+        // Find generated dex file
+        const dexPath = path.join(dexOutputDir, 'classes.dex');
+        if (!fs.existsSync(dexPath)) {
+            return {
+                success: false,
+                dexPath: '',
+                dexBytes: null,
+                errors: ['DEX file not generated']
+            };
+        }
+        const dexBytes = fs.readFileSync(dexPath);
+        (0, logger_1.log)(`Generated DEX: ${dexBytes.length} bytes`);
+        return {
+            success: true,
+            dexPath,
+            dexBytes,
+            errors: []
+        };
+    }
+    /**
+     * Run a command and return result
+     */
+    runCommand(cmd, args) {
+        return new Promise((resolve) => {
+            const proc = (0, child_process_1.spawn)(cmd, args, {
+                shell: os.platform() === 'win32',
+                env: process.env
+            });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            proc.on('close', (code) => {
+                resolve({
+                    success: code === 0,
+                    stdout,
+                    stderr
+                });
+            });
+            proc.on('error', (err) => {
+                resolve({
+                    success: false,
+                    stdout: '',
+                    stderr: err.message
+                });
+            });
+        });
+    }
+}
+exports.DexGenerator = DexGenerator;
+//# sourceMappingURL=dex-generator.js.map

package/dist/build/dsl-parser.d.ts

@@ -13,42 +13,15 @@ export declare class DSLParser {
      * Parse Kotlin content and extract UI definition
      */
     static parseContent(content: string, filePath: string): ParseResult;
-    /**
-     * Extract DSL JSON from getDefaultDSL() or similar function (legacy support)
-     */
     private static extractDSLFromFunction;
     /**
      * Find the main @Composable function in the file
      */
-    private static findMainComposable;
-    /**
-     * Extract function body handling nested braces
-     */
-    private static extractFunctionBody;
-    /**
-     * Parse the composable body and extract UI structure
-     */
-    private static parseComposableBody;
-    /**
-     * Parse a layout element (Column, Row, Box)
-     */
-    private static parseLayout;
-    /**
-     * Parse modifier chain
-     */
-    private static parseModifier;
-    /**
-     * Parse children elements (handles multi-line elements)
-     * Maintains source code order
-     */
-    private static parseChildren;
-    /**
-     * Extract content within parentheses (handles nesting)
-     */
-    private static extractParenthesesContent;
     /**
-     * Generate default DSL when parsing fails
+     * Find the main @Composable and a library of all others
      */
+    private static extractComposables;
+    private static findMatchingBracket;
     private static generateDefaultDSL;
 }
 //# sourceMappingURL=dsl-parser.d.ts.map