@ebowwa/codespaces-types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ebowwa Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @ebowwa/codespaces-types
+
+Shared TypeScript type definitions for Codespaces packages.
+
+## Installation
+
+```bash
+npm install @ebowwa/codespaces-types
+```
+
+## Usage
+
+This package contains shared type definitions used across various Codespaces packages:
+
+### Main Types
+
+```typescript
+import {
+  Environment,
+  EnvironmentStatus,
+  HetznerServerType,
+  HetznerLocation,
+  // ... and more
+} from '@ebowwa/codespaces-types';
+```
+
+### Resource Parsing
+
+```typescript
+import { parseResources, parseCPU, parseMemory } from '@ebowwa/codespaces-types/resources';
+```
+
+### Terminal WebSocket Types
+
+```typescript
+import {
+  ClientToServerMessage,
+  ServerToClientMessage,
+  WebSocketCloseCode
+} from '@ebowwa/codespaces-types/terminal-websocket';
+```
+
+### Time Formatting
+
+```typescript
+import { formatElapsedTime } from '@ebowwa/codespaces-types/time';
+```
+
+### Validation
+
+```typescript
+import {
+  EnvironmentNameSchema,
+  validateEnvironmentName
+} from '@ebowwa/codespaces-types/validation';
+```
+
+## Features
+
+- **Shared Types**: Common interfaces for environments, Hetzner API, and more
+- **Resource Parsing**: Utilities for parsing CPU, memory, disk, and GPU usage
+- **WebSocket Types**: Terminal WebSocket message types for real-time communication
+- **Validation**: Zod schemas for validating environment names, SSH keys, and API tokens
+- **Time Utilities**: Functions for formatting elapsed time
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,436 @@
+/**
+ * Shared type definitions for frontend and server
+ */
+/**
+ * Hetzner server type with pricing information
+ */
+export interface HetznerServerType {
+    id: number;
+    name: string;
+    description: string;
+    cores: number;
+    memory: number;
+    disk: number;
+    deprecated?: boolean;
+    prices: Array<{
+        location: string | null;
+        price_hourly: {
+            net: string;
+            gross: string;
+        };
+        price_monthly: {
+            net: string;
+            gross: string;
+        };
+    }>;
+    storage_type: "local" | "network";
+    cpu_type: "shared" | "dedicated";
+}
+/**
+ * Hetzner location/datacenter
+ */
+export interface HetznerLocation {
+    id: number;
+    name: string;
+    description: string;
+    country: string;
+    city: string;
+    latitude: number;
+    longitude: number;
+    network_zone: string;
+}
+/**
+ * Hetzner datacenter (specific facility within a location)
+ * Previously backend-only, now shared for full object graph preservation
+ */
+export interface HetznerDatacenter {
+    id: number;
+    name: string;
+    description: string;
+    location: HetznerLocation;
+    supported_server_types?: Array<{
+        id: number;
+        name: string;
+    }> | null;
+    available_server_types?: Array<{
+        id: number;
+        name: string;
+    }>;
+}
+/**
+ * Environment status - used by Environment interface and HetznerServer mapping
+ *
+ * Hetzner API returns: "running" | "stopped" | "starting" | "stopping" | "initializing"
+ * Environment uses subset: "running" | "stopped" | "creating" | "deleting"
+ *
+ * Mapping:
+ * - "running" → "running"
+ * - "stopped" → "stopped"
+ * - "starting" → "creating"
+ * - "stopping" → "deleting"
+ * - "initializing" → "creating"
+ */
+export declare enum EnvironmentStatus {
+    Running = "running",
+    Stopped = "stopped",
+    Creating = "creating",
+    Deleting = "deleting",
+    Starting = "starting",
+    Stopping = "stopping",
+    Initializing = "initializing"
+}
+/**
+ * Action status - used by HetznerAction
+ */
+export declare enum ActionStatus {
+    Running = "running",
+    Success = "success",
+    Error = "error"
+}
+/**
+ * Volume status - used by HetznerVolume
+ */
+export declare enum VolumeStatus {
+    Creating = "creating",
+    Available = "available",
+    Deleting = "deleting"
+}
+/**
+ * Ralph Loop status - used by RalphLoop interface
+ */
+export declare enum LoopStatus {
+    Running = "running",
+    Stopped = "stopped",
+    Error = "error",
+    Completed = "completed"
+}
+/**
+ * Active port on a server
+ */
+export interface ActivePort {
+    port: number;
+    protocol: "tcp" | "udp";
+    service?: string;
+    state: "open" | "closed" | "filtered";
+}
+/**
+ * Base permissions structure shared by Environment and EnvironmentMetadata
+ */
+export interface BasePermissions {
+    seedConfig?: {
+        sourceEnvironmentId?: string;
+        dependencySnapshot?: string;
+        setupScript?: string;
+    };
+    logins?: {
+        github?: {
+            enabled: boolean;
+            username?: string;
+            tokenScopes?: string[];
+        };
+        doppler?: {
+            enabled: boolean;
+            project?: string;
+            config?: string;
+        };
+        tailscale?: {
+            enabled: boolean;
+            authKey?: string;
+            hostname?: string;
+        };
+    };
+    vpns?: Array<{
+        name: string;
+        type: "wireguard" | "openvpn" | "tailscale";
+        config: string;
+        connected: boolean;
+    }>;
+    plugins?: Record<string, ClaudeCodePlugin>;
+}
+/**
+ * Base fields shared by Environment and EnvironmentMetadata
+ */
+export interface EnvironmentBase {
+    id: string;
+    description?: string;
+    project?: string;
+    owner?: string;
+    purpose?: string;
+    environmentType?: "development" | "staging" | "production" | "testing";
+    hoursActive?: number;
+    lastActive?: string;
+    activePorts?: ActivePort[];
+    /** Cloud-init bootstrap status */
+    bootstrapStatus?: "bootstrapping" | "ready" | "failed";
+}
+/**
+ * Claude Code hook event types
+ */
+export type HookEventType = "SessionStart" | "UserPromptSubmit" | "PreToolUse" | "PostToolUse" | "PreCommand" | "PostCommand" | "Stop" | "Error" | "FileChange";
+/**
+ * Claude Code hook configuration
+ */
+export interface ClaudeCodeHook {
+    event: HookEventType;
+    description?: string;
+    command?: string;
+    output?: {
+        allow?: boolean;
+        context?: string;
+        modifyInput?: string;
+    };
+}
+/**
+ * Claude Code agent configuration
+ */
+export interface ClaudeCodeAgent {
+    name: string;
+    description?: string;
+    instructions?: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+/**
+ * Claude Code command configuration
+ */
+export interface ClaudeCodeCommand {
+    name: string;
+    description?: string;
+    instructions?: string;
+    agent?: string;
+    shouldConfirm?: boolean;
+    parameters?: Record<string, {
+        type: "string" | "boolean" | "number" | "array";
+        description?: string;
+        required?: boolean;
+        default?: unknown;
+    }>;
+}
+/**
+ * Claude Code skill configuration
+ */
+export interface ClaudeCodeSkill {
+    name: string;
+    description?: string;
+    instructions?: string;
+    trigger?: {
+        patterns?: string[];
+        fileTypes?: string[];
+        always?: boolean;
+    };
+}
+/**
+ * MCP (Model Context Protocol) Server Configuration
+ *
+ * === LAYER 2: CLI Wrapper Plugin System ===
+ *
+ * MCP is NOT part of the OpenAI protocol (Layer 1).
+ * It's a separate plugin system for exposing tools/resources to AI models.
+ *
+ * These types are defined but NOT yet implemented in cheapspaces.
+ *
+ * Reference Implementation: tools/continue/core/context/mcp/
+ *
+ * Potential MCP Tools for Cheapspaces:
+ * - hetzner_create: Create new server (wrap HetznerClient.createServer())
+ * - hetzner_delete: Delete server (wrap HetznerClient.deleteServer())
+ * - hetzner_power: Power on/off (wrap powerOn/powerOff)
+ * - ssh_exec: Execute remote command (wrap execSSH())
+ * - ssh_upload: Upload file via SCP (wrap scpUpload())
+ * - ssh_download: Download file via SCP (wrap scpDownload())
+ * - resources_get: Get resource usage (wrap getResources())
+ *
+ * To implement (Layer 2 only):
+ * 1. Create MCPManagerSingleton (see continue's pattern)
+ * 2. Create MCPConnection wrapper for stdio/HTTP servers
+ * 3. Expose Hetzner/SSH operations as MCP tools
+ * 4. Integrate with AI chat for tool calling
+ */
+export interface MCPServerConfig {
+    name: string;
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/**
+ * Claude Code plugin configuration
+ */
+export interface ClaudeCodePlugin {
+    enabled: boolean;
+    name?: string;
+    description?: string;
+    version?: string;
+    author?: string;
+    commands?: ClaudeCodeCommand[];
+    agents?: ClaudeCodeAgent[];
+    skills?: ClaudeCodeSkill[];
+    hooks?: ClaudeCodeHook[];
+    mcpServers?: MCPServerConfig[];
+    config?: Record<string, unknown>;
+}
+/**
+ * Server image information
+ */
+export interface ServerImage {
+    id: number;
+    name: string;
+    description: string;
+    type: "snapshot" | "backup" | "system";
+}
+/**
+ * Environment data - shared between frontend and server
+ */
+export interface Environment extends EnvironmentBase {
+    name: string;
+    status: EnvironmentStatus.Running | EnvironmentStatus.Stopped | EnvironmentStatus.Creating | EnvironmentStatus.Deleting;
+    progress?: number;
+    serverId: number;
+    serverType: string;
+    image: ServerImage;
+    location?: HetznerLocation;
+    datacenter?: HetznerDatacenter;
+    ipv4: string | null;
+    ipv6: string | null;
+    createdAt: string;
+    lastUsed: string | null;
+    tags: string[];
+    resources?: {
+        cpuPercent: number;
+        memoryPercent: number;
+        memoryUsed: string;
+        memoryTotal: string;
+        diskPercent: number;
+        diskUsed: string;
+        diskTotal: string;
+        gpuPercent?: number;
+        gpuMemoryUsed?: string;
+        gpuMemoryTotal?: string;
+        lastUpdated?: string;
+    };
+    nodeAgent?: NodeAgentInfo;
+    permissions?: BasePermissions & {
+        skills?: Array<{
+            name: string;
+            enabled: boolean;
+            config?: Record<string, unknown>;
+        }>;
+    };
+}
+/**
+ * Get the location object from an environment
+ * @param env - The environment object
+ * @returns The location object or null
+ */
+export declare function getEnvLocation(env: Environment | undefined | null): HetznerLocation | null;
+/**
+ * Get the region name (short format like "nbg1") from an environment
+ * @param env - The environment object
+ * @returns The region name (e.g., "nbg1") or "Unknown"
+ */
+export declare function getEnvRegionName(env: Environment | undefined | null): string;
+/**
+ * Get a human-readable location label with city and country
+ * @param env - The environment object
+ * @returns A formatted location string (e.g., "Nuremberg, DE" or "nbg1" as fallback)
+ */
+export declare function getEnvLocationLabel(env: Environment | undefined | null): string;
+/**
+ * Environment metadata for storage
+ * Extends EnvironmentBase with storage-specific fields
+ */
+export interface EnvironmentMetadata extends EnvironmentBase {
+    sshKeyPath?: string;
+    permissions?: BasePermissions;
+    updatedAt?: string;
+}
+/**
+ * Node Agent - Ralph Loop orchestration service running on each VPS
+ */
+/**
+ * Git worktree information
+ */
+export interface Worktree {
+    id: string;
+    branch: string;
+    commit: string;
+    path: string;
+    created?: string;
+}
+/**
+ * Ralph Loop status and progress
+ */
+export interface RalphLoop {
+    id: string;
+    worktree_id: string;
+    iteration: number;
+    max_iterations: number;
+    status: LoopStatus;
+    started_at: string;
+    last_activity?: string;
+    recent_commits?: Array<{
+        hash: string;
+        message: string;
+    }>;
+    prompt?: string;
+    completion_promise?: string | null;
+    project_path?: string;
+    git_info?: {
+        remote: string | null;
+        branch: string | null;
+    };
+    phase?: "planning" | "executing" | "review" | "complete";
+    current_task?: string | null;
+    total_subtasks?: number;
+    completed_subtasks?: number;
+    subtasks?: Array<{
+        id: string;
+        title: string;
+        status: "pending" | "in_progress" | "completed";
+    }>;
+}
+/**
+ * Node Agent capacity metrics (system resources)
+ */
+export interface NodeCapacity {
+    cpu_percent: number;
+    memory_percent: number;
+    disk_percent: number;
+    claude_cpu_total?: number;
+    claude_process_count?: number;
+}
+/**
+ * Active Claude Code process info
+ */
+export interface ClaudeCodeProcess {
+    pid: number;
+    worktreeId?: string;
+    loopId?: string;
+    startTime: string;
+    command: string;
+    cpuPercent: number;
+    memoryPercent: number;
+}
+/**
+ * Node Agent status response
+ */
+export interface NodeAgentStatus {
+    node_id: string;
+    hostname: string;
+    tailscale_ip: string;
+    capacity: NodeCapacity;
+    worktrees: Worktree[];
+    ralph_loops: RalphLoop[];
+    active_claude_processes?: ClaudeCodeProcess[];
+}
+/**
+ * Node Agent connection info for UI display
+ */
+export interface NodeAgentInfo {
+    running: boolean;
+    port?: number;
+    status?: NodeAgentStatus;
+    lastChecked?: string;
+    error?: string;
+}

package/dist/index.js

@@ -0,0 +1,96 @@
+/**
+ * Shared type definitions for frontend and server
+ */
+// ============================================================================
+// Application Types
+// ============================================================================
+// ============================================================================
+// Shared Status Enums
+// ============================================================================
+/**
+ * Environment status - used by Environment interface and HetznerServer mapping
+ *
+ * Hetzner API returns: "running" | "stopped" | "starting" | "stopping" | "initializing"
+ * Environment uses subset: "running" | "stopped" | "creating" | "deleting"
+ *
+ * Mapping:
+ * - "running" → "running"
+ * - "stopped" → "stopped"
+ * - "starting" → "creating"
+ * - "stopping" → "deleting"
+ * - "initializing" → "creating"
+ */
+export var EnvironmentStatus;
+(function (EnvironmentStatus) {
+    EnvironmentStatus["Running"] = "running";
+    EnvironmentStatus["Stopped"] = "stopped";
+    EnvironmentStatus["Creating"] = "creating";
+    EnvironmentStatus["Deleting"] = "deleting";
+    // Additional Hetzner server statuses (for API compatibility)
+    EnvironmentStatus["Starting"] = "starting";
+    EnvironmentStatus["Stopping"] = "stopping";
+    EnvironmentStatus["Initializing"] = "initializing";
+})(EnvironmentStatus || (EnvironmentStatus = {}));
+/**
+ * Action status - used by HetznerAction
+ */
+export var ActionStatus;
+(function (ActionStatus) {
+    ActionStatus["Running"] = "running";
+    ActionStatus["Success"] = "success";
+    ActionStatus["Error"] = "error";
+})(ActionStatus || (ActionStatus = {}));
+/**
+ * Volume status - used by HetznerVolume
+ */
+export var VolumeStatus;
+(function (VolumeStatus) {
+    VolumeStatus["Creating"] = "creating";
+    VolumeStatus["Available"] = "available";
+    VolumeStatus["Deleting"] = "deleting";
+})(VolumeStatus || (VolumeStatus = {}));
+/**
+ * Ralph Loop status - used by RalphLoop interface
+ */
+export var LoopStatus;
+(function (LoopStatus) {
+    LoopStatus["Running"] = "running";
+    LoopStatus["Stopped"] = "stopped";
+    LoopStatus["Error"] = "error";
+    LoopStatus["Completed"] = "completed";
+})(LoopStatus || (LoopStatus = {}));
+/**
+ * Get the location object from an environment
+ * @param env - The environment object
+ * @returns The location object or null
+ */
+export function getEnvLocation(env) {
+    if (!env)
+        return null;
+    return env.location || null;
+}
+/**
+ * Get the region name (short format like "nbg1") from an environment
+ * @param env - The environment object
+ * @returns The region name (e.g., "nbg1") or "Unknown"
+ */
+export function getEnvRegionName(env) {
+    if (!env)
+        return "Unknown";
+    return env.location?.name || "Unknown";
+}
+/**
+ * Get a human-readable location label with city and country
+ * @param env - The environment object
+ * @returns A formatted location string (e.g., "Nuremberg, DE" or "nbg1" as fallback)
+ */
+export function getEnvLocationLabel(env) {
+    if (!env)
+        return "Unknown";
+    // Show city, country for better UX
+    if (env.location?.city && env.location?.country) {
+        return `${env.location.city}, ${env.location.country}`;
+    }
+    // Fallback to location name
+    return env.location?.name || "Unknown";
+}

package/dist/resources.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared resource parsing utilities
+ */
+/**
+ * Parse CPU usage from raw output with validation
+ */
+export declare function parseCPU(raw: string | undefined): number;
+/**
+ * Parse memory usage from raw output with validation
+ * Returns: { percent, used, total }
+ */
+export declare function parseMemory(raw: string | undefined): {
+    percent: number;
+    used: string;
+    total: string;
+};
+/**
+ * Parse disk usage from raw output with validation
+ * Handles formats like "4% 2.8G 75G" -> adds space before unit
+ */
+export declare function parseDisk(raw: string | undefined): {
+    percent: number;
+    used: string;
+    total: string;
+};
+/**
+ * Parse GPU usage from raw output with validation
+ * Returns undefined if no GPU present
+ */
+export declare function parseGPU(raw: string | undefined): {
+    gpuPercent: number;
+    gpuMemoryUsed: string;
+    gpuMemoryTotal: string;
+} | undefined;
+/**
+ * Parse all resources from raw command outputs
+ */
+export declare function parseResources(raw: {
+    cpu?: string;
+    memory?: string;
+    disk?: string;
+    gpu?: string;
+    network?: string;
+    loadavg?: string;
+    processes?: string;
+    connections?: string;
+    ports?: string;
+}): {
+    cpu: number;
+    memory: number;
+    disk: number;
+    gpu?: string;
+    network?: string;
+    loadavg?: string;
+    processes?: string;
+    connections?: string;
+    ports?: string;
+    cpuPercent: number;
+    memoryPercent: number;
+    memoryUsed: string;
+    memoryTotal: string;
+    diskPercent: number;
+    diskUsed: string;
+    diskTotal: string;
+    gpuPercent?: number;
+    gpuMemoryUsed?: string;
+    gpuMemoryTotal?: string;
+};