orbital-command 0.1.0

package/server/adapters/iterm2-adapter.ts

@@ -0,0 +1,37 @@
+import { execFileSync } from 'child_process';
+import type { TerminalAdapter, LaunchOptions, CategorizedLaunchOptions } from './terminal-adapter.js';
+import {
+  launchInTerminal,
+  launchInCategorizedTerminal,
+} from '../utils/terminal-launcher.js';
+
+/**
+ * iTerm2 terminal adapter for macOS.
+ * Uses AppleScript to create windows, tabs, and dynamic profiles.
+ * Provides categorized window grouping (tabs grouped by workflow stage).
+ */
+export class ITerm2Adapter implements TerminalAdapter {
+  async launch(command: string, _opts?: LaunchOptions): Promise<void> {
+    await launchInTerminal(command);
+  }
+
+  async launchCategorized(command: string, fullCmd: string, opts?: CategorizedLaunchOptions): Promise<void> {
+    await launchInCategorizedTerminal(command, fullCmd, opts?.tabName);
+  }
+
+  // ensureProfiles is handled directly via ensureDynamicProfiles(engine) in server startup
+}
+
+/** Check if iTerm2 is available on this system */
+export function isITerm2Available(): boolean {
+  if (process.platform !== 'darwin') return false;
+
+  try {
+    execFileSync('osascript', [
+      '-e', 'tell application "System Events" to (name of processes) contains "iTerm2"',
+    ], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/server/adapters/subprocess-adapter.ts

@@ -0,0 +1,25 @@
+import { spawn } from 'child_process';
+import type { TerminalAdapter, LaunchOptions, CategorizedLaunchOptions } from './terminal-adapter.js';
+import { createLogger } from '../utils/logger.js';
+
+const log = createLogger('terminal');
+
+/**
+ * Cross-platform terminal adapter using child_process.spawn.
+ * Runs Claude sessions as background subprocesses — works on any OS.
+ * Does not provide windowed/tabbed grouping (use iTerm2 adapter for that).
+ */
+export class SubprocessAdapter implements TerminalAdapter {
+  async launch(command: string, _opts?: LaunchOptions): Promise<void> {
+    const child = spawn('sh', ['-c', command], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.on('error', (err: Error) => log.error('Subprocess launch failed', { error: err.message }));
+    child.unref();
+  }
+
+  async launchCategorized(_command: string, fullCmd: string, _opts?: CategorizedLaunchOptions): Promise<void> {
+    await this.launch(fullCmd);
+  }
+}

package/server/adapters/terminal-adapter.ts

@@ -0,0 +1,24 @@
+/**
+ * Terminal adapter interface for cross-platform session launching.
+ * Implementations handle the specifics of opening new terminal windows/tabs.
+ */
+export interface TerminalAdapter {
+  /** Launch a command in a new terminal window/process */
+  launch(command: string, opts?: LaunchOptions): Promise<void>;
+
+  /** Launch a command in a categorized window (tabs grouped by category) */
+  launchCategorized(command: string, fullCmd: string, opts?: CategorizedLaunchOptions): Promise<void>;
+
+  /** Set up any required profiles/configuration (e.g., iTerm2 dynamic profiles) */
+  ensureProfiles?(): Promise<void>;
+}
+
+export interface LaunchOptions {
+  name?: string;
+}
+
+export interface CategorizedLaunchOptions {
+  tabName?: string | null;
+}
+
+export type WindowCategory = 'Scoping' | 'Planning' | 'Implementing' | 'Reviewing' | 'Deploying';

package/server/config.ts

@@ -0,0 +1,234 @@
+import path from 'path';
+import fs from 'fs';
+import { execFileSync } from 'child_process';
+import os from 'os';
+import { createLogger } from './utils/logger.js';
+
+// ─── Types ──────────────────────────────────────────────────
+
+export interface TerminalConfig {
+  adapter: 'auto' | 'iterm2' | 'subprocess' | 'none';
+  profilePrefix: string;
+}
+
+export interface ClaudeConfig {
+  executable: string;
+  flags: string[];
+}
+
+export interface CommandsConfig {
+  typeCheck: string | null;
+  lint: string | null;
+  build: string | null;
+  test: string | null;
+  validateTemplates: string | null;
+  validateDocs: string | null;
+  checkRules: string | null;
+}
+
+export type { AgentConfig } from '../shared/api-types.js';
+import type { AgentConfig } from '../shared/api-types.js';
+
+export interface OrbitalConfig {
+  projectName: string;
+  projectRoot: string;
+
+  // Directories (resolved to absolute paths)
+  scopesDir: string;
+  eventsDir: string;
+  dbDir: string;
+  configDir: string;
+
+  // Ports
+  serverPort: number;
+  clientPort: number;
+
+  // Terminal integration
+  terminal: TerminalConfig;
+
+  // Claude Code CLI
+  claude: ClaudeConfig;
+
+  // Build/test commands
+  commands: CommandsConfig;
+
+  // Logging
+  logLevel: 'debug' | 'info' | 'warn' | 'error';
+
+  // Dynamic configuration
+  categories: string[];
+  agents: AgentConfig[];
+}
+
+// ─── Defaults ───────────────────────────────────────────────
+
+const DEFAULT_CONFIG: Omit<OrbitalConfig, 'projectRoot'> = {
+  projectName: 'Project',
+  scopesDir: 'scopes',
+  eventsDir: '.claude/orbital-events',
+  dbDir: '.claude/orbital',
+  configDir: '.claude/config',
+  serverPort: 4444,
+  clientPort: 4445,
+  terminal: {
+    adapter: 'auto',
+    profilePrefix: 'Orbital',
+  },
+  claude: {
+    executable: 'claude',
+    flags: ['--dangerously-skip-permissions'],
+  },
+  commands: {
+    typeCheck: null,
+    lint: null,
+    build: null,
+    test: null,
+    validateTemplates: null,
+    validateDocs: null,
+    checkRules: null,
+  },
+  logLevel: 'info' as const,
+  categories: ['feature', 'bugfix', 'refactor', 'infrastructure', 'docs'],
+  agents: [
+    { id: 'attacker', label: 'Attacker', emoji: '\u{1F5E1}\u{FE0F}', color: '#ff1744' },
+    { id: 'chaos', label: 'Chaos', emoji: '\u{1F4A5}', color: '#F97316' },
+    { id: 'solana-expert', label: 'Solana Expert', emoji: '\u{26D3}\u{FE0F}', color: '#8B5CF6' },
+    { id: 'frontend-designer', label: 'Frontend Designer', emoji: '\u{1F3A8}', color: '#EC4899' },
+    { id: 'architect', label: 'Architect', emoji: '\u{1F3D7}\u{FE0F}', color: '#536dfe' },
+    { id: 'rules-enforcer', label: 'Rules Enforcer', emoji: '\u{1F4CB}', color: '#6B7280' },
+  ],
+};
+
+// ─── Project Root Resolution ────────────────────────────────
+
+/**
+ * Resolve the project root directory.
+ * Priority: ORBITAL_PROJECT_ROOT env > git rev-parse > cwd walk > cwd
+ */
+export function resolveProjectRoot(): string {
+  // 1. Explicit env var
+  if (process.env.ORBITAL_PROJECT_ROOT) {
+    return path.resolve(process.env.ORBITAL_PROJECT_ROOT);
+  }
+
+  // 2. git rev-parse --show-toplevel
+  try {
+    const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (gitRoot) return gitRoot;
+  } catch {
+    // Not in a git repo — continue
+  }
+
+  // 3. Walk up from cwd looking for .git directory
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    dir = path.dirname(dir);
+  }
+
+  // 4. Fall back to cwd
+  return process.cwd();
+}
+
+// ─── Claude Sessions Path ───────────────────────────────────
+
+/**
+ * Derive the Claude Code sessions directory for a project.
+ * Claude Code encodes the project path by replacing `/` with `-`.
+ * The leading `/` becomes the leading `-` in the directory name.
+ */
+export function getClaudeSessionsDir(projectRoot: string): string {
+  const encoded = projectRoot.replace(/\//g, '-');
+  return path.join(os.homedir(), '.claude', 'projects', encoded);
+}
+
+// ─── Config Loading ─────────────────────────────────────────
+
+/**
+ * Load and merge orbital.config.json with defaults.
+ * Resolves all relative paths to absolute using projectRoot.
+ */
+export function loadConfig(projectRoot?: string): OrbitalConfig {
+  const root = projectRoot ?? resolveProjectRoot();
+
+  // Try loading user config
+  const configPath = path.join(root, '.claude', 'orbital.config.json');
+  let userConfig: Record<string, unknown> = {};
+
+  const log = createLogger('config');
+
+  if (fs.existsSync(configPath)) {
+    try {
+      userConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch (err) {
+      log.warn('Failed to parse orbital.config.json — using defaults', { error: (err as Error).message });
+    }
+  }
+
+  // Merge with defaults
+  const projectName = (userConfig.projectName as string) ?? DEFAULT_CONFIG.projectName;
+
+  const scopesDir = path.resolve(root, (userConfig.scopesDir as string) ?? DEFAULT_CONFIG.scopesDir);
+  const eventsDir = path.resolve(root, (userConfig.eventsDir as string) ?? DEFAULT_CONFIG.eventsDir);
+  const dbDir = path.resolve(root, (userConfig.dbDir as string) ?? DEFAULT_CONFIG.dbDir);
+  const configDir = path.resolve(root, (userConfig.configDir as string) ?? DEFAULT_CONFIG.configDir);
+
+  const serverPort = (userConfig.serverPort as number) ?? DEFAULT_CONFIG.serverPort;
+  const clientPort = (userConfig.clientPort as number) ?? DEFAULT_CONFIG.clientPort;
+
+  const terminal: TerminalConfig = {
+    ...DEFAULT_CONFIG.terminal,
+    ...(userConfig.terminal as Partial<TerminalConfig> ?? {}),
+  };
+
+  const claude: ClaudeConfig = {
+    ...DEFAULT_CONFIG.claude,
+    ...(userConfig.claude as Partial<ClaudeConfig> ?? {}),
+  };
+
+  const commands: CommandsConfig = {
+    ...DEFAULT_CONFIG.commands,
+    ...(userConfig.commands as Partial<CommandsConfig> ?? {}),
+  };
+
+  const logLevel = (userConfig.logLevel as OrbitalConfig['logLevel']) ?? DEFAULT_CONFIG.logLevel;
+  const categories = (userConfig.categories as string[]) ?? DEFAULT_CONFIG.categories;
+  const agents = (userConfig.agents as AgentConfig[]) ?? DEFAULT_CONFIG.agents;
+
+  return {
+    projectName,
+    projectRoot: root,
+    scopesDir,
+    eventsDir,
+    dbDir,
+    configDir,
+    serverPort,
+    clientPort,
+    terminal,
+    claude,
+    commands,
+    logLevel,
+    categories,
+    agents,
+  };
+}
+
+// ─── Singleton ──────────────────────────────────────────────
+
+let _config: OrbitalConfig | null = null;
+
+/** Get the global config singleton. Lazy-loaded on first access. */
+export function getConfig(): OrbitalConfig {
+  if (!_config) {
+    _config = loadConfig();
+  }
+  return _config;
+}
+
+/** Reset the config singleton (for testing or hot-reload). */
+export function resetConfig(): void {
+  _config = null;
+}

package/server/database.ts

@@ -0,0 +1,107 @@
+import Database from 'better-sqlite3';
+import path from 'path';
+import fs from 'fs';
+import { SCHEMA_DDL } from './schema.js';
+import { getConfig } from './config.js';
+import { createLogger } from './utils/logger.js';
+
+const log = createLogger('database');
+
+function getDbPaths(): { dir: string; file: string } {
+  const config = getConfig();
+  return { dir: config.dbDir, file: path.join(config.dbDir, 'orbital.db') };
+}
+
+let db: Database.Database | null = null;
+
+export function getDatabase(): Database.Database {
+  if (db) return db;
+
+  const { dir, file } = getDbPaths();
+  fs.mkdirSync(dir, { recursive: true });
+
+  db = new Database(file);
+  log.info('Database initialized', { path: file });
+
+  // Performance pragmas for a local dev tool
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+  db.pragma('foreign_keys = ON');
+
+  // Run schema migrations (SQLite db.exec, not child_process)
+  db.exec(SCHEMA_DDL);
+
+  // Incremental migrations for existing databases
+  runMigrations(db);
+
+  return db;
+}
+
+/** Check if a table exists in the database */
+function tableExists(database: Database.Database, tableName: string): boolean {
+  const row = database.prepare(
+    "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+  ).get(tableName) as { name: string } | undefined;
+  return row !== undefined;
+}
+
+/** Run incremental migrations for schema changes on existing databases */
+function runMigrations(database: Database.Database): void {
+  log.debug('Running database migrations');
+  // Migration 2: Add claude_session_id column to sessions
+  const sessionCols = database.pragma('table_info(sessions)') as Array<{ name: string }>;
+  if (!sessionCols.some((c) => c.name === 'claude_session_id')) {
+    database.exec('ALTER TABLE sessions ADD COLUMN claude_session_id TEXT');
+  }
+
+  // Migration 6: Add action column to sessions for frontmatter lifecycle phase
+  if (!sessionCols.some((c) => c.name === 'action')) {
+    database.exec('ALTER TABLE sessions ADD COLUMN action TEXT');
+  }
+
+  // Migration 8: Add batch group columns to sprints
+  const sprintCols = database.pragma('table_info(sprints)') as Array<{ name: string }>;
+  if (!sprintCols.some((c) => c.name === 'target_column')) {
+    database.exec("ALTER TABLE sprints ADD COLUMN target_column TEXT DEFAULT 'backlog'");
+    database.exec("ALTER TABLE sprints ADD COLUMN group_type TEXT DEFAULT 'sprint'");
+    database.exec("ALTER TABLE sprints ADD COLUMN dispatch_result TEXT DEFAULT '{}'");
+    database.exec('CREATE INDEX IF NOT EXISTS idx_sprints_target_column ON sprints(target_column)');
+  }
+
+  // Migration 7: Drop scopes table — scopes are now served from in-memory cache.
+  // Recreate sprint_scopes without the FK to scopes.
+  if (tableExists(database, 'scopes')) {
+    database.exec(`
+      -- Backup sprint_scopes data
+      CREATE TABLE IF NOT EXISTS sprint_scopes_backup AS SELECT * FROM sprint_scopes;
+      -- Drop tables with FK dependencies first
+      DROP TABLE IF EXISTS sprint_scopes;
+      -- Drop the scopes table
+      DROP TABLE IF EXISTS scopes;
+      -- Recreate sprint_scopes without FK to scopes
+      CREATE TABLE IF NOT EXISTS sprint_scopes (
+        sprint_id INTEGER NOT NULL,
+        scope_id INTEGER NOT NULL,
+        layer INTEGER,
+        dispatch_status TEXT NOT NULL DEFAULT 'pending',
+        dispatched_at TEXT,
+        completed_at TEXT,
+        error TEXT,
+        PRIMARY KEY (sprint_id, scope_id),
+        FOREIGN KEY (sprint_id) REFERENCES sprints(id) ON DELETE CASCADE
+      );
+      -- Restore data
+      INSERT OR IGNORE INTO sprint_scopes SELECT * FROM sprint_scopes_backup;
+      -- Cleanup
+      DROP TABLE IF EXISTS sprint_scopes_backup;
+    `);
+  }
+}
+
+export function closeDatabase(): void {
+  if (db) {
+    db.close();
+    db = null;
+    log.debug('Database closed');
+  }
+}