orbital-command 0.1.0

package/dist/server/shared/workflow-engine.js

@@ -0,0 +1,353 @@
+import { getHookEnforcement } from './workflow-config.js';
+// ─── WorkflowEngine ─────────────────────────────────────────
+//
+// Config-driven query layer over the WorkflowConfig JSON.
+// Pure class — no I/O, no global state, no side effects.
+export class WorkflowEngine {
+    config;
+    listMap;
+    edgeMap;
+    edgesByFrom;
+    statusOrder;
+    hookMap;
+    terminalStatuses;
+    allowedPrefixes;
+    constructor(config) {
+        this.init(config);
+    }
+    /**
+     * Hot-reload the engine with a new config. All services holding a reference
+     * to this engine instance will see the updated config immediately.
+     */
+    reload(config) {
+        this.init(config);
+    }
+    init(config) {
+        this.config = config;
+        if (!config.lists.length)
+            throw new Error('WorkflowConfig must have at least 1 list');
+        if (!config.edges.length)
+            throw new Error('WorkflowConfig must have at least 1 edge');
+        const entryPoints = config.lists.filter((l) => l.isEntryPoint);
+        if (entryPoints.length !== 1) {
+            throw new Error(`WorkflowConfig must have exactly 1 entry point, found ${entryPoints.length}`);
+        }
+        this.listMap = new Map(config.lists.map((l) => [l.id, l]));
+        this.edgeMap = new Map(config.edges.map((e) => [`${e.from}:${e.to}`, e]));
+        this.edgesByFrom = new Map();
+        for (const edge of config.edges) {
+            const existing = this.edgesByFrom.get(edge.from);
+            if (existing)
+                existing.push(edge);
+            else
+                this.edgesByFrom.set(edge.from, [edge]);
+        }
+        this.statusOrder = new Map(config.lists.map((l) => [l.id, l.order]));
+        this.hookMap = new Map((config.hooks ?? []).map((h) => [h.id, h]));
+        this.terminalStatuses = new Set(config.terminalStatuses ?? []);
+        this.allowedPrefixes = config.allowedCommandPrefixes ?? [];
+    }
+    // ─── Config Access ──────────────────────────────────────────
+    getConfig() {
+        return this.config;
+    }
+    getBranchingMode() {
+        return this.config.branchingMode ?? 'trunk';
+    }
+    // ─── List Queries ───────────────────────────────────────────
+    getLists() {
+        return [...this.config.lists].sort((a, b) => a.order - b.order);
+    }
+    getList(id) {
+        return this.listMap.get(id);
+    }
+    getEntryPoint() {
+        return this.config.lists.find((l) => l.isEntryPoint);
+    }
+    getBatchLists() {
+        return this.config.lists.filter((l) => l.supportsBatch);
+    }
+    getSprintLists() {
+        return this.config.lists.filter((l) => l.supportsSprint);
+    }
+    getBoardColumns() {
+        return this.getLists().map((l) => ({ id: l.id, label: l.label, color: l.color }));
+    }
+    // ─── Edge Queries ───────────────────────────────────────────
+    findEdge(from, to) {
+        return this.edgeMap.get(`${from}:${to}`);
+    }
+    isValidTransition(from, to) {
+        return this.edgeMap.has(`${from}:${to}`);
+    }
+    getValidTargets(from) {
+        return (this.edgesByFrom.get(from) ?? []).map((e) => e.to);
+    }
+    getAllEdges() {
+        return this.config.edges;
+    }
+    getEdgesByDirection(dir) {
+        return this.config.edges.filter((e) => e.direction === dir);
+    }
+    // ─── Validation ─────────────────────────────────────────────
+    validateTransition(from, to, context) {
+        if (!this.listMap.has(to)) {
+            return { ok: false, error: `Invalid status: '${to}'`, code: 'INVALID_STATUS' };
+        }
+        // bulk-sync and rollback are trusted contexts — skip transition checks
+        if (context === 'bulk-sync' || context === 'rollback')
+            return { ok: true };
+        // Same status is a no-op, always allowed
+        if (from === to)
+            return { ok: true };
+        const edge = this.findEdge(from, to);
+        if (!edge) {
+            return { ok: false, error: `Transition '${from}' -> '${to}' is not allowed`, code: 'INVALID_TRANSITION' };
+        }
+        // patch context cannot trigger dispatch-only transitions
+        if (context === 'patch' && edge.dispatchOnly) {
+            return { ok: false, error: `Transition '${from}' -> '${to}' requires dispatch (use a skill command)`, code: 'DISPATCH_REQUIRED' };
+        }
+        return { ok: true };
+    }
+    isValidStatus(status) {
+        return this.listMap.has(status);
+    }
+    isTerminalStatus(status) {
+        return this.terminalStatuses.has(status);
+    }
+    // ─── Commands ───────────────────────────────────────────────
+    buildCommand(edge, scopeId) {
+        if (!edge.command)
+            return null;
+        return edge.command.replace('{id}', String(scopeId));
+    }
+    isAllowedCommand(cmd) {
+        return this.allowedPrefixes.some((prefix) => cmd.startsWith(prefix));
+    }
+    // ─── Batch / Sprint ─────────────────────────────────────────
+    getBatchTargetStatus(column) {
+        const edges = this.edgesByFrom.get(column) ?? [];
+        const edge = edges.find((e) => (e.direction === 'forward' || e.direction === 'shortcut') && e.dispatchOnly);
+        return edge?.to;
+    }
+    getBatchCommand(column) {
+        const edges = this.edgesByFrom.get(column) ?? [];
+        const edge = edges.find((e) => (e.direction === 'forward' || e.direction === 'shortcut') && e.dispatchOnly);
+        if (!edge?.command)
+            return undefined;
+        // Strip {id} placeholder — batch consumers handle substitution themselves
+        return edge.command.replace(' {id}', '').replace('{id}', '');
+    }
+    // ─── Event Inference ────────────────────────────────────────
+    inferStatus(eventType, currentStatus, data) {
+        const rules = (this.config.eventInference ?? []).filter((r) => r.eventType === eventType);
+        if (!rules.length)
+            return null;
+        // Check rules with conditions first (more specific), then without
+        const withConditions = rules.filter((r) => r.conditions && Object.keys(r.conditions).length > 0);
+        const withoutConditions = rules.filter((r) => !r.conditions || Object.keys(r.conditions).length === 0);
+        const matchedRule = withConditions.find((r) => this.matchesConditions(r.conditions, data))
+            ?? withoutConditions[0]
+            ?? null;
+        if (!matchedRule)
+            return null;
+        // Handle dispatch resolution (e.g. AGENT_COMPLETED with outcome)
+        if (matchedRule.conditions?.dispatchResolution === true) {
+            const outcome = data.outcome;
+            return { dispatchResolution: true, resolution: outcome === 'failure' ? 'failed' : 'completed' };
+        }
+        // Determine target status
+        let newStatus;
+        if (matchedRule.targetStatus === '' && matchedRule.dataField) {
+            const rawValue = String(data[matchedRule.dataField] ?? '');
+            if (matchedRule.dataMap) {
+                newStatus = matchedRule.dataMap[rawValue] ?? matchedRule.dataMap['_default'] ?? '';
+            }
+            else {
+                newStatus = rawValue;
+            }
+        }
+        else {
+            newStatus = matchedRule.targetStatus;
+        }
+        if (!newStatus)
+            return null;
+        // Forward-only guard: event inference must not regress scope status
+        if (matchedRule.forwardOnly) {
+            const currentOrder = this.statusOrder.get(currentStatus) ?? -1;
+            const newOrder = this.statusOrder.get(newStatus) ?? -1;
+            if (newOrder <= currentOrder)
+                return null;
+        }
+        return newStatus;
+    }
+    matchesConditions(conditions, data) {
+        for (const [key, expected] of Object.entries(conditions)) {
+            // dispatchResolution is a flag, not a data check
+            if (key === 'dispatchResolution')
+                continue;
+            const actual = data[key];
+            if (Array.isArray(expected)) {
+                if (!expected.includes(actual))
+                    return false;
+            }
+            else {
+                if (actual !== expected)
+                    return false;
+            }
+        }
+        return true;
+    }
+    // ─── Git / Lifecycle ────────────────────────────────────────
+    getListByGitBranch(branch) {
+        return this.config.lists.find((l) => l.gitBranch === branch);
+    }
+    getGitBranch(listId) {
+        return this.listMap.get(listId)?.gitBranch;
+    }
+    getSessionKey(listId) {
+        return this.listMap.get(listId)?.sessionKey;
+    }
+    getActiveHooksForList(listId) {
+        return this.listMap.get(listId)?.activeHooks ?? [];
+    }
+    getAgentsForEdge(from, to) {
+        return this.findEdge(from, to)?.agents ?? [];
+    }
+    // ─── Status Order ───────────────────────────────────────────
+    getStatusOrder(status) {
+        return this.statusOrder.get(status) ?? -1;
+    }
+    isForwardMovement(from, to) {
+        return this.getStatusOrder(to) > this.getStatusOrder(from);
+    }
+    // ─── Hooks ──────────────────────────────────────────────────
+    getHooksForEdge(from, to) {
+        const edge = this.findEdge(from, to);
+        if (!edge?.hooks?.length)
+            return [];
+        return edge.hooks
+            .map((id) => this.hookMap.get(id))
+            .filter((h) => h !== undefined);
+    }
+    getAllHooks() {
+        return this.config.hooks ?? [];
+    }
+    getHookEnforcement(hook) {
+        return getHookEnforcement(hook);
+    }
+    getHooksByCategory(category) {
+        return (this.config.hooks ?? []).filter((h) => h.category === category);
+    }
+    // ─── Generation ─────────────────────────────────────────────
+    generateCSSVariables() {
+        return this.getLists()
+            .map((l) => `--status-${l.id}: ${l.color};`)
+            .join('\n');
+    }
+    generateShellManifest() {
+        const lines = [];
+        const sorted = this.getLists();
+        // Header
+        lines.push('#!/bin/bash');
+        lines.push('# Auto-generated by WorkflowEngine — DO NOT EDIT');
+        lines.push(`# Generated: ${new Date().toISOString()}`);
+        lines.push(`# Workflow: "${this.config.name}" (version ${this.config.version})`);
+        lines.push('');
+        // Branching mode
+        lines.push('# ─── Branching mode (trunk or worktree) ───');
+        lines.push(`WORKFLOW_BRANCHING_MODE="${this.getBranchingMode()}"`);
+        lines.push('');
+        // Valid statuses
+        lines.push('# ─── Valid statuses (space-separated) ───');
+        lines.push(`WORKFLOW_STATUSES="${sorted.map((l) => l.id).join(' ')}"`);
+        lines.push('');
+        // Directory statuses
+        lines.push('# ─── Statuses that have a scopes/ subdirectory ───');
+        const dirStatuses = sorted.filter((l) => l.hasDirectory).map((l) => l.id);
+        lines.push(`WORKFLOW_DIR_STATUSES="${dirStatuses.join(' ')}"`);
+        lines.push('');
+        // Terminal statuses
+        lines.push('# ─── Terminal statuses ───');
+        lines.push(`WORKFLOW_TERMINAL_STATUSES="${[...this.terminalStatuses].join(' ')}"`);
+        lines.push('');
+        // Entry point
+        lines.push('# ─── Entry point status ───');
+        lines.push(`WORKFLOW_ENTRY_STATUS="${this.getEntryPoint().id}"`);
+        lines.push('');
+        // Edges
+        lines.push('# ─── Transition edges (from:to:sessionKey) ───');
+        lines.push('WORKFLOW_EDGES=(');
+        for (const edge of this.config.edges) {
+            const targetList = this.listMap.get(edge.to);
+            const sessionKey = targetList?.sessionKey ?? '';
+            lines.push(`  "${edge.from}:${edge.to}:${sessionKey}"`);
+        }
+        lines.push(')');
+        lines.push('');
+        // Branch map
+        lines.push('# ─── Branch-to-transition mapping (gitBranch:from:to:sessionKey) ───');
+        lines.push('WORKFLOW_BRANCH_MAP=(');
+        for (const edge of this.config.edges) {
+            const targetList = this.listMap.get(edge.to);
+            if (targetList?.gitBranch) {
+                const sessionKey = targetList.sessionKey ?? '';
+                lines.push(`  "${targetList.gitBranch}:${edge.from}:${edge.to}:${sessionKey}"`);
+            }
+        }
+        lines.push(')');
+        lines.push('');
+        // Commit branch patterns
+        lines.push('# ─── Commit session branch patterns (regex) ───');
+        lines.push(`WORKFLOW_COMMIT_BRANCHES="${this.config.commitBranchPatterns ?? ''}"`);
+        lines.push('');
+        // Direction aliases (deployment edges: forward+dispatchOnly targeting deployment-group lists)
+        lines.push('# ─── Backward-compat direction aliases (alias:from:to:sessionKey) ───');
+        lines.push('WORKFLOW_DIRECTION_ALIASES=(');
+        for (const edge of this.config.edges) {
+            if (edge.direction !== 'forward' || !edge.dispatchOnly)
+                continue;
+            const targetList = this.listMap.get(edge.to);
+            if (!targetList)
+                continue;
+            // Generate aliases for deployment-group targets (dev, staging, production)
+            const group = targetList.group;
+            if (group === 'deployment') {
+                const sessionKey = targetList.sessionKey ?? '';
+                lines.push(`  "to-${edge.to}:${edge.from}:${edge.to}:${sessionKey}"`);
+            }
+        }
+        lines.push(')');
+        lines.push('');
+        // Helper functions
+        lines.push('# ─── Helper functions ──────────────────────────────');
+        lines.push('');
+        lines.push('status_to_dir() {');
+        lines.push('  local scope_status="$1"');
+        lines.push('  for s in $WORKFLOW_DIR_STATUSES; do');
+        lines.push('    [ "$s" = "$scope_status" ] && echo "$scope_status" && return 0');
+        lines.push('  done');
+        lines.push('  echo "$WORKFLOW_ENTRY_STATUS"');
+        lines.push('}');
+        lines.push('');
+        lines.push('status_to_branch() {');
+        lines.push('  local status="$1"');
+        lines.push('  for entry in "${WORKFLOW_BRANCH_MAP[@]}"; do');
+        lines.push('    IFS=\':\' read -r branch from to skey <<< "$entry"');
+        lines.push('    [ "$to" = "$status" ] && echo "$branch" && return 0');
+        lines.push('  done');
+        lines.push('  echo ""');
+        lines.push('}');
+        lines.push('');
+        lines.push('is_valid_status() {');
+        lines.push('  local status="$1"');
+        lines.push('  for s in $WORKFLOW_STATUSES; do');
+        lines.push('    [ "$s" = "$status" ] && return 0');
+        lines.push('  done');
+        lines.push('  return 1');
+        lines.push('}');
+        return lines.join('\n') + '\n';
+    }
+}
+export default WorkflowEngine;

package/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en" class="h-full bg-gray-950" data-theme="neon-glass">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Orbital Command</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;600;700&family=Space+Grotesk:wght@300;400;500;600;700&display=swap" rel="stylesheet" />
+  </head>
+  <body class="h-full">
+    <div id="root" class="h-full"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "orbital-command",
+  "version": "0.1.0",
+  "description": "Orbital Command — mission control dashboard for Claude Code projects",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "project-management",
+    "kanban",
+    "mission-control",
+    "dashboard",
+    "workflow",
+    "ai-agents",
+    "scope-management",
+    "sprint",
+    "devtools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SakaraLabs/orbital-command.git"
+  },
+  "homepage": "https://github.com/SakaraLabs/orbital-command#readme",
+  "bugs": {
+    "url": "https://github.com/SakaraLabs/orbital-command/issues"
+  },
+  "bin": {
+    "orbital": "bin/orbital.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "server/",
+    "shared/",
+    "src/",
+    "templates/",
+    "schemas/",
+    "scripts/",
+    "index.html",
+    "vite.config.ts",
+    "tailwind.config.js",
+    "postcss.config.js",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "orbital dev",
+    "dev:local": "trap 'lsof -ti:4444,4445 | xargs kill 2>/dev/null' EXIT; concurrently -n server,client -c blue,green \"npm run dev:server\" \"npm run dev:client\"",
+    "dev:server": "tsx watch server/index.ts",
+    "dev:client": "vite",
+    "build": "./node_modules/.bin/vite build",
+    "build:server": "./node_modules/.bin/tsc -p tsconfig.server.json",
+    "typecheck": "./node_modules/.bin/tsc --noEmit && ./node_modules/.bin/tsc --noEmit -p tsconfig.server.json",
+    "postinstall": "node scripts/postinstall.js",
+    "prepublishOnly": "npm run typecheck && npm run build && npm run build:server",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@radix-ui/react-dialog": "^1.1.4",
+    "@radix-ui/react-dropdown-menu": "^2.1.4",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-scroll-area": "^1.2.2",
+    "@radix-ui/react-select": "^2.1.4",
+    "@radix-ui/react-separator": "^1.1.1",
+    "@radix-ui/react-slot": "^1.1.1",
+    "@radix-ui/react-tabs": "^1.1.2",
+    "@radix-ui/react-tooltip": "^1.1.6",
+    "@xyflow/react": "^12.10.1",
+    "better-sqlite3": "^12.0.0",
+    "chokidar": "^4.0.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
+    "express": "^4.21.2",
+    "framer-motion": "^11.15.0",
+    "gray-matter": "^4.0.3",
+    "lucide-react": "^0.577.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-markdown": "^10.1.0",
+    "react-router-dom": "^6.30.2",
+    "recharts": "^2.15.0",
+    "remark-gfm": "^4.0.1",
+    "socket.io": "^4.8.1",
+    "socket.io-client": "^4.8.1",
+    "tailwind-merge": "^2.6.0",
+    "tsx": "^4.19.2",
+    "vite": "^6.0.7"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/express": "^5.0.0",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@vitejs/plugin-react": "^4.7.0",
+    "autoprefixer": "^10.4.27",
+    "concurrently": "^9.2.1",
+    "postcss": "^8.5.8",
+    "tailwindcss": "^3.4.19",
+    "tailwindcss-animate": "^1.0.7",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/schemas/orbital.config.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "https://orbital-command.dev/schemas/orbital.config.schema.json",
+  "title": "Orbital Command Configuration",
+  "description": "Configuration file for Orbital Command — mission control for Claude Code projects",
+  "type": "object",
+  "properties": {
+    "projectName": { "type": "string", "description": "Display name in dashboard header", "default": "My Project" },
+    "scopesDir": { "type": "string", "description": "Directory for scope documents (relative to project root)", "default": "scopes" },
+    "eventsDir": { "type": "string", "description": "Directory for event bus files (relative to project root)", "default": ".claude/orbital-events" },
+    "dbDir": { "type": "string", "description": "Directory for SQLite database (relative to project root)", "default": ".claude/orbital" },
+    "configDir": { "type": "string", "description": "Directory for workflow config + manifest (relative to project root)", "default": ".claude/config" },
+    "serverPort": { "type": "integer", "description": "API server port", "default": 4444, "minimum": 1, "maximum": 65535 },
+    "clientPort": { "type": "integer", "description": "Vite dev server port", "default": 4445, "minimum": 1, "maximum": 65535 },
+    "terminal": {
+      "type": "object",
+      "properties": {
+        "adapter": { "type": "string", "enum": ["auto", "iterm2", "subprocess", "none"], "default": "auto", "description": "Terminal adapter for session launching" },
+        "profilePrefix": { "type": "string", "default": "Orbital", "description": "Prefix for iTerm2 dynamic profile names" }
+      },
+      "additionalProperties": false
+    },
+    "claude": {
+      "type": "object",
+      "properties": {
+        "executable": { "type": "string", "default": "claude", "description": "Path to Claude Code CLI executable" },
+        "flags": { "type": "array", "items": { "type": "string" }, "default": ["--dangerously-skip-permissions"], "description": "Default flags for Claude Code sessions" }
+      },
+      "additionalProperties": false
+    },
+    "commands": {
+      "type": "object",
+      "description": "Build/test/lint commands. Set to null to skip.",
+      "properties": {
+        "typeCheck": { "type": ["string", "null"], "default": null },
+        "lint": { "type": ["string", "null"], "default": null },
+        "build": { "type": ["string", "null"], "default": null },
+        "test": { "type": ["string", "null"], "default": null },
+        "validateTemplates": { "type": ["string", "null"], "default": null },
+        "validateDocs": { "type": ["string", "null"], "default": null },
+        "checkRules": { "type": ["string", "null"], "default": null }
+      },
+      "additionalProperties": false
+    },
+    "categories": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": ["feature", "bugfix", "refactor", "infrastructure", "docs"],
+      "description": "Scope categories shown in the dashboard"
+    },
+    "agents": {
+      "type": "array",
+      "description": "Agent definitions for the dashboard and agent system",
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "emoji", "color"],
+        "properties": {
+          "id": { "type": "string", "description": "Agent identifier (lowercase, kebab-case)" },
+          "label": { "type": "string", "description": "Display name" },
+          "emoji": { "type": "string", "description": "Emoji icon for the agent" },
+          "color": { "type": "string", "description": "Hex color for dashboard display" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "logLevel": {
+      "type": "string",
+      "enum": ["debug", "info", "warn", "error"],
+      "default": "info",
+      "description": "Server log verbosity level"
+    },
+    "healthChecks": {
+      "type": "object",
+      "description": "Health check URLs by environment",
+      "properties": {
+        "staging": { "type": "string", "format": "uri" },
+        "production": { "type": "string", "format": "uri" }
+      },
+      "additionalProperties": { "type": "string", "format": "uri" }
+    }
+  },
+  "additionalProperties": false
+}

package/scripts/postinstall.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+// Safety net for esbuild's platform-specific binary.
+//
+// esbuild (a transitive dependency of Vite) ships as a stub that downloads
+// its native binary via postinstall. If that step was skipped or failed
+// silently, this script re-triggers the download.
+
+import { existsSync } from 'fs';
+import { execFileSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+const esbuildInstall = path.join(packageRoot, 'node_modules', 'esbuild', 'install.js');
+
+if (existsSync(esbuildInstall)) {
+  try {
+    execFileSync('node', [esbuildInstall], { stdio: 'pipe' });
+  } catch {
+    // Already installed or not applicable
+  }
+}

package/scripts/start.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Start Orbital Command
+# Usage: ./scripts/start.sh
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+cd "$PROJECT_DIR"
+
+# Install deps if needed
+if [ ! -d "node_modules" ]; then
+  echo "[Orbital] Installing dependencies..."
+  npm install
+fi
+
+# Start both server and client
+echo "[Orbital] Starting Orbital Command..."
+npm run dev

package/server/adapters/index.ts

@@ -0,0 +1,41 @@
+import type { TerminalAdapter } from './terminal-adapter.js';
+import { getConfig } from '../config.js';
+import { ITerm2Adapter, isITerm2Available } from './iterm2-adapter.js';
+import { SubprocessAdapter } from './subprocess-adapter.js';
+
+export type { TerminalAdapter, LaunchOptions, CategorizedLaunchOptions, WindowCategory } from './terminal-adapter.js';
+
+let _adapter: TerminalAdapter | null = null;
+
+/**
+ * Get the terminal adapter singleton.
+ * Auto-detects based on config and platform:
+ *   - "iterm2" → iTerm2 adapter (macOS only)
+ *   - "subprocess" → cross-platform subprocess fallback
+ *   - "none" → no-op adapter (for headless/CI)
+ *   - "auto" → iTerm2 if available, else subprocess
+ */
+export function getTerminalAdapter(): TerminalAdapter {
+  if (_adapter) return _adapter;
+
+  const preference = getConfig().terminal.adapter;
+
+  if (preference === 'none') {
+    _adapter = { launch: async () => {}, launchCategorized: async () => {} };
+    return _adapter;
+  }
+
+  if (preference === 'iterm2' || preference === 'auto') {
+    try {
+      if (preference === 'iterm2' || isITerm2Available()) {
+        _adapter = new ITerm2Adapter();
+        return _adapter;
+      }
+    } catch {
+      // iTerm2 adapter not available — fall through
+    }
+  }
+
+  _adapter = new SubprocessAdapter();
+  return _adapter;
+}