orbital-command 0.2.0 → 1.0.0

package/server/__tests__/sprint-routes.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, beforeAll, vi } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { createSprintRoutes } from '../routes/sprint-routes.js';
+
+describe('sprint-routes', () => {
+  let app: express.Express;
+
+  const mockSprintService = {
+    create: vi.fn().mockReturnValue({ id: 1, name: 'Sprint 1', status: 'assembling', scope_ids: [], scopes: [], layers: null, progress: { pending: 0, in_progress: 0, completed: 0, failed: 0, skipped: 0 } }),
+    getAll: vi.fn().mockReturnValue([]),
+    getById: vi.fn((id: number) => id === 1 ? { id: 1, name: 'Sprint 1', status: 'assembling', scope_ids: [], scopes: [] } : null),
+    rename: vi.fn().mockReturnValue(true),
+    delete: vi.fn().mockReturnValue(true),
+    addScopes: vi.fn().mockReturnValue({ added: [1, 2], unmet_dependencies: [] }),
+    removeScopes: vi.fn().mockReturnValue(true),
+  };
+
+  const mockSprintOrchestrator = {
+    startSprint: vi.fn().mockReturnValue({ ok: true, layers: [[1], [2]] }),
+    cancelSprint: vi.fn().mockReturnValue({ ok: true }),
+    getExecutionGraph: vi.fn().mockReturnValue({ nodes: [], edges: [] }),
+  };
+
+  const mockBatchOrchestrator = {
+    dispatch: vi.fn().mockReturnValue({ ok: true }),
+  };
+
+  beforeAll(() => {
+    const router = createSprintRoutes({
+      sprintService: mockSprintService as any,
+      sprintOrchestrator: mockSprintOrchestrator as any,
+      batchOrchestrator: mockBatchOrchestrator as any,
+    });
+
+    app = express();
+    app.use(express.json());
+    app.use('/api/orbital', router);
+  });
+
+  describe('POST /sprints', () => {
+    it('creates sprint with name (201)', async () => {
+      const res = await request(app)
+        .post('/api/orbital/sprints')
+        .send({ name: 'New Sprint' });
+      expect(res.status).toBe(201);
+      expect(mockSprintService.create).toHaveBeenCalledWith('New Sprint', expect.anything());
+    });
+
+    it('rejects empty name (400)', async () => {
+      const res = await request(app)
+        .post('/api/orbital/sprints')
+        .send({ name: '  ' });
+      expect(res.status).toBe(400);
+    });
+  });
+
+  describe('GET /sprints', () => {
+    it('returns sprint list', async () => {
+      const res = await request(app).get('/api/orbital/sprints');
+      expect(res.status).toBe(200);
+      expect(Array.isArray(res.body)).toBe(true);
+    });
+
+    it('passes status filter', async () => {
+      await request(app).get('/api/orbital/sprints?status=assembling');
+      expect(mockSprintService.getAll).toHaveBeenCalledWith('assembling', undefined);
+    });
+  });
+
+  describe('PATCH /sprints/:id', () => {
+    it('renames sprint', async () => {
+      const res = await request(app)
+        .patch('/api/orbital/sprints/1')
+        .send({ name: 'Renamed' });
+      expect(res.status).toBe(200);
+    });
+
+    it('rejects missing name (400)', async () => {
+      const res = await request(app)
+        .patch('/api/orbital/sprints/1')
+        .send({});
+      expect(res.status).toBe(400);
+    });
+  });
+
+  describe('DELETE /sprints/:id', () => {
+    it('deletes sprint', async () => {
+      const res = await request(app).delete('/api/orbital/sprints/1');
+      expect(res.status).toBe(200);
+    });
+  });
+
+  describe('POST /sprints/:id/scopes', () => {
+    it('adds scopes to sprint', async () => {
+      const res = await request(app)
+        .post('/api/orbital/sprints/1/scopes')
+        .send({ scope_ids: [1, 2] });
+      expect(res.status).toBe(200);
+    });
+
+    it('rejects empty scope_ids (400)', async () => {
+      const res = await request(app)
+        .post('/api/orbital/sprints/1/scopes')
+        .send({ scope_ids: [] });
+      expect(res.status).toBe(400);
+    });
+  });
+
+  describe('POST /sprints/:id/dispatch', () => {
+    it('dispatches sprint', async () => {
+      const res = await request(app)
+        .post('/api/orbital/sprints/1/dispatch')
+        .send({});
+      expect(res.status).toBe(200);
+    });
+  });
+});

package/server/__tests__/workflow-routes.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeAll, vi } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { createWorkflowRoutes } from '../routes/workflow-routes.js';
+import { WorkflowEngine } from '../../shared/workflow-engine.js';
+import { DEFAULT_CONFIG, MINIMAL_CONFIG } from '../../shared/__fixtures__/workflow-configs.js';
+
+describe('workflow-routes', () => {
+  let app: express.Express;
+  const engine = new WorkflowEngine(DEFAULT_CONFIG);
+
+  const mockWorkflowService = {
+    getActive: vi.fn().mockReturnValue(DEFAULT_CONFIG),
+    updateActive: vi.fn().mockReturnValue({ valid: true, errors: [], warnings: [] }),
+    listPresets: vi.fn().mockReturnValue([{ name: 'default', createdAt: '2026-01-01', listCount: 7, edgeCount: 14 }]),
+    savePreset: vi.fn(),
+    getPreset: vi.fn((name: string) => name === 'default' ? DEFAULT_CONFIG : (() => { throw new Error('Not found'); })()),
+    deletePreset: vi.fn((name: string) => { if (name === 'default') throw new Error('Cannot delete default'); }),
+    previewMigration: vi.fn().mockReturnValue({ orphanedScopes: [], addedLists: [], removedLists: [], scopeMoves: [] }),
+    applyMigration: vi.fn().mockReturnValue({ orphanedScopes: [], addedLists: [], removedLists: [], scopeMoves: [] }),
+    getEngine: vi.fn().mockReturnValue(engine),
+  };
+
+  beforeAll(() => {
+    const router = createWorkflowRoutes({
+      workflowService: mockWorkflowService as any,
+      projectRoot: '/tmp/test-project',
+    });
+
+    app = express();
+    app.use(express.json());
+    app.use('/api/orbital', router);
+  });
+
+  describe('GET /workflow', () => {
+    it('returns active workflow config', async () => {
+      const res = await request(app).get('/api/orbital/workflow');
+      expect(res.status).toBe(200);
+      expect(res.body.success).toBe(true);
+      expect(res.body.data.name).toBe('Default Workflow');
+    });
+  });
+
+  describe('PUT /workflow', () => {
+    it('updates workflow config', async () => {
+      const res = await request(app)
+        .put('/api/orbital/workflow')
+        .send(MINIMAL_CONFIG);
+      expect(res.status).toBe(200);
+    });
+
+    it('returns 400 for invalid config', async () => {
+      mockWorkflowService.updateActive.mockReturnValueOnce({ valid: false, errors: ['Missing lists'], warnings: [] });
+      const res = await request(app)
+        .put('/api/orbital/workflow')
+        .send({ version: 1, name: 'Bad', lists: [], edges: [] });
+      expect(res.status).toBe(400);
+    });
+  });
+
+  describe('GET /workflow/presets', () => {
+    it('returns preset list', async () => {
+      const res = await request(app).get('/api/orbital/workflow/presets');
+      expect(res.status).toBe(200);
+      expect(res.body.success).toBe(true);
+      expect(Array.isArray(res.body.data)).toBe(true);
+    });
+  });
+
+  describe('POST /workflow/presets', () => {
+    it('saves preset with valid name', async () => {
+      const res = await request(app)
+        .post('/api/orbital/workflow/presets')
+        .send({ name: 'my-preset' });
+      expect(res.status).toBe(200);
+      expect(mockWorkflowService.savePreset).toHaveBeenCalledWith('my-preset');
+    });
+
+    it('rejects missing name (400)', async () => {
+      const res = await request(app)
+        .post('/api/orbital/workflow/presets')
+        .send({});
+      expect(res.status).toBe(400);
+    });
+  });
+
+  describe('DELETE /workflow/presets/:name', () => {
+    it('rejects deleting default preset', async () => {
+      const res = await request(app).delete('/api/orbital/workflow/presets/default');
+      expect(res.status).toBe(400);
+    });
+  });
+
+  describe('GET /workflow/hooks', () => {
+    it('returns hooks with edge mapping', async () => {
+      const res = await request(app).get('/api/orbital/workflow/hooks');
+      expect(res.status).toBe(200);
+      expect(res.body.success).toBe(true);
+    });
+  });
+
+  describe('GET /workflow/hooks/:id/source', () => {
+    it('rejects path traversal attempts', async () => {
+      // The engine has hooks with targets like '.claude/hooks/blocker-check.sh'
+      // Trying to traverse out should fail
+      const res = await request(app).get('/api/orbital/workflow/hooks/../../etc/passwd/source');
+      expect([400, 404]).toContain(res.status);
+    });
+  });
+
+  describe('POST /workflow/preview', () => {
+    it('returns migration preview', async () => {
+      const res = await request(app)
+        .post('/api/orbital/workflow/preview')
+        .send(MINIMAL_CONFIG);
+      expect(res.status).toBe(200);
+      expect(res.body.success).toBe(true);
+    });
+  });
+});

package/server/config-migrator.ts

@@ -0,0 +1,160 @@
+/**
+ * Config migration runner for orbital.config.json.
+ *
+ * Applies incremental, idempotent migrations when upgrading between
+ * package versions. Also fills schema defaults for new fields that
+ * don't require explicit migration logic.
+ */
+
+import fs from 'fs';
+import type { ConfigMigration } from './manifest-types.js';
+
+// ─── Migration Registry ─────────────────────────────────────
+
+/**
+ * All config migrations, ordered by target version.
+ *
+ * Rules:
+ * - Each migration MUST be idempotent (safe to run twice)
+ * - Each migration MUST check before applying (don't blindly overwrite)
+ * - ID format: "fromVersion->toVersion"
+ */
+const MIGRATIONS: ConfigMigration[] = [
+  // Future migrations go here. Example:
+  // {
+  //   id: '0.2.0->0.3.0',
+  //   description: 'Add notifications config section',
+  //   migrate: (config) => {
+  //     if (!('notifications' in config)) {
+  //       config.notifications = { enabled: false };
+  //     }
+  //     return config;
+  //   },
+  // },
+];
+
+// ─── Schema Defaults ────────────────────────────────────────
+
+/** Default values from the schema, keyed by property path. */
+const SCHEMA_DEFAULTS: Record<string, unknown> = {
+  projectName: 'My Project',
+  scopesDir: 'scopes',
+  eventsDir: '.claude/orbital-events',
+  dbDir: '.claude/orbital',
+  configDir: '.claude/config',
+  serverPort: 4444,
+  clientPort: 4445,
+  logLevel: 'info',
+  categories: ['feature', 'bugfix', 'refactor', 'infrastructure', 'docs'],
+};
+
+const NESTED_DEFAULTS: Record<string, Record<string, unknown>> = {
+  terminal: {
+    adapter: 'auto',
+    profilePrefix: 'Orbital',
+  },
+  claude: {
+    executable: 'claude',
+    flags: ['--dangerously-skip-permissions'],
+  },
+  commands: {
+    typeCheck: null,
+    lint: null,
+    build: null,
+    test: null,
+  },
+};
+
+// ─── Public API ─────────────────────────────────────────────
+
+export interface MigrationResult {
+  applied: string[];
+  defaultsFilled: string[];
+  errors: string[];
+}
+
+/**
+ * Run all pending config migrations and fill schema defaults.
+ *
+ * @param configPath - Path to orbital.config.json
+ * @param appliedMigrations - IDs already recorded in the manifest
+ * @returns List of migration IDs that were applied
+ */
+export function migrateConfig(
+  configPath: string,
+  appliedMigrations: string[],
+): MigrationResult {
+  const result: MigrationResult = { applied: [], defaultsFilled: [], errors: [] };
+
+  if (!fs.existsSync(configPath)) return result;
+
+  let config: Record<string, unknown>;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch {
+    result.errors.push('Failed to parse orbital.config.json');
+    return result;
+  }
+
+  const appliedSet = new Set(appliedMigrations);
+
+  // Apply explicit migrations in order
+  for (const migration of MIGRATIONS) {
+    if (appliedSet.has(migration.id)) continue;
+
+    try {
+      config = migration.migrate(config);
+      result.applied.push(migration.id);
+    } catch (err) {
+      result.errors.push(`Migration ${migration.id} failed: ${String(err)}`);
+    }
+  }
+
+  // Fill schema defaults for missing top-level properties
+  for (const [key, defaultValue] of Object.entries(SCHEMA_DEFAULTS)) {
+    if (!(key in config)) {
+      config[key] = defaultValue;
+      result.defaultsFilled.push(key);
+    }
+  }
+
+  // Fill nested defaults
+  for (const [section, defaults] of Object.entries(NESTED_DEFAULTS)) {
+    if (!(section in config)) {
+      config[section] = { ...defaults };
+      result.defaultsFilled.push(section);
+    } else if (typeof config[section] === 'object' && config[section] !== null) {
+      const sectionObj = config[section] as Record<string, unknown>;
+      for (const [key, defaultValue] of Object.entries(defaults)) {
+        if (!(key in sectionObj)) {
+          sectionObj[key] = defaultValue;
+          result.defaultsFilled.push(`${section}.${key}`);
+        }
+      }
+    }
+  }
+
+  // Write back if any changes were made
+  if (result.applied.length > 0 || result.defaultsFilled.length > 0) {
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+  }
+
+  return result;
+}
+
+/**
+ * Get all migration IDs that haven't been applied yet.
+ */
+export function getPendingMigrations(appliedMigrations: string[]): string[] {
+  const appliedSet = new Set(appliedMigrations);
+  return MIGRATIONS
+    .filter(m => !appliedSet.has(m.id))
+    .map(m => m.id);
+}
+
+/**
+ * Get all registered migrations (for display/debug).
+ */
+export function getAllMigrations(): Array<{ id: string; description: string }> {
+  return MIGRATIONS.map(m => ({ id: m.id, description: m.description }));
+}

package/server/config.ts

@@ -14,6 +14,7 @@ export interface TerminalConfig {
 export interface ClaudeConfig {
   executable: string;
   flags: string[];
+  dispatchFlags: DispatchFlags;
 }
 
 export interface CommandsConfig {
@@ -21,13 +22,18 @@ export interface CommandsConfig {
   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 type { AgentConfig, DispatchFlags, DispatchConfig } from '../shared/api-types.js';
+import type { AgentConfig, DispatchFlags, DispatchConfig } from '../shared/api-types.js';
+import { DEFAULT_DISPATCH_FLAGS, DEFAULT_DISPATCH_CONFIG } from '../shared/api-types.js';
+import { loadGlobalConfig as loadGlobal } from './global-config.js';
+
+export interface TelemetryConfig {
+  enabled: boolean;
+  url: string;
+  headers: Record<string, string>;
+}
 
 export interface OrbitalConfig {
   projectName: string;
@@ -49,6 +55,9 @@ export interface OrbitalConfig {
   // Claude Code CLI
   claude: ClaudeConfig;
 
+  // Dispatch operational settings
+  dispatch: DispatchConfig;
+
   // Build/test commands
   commands: CommandsConfig;
 
@@ -58,6 +67,9 @@ export interface OrbitalConfig {
   // Dynamic configuration
   categories: string[];
   agents: AgentConfig[];
+
+  // Telemetry
+  telemetry: TelemetryConfig;
 }
 
 // ─── Defaults ───────────────────────────────────────────────
@@ -77,22 +89,25 @@ const DEFAULT_CONFIG: Omit<OrbitalConfig, 'projectRoot'> = {
   claude: {
     executable: 'claude',
     flags: ['--dangerously-skip-permissions'],
+    dispatchFlags: DEFAULT_DISPATCH_FLAGS,
   },
+  dispatch: DEFAULT_DISPATCH_CONFIG,
   commands: {
     typeCheck: null,
     lint: null,
     build: null,
     test: null,
-    validateTemplates: null,
-    validateDocs: null,
-    checkRules: null,
   },
   logLevel: 'info' as const,
+  telemetry: {
+    enabled: false,
+    url: '',
+    headers: {},
+  },
   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' },
@@ -154,6 +169,15 @@ export function getClaudeSessionsDir(projectRoot: string): string {
 export function loadConfig(projectRoot?: string): OrbitalConfig {
   const root = projectRoot ?? resolveProjectRoot();
 
+  // Try loading edition overrides (e.g. edition.json at repo root)
+  const editionPath = path.join(root, 'edition.json');
+  let editionConfig: Record<string, unknown> = {};
+  if (fs.existsSync(editionPath)) {
+    try {
+      editionConfig = JSON.parse(fs.readFileSync(editionPath, 'utf-8'));
+    } catch { /* malformed edition.json — ignore */ }
+  }
+
   // Try loading user config
   const configPath = path.join(root, '.claude', 'orbital.config.json');
   let userConfig: Record<string, unknown> = {};
@@ -168,8 +192,11 @@ export function loadConfig(projectRoot?: string): OrbitalConfig {
     }
   }
 
-  // Merge with defaults
-  const projectName = (userConfig.projectName as string) ?? DEFAULT_CONFIG.projectName;
+  // Merge with defaults — derive project name from directory if not configured
+  const defaultProjectName = path.basename(root)
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+  const projectName = (userConfig.projectName as string) ?? defaultProjectName;
 
   const scopesDir = path.resolve(root, (userConfig.scopesDir as string) ?? DEFAULT_CONFIG.scopesDir);
   const eventsDir = path.resolve(root, (userConfig.eventsDir as string) ?? DEFAULT_CONFIG.eventsDir);
@@ -184,11 +211,26 @@ export function loadConfig(projectRoot?: string): OrbitalConfig {
     ...(userConfig.terminal as Partial<TerminalConfig> ?? {}),
   };
 
+  // Global settings — seed from ~/.orbital/config.json
+  let globalDispatchFlags = DEFAULT_DISPATCH_FLAGS;
+  let globalDispatch = DEFAULT_DISPATCH_CONFIG;
+  let globalTelemetry: Partial<TelemetryConfig> = {};
+  try {
+    const global = loadGlobal();
+    if (global.dispatchFlags) globalDispatchFlags = { ...DEFAULT_DISPATCH_FLAGS, ...global.dispatchFlags };
+    if (global.dispatch) globalDispatch = { ...DEFAULT_DISPATCH_CONFIG, ...global.dispatch };
+    if (global.telemetry) globalTelemetry = global.telemetry;
+  } catch { /* global config may not exist yet */ }
+
+  const userClaude = (userConfig.claude as Partial<ClaudeConfig>) ?? {};
   const claude: ClaudeConfig = {
     ...DEFAULT_CONFIG.claude,
-    ...(userConfig.claude as Partial<ClaudeConfig> ?? {}),
+    ...userClaude,
+    dispatchFlags: globalDispatchFlags,
   };
 
+  const dispatch: DispatchConfig = globalDispatch;
+
   const commands: CommandsConfig = {
     ...DEFAULT_CONFIG.commands,
     ...(userConfig.commands as Partial<CommandsConfig> ?? {}),
@@ -198,6 +240,14 @@ export function loadConfig(projectRoot?: string): OrbitalConfig {
   const categories = (userConfig.categories as string[]) ?? DEFAULT_CONFIG.categories;
   const agents = (userConfig.agents as AgentConfig[]) ?? DEFAULT_CONFIG.agents;
 
+  const telemetry: TelemetryConfig = {
+    ...DEFAULT_CONFIG.telemetry,
+    ...globalTelemetry,
+    ...(editionConfig.telemetry as Partial<TelemetryConfig> ?? {}),
+    ...(userConfig.telemetry as Partial<TelemetryConfig> ?? {}),
+  };
+  if (process.env.ORBITAL_TELEMETRY === 'false') telemetry.enabled = false;
+
   return {
     projectName,
     projectRoot: root,
@@ -209,10 +259,12 @@ export function loadConfig(projectRoot?: string): OrbitalConfig {
     clientPort,
     terminal,
     claude,
+    dispatch,
     commands,
     logLevel,
     categories,
     agents,
+    telemetry,
   };
 }
 

package/server/database.ts

@@ -2,39 +2,33 @@ 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;
+// ─── Factory (multi-project) ────────────────────────────────
 
-  const { dir, file } = getDbPaths();
-  fs.mkdirSync(dir, { recursive: true });
+/**
+ * Open a project-scoped SQLite database at the given directory.
+ * Creates the directory if needed, applies schema DDL and migrations.
+ *
+ * Each call returns a NEW connection — callers manage their own lifecycle.
+ */
+export function openProjectDatabase(dbDir: string): Database.Database {
+  fs.mkdirSync(dbDir, { recursive: true });
+  const file = path.join(dbDir, 'orbital.db');
 
-  db = new Database(file);
+  const database = 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');
+  database.pragma('journal_mode = WAL');
+  database.pragma('synchronous = NORMAL');
+  database.pragma('foreign_keys = ON');
 
-  // Run schema migrations (SQLite db.exec, not child_process)
-  db.exec(SCHEMA_DDL);
+  database.exec(SCHEMA_DDL);
+  runMigrations(database);
 
-  // Incremental migrations for existing databases
-  runMigrations(db);
-
-  return db;
+  return database;
 }
 
 /** Check if a table exists in the database */
@@ -59,6 +53,11 @@ function runMigrations(database: Database.Database): void {
     database.exec('ALTER TABLE sessions ADD COLUMN action TEXT');
   }
 
+  // Migration 9: Add telemetry_sent_at column to sessions
+  if (!sessionCols.some((c) => c.name === 'telemetry_sent_at')) {
+    database.exec('ALTER TABLE sessions ADD COLUMN telemetry_sent_at 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')) {
@@ -97,11 +96,3 @@ function runMigrations(database: Database.Database): void {
     `);
   }
 }
-
-export function closeDatabase(): void {
-  if (db) {
-    db.close();
-    db = null;
-    log.debug('Database closed');
-  }
-}