orbital-command 0.1.4 → 0.3.0

package/server/parsers/scope-parser.ts

@@ -8,6 +8,7 @@ const log = createLogger('scope');
 export interface ParsedScope {
   id: number;
   title: string;
+  slug?: string;
   status: string;
   priority: string | null;
   effort_estimate: string | null;
@@ -21,6 +22,7 @@ export interface ParsedScope {
   raw_content: string;
   sessions: Record<string, string[]>;
   is_ghost: boolean;
+  favourite: boolean;
 }
 
 const VALID_PRIORITIES = new Set(['critical', 'high', 'medium', 'low']);
@@ -69,35 +71,73 @@ export function normalizeStatus(raw: string): string {
   return STATUS_MAP[raw] ?? raw;
 }
 
+/** Generate a stable positive integer hash from a string (for synthetic icebox IDs) */
+function slugHash(s: string): number {
+  let hash = 5381;
+  for (let i = 0; i < s.length; i++) {
+    hash = ((hash << 5) + hash + s.charCodeAt(i)) >>> 0;
+  }
+  // Keep in range 10000-2147483647 to avoid collisions with real scope IDs and suffix-encoded IDs
+  return 10000 + (hash % 2137483647);
+}
+
 /**
  * Parse a scope markdown file into structured data.
  * Handles both YAML frontmatter and plain markdown formats.
  */
 export function parseScopeFile(filePath: string): ParsedScope | null {
-  const content = fs.readFileSync(filePath, 'utf-8');
-  const fileName = path.basename(filePath, '.md');
-  const dirName = path.basename(path.dirname(filePath));
-
-  // Extract ID from filename pattern: NNN[suffix]-description.md
-  // Suffixes (a-d, X) encode as thousands offset for unique DB keys
-  const idMatch = fileName.match(/^(\d+)([a-dA-DxX])?/);
-  const fileId = idMatch ? scopeFileId(parseInt(idMatch[1], 10), idMatch[2]) : 0;
-
-  // Skip non-scope files
-  if (fileId === 0 && !fileName.startsWith('0')) {
-    // Files like _template.md, technical-debt.md, backlog_plan.md
-    if (fileName.startsWith('_') || !idMatch) return null;
-  }
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const fileName = path.basename(filePath, '.md');
+    const dirName = path.basename(path.dirname(filePath));
 
-  // Try YAML frontmatter first
-  const { data: frontmatter, content: markdownBody } = matter(content);
+    // Extract ID from filename pattern: NNN[suffix]-description.md
+    // Suffixes (a-d, X) encode as thousands offset for unique DB keys
+    const idMatch = fileName.match(/^(\d+)([a-dA-DxX])?/);
+    const fileId = idMatch ? scopeFileId(parseInt(idMatch[1], 10), idMatch[2]) : 0;
 
-  if (frontmatter && Object.keys(frontmatter).length > 0) {
-    return parseFrontmatterScope(frontmatter, markdownBody, filePath, fileId, dirName);
-  }
+    // Slug-only icebox files: no numeric prefix, e.g. "onboarding-flow.md"
+    const isSlugOnly = !idMatch && dirName === 'icebox';
+
+    // Skip non-scope files (but allow slug-only icebox files)
+    if (fileId === 0 && !fileName.startsWith('0') && !isSlugOnly) {
+      // Files like _template.md, technical-debt.md, backlog_plan.md
+      if (fileName.startsWith('_') || !idMatch) return null;
+    }
+
+    // For slug-only icebox files, generate a stable negative ID for internal cache indexing.
+    // This avoids collisions with real scope IDs (positive) and between icebox items.
+    const effectiveId = isSlugOnly ? -slugHash(fileName) : fileId;
 
-  // Fallback: extract from markdown structure
-  return parseMarkdownScope(content, filePath, fileId, dirName);
+    // Try YAML frontmatter first
+    let frontmatter: Record<string, unknown>;
+    let markdownBody: string;
+    try {
+      ({ data: frontmatter, content: markdownBody } = matter(content));
+    } catch (err) {
+      log.warn('Skipping scope with malformed YAML frontmatter', { file: filePath, error: (err as Error).message });
+      return null;
+    }
+
+    if (frontmatter && Object.keys(frontmatter).length > 0) {
+      const scope = parseFrontmatterScope(frontmatter, markdownBody, filePath, effectiveId, dirName);
+      // Populate slug for icebox items
+      if (isSlugOnly || dirName === 'icebox') {
+        scope.slug = isSlugOnly ? fileName : fileName.replace(/^\d+[a-dA-DxX]?-/, '');
+      }
+      return scope;
+    }
+
+    // Fallback: extract from markdown structure
+    const fallbackScope = parseMarkdownScope(content, filePath, effectiveId, dirName);
+    if (isSlugOnly || dirName === 'icebox') {
+      fallbackScope.slug = isSlugOnly ? fileName : fileName.replace(/^\d+[a-dA-DxX]?-/, '');
+    }
+    return fallbackScope;
+  } catch (err) {
+    log.warn('Failed to parse scope file', { file: filePath, error: (err as Error).message });
+    return null;
+  }
 }
 
 function parseFrontmatterScope(
@@ -128,6 +168,7 @@ function parseFrontmatterScope(
     raw_content: body.trim(),
     sessions: parseSessions(fm.sessions),
     is_ghost: fm.ghost === true,
+    favourite: fm.favourite === true,
   };
 }
 
@@ -173,6 +214,7 @@ function parseMarkdownScope(
     raw_content: content,
     sessions: {},
     is_ghost: false,
+    favourite: false,
   };
 }
 
@@ -194,7 +236,7 @@ export function setValidStatuses(statuses: Iterable<string>): void {
   validDirStatuses = new Set(statuses);
 }
 
-function inferStatusFromDir(dirName: string): string {
+export function inferStatusFromDir(dirName: string): string {
   if (validDirStatuses) {
     return validDirStatuses.has(dirName) ? dirName : 'planning';
   }
@@ -215,26 +257,32 @@ export function parseAllScopes(scopesDir: string): ParsedScope[] {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        scanDir(fullPath);
-      } else if (entry.name.endsWith('.md') && !entry.name.startsWith('_')) {
-        const parsed = parseScopeFile(fullPath);
-        if (parsed) scopes.push(parsed);
+      try {
+        if (entry.isDirectory()) {
+          scanDir(fullPath);
+        } else if (entry.name.endsWith('.md') && !entry.name.startsWith('_')) {
+          const parsed = parseScopeFile(fullPath);
+          if (parsed) scopes.push(parsed);
+        }
+      } catch (err) {
+        log.warn('Failed to process scope entry', { file: fullPath, error: (err as Error).message });
       }
     }
   }
 
   scanDir(scopesDir);
 
-  // Detect ID collisions — last-write-wins but warn on stderr
+  // Detect ID collisions — first-seen wins, duplicates are dropped
   const seen = new Map<number, string>();
-  for (const scope of scopes) {
+  const deduped = scopes.filter(scope => {
     const existing = seen.get(scope.id);
     if (existing) {
       log.error('Scope ID collision — renumber one of them', { id: scope.id, existing, duplicate: scope.file_path });
+      return false;
     }
     seen.set(scope.id, scope.file_path);
-  }
+    return true;
+  });
 
-  return scopes.sort((a, b) => a.id - b.id);
+  return deduped.sort((a, b) => a.id - b.id);
 }

package/server/project-context.ts

@@ -0,0 +1,309 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import type Database from 'better-sqlite3';
+import type { FSWatcher } from 'chokidar';
+import { openProjectDatabase } from './database.js';
+import { loadConfig } from './config.js';
+import type { OrbitalConfig } from './config.js';
+import { ProjectEmitter } from './project-emitter.js';
+import { ScopeCache } from './services/scope-cache.js';
+import { ScopeService } from './services/scope-service.js';
+import { EventService } from './services/event-service.js';
+import { GateService } from './services/gate-service.js';
+import { DeployService } from './services/deploy-service.js';
+import { SprintService } from './services/sprint-service.js';
+import { SprintOrchestrator } from './services/sprint-orchestrator.js';
+import { BatchOrchestrator } from './services/batch-orchestrator.js';
+import { ReadinessService } from './services/readiness-service.js';
+import { WorkflowService } from './services/workflow-service.js';
+import { GitService } from './services/git-service.js';
+import { GitHubService } from './services/github-service.js';
+import { WorkflowEngine } from '../shared/workflow-engine.js';
+import type { WorkflowConfig } from '../shared/workflow-config.js';
+import defaultWorkflow from '../shared/default-workflow.json' with { type: 'json' };
+import { startScopeWatcher } from './watchers/scope-watcher.js';
+import { startEventWatcher } from './watchers/event-watcher.js';
+import { resolveStaleDispatches, resolveActiveDispatchesForScope, resolveDispatchesByPid, resolveDispatchesByDispatchId, linkPidToDispatch, tryAutoRevertAndClear } from './utils/dispatch-utils.js';
+import { syncClaudeSessionsToDB } from './services/claude-session-service.js';
+import { TelemetryService } from './services/telemetry-service.js';
+import { ensureDynamicProfiles } from './utils/terminal-launcher.js';
+import { createLogger } from './utils/logger.js';
+
+const log = createLogger('project-context');
+
+// ─── Types ──────────────────────────────────────────────────
+
+export type ProjectStatus = 'active' | 'error' | 'offline';
+
+export interface ProjectContext {
+  /** Project slug ID (derived from directory name) */
+  id: string;
+  /** Loaded project config */
+  config: OrbitalConfig;
+  /** Per-project SQLite database */
+  db: Database.Database;
+  /** Per-project workflow engine */
+  workflowEngine: WorkflowEngine;
+  /** Project-scoped socket emitter */
+  emitter: ProjectEmitter;
+
+  // Services
+  scopeCache: ScopeCache;
+  scopeService: ScopeService;
+  eventService: EventService;
+  gateService: GateService;
+  deployService: DeployService;
+  sprintService: SprintService;
+  sprintOrchestrator: SprintOrchestrator;
+  batchOrchestrator: BatchOrchestrator;
+  readinessService: ReadinessService;
+  workflowService: WorkflowService;
+  gitService: GitService;
+  githubService: GitHubService;
+  telemetryService: TelemetryService;
+
+  // Watchers
+  scopeWatcher: FSWatcher;
+  eventWatcher: FSWatcher;
+
+  // Intervals (cleanup, sync, polling)
+  intervals: ReturnType<typeof setInterval>[];
+
+  // Status
+  status: ProjectStatus;
+  error?: string;
+
+  // Lifecycle
+  shutdown(): Promise<void>;
+}
+
+// ─── Factory ────────────────────────────────────────────────
+
+/** Resolve the path to the bundled default workflow JSON. */
+function getDefaultConfigPath(): string {
+  const __selfDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(__selfDir, '../shared/default-workflow.json');
+}
+
+/**
+ * Create a fully wired ProjectContext for a single project.
+ *
+ * Create a fully wired context for a single project. Each ProjectContext has its own
+ * database, services, watchers, and intervals.
+ */
+export async function createProjectContext(
+  projectId: string,
+  projectRoot: string,
+  emitter: ProjectEmitter,
+): Promise<ProjectContext> {
+  // Load project config
+  const config = loadConfig(projectRoot);
+
+  // Initialize database
+  const db = openProjectDatabase(config.dbDir);
+
+  // Initialize workflow engine
+  const workflowEngine = new WorkflowEngine(defaultWorkflow as WorkflowConfig);
+
+  // Generate shell manifest for bash hooks
+  if (!fs.existsSync(config.configDir)) fs.mkdirSync(config.configDir, { recursive: true });
+  const manifestPath = path.join(config.configDir, 'workflow-manifest.sh');
+  fs.writeFileSync(manifestPath, workflowEngine.generateShellManifest(), 'utf-8');
+
+  // Ensure icebox directory exists
+  const iceboxDir = path.join(config.scopesDir, 'icebox');
+  if (!fs.existsSync(iceboxDir)) fs.mkdirSync(iceboxDir, { recursive: true });
+
+  // Initialize services
+  const scopeCache = new ScopeCache();
+  const scopeService = new ScopeService(scopeCache, emitter, config.scopesDir, workflowEngine);
+  const eventService = new EventService(db, emitter);
+  const gateService = new GateService(db, emitter);
+  const deployService = new DeployService(db, emitter);
+  const sprintService = new SprintService(db, emitter, scopeService);
+  const sprintOrchestrator = new SprintOrchestrator(db, emitter, sprintService, scopeService, workflowEngine, config.projectRoot);
+  const batchOrchestrator = new BatchOrchestrator(db, emitter, sprintService, scopeService, workflowEngine, config.projectRoot);
+  const readinessService = new ReadinessService(scopeService, gateService, workflowEngine, config.projectRoot);
+  const workflowService = new WorkflowService(config.configDir, workflowEngine, config.scopesDir, getDefaultConfigPath());
+  workflowService.setSocketServer(emitter);
+
+  // Ensure engine reflects active config (may differ from bundled default)
+  workflowEngine.reload(workflowService.getActive());
+  const gitService = new GitService(config.projectRoot, scopeCache);
+  const githubService = new GitHubService(config.projectRoot);
+  const telemetryService = new TelemetryService(db, config.telemetry, config.projectName, config.projectRoot);
+
+  // Wire active-group guard
+  scopeService.setActiveGroupCheck((scopeId) => sprintService.getActiveGroupForScope(scopeId));
+
+  // Wire event inference (Fix 8: diagnostic log lines match index.ts)
+  eventService.onIngest((eventType, scopeId, data) => {
+    if (eventType === 'SESSION_START' && typeof data.dispatch_id === 'string' && typeof data.pid === 'number') {
+      linkPidToDispatch(db, data.dispatch_id, data.pid);
+      log.debug('Linked PID to dispatch', { pid: data.pid, dispatch_id: data.dispatch_id });
+      return;
+    }
+    if (eventType === 'SCOPE_GATE_LIFTED' && scopeId != null) {
+      const id = Number(scopeId);
+      if (!isNaN(id) && id > 0) {
+        resolveActiveDispatchesForScope(db, emitter, id, 'completed');
+        log.debug('Resolved dispatches for scope gate lift', { scope_id: id });
+      }
+      return;
+    }
+    if (eventType === 'SESSION_END') {
+      const outcome = data.normal_exit === true ? 'completed' : 'abandoned';
+      let resolvedIds: string[] = [];
+      if (typeof data.dispatch_id === 'string') {
+        resolvedIds = resolveDispatchesByDispatchId(db, emitter, data.dispatch_id, outcome);
+      }
+      if (resolvedIds.length === 0 && typeof data.pid === 'number') {
+        resolvedIds = resolveDispatchesByPid(db, emitter, data.pid, outcome);
+      }
+      if (resolvedIds.length > 0) log.info('Session resolved', { count: resolvedIds.length, outcome });
+      // For abandoned dispatches, immediately try auto-revert so the scope
+      // returns to its pre-dispatch status without requiring user interaction
+      if (outcome === 'abandoned') {
+        for (const eventId of resolvedIds) {
+          tryAutoRevertAndClear(db, emitter, scopeService, workflowEngine, eventId);
+        }
+      }
+      if (resolvedIds.length > 0) batchOrchestrator.resolveStaleBatches();
+      return;
+    }
+    // Status inference
+    if (scopeId == null) return;
+    const id = Number(scopeId);
+    if (isNaN(id) || id <= 0) return;
+    const current = scopeService.getById(id);
+    if (current?.status === 'icebox') return;
+    const currentStatus = current?.status ?? '';
+    const result = workflowEngine.inferStatus(eventType, currentStatus, data);
+    if (result === null) return;
+    if (typeof result === 'object' && 'dispatchResolution' in result) {
+      resolveActiveDispatchesForScope(db, emitter, id, result.resolution as 'completed' | 'failed');
+      return;
+    }
+    scopeService.updateStatus(id, result, 'event');
+  });
+
+  // Wire status change callbacks
+  scopeService.onStatusChange((scopeId, newStatus) => {
+    if (newStatus === 'dev') sprintOrchestrator.onScopeReachedDev(scopeId);
+    batchOrchestrator.onScopeStatusChanged(scopeId, newStatus);
+  });
+  scopeService.onStatusChange((scopeId, newStatus) => {
+    if (workflowEngine.isTerminalStatus(newStatus)) {
+      resolveActiveDispatchesForScope(db, emitter, scopeId, 'completed');
+    }
+  });
+
+  // Load scopes from filesystem and reconcile directory mismatches
+  const scopeCount = scopeService.syncFromFilesystem();
+  const reconciled = scopeService.reconcileDirectories();
+  if (reconciled > 0) log.info('Reconciled scope directories', { id: projectId, count: reconciled });
+
+  // Start watchers
+  const scopeWatcher = startScopeWatcher(config.scopesDir, scopeService);
+  const eventWatcher = startEventWatcher(config.eventsDir, eventService);
+
+  // Write iTerm2 dispatch profiles (Fix 2 + Fix 5: per-project prefix)
+  ensureDynamicProfiles(workflowEngine, config.terminal.profilePrefix);
+
+  // Recover active sprints/batches
+  await sprintOrchestrator.recoverActiveSprints();
+  await batchOrchestrator.recoverActiveBatches();
+
+  // Resolve stale batches on startup (Fix 6: catches stuck dispatches from previous runs)
+  const staleBatchesResolved = batchOrchestrator.resolveStaleBatches();
+  if (staleBatchesResolved > 0) log.info('Resolved stale batches', { count: staleBatchesResolved });
+
+  // Resolve stale dispatches
+  resolveStaleDispatches(db, emitter, scopeService, workflowEngine);
+
+  // Initial session sync + legacy purge (Fix 7)
+  syncClaudeSessionsToDB(db, scopeService, config.projectRoot).then((count) => {
+    if (count > 0) log.info('Synced sessions', { id: projectId, count });
+    const purged = db.prepare("DELETE FROM sessions WHERE action IS NULL AND id LIKE 'claude-%'").run();
+    if (purged.changes > 0) log.info('Purged legacy session rows', { count: purged.changes });
+    if (telemetryService.enabled) {
+      telemetryService.uploadChangedSessions().catch(() => {});
+    }
+  }).catch(err => log.error('Session sync failed', { error: err.message }));
+
+  // Start periodic intervals
+  const intervals: ReturnType<typeof setInterval>[] = [];
+
+  // Fix 11: periodic batch recovery (two-phase completion B-1)
+  intervals.push(setInterval(() => {
+    batchOrchestrator.recoverActiveBatches().catch(err => log.error('Batch recovery failed', { error: err.message }));
+  }, 30_000));
+
+  intervals.push(setInterval(() => {
+    batchOrchestrator.resolveStaleBatches();
+  }, 30_000));
+
+  intervals.push(setInterval(() => {
+    resolveStaleDispatches(db, emitter, scopeService, workflowEngine);
+  }, 30_000));
+
+  intervals.push(setInterval(async () => {
+    const count = await syncClaudeSessionsToDB(db, scopeService, config.projectRoot);
+    if (count > 0) emitter.emit('session:updated', { type: 'resync', count });
+    if (telemetryService.enabled) {
+      telemetryService.uploadChangedSessions().catch(() => {});
+    }
+  }, 5 * 60_000));
+
+  let lastGitHash = '';
+  intervals.push(setInterval(async () => {
+    try {
+      const hash = await gitService.getStatusHash();
+      if (lastGitHash && hash !== lastGitHash) {
+        gitService.clearCache();
+        emitter.emit('git:status:changed');
+      }
+      lastGitHash = hash;
+    } catch { /* ok */ }
+  }, 10_000));
+
+  log.info('Project ready', { id: projectId, scopes: scopeCount });
+
+  const ctx: ProjectContext = {
+    id: projectId,
+    config,
+    db,
+    workflowEngine,
+    emitter,
+    scopeCache,
+    scopeService,
+    eventService,
+    gateService,
+    deployService,
+    sprintService,
+    sprintOrchestrator,
+    batchOrchestrator,
+    readinessService,
+    workflowService,
+    gitService,
+    githubService,
+    telemetryService,
+    scopeWatcher,
+    eventWatcher,
+    intervals,
+    status: 'active',
+
+    async shutdown() {
+      log.info('Shutting down project context', { id: projectId });
+      for (const interval of intervals) clearInterval(interval);
+      intervals.length = 0;
+      try { await scopeWatcher.close(); } catch (e) { log.error('Scope watcher close failed', { id: projectId, error: String(e) }); }
+      try { await eventWatcher.close(); } catch (e) { log.error('Event watcher close failed', { id: projectId, error: String(e) }); }
+      try { db.close(); } catch (e) { log.error('DB close failed', { id: projectId, error: String(e) }); }
+      ctx.status = 'offline';
+    },
+  };
+
+  return ctx;
+}

package/server/project-emitter.ts

@@ -0,0 +1,50 @@
+import type { Server } from 'socket.io';
+
+/**
+ * A project-scoped Socket.io emitter.
+ *
+ * Services use this instead of the raw Socket.io Server so that events
+ * are automatically scoped to the correct project room. Events are emitted
+ * to both the project-specific room (`project:{id}`) and the aggregate
+ * room (`all-projects`) so that the All Projects dashboard view receives
+ * updates from every project.
+ *
+ * The emit() signature matches Socket.io's Server.emit() so existing
+ * service code requires only a type change (Server → ProjectEmitter).
+ */
+export class ProjectEmitter {
+  constructor(
+    private io: Server,
+    private projectId: string,
+  ) {}
+
+  /** Emit an event to this project's room and the all-projects room. */
+  emit(event: string, ...args: unknown[]): boolean {
+    // Inject project_id into the first data argument if it's an object
+    const enrichedArgs = args.map((arg, i) => {
+      if (i === 0 && arg !== null && typeof arg === 'object' && !Array.isArray(arg)) {
+        return { ...(arg as Record<string, unknown>), project_id: this.projectId };
+      }
+      return arg;
+    });
+
+    this.io.to(`project:${this.projectId}`).emit(event, ...enrichedArgs);
+    this.io.to('all-projects').emit(event, ...enrichedArgs);
+    return true;
+  }
+
+  /** Get the underlying Socket.io server (for operations that need it, e.g., connection handling). */
+  getServer(): Server {
+    return this.io;
+  }
+
+  /** Get the project ID this emitter is scoped to. */
+  getProjectId(): string {
+    return this.projectId;
+  }
+}
+
+/**
+ * Type alias used by services and routes for the project-scoped emitter.
+ */
+export type Emitter = ProjectEmitter;