orbital-command 0.1.4 → 0.3.0

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,163 @@
+/**
+ * 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,
+    validateTemplates: null,
+    validateDocs: null,
+    checkRules: 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

@@ -29,6 +29,12 @@ export interface CommandsConfig {
 export type { AgentConfig } from '../shared/api-types.js';
 import type { AgentConfig } from '../shared/api-types.js';
 
+export interface TelemetryConfig {
+  enabled: boolean;
+  url: string;
+  headers: Record<string, string>;
+}
+
 export interface OrbitalConfig {
   projectName: string;
   projectRoot: string;
@@ -58,6 +64,9 @@ export interface OrbitalConfig {
   // Dynamic configuration
   categories: string[];
   agents: AgentConfig[];
+
+  // Telemetry
+  telemetry: TelemetryConfig;
 }
 
 // ─── Defaults ───────────────────────────────────────────────
@@ -88,6 +97,11 @@ const DEFAULT_CONFIG: Omit<OrbitalConfig, 'projectRoot'> = {
     checkRules: null,
   },
   logLevel: 'info' as const,
+  telemetry: {
+    enabled: true,
+    url: '',
+    headers: {},
+  },
   categories: ['feature', 'bugfix', 'refactor', 'infrastructure', 'docs'],
   agents: [
     { id: 'attacker', label: 'Attacker', emoji: '\u{1F5E1}\u{FE0F}', color: '#ff1744' },
@@ -168,8 +182,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);
@@ -198,6 +215,12 @@ 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,
+    ...(userConfig.telemetry as Partial<TelemetryConfig> ?? {}),
+  };
+  if (process.env.ORBITAL_TELEMETRY === 'false') telemetry.enabled = false;
+
   return {
     projectName,
     projectRoot: root,
@@ -213,6 +236,7 @@ export function loadConfig(projectRoot?: string): OrbitalConfig {
     logLevel,
     categories,
     agents,
+    telemetry,
   };
 }
 

package/server/database.ts

@@ -7,6 +7,34 @@ import { createLogger } from './utils/logger.js';
 
 const log = createLogger('database');
 
+// ─── Factory (multi-project) ────────────────────────────────
+
+/**
+ * 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.
+ * This is the multi-project replacement for the getDatabase() singleton.
+ */
+export function openProjectDatabase(dbDir: string): Database.Database {
+  fs.mkdirSync(dbDir, { recursive: true });
+  const file = path.join(dbDir, 'orbital.db');
+
+  const database = new Database(file);
+  log.info('Database initialized', { path: file });
+
+  database.pragma('journal_mode = WAL');
+  database.pragma('synchronous = NORMAL');
+  database.pragma('foreign_keys = ON');
+
+  database.exec(SCHEMA_DDL);
+  runMigrations(database);
+
+  return database;
+}
+
+// ─── Singleton (backward compat, used by index.ts) ──────────
+
 function getDbPaths(): { dir: string; file: string } {
   const config = getConfig();
   return { dir: config.dbDir, file: path.join(config.dbDir, 'orbital.db') };
@@ -14,26 +42,10 @@ function getDbPaths(): { dir: string; file: string } {
 
 let db: Database.Database | null = null;
 
+/** @deprecated Use openProjectDatabase() for multi-project support. */
 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);
-
+  db = openProjectDatabase(getDbPaths().dir);
   return db;
 }
 
@@ -59,6 +71,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')) {

package/server/global-config.ts

@@ -0,0 +1,200 @@
+import crypto from 'crypto';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import { createLogger } from './utils/logger.js';
+
+const log = createLogger('global-config');
+
+// ─── Types ──────────────────────────────────────────────────
+
+export interface ProjectRegistration {
+  /** Slug ID derived from directory name, e.g. "orbital-command" */
+  id: string;
+  /** Absolute path to project root */
+  path: string;
+  /** Human-readable display name */
+  name: string;
+  /** HSL color string for project badge, e.g. "210 80% 55%" */
+  color: string;
+  /** ISO 8601 timestamp of registration */
+  registeredAt: string;
+  /** Can be disabled without removal */
+  enabled: boolean;
+}
+
+export interface OrbitalGlobalConfig {
+  version: 1;
+  projects: ProjectRegistration[];
+  privateMode?: boolean;
+}
+
+// ─── Constants ──────────────────────────────────────────────
+
+/** Global Orbital Command directory */
+export const ORBITAL_HOME = path.join(os.homedir(), '.orbital');
+
+/** Path to the global registry file */
+export const REGISTRY_PATH = path.join(ORBITAL_HOME, 'config.json');
+
+/** Path to global primitives directory */
+export const GLOBAL_PRIMITIVES_DIR = path.join(ORBITAL_HOME, 'primitives');
+
+/** Path to global workflow config */
+export const GLOBAL_WORKFLOW_PATH = path.join(ORBITAL_HOME, 'workflow.json');
+
+/** Import from shared — re-exported for convenience */
+import { PROJECT_COLORS } from '../shared/project-colors.js';
+export { PROJECT_COLORS };
+
+// ─── Slug Generation ────────────────────────────────────────
+
+/**
+ * Generate a project slug from a filesystem path.
+ * Uses the directory basename, lowercased, with non-alphanumeric chars
+ * replaced by hyphens. Deduplicates against existing IDs with a 4-char hash.
+ */
+export function generateProjectId(projectRoot: string, existingIds: string[]): string {
+  const base = path.basename(projectRoot)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  const slug = base || 'project';
+  if (!existingIds.includes(slug)) return slug;
+
+  // Collision — append 4-char hash of the full path
+  const hash = crypto.createHash('sha256').update(projectRoot).digest('hex').slice(0, 4);
+  return `${slug}-${hash}`;
+}
+
+// ─── Registry I/O ───────────────────────────────────────────
+
+/** Ensure ~/.orbital/ directory structure exists, including primitives subdirectories. */
+export function ensureOrbitalHome(): void {
+  if (!fs.existsSync(ORBITAL_HOME)) {
+    fs.mkdirSync(ORBITAL_HOME, { recursive: true });
+    log.info('Created ~/.orbital/', { path: ORBITAL_HOME });
+  }
+  // Ensure primitives subdirectories exist so the global watcher can start
+  for (const sub of ['agents', 'skills', 'hooks', 'config']) {
+    const dir = path.join(GLOBAL_PRIMITIVES_DIR, sub);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/** Load the global registry. Creates default if missing. */
+export function loadGlobalConfig(): OrbitalGlobalConfig {
+  ensureOrbitalHome();
+
+  if (!fs.existsSync(REGISTRY_PATH)) {
+    const config: OrbitalGlobalConfig = { version: 1, projects: [] };
+    saveGlobalConfig(config);
+    return config;
+  }
+
+  try {
+    const raw = fs.readFileSync(REGISTRY_PATH, 'utf-8');
+    return JSON.parse(raw) as OrbitalGlobalConfig;
+  } catch (err) {
+    log.error('Failed to read global config, creating fresh', { error: String(err) });
+    const config: OrbitalGlobalConfig = { version: 1, projects: [] };
+    saveGlobalConfig(config);
+    return config;
+  }
+}
+
+/** Save the global registry atomically. */
+export function saveGlobalConfig(config: OrbitalGlobalConfig): void {
+  ensureOrbitalHome();
+  const tmpPath = REGISTRY_PATH + '.tmp';
+  fs.writeFileSync(tmpPath, JSON.stringify(config, null, 2), 'utf-8');
+  fs.renameSync(tmpPath, REGISTRY_PATH);
+}
+
+// ─── Project Registration ───────────────────────────────────
+
+/** Pick the next unused color from the palette. */
+function nextColor(usedColors: string[]): string {
+  const available = PROJECT_COLORS.filter(c => !usedColors.includes(c));
+  return available[0] ?? PROJECT_COLORS[0];
+}
+
+/** Register a project in the global config. Returns the registration. */
+export function registerProject(
+  projectRoot: string,
+  options?: { name?: string; color?: string },
+): ProjectRegistration {
+  const absPath = path.resolve(projectRoot);
+  const config = loadGlobalConfig();
+
+  // Check if already registered
+  const existing = config.projects.find(p => p.path === absPath);
+  if (existing) {
+    log.info('Project already registered', { id: existing.id, path: absPath });
+    return existing;
+  }
+
+  const existingIds = config.projects.map(p => p.id);
+  const usedColors = config.projects.map(p => p.color);
+
+  const registration: ProjectRegistration = {
+    id: generateProjectId(absPath, existingIds),
+    path: absPath,
+    name: options?.name ?? path.basename(absPath),
+    color: options?.color ?? nextColor(usedColors),
+    registeredAt: new Date().toISOString(),
+    enabled: true,
+  };
+
+  config.projects.push(registration);
+  saveGlobalConfig(config);
+  log.info('Project registered', { id: registration.id, path: absPath });
+
+  return registration;
+}
+
+/** Unregister a project by ID or path. Returns true if found. */
+export function unregisterProject(idOrPath: string): boolean {
+  const config = loadGlobalConfig();
+  const absPath = path.isAbsolute(idOrPath) ? idOrPath : path.resolve(idOrPath);
+
+  const idx = config.projects.findIndex(
+    p => p.id === idOrPath || p.path === absPath,
+  );
+  if (idx === -1) return false;
+
+  const removed = config.projects.splice(idx, 1)[0];
+  saveGlobalConfig(config);
+  log.info('Project unregistered', { id: removed.id, path: removed.path });
+
+  return true;
+}
+
+/** Update a project's registration (color, name, enabled). */
+export function updateProject(
+  id: string,
+  updates: Partial<Pick<ProjectRegistration, 'name' | 'color' | 'enabled'>>,
+): ProjectRegistration | null {
+  const config = loadGlobalConfig();
+  const project = config.projects.find(p => p.id === id);
+  if (!project) return null;
+
+  if (updates.name !== undefined) project.name = updates.name;
+  if (updates.color !== undefined) project.color = updates.color;
+  if (updates.enabled !== undefined) project.enabled = updates.enabled;
+
+  saveGlobalConfig(config);
+  return project;
+}
+
+/** Get all registered projects. */
+export function getRegisteredProjects(): ProjectRegistration[] {
+  return loadGlobalConfig().projects;
+}
+
+/** Find a registered project by ID. */
+export function findProject(id: string): ProjectRegistration | undefined {
+  return loadGlobalConfig().projects.find(p => p.id === id);
+}