@jetstart/shared 1.7.0 → 2.0.0

package/README.md

@@ -1,108 +1,261 @@
-# @jetstart/shared
+# @jetstart/shared
 
-Shared types, protocols, and utilities for the JetStart ecosystem.
+Shared TypeScript types, WebSocket protocol definitions, validation utilities, and constants used across every JetStart package.
 
 ## Overview
 
-This package contains common code shared across all JetStart packages:
+`@jetstart/shared` is the single source of truth for the JetStart communication contract. All other packages — `core`, `cli`, `web`, `logs` — import types and constants from here. Nothing about the protocol is duplicated across packages.
 
-- **Types**: TypeScript interfaces and type definitions
-- **Protocols**: WebSocket message protocols and event systems
-- **Utils**: Validation functions and constants
+```
+src/
+├── types/
+│   ├── session.ts      # Session, SessionStatus, SessionToken, QRCodeData
+│   ├── build.ts        # BuildConfig, BuildResult, BuildStatus, APKInfo, BuildError
+│   ├── device.ts       # DeviceInfo, Platform, Architecture
+│   └── log.ts          # LogEntry, LogLevel, LogSource, LogFilter, LogStats
+├── protocols/
+│   ├── websocket.ts    # All WebSocket message interfaces + WSMessage union type
+│   ├── events.ts       # EventEmitter-style event definitions
+│   └── index.ts
+└── utils/
+    ├── constants.ts        # Ports, timeouts, size limits, version, error codes
+    ├── validation.ts       # isValidProjectName, isValidPackageName, isValidSessionId
+    ├── version-compare.ts  # Semantic version comparison
+    ├── colors.ts           # Log level color helpers
+    └── index.ts
+```
+
+---
+
+## Installation
+
+`@jetstart/shared` is an internal monorepo package. Import it from any workspace:
 
-## Usage
 ```typescript
 import {
   Session,
-  SessionStatus,
   BuildConfig,
-  LogLevel,
-  ClientMessage,
-  CoreMessage,
-  isValidSessionId,
+  WSMessage,
   DEFAULT_CORE_PORT,
+  isValidProjectName,
 } from '@jetstart/shared';
 ```
 
-## Structure
-```
-src/
-├── types/          # Type definitions
-│   ├── session.ts  # Session management types
-│   ├── build.ts    # Build system types
-│   ├── device.ts   # Device information types
-│   └── log.ts      # Logging types
-├── protocols/      # Communication protocols
-│   ├── websocket.ts # WebSocket messages
-│   └── events.ts   # Event system
-└── utils/          # Utilities
-    ├── validation.ts # Validation functions
-    └── constants.ts  # Shared constants
-```
+---
 
-## Key Types
+## Types
 
-### Session Management
-- `Session` - Development session state
-- `SessionStatus` - Connection status enum
-- `SessionToken` - Authentication token
-- `QRCodeData` - QR code payload
+### Session
 
-### Build System
-- `BuildConfig` - Build configuration
-- `BuildResult` - Build output
-- `BuildStatus` - Build progress
-- `APKInfo` - APK metadata
+```typescript
+interface Session {
+  id: string;
+  token: string;
+  projectName: string;
+  projectPath: string;
+  createdAt: number;
+  lastActivity: number;
+}
 
-### Device Information
-- `DeviceInfo` - Device details
-- `Platform` - Platform enum
-- `Architecture` - CPU architecture
+enum SessionStatus {
+  CONNECTING   = 'connecting',
+  CONNECTED    = 'connected',
+  IDLE         = 'idle',
+  DISCONNECTED = 'disconnected',
+  ERROR        = 'error',
+}
+```
 
-### Logging
-- `LogEntry` - Log message structure
-- `LogLevel` - Log severity levels
-- `LogSource` - Log origin
+### Build
 
-## Protocols
+```typescript
+interface BuildConfig {
+  projectPath: string;
+  outputPath?: string;
+  buildType: 'debug' | 'release';
+  debuggable?: boolean;
+  minifyEnabled?: boolean;
+  versionCode?: number;
+  versionName?: string;
+  applicationId?: string;
+}
 
-### WebSocket Messages
+interface BuildResult {
+  success: boolean;
+  buildTime: number;
+  apkPath?: string;
+  apkSize?: number;
+  errors?: BuildError[];
+}
 
-**Client → Core:**
-- `client:connect` - Initial connection
-- `client:status` - Status update
-- `client:log` - Log message
-- `client:heartbeat` - Keep-alive
+interface APKInfo {
+  path: string;
+  size: number;
+  hash: string;
+  versionCode: number;
+  versionName: string;
+  minSdkVersion: number;    // minimum: 24 (Android 7.0)
+  targetSdkVersion: number; // current target: 34 (Android 14)
+  applicationId: string;
+}
+```
 
-**Core → Client:**
-- `core:connected` - Connection confirmed
-- `core:build-start` - Build started
-- `core:build-status` - Build progress
-- `core:build-complete` - Build finished
-- `core:build-error` - Build failed
-- `core:reload` - Trigger reload
+### Device
 
-## Validation
 ```typescript
-import { isValidSessionId, isValidProjectName } from '@jetstart/shared';
+interface DeviceInfo {
+  id: string;
+  model: string;
+  platform: Platform;
+  architecture: Architecture;
+  androidVersion?: string;
+  apiLevel?: number;
+}
+
+enum Platform      { ANDROID = 'android', WEB = 'web' }
+enum Architecture  { ARM64 = 'arm64', X86_64 = 'x86_64', X86 = 'x86' }
+```
+
+### Logging
 
-if (isValidSessionId(sessionId)) {
-  // Valid session ID
+```typescript
+interface LogEntry {
+  id: string;
+  timestamp: number;
+  level: LogLevel;
+  tag: string;
+  message: string;
+  source: LogSource;
+  metadata?: Record<string, unknown>;
 }
 
-if (isValidProjectName(name)) {
-  // Valid project name
+enum LogLevel  { VERBOSE, DEBUG, INFO, WARN, ERROR, FATAL }
+enum LogSource { CLI, CORE, CLIENT, BUILD, NETWORK, SYSTEM }
+```
+
+---
+
+## WebSocket Protocol
+
+All messages extend `BaseMessage`:
+
+```typescript
+interface BaseMessage {
+  type: string;
+  timestamp: number;
+  sessionId?: string;
 }
+
+type WSMessage = ClientMessage | CoreMessage;
 ```
 
+### Device / Browser → Core
+
+| `type` | Key fields | Description |
+|---|---|---|
+| `client:connect` | `sessionId`, `token`, `deviceInfo` | Authenticate with session credentials |
+| `client:status` | `status: SessionStatus` | Send a status update |
+| `client:log` | `log: LogEntry` | Forward a device log to the server |
+| `client:heartbeat` | — | Keep-alive ping |
+| `client:disconnect` | `reason?` | Graceful disconnect |
+| `client:click` | `action`, `elementType`, `elementText?` | UI interaction event from web emulator |
+
+### Core → Device / Browser
+
+| `type` | Key fields | Description |
+|---|---|---|
+| `core:connected` | `projectName` | Authentication accepted |
+| `core:build-start` | — | Gradle build has started |
+| `core:build-status` | `status: BuildStatus` | Mid-build progress update |
+| `core:build-complete` | `apkInfo: APKInfo`, `downloadUrl` | APK is ready |
+| `core:build-error` | `error`, `details?` | Build failed |
+| `core:reload` | `reloadType: 'full' \| 'hot'` | Request an app reload |
+| `core:dex-reload` | `dexBase64`, `classNames: string[]` | Hot reload DEX patch for Android |
+| `core:js-update` | `jsBase64`, `sourceFile`, `byteSize` | ES module update for the web emulator |
+| `core:log` | `log: LogEntry` | Broadcast a device log to dashboard clients |
+| `core:disconnect` | `reason` | Server is shutting down |
+
+---
+
 ## Constants
+
 ```typescript
-import { DEFAULT_CORE_PORT, JETSTART_VERSION } from '@jetstart/shared';
+// Default ports
+DEFAULT_CORE_PORT = 8765   // HTTP server
+DEFAULT_WS_PORT   = 8766   // WebSocket server
+DEFAULT_LOGS_PORT = 8767   // Logs server
+
+// WebSocket behaviour
+WS_HEARTBEAT_INTERVAL     = 30_000   // ms between heartbeat pings
+WS_RECONNECT_DELAY        = 5_000    // ms before reconnect attempt
+WS_MAX_RECONNECT_ATTEMPTS = 5
 
-console.log(`JetStart v${JETSTART_VERSION}`);
-console.log(`Core server on port ${DEFAULT_CORE_PORT}`);
+// Session lifecycle
+SESSION_TOKEN_EXPIRY      = 3_600_000  // 1 hour
+SESSION_CLEANUP_INTERVAL  = 60_000     // 1 minute
+SESSION_IDLE_TIMEOUT      = 1_800_000  // 30 minutes
+
+// Build limits
+BUILD_CACHE_SIZE_LIMIT    = 1_073_741_824  // 1 GB
+BUILD_TIMEOUT             = 300_000         // 5 minutes
+MAX_CONCURRENT_BUILDS     = 3
+
+// File limits
+MAX_APK_SIZE              = 104_857_600  // 100 MB
+MAX_LOG_ENTRIES           = 10_000
+
+// Android targets
+MIN_ANDROID_API_LEVEL     = 24  // Android 7.0
+TARGET_ANDROID_API_LEVEL  = 34  // Android 14
+
+// Version
+JETSTART_VERSION          = '0.1.0'
 ```
 
+---
+
+## Validation
+
+```typescript
+import { isValidProjectName, isValidPackageName, isValidSessionId } from '@jetstart/shared';
+
+// Letters, numbers, hyphens, underscores; must start with a letter; 1–64 chars
+isValidProjectName('my-app')           // true
+isValidProjectName('123bad')           // false
+
+// Reverse-domain format, at least two segments
+isValidPackageName('com.example.app')  // true
+isValidPackageName('example')          // false
+
+isValidSessionId(sessionId)            // validates generated session ID format
+```
+
+---
+
+## WebSocket State & Error Types
+
+```typescript
+enum WSState {
+  CONNECTING    = 'connecting',
+  CONNECTED     = 'connected',
+  DISCONNECTING = 'disconnecting',
+  DISCONNECTED  = 'disconnected',
+  ERROR         = 'error',
+}
+
+enum WSErrorCode {
+  CONNECTION_FAILED     = 'connection_failed',
+  AUTHENTICATION_FAILED = 'authentication_failed',
+  TIMEOUT               = 'timeout',
+  INVALID_MESSAGE       = 'invalid_message',
+  SESSION_EXPIRED       = 'session_expired',
+  UNKNOWN               = 'unknown',
+}
+```
+
+---
+
 ## License
 
-Apache-2.0
+MIT
+

package/dist/protocols/websocket.d.ts

@@ -46,7 +46,7 @@ export interface ClientClickEventMessage extends BaseMessage {
 /**
  * Messages from Core to Client
  */
-export type CoreMessage = CoreConnectedMessage | CoreBuildStartMessage | CoreBuildStatusMessage | CoreBuildCompleteMessage | CoreBuildErrorMessage | CoreReloadMessage | CoreUIUpdateMessage | CoreDisconnectMessage | CoreLogMessage;
+export type CoreMessage = CoreConnectedMessage | CoreBuildStartMessage | CoreBuildStatusMessage | CoreBuildCompleteMessage | CoreBuildErrorMessage | CoreReloadMessage | CoreUIUpdateMessage | CoreDexReloadMessage | CoreDisconnectMessage | CoreLogMessage;
 export interface CoreConnectedMessage extends BaseMessage {
     type: 'core:connected';
     sessionId: string;
@@ -79,6 +79,25 @@ export interface CoreUIUpdateMessage extends BaseMessage {
     screens?: string[];
     hash?: string;
 }
+export interface CoreDexReloadMessage extends BaseMessage {
+    type: 'core:dex-reload';
+    dexBase64: string;
+    classNames: string[];
+}
+/**
+ * Compiled Kotlin→JS module for web emulator preview.
+ * The browser imports this as an ES module, executes renderScreen(),
+ * and gets back a component tree it renders as Material You HTML.
+ */
+export interface CoreJsUpdateMessage extends BaseMessage {
+    type: 'core:js-update';
+    /** Base64-encoded ES module (.mjs) compiled by kotlinc-js */
+    jsBase64: string;
+    /** Source file that triggered this update */
+    sourceFile: string;
+    /** Size in bytes for display */
+    byteSize: number;
+}
 export interface CoreDisconnectMessage extends BaseMessage {
     type: 'core:disconnect';
     reason: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetstart/shared",
-  "version": "1.7.0",
+  "version": "2.0.0",
   "description": "Shared types, protocols, and utilities for JetStart",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/protocols/websocket.ts

@@ -76,6 +76,7 @@ export type CoreMessage =
   | CoreBuildErrorMessage
   | CoreReloadMessage
   | CoreUIUpdateMessage
+  | CoreDexReloadMessage
   | CoreDisconnectMessage
   | CoreLogMessage;
 
@@ -118,6 +119,27 @@ export interface CoreUIUpdateMessage extends BaseMessage {
   hash?: string;
 }
 
+export interface CoreDexReloadMessage extends BaseMessage {
+  type: 'core:dex-reload';
+  dexBase64: string;
+  classNames: string[];
+}
+
+/**
+ * Compiled Kotlin→JS module for web emulator preview.
+ * The browser imports this as an ES module, executes renderScreen(),
+ * and gets back a component tree it renders as Material You HTML.
+ */
+export interface CoreJsUpdateMessage extends BaseMessage {
+  type: 'core:js-update';
+  /** Base64-encoded ES module (.mjs) compiled by kotlinc-js */
+  jsBase64: string;
+  /** Source file that triggered this update */
+  sourceFile: string;
+  /** Size in bytes for display */
+  byteSize: number;
+}
+
 export interface CoreDisconnectMessage extends BaseMessage {
   type: 'core:disconnect';
   reason: string;