@gravito/launchpad 1.0.0-beta.1 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# @gravito/launchpad
+
+## 1.1.0
+
+### Minor Changes
+
+- Launch standalone high-performance engine and core optimizations.
+
+### Patch Changes
+
+- q
+- Updated dependencies
+- Updated dependencies
+  - @gravito/core@1.1.0
+  - @gravito/enterprise@1.0.1
+  - @gravito/ripple@2.0.0
+  - @gravito/stasis@2.0.0
+
+## 1.0.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @gravito/core@1.0.0
+  - @gravito/enterprise@1.0.0
+  - @gravito/ripple@1.0.0
+  - @gravito/stasis@1.0.0

package/README.md

@@ -1,44 +1,102 @@
 # @gravito/launchpad
 
-> 🚀 Bun 火箭回收系統：專為 Bun 打造的秒級容器部署與生命週期管理系統。
+> 🚀 Instant Deployment System for Bun. Container lifecycle management and zero-downtime deployment.
 
-## 核心特性
+**Gravito Launchpad** is a specialized orchestration system built for the Bun runtime. It uses a unique "Rocket Pool" architecture to pre-warm containers, enabling sub-second deployments by injecting code into already running instances instead of building images from scratch.
 
-- **Rocket Pool**: 預熱容器池，消除啟動冷啟動。
-- **Payload Injection**: 跳過 Docker Build，透過 `docker cp` 秒級注入代碼。
-- **DDD 架構**: 基於 `@gravito/enterprise` 實作，具備嚴謹的狀態機管理。
-- **可回收性**: 任務結束後自動翻新容器，資源零浪費。
+## ✨ Core Features
 
-## 架構概覽
+- **🔥 Rocket Pool**: Pre-warmed container pool eliminates cold start times.
+- **💉 Payload Injection**: Skip `docker build`. Code is injected via `docker cp` in milliseconds.
+- **🏗️ DDD Architecture**: Built on `@gravito/enterprise` with rigorous state machine management.
+- **♻️ Auto-Recycling**: Containers are automatically refurbished and returned to the pool after missions.
+- **🤖 GitHub Integration**: Built-in webhook handler for PR previews and automated comments.
+- **🛡️ Secure Isolation**: Each deployment runs in an isolated container environment.
 
-本套件遵循 **Clean Architecture** 與 **DDD**:
+## 🏗️ Architecture Overview
 
-- **Domain**: 定義 `Rocket` 狀態機與 `Mission` 邏輯。
-- **Application**: `PoolManager` (調度) 與 `PayloadInjector` (部署)。
-- **Infrastructure**: 底層 Docker 與 Git 操作實作。
+Launchpad follows **Clean Architecture** principles:
 
-## 快速開始
+### Domain Layer
+- **Rocket**: The aggregate root representing a container instance.
+- **Mission**: Represents a deployment task (repo, commit, branch).
+- **Status Machine**: Strictly manages transitions (Idle -> Assigned -> Deployed -> Recycling).
+
+### Application Layer
+- **PoolManager**: Orchestrates the lifecycle of Rockets (warmup, assignment, recycling).
+- **PayloadInjector**: Handles the git clone and code injection process.
+- **MissionControl**: High-level facade for launching missions.
+- **RefurbishUnit**: Cleans up used containers for reuse.
+
+### Infrastructure Layer
+- **DockerAdapter**: Low-level communication with Docker daemon.
+- **ShellGitAdapter**: Git operations via shell commands.
+- **BunProxyAdapter**: Manages reverse proxying to active containers.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+bun add @gravito/launchpad
+```
+
+### Basic Usage
 
 ```typescript
-import { PoolManager, PayloadInjector } from '@gravito/launchpad'
+import { PoolManager, PayloadInjector, Mission } from '@gravito/launchpad'
 import { DockerAdapter, ShellGitAdapter, InMemoryRocketRepository } from '@gravito/launchpad/infra'
 
-const manager = new PoolManager(new DockerAdapter(), new InMemoryRocketRepository())
-const injector = new PayloadInjector(new DockerAdapter(), new ShellGitAdapter())
+// Initialize adapters
+const docker = new DockerAdapter()
+const repo = new InMemoryRocketRepository()
+const manager = new PoolManager(docker, repo)
 
-// 1. 預熱池子
+// 1. Warmup the pool (Create 3 idle containers)
 await manager.warmup(3)
 
-// 2. 指派任務
-const mission = Mission.create({ ... })
-const rocket = await manager.assignMission(mission)
+// 2. Create a mission
+const mission = Mission.create({
+  id: 'mission-1',
+  repoUrl: 'https://github.com/user/repo.git',
+  commitSha: 'latest'
+})
 
-// 3. 秒級部署
+// 3. Launch! (Assigns a rocket and injects code)
+const rocket = await manager.assignMission(mission)
+const injector = new PayloadInjector(docker, new ShellGitAdapter())
 await injector.deploy(rocket)
+
+console.log(`Mission deployed to http://localhost:${rocket.port}`)
 ```
 
-## 測試
+### Running as a Service (Orbit)
+
+Launchpad can run as a Gravito Orbit, providing a REST API and Webhook support.
+
+```typescript
+import { bootstrapLaunchpad } from '@gravito/launchpad'
+
+const { port } = await bootstrapLaunchpad()
+console.log(`Launchpad Server running on port ${port}`)
+```
+
+## ⚙️ Configuration
+
+Launchpad relies on Docker. Ensure Docker is installed and running.
+
+| Environment Variable | Description | Default |
+|----------------------|-------------|---------|
+| `GITHUB_TOKEN` | Token for GitHub API access | (Required for PR comments) |
+| `GITHUB_WEBHOOK_SECRET` | Secret for verifying webhooks | (Optional) |
+| `POOL_SIZE` | Target number of pre-warmed containers | `3` |
+
+## 🧪 Testing
 
 ```bash
 bun test
 ```
+
+## 📄 License
+
+MIT © Gravito Framework

package/debug-launch.ts

@@ -1,3 +1,4 @@
+import { getRuntimeAdapter } from '@gravito/core'
 import { DockerAdapter } from './src/Infrastructure/Docker/DockerAdapter'
 import { bootstrapLaunchpad } from './src/index'
 
@@ -6,23 +7,25 @@ async function run() {
 
   // 1. Cleanup
   const _docker = new DockerAdapter()
+  const runtime = getRuntimeAdapter()
   try {
-    const containers = await Bun.spawn([
+    const listProc = runtime.spawn([
       'docker',
       'ps',
       '-aq',
       '--filter',
       'label=gravito-origin=launchpad',
-    ]).text()
+    ])
+    const containers = await new Response(listProc.stdout ?? null).text()
     if (containers.trim()) {
       console.log('🧹 Cleaning up old containers...')
-      await Bun.spawn(['docker', 'rm', '-f', ...containers.trim().split('\n')]).exited
+      await runtime.spawn(['docker', 'rm', '-f', ...containers.trim().split('\n')]).exited
     }
   } catch (_e) {}
 
   // 2. Start Server
   const config = await bootstrapLaunchpad()
-  const server = Bun.serve(config)
+  const server = runtime.serve(config)
   console.log(`🚀 Server started at http://localhost:${config.port}`)
 
   // 3. Launch Mission

package/dist/index.d.mts

@@ -0,0 +1,205 @@
+import * as _gravito_ripple from '@gravito/ripple';
+import { OrbitRipple } from '@gravito/ripple';
+import { GravitoOrbit, PlanetCore } from '@gravito/core';
+import { ValueObject, AggregateRoot } from '@gravito/enterprise';
+
+interface MissionProps {
+    id: string;
+    repoUrl: string;
+    branch: string;
+    commitSha: string;
+}
+declare class Mission extends ValueObject<MissionProps> {
+    get id(): string;
+    get repoUrl(): string;
+    get branch(): string;
+    get commitSha(): string;
+    static create(props: MissionProps): Mission;
+}
+
+/**
+ * 火箭生命週期狀態
+ */
+declare enum RocketStatus {
+    IDLE = "IDLE",// 待命：容器運行中，無任務
+    PREPARING = "PREPARING",// 裝填：正在注入代碼 (Locked)
+    ORBITING = "ORBITING",// 運行：應用服務中
+    REFURBISHING = "REFURBISHING",// 翻新：正在清理環境
+    DECOMMISSIONED = "DECOMMISSIONED"
+}
+
+declare class Rocket extends AggregateRoot<string> {
+    private _status;
+    private _currentMission;
+    private _containerId;
+    private _assignedDomain;
+    constructor(id: string, containerId: string);
+    get status(): RocketStatus;
+    get currentMission(): Mission | null;
+    get containerId(): string;
+    get assignedDomain(): string | null;
+    /**
+     * 分配域名
+     */
+    assignDomain(domain: string): void;
+    /**
+     * 分配任務 (指派任務給 IDLE 的火箭)
+     */
+    assignMission(mission: Mission): void;
+    /**
+     * 點火啟動 (應用程式啟動成功)
+     */
+    ignite(): void;
+    /**
+     * 任務降落 (PR 合併或關閉，暫停服務)
+     */
+    splashDown(): void;
+    /**
+     * 翻新完成 (清理完畢，回歸池中)
+     */
+    finishRefurbishment(): void;
+    /**
+     * 火箭除役 (移除容器)
+     */
+    decommission(): void;
+    toJSON(): {
+        id: string;
+        containerId: string;
+        status: RocketStatus;
+        currentMission: Mission | null;
+        assignedDomain: string | null;
+    };
+    static fromJSON(data: any): Rocket;
+}
+
+/**
+ * 負責與底層容器引擎（如 Docker）溝通的轉接器介面
+ */
+interface IDockerAdapter {
+    createBaseContainer(): Promise<string>;
+    copyFiles(containerId: string, sourcePath: string, targetPath: string): Promise<void>;
+    executeCommand(containerId: string, command: string[]): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /**
+     * 獲取容器映射到宿主機的真實端口
+     */
+    getExposedPort(containerId: string, containerPort?: number): Promise<number>;
+    removeContainer(containerId: string): Promise<void>;
+    /**
+     * 根據 Label 批量移除容器
+     */
+    removeContainerByLabel(label: string): Promise<void>;
+    streamLogs(containerId: string, onData: (data: string) => void): void;
+    getStats(containerId: string): Promise<{
+        cpu: string;
+        memory: string;
+    }>;
+}
+/**
+ * 負責代碼獲取
+ */
+interface IGitAdapter {
+    clone(repoUrl: string, branch: string): Promise<string>;
+}
+/**
+ * 負責動態反向代理與域名路由的轉接器
+ */
+interface IRouterAdapter {
+    /**
+     * 註冊一個域名映射到指定的目標 (URL)
+     */
+    register(domain: string, targetUrl: string): void;
+    /**
+     * 註銷域名
+     */
+    unregister(domain: string): void;
+    /**
+     * 啟動代理伺服器
+     */
+    start(port: number): void;
+}
+/**
+ * 負責動態反向代理與域名路由的轉接器
+ */
+interface IRouterAdapter {
+    register(domain: string, targetUrl: string): void;
+    unregister(domain: string): void;
+    start(port: number): void;
+}
+/**
+ * 負責持久化火箭狀態的儲存庫介面
+ */
+interface IRocketRepository {
+    save(rocket: Rocket): Promise<void>;
+    findById(id: string): Promise<Rocket | null>;
+    findIdle(): Promise<Rocket | null>;
+    findAll(): Promise<Rocket[]>;
+    delete(id: string): Promise<void>;
+}
+
+declare class PayloadInjector {
+    private docker;
+    private git;
+    constructor(docker: IDockerAdapter, git: IGitAdapter);
+    deploy(rocket: Rocket): Promise<void>;
+}
+
+declare class RefurbishUnit {
+    private docker;
+    constructor(docker: IDockerAdapter);
+    /**
+     * 執行火箭翻新邏輯
+     */
+    refurbish(rocket: Rocket): Promise<void>;
+}
+
+declare class PoolManager {
+    private dockerAdapter;
+    private rocketRepository;
+    private refurbishUnit?;
+    private router?;
+    constructor(dockerAdapter: IDockerAdapter, rocketRepository: IRocketRepository, refurbishUnit?: RefurbishUnit | undefined, router?: IRouterAdapter | undefined);
+    /**
+     * 初始化發射場：預先準備指定數量的火箭
+     */
+    warmup(count: number): Promise<void>;
+    /**
+     * 獲取一架可用的火箭並分配任務
+     */
+    assignMission(mission: Mission): Promise<Rocket>;
+    /**
+     * 回收指定任務的火箭
+     */
+    recycle(missionId: string): Promise<void>;
+}
+
+declare class MissionControl {
+    private poolManager;
+    private injector;
+    private docker;
+    private router?;
+    constructor(poolManager: PoolManager, injector: PayloadInjector, docker: IDockerAdapter, router?: IRouterAdapter | undefined);
+    launch(mission: Mission, onTelemetry: (type: string, data: any) => void): Promise<string>;
+}
+
+/**
+ * Gravito Launchpad Orbit
+ */
+declare class LaunchpadOrbit implements GravitoOrbit {
+    private ripple;
+    constructor(ripple: OrbitRipple);
+    install(core: PlanetCore): Promise<void>;
+}
+/**
+ * 一鍵啟動 Launchpad 應用程式
+ */
+declare function bootstrapLaunchpad(): Promise<{
+    port: number;
+    websocket: _gravito_ripple.WebSocketHandlerConfig;
+    fetch: (req: Request, server: any) => Response | Promise<Response> | undefined;
+}>;
+
+export { LaunchpadOrbit, Mission, MissionControl, PayloadInjector, PoolManager, RefurbishUnit, Rocket, RocketStatus, bootstrapLaunchpad };

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+import * as _gravito_ripple from '@gravito/ripple';
+import { OrbitRipple } from '@gravito/ripple';
+import { GravitoOrbit, PlanetCore } from '@gravito/core';
+import { ValueObject, AggregateRoot } from '@gravito/enterprise';
+
+interface MissionProps {
+    id: string;
+    repoUrl: string;
+    branch: string;
+    commitSha: string;
+}
+declare class Mission extends ValueObject<MissionProps> {
+    get id(): string;
+    get repoUrl(): string;
+    get branch(): string;
+    get commitSha(): string;
+    static create(props: MissionProps): Mission;
+}
+
+/**
+ * 火箭生命週期狀態
+ */
+declare enum RocketStatus {
+    IDLE = "IDLE",// 待命：容器運行中，無任務
+    PREPARING = "PREPARING",// 裝填：正在注入代碼 (Locked)
+    ORBITING = "ORBITING",// 運行：應用服務中
+    REFURBISHING = "REFURBISHING",// 翻新：正在清理環境
+    DECOMMISSIONED = "DECOMMISSIONED"
+}
+
+declare class Rocket extends AggregateRoot<string> {
+    private _status;
+    private _currentMission;
+    private _containerId;
+    private _assignedDomain;
+    constructor(id: string, containerId: string);
+    get status(): RocketStatus;
+    get currentMission(): Mission | null;
+    get containerId(): string;
+    get assignedDomain(): string | null;
+    /**
+     * 分配域名
+     */
+    assignDomain(domain: string): void;
+    /**
+     * 分配任務 (指派任務給 IDLE 的火箭)
+     */
+    assignMission(mission: Mission): void;
+    /**
+     * 點火啟動 (應用程式啟動成功)
+     */
+    ignite(): void;
+    /**
+     * 任務降落 (PR 合併或關閉，暫停服務)
+     */
+    splashDown(): void;
+    /**
+     * 翻新完成 (清理完畢，回歸池中)
+     */
+    finishRefurbishment(): void;
+    /**
+     * 火箭除役 (移除容器)
+     */
+    decommission(): void;
+    toJSON(): {
+        id: string;
+        containerId: string;
+        status: RocketStatus;
+        currentMission: Mission | null;
+        assignedDomain: string | null;
+    };
+    static fromJSON(data: any): Rocket;
+}
+
+/**
+ * 負責與底層容器引擎（如 Docker）溝通的轉接器介面
+ */
+interface IDockerAdapter {
+    createBaseContainer(): Promise<string>;
+    copyFiles(containerId: string, sourcePath: string, targetPath: string): Promise<void>;
+    executeCommand(containerId: string, command: string[]): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /**
+     * 獲取容器映射到宿主機的真實端口
+     */
+    getExposedPort(containerId: string, containerPort?: number): Promise<number>;
+    removeContainer(containerId: string): Promise<void>;
+    /**
+     * 根據 Label 批量移除容器
+     */
+    removeContainerByLabel(label: string): Promise<void>;
+    streamLogs(containerId: string, onData: (data: string) => void): void;
+    getStats(containerId: string): Promise<{
+        cpu: string;
+        memory: string;
+    }>;
+}
+/**
+ * 負責代碼獲取
+ */
+interface IGitAdapter {
+    clone(repoUrl: string, branch: string): Promise<string>;
+}
+/**
+ * 負責動態反向代理與域名路由的轉接器
+ */
+interface IRouterAdapter {
+    /**
+     * 註冊一個域名映射到指定的目標 (URL)
+     */
+    register(domain: string, targetUrl: string): void;
+    /**
+     * 註銷域名
+     */
+    unregister(domain: string): void;
+    /**
+     * 啟動代理伺服器
+     */
+    start(port: number): void;
+}
+/**
+ * 負責動態反向代理與域名路由的轉接器
+ */
+interface IRouterAdapter {
+    register(domain: string, targetUrl: string): void;
+    unregister(domain: string): void;
+    start(port: number): void;
+}
+/**
+ * 負責持久化火箭狀態的儲存庫介面
+ */
+interface IRocketRepository {
+    save(rocket: Rocket): Promise<void>;
+    findById(id: string): Promise<Rocket | null>;
+    findIdle(): Promise<Rocket | null>;
+    findAll(): Promise<Rocket[]>;
+    delete(id: string): Promise<void>;
+}
+
+declare class PayloadInjector {
+    private docker;
+    private git;
+    constructor(docker: IDockerAdapter, git: IGitAdapter);
+    deploy(rocket: Rocket): Promise<void>;
+}
+
+declare class RefurbishUnit {
+    private docker;
+    constructor(docker: IDockerAdapter);
+    /**
+     * 執行火箭翻新邏輯
+     */
+    refurbish(rocket: Rocket): Promise<void>;
+}
+
+declare class PoolManager {
+    private dockerAdapter;
+    private rocketRepository;
+    private refurbishUnit?;
+    private router?;
+    constructor(dockerAdapter: IDockerAdapter, rocketRepository: IRocketRepository, refurbishUnit?: RefurbishUnit | undefined, router?: IRouterAdapter | undefined);
+    /**
+     * 初始化發射場：預先準備指定數量的火箭
+     */
+    warmup(count: number): Promise<void>;
+    /**
+     * 獲取一架可用的火箭並分配任務
+     */
+    assignMission(mission: Mission): Promise<Rocket>;
+    /**
+     * 回收指定任務的火箭
+     */
+    recycle(missionId: string): Promise<void>;
+}
+
+declare class MissionControl {
+    private poolManager;
+    private injector;
+    private docker;
+    private router?;
+    constructor(poolManager: PoolManager, injector: PayloadInjector, docker: IDockerAdapter, router?: IRouterAdapter | undefined);
+    launch(mission: Mission, onTelemetry: (type: string, data: any) => void): Promise<string>;
+}
+
+/**
+ * Gravito Launchpad Orbit
+ */
+declare class LaunchpadOrbit implements GravitoOrbit {
+    private ripple;
+    constructor(ripple: OrbitRipple);
+    install(core: PlanetCore): Promise<void>;
+}
+/**
+ * 一鍵啟動 Launchpad 應用程式
+ */
+declare function bootstrapLaunchpad(): Promise<{
+    port: number;
+    websocket: _gravito_ripple.WebSocketHandlerConfig;
+    fetch: (req: Request, server: any) => Response | Promise<Response> | undefined;
+}>;
+
+export { LaunchpadOrbit, Mission, MissionControl, PayloadInjector, PoolManager, RefurbishUnit, Rocket, RocketStatus, bootstrapLaunchpad };