orbital-command 0.2.0 → 1.0.0

package/dist/server/server/parsers/scope-parser.test.js

@@ -0,0 +1,230 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { normalizeStatus, inferStatusFromDir, setValidStatuses, parseScopeFile, parseAllScopes } from './scope-parser.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+// ─── Pure function tests (no I/O) ──────────────────────────
+describe('normalizeStatus()', () => {
+    it('maps "in-progress" to "implementing"', () => {
+        expect(normalizeStatus('in-progress')).toBe('implementing');
+    });
+    it('maps "in_progress" to "implementing"', () => {
+        expect(normalizeStatus('in_progress')).toBe('implementing');
+    });
+    it('maps "complete" to "completed"', () => {
+        expect(normalizeStatus('complete')).toBe('completed');
+    });
+    it('maps "done" to "production"', () => {
+        expect(normalizeStatus('done')).toBe('production');
+    });
+    it('maps "exploring" to "planning"', () => {
+        expect(normalizeStatus('exploring')).toBe('planning');
+    });
+    it('maps "blocked" to "backlog"', () => {
+        expect(normalizeStatus('blocked')).toBe('backlog');
+    });
+    it('maps "testing" to "review"', () => {
+        expect(normalizeStatus('testing')).toBe('review');
+    });
+    it('returns identity for already-valid statuses', () => {
+        expect(normalizeStatus('implementing')).toBe('implementing');
+        expect(normalizeStatus('icebox')).toBe('icebox');
+        expect(normalizeStatus('staging')).toBe('staging');
+    });
+    it('returns raw value for unknown statuses', () => {
+        expect(normalizeStatus('custom-status')).toBe('custom-status');
+    });
+});
+describe('setValidStatuses() + inferStatusFromDir()', () => {
+    beforeEach(() => {
+        setValidStatuses(['icebox', 'planning', 'backlog', 'implementing', 'review', 'completed', 'main']);
+    });
+    it('returns dir name when it is a valid status', () => {
+        expect(inferStatusFromDir('implementing')).toBe('implementing');
+        expect(inferStatusFromDir('backlog')).toBe('backlog');
+    });
+    it('returns "planning" for unknown dir name', () => {
+        expect(inferStatusFromDir('unknown-dir')).toBe('planning');
+    });
+    it('returns dir name as-is when validDirStatuses not yet set', () => {
+        // Reset by setting to a set that doesn't include our test value
+        setValidStatuses([]);
+        expect(inferStatusFromDir('anything')).toBe('planning');
+    });
+});
+// ─── File-based tests ───────────────────────────────────────
+describe('parseScopeFile()', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scope-test-'));
+        setValidStatuses(['icebox', 'planning', 'backlog', 'implementing', 'review', 'completed', 'main']);
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    function writeScopeFile(subDir, filename, content) {
+        const dir = path.join(tmpDir, subDir);
+        fs.mkdirSync(dir, { recursive: true });
+        const filePath = path.join(dir, filename);
+        fs.writeFileSync(filePath, content);
+        return filePath;
+    }
+    it('parses YAML frontmatter scope', () => {
+        const file = writeScopeFile('backlog', '001-test-scope.md', `---
+title: Test Scope
+status: backlog
+priority: high
+tags: [feature, backend]
+blocked_by: [2, 3]
+---
+# Test Scope
+
+Some content here.
+`);
+        const result = parseScopeFile(file);
+        expect(result).not.toBeNull();
+        expect(result.id).toBe(1);
+        expect(result.title).toBe('Test Scope');
+        expect(result.status).toBe('backlog');
+        expect(result.priority).toBe('high');
+        expect(result.tags).toEqual(['feature', 'backend']);
+        expect(result.blocked_by).toEqual([2, 3]);
+        expect(result.raw_content).toContain('Some content here.');
+    });
+    it('extracts ID with suffix encoding: a→1000+base', () => {
+        const file = writeScopeFile('implementing', '047a-variant.md', `---
+title: Variant A
+status: implementing
+---
+Content
+`);
+        const result = parseScopeFile(file);
+        expect(result.id).toBe(1047); // 1000 + 47
+    });
+    it('extracts ID with suffix encoding: X→9000+base', () => {
+        const file = writeScopeFile('review', '075X-experimental.md', `---
+title: Experimental
+status: review
+---
+Content
+`);
+        const result = parseScopeFile(file);
+        expect(result.id).toBe(9075); // 9000 + 75
+    });
+    it('generates negative hash ID for slug-only icebox files', () => {
+        const file = writeScopeFile('icebox', 'onboarding-flow.md', `---
+title: Onboarding Flow
+status: icebox
+---
+An idea for onboarding.
+`);
+        const result = parseScopeFile(file);
+        expect(result).not.toBeNull();
+        expect(result.id).toBeLessThan(0);
+        expect(result.slug).toBe('onboarding-flow');
+    });
+    it('parses markdown-only scope (no YAML)', () => {
+        const file = writeScopeFile('planning', '010-markdown-only.md', `# Scope 010: Markdown Feature
+## Priority: high
+## Estimated Effort: 3 days
+## Category: Backend
+
+Implementation details...
+`);
+        const result = parseScopeFile(file);
+        expect(result).not.toBeNull();
+        expect(result.id).toBe(10);
+        expect(result.title).toBe('Markdown Feature');
+        expect(result.priority).toBe('high');
+        expect(result.effort_estimate).toBe('3 days');
+        expect(result.category).toBe('Backend');
+    });
+    it('rejects invalid priority', () => {
+        const file = writeScopeFile('backlog', '002-test.md', `---
+title: Bad Priority
+status: backlog
+priority: urgent
+---
+Content
+`);
+        const result = parseScopeFile(file);
+        expect(result.priority).toBeNull();
+    });
+    it('validates session keys', () => {
+        const file = writeScopeFile('implementing', '003-sessions.md', `---
+title: With Sessions
+status: implementing
+sessions:
+  implementScope: ["session-1"]
+  invalidKey: ["session-2"]
+---
+Content
+`);
+        const result = parseScopeFile(file);
+        expect(result.sessions).toHaveProperty('implementScope');
+        expect(result.sessions).not.toHaveProperty('invalidKey');
+    });
+    it('handles ghost scopes', () => {
+        const file = writeScopeFile('icebox', '004-ghost.md', `---
+title: Ghost Idea
+status: icebox
+ghost: true
+---
+AI-generated idea
+`);
+        const result = parseScopeFile(file);
+        expect(result.is_ghost).toBe(true);
+    });
+    it('returns null for template/non-scope files', () => {
+        const file = writeScopeFile('backlog', '_template.md', `---
+title: Template
+---
+Template content
+`);
+        expect(parseScopeFile(file)).toBeNull();
+    });
+});
+describe('parseAllScopes()', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'scopes-test-'));
+        setValidStatuses(['icebox', 'planning', 'backlog', 'implementing']);
+    });
+    afterEach(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('recursively scans and parses all .md files', () => {
+        const backlogDir = path.join(tmpDir, 'backlog');
+        const planningDir = path.join(tmpDir, 'planning');
+        fs.mkdirSync(backlogDir, { recursive: true });
+        fs.mkdirSync(planningDir, { recursive: true });
+        fs.writeFileSync(path.join(backlogDir, '001-first.md'), '---\ntitle: First\nstatus: backlog\n---\nContent\n');
+        fs.writeFileSync(path.join(planningDir, '002-second.md'), '---\ntitle: Second\nstatus: planning\n---\nContent\n');
+        const scopes = parseAllScopes(tmpDir);
+        expect(scopes).toHaveLength(2);
+        expect(scopes[0].id).toBe(1);
+        expect(scopes[1].id).toBe(2);
+    });
+    it('deduplicates by ID (first-seen wins)', () => {
+        const dir1 = path.join(tmpDir, 'backlog');
+        const dir2 = path.join(tmpDir, 'planning');
+        fs.mkdirSync(dir1, { recursive: true });
+        fs.mkdirSync(dir2, { recursive: true });
+        fs.writeFileSync(path.join(dir1, '001-original.md'), '---\ntitle: Original\nstatus: backlog\n---\n');
+        fs.writeFileSync(path.join(dir2, '001-duplicate.md'), '---\ntitle: Duplicate\nstatus: planning\n---\n');
+        const scopes = parseAllScopes(tmpDir);
+        expect(scopes).toHaveLength(1);
+    });
+    it('returns empty array for non-existent directory', () => {
+        expect(parseAllScopes('/tmp/nonexistent-scopes-dir')).toEqual([]);
+    });
+    it('returns sorted by ID', () => {
+        const dir = path.join(tmpDir, 'backlog');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, '003-third.md'), '---\ntitle: Third\nstatus: backlog\n---\n');
+        fs.writeFileSync(path.join(dir, '001-first.md'), '---\ntitle: First\nstatus: backlog\n---\n');
+        fs.writeFileSync(path.join(dir, '002-second.md'), '---\ntitle: Second\nstatus: backlog\n---\n');
+        const scopes = parseAllScopes(tmpDir);
+        expect(scopes.map(s => s.id)).toEqual([1, 2, 3]);
+    });
+});

package/dist/server/server/project-context.js

@@ -0,0 +1,265 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+import { openProjectDatabase } from './database.js';
+import { loadConfig } from './config.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 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 { ensureDynamicProfiles } from './utils/terminal-launcher.js';
+import { createLogger } from './utils/logger.js';
+const log = createLogger('project-context');
+// ─── Factory ────────────────────────────────────────────────
+/** Resolve the path to the bundled default workflow JSON. */
+function getDefaultConfigPath() {
+    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, projectRoot, emitter) {
+    // Load project config
+    const config = loadConfig(projectRoot);
+    // Initialize database
+    const db = openProjectDatabase(config.dbDir);
+    // Initialize workflow engine
+    const workflowEngine = new WorkflowEngine(defaultWorkflow);
+    // 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, config);
+    const batchOrchestrator = new BatchOrchestrator(db, emitter, sprintService, scopeService, workflowEngine, config.projectRoot, config);
+    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);
+    let telemetryService = null;
+    let telemetryRouter = null;
+    const telemetryMod = './services/telemetry-service.js';
+    try {
+        const mod = await import(telemetryMod);
+        telemetryService = new mod.TelemetryService(db, config.telemetry, config.projectName, config.projectRoot);
+        if (telemetryService?.enabled) {
+            telemetryRouter = mod.createTelemetryRoutes({ telemetryService });
+        }
+    }
+    catch { /* telemetry service not installed */ }
+    // 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 = [];
+            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);
+            return;
+        }
+        scopeService.updateStatus(id, result, 'event');
+    });
+    // Wire status change callbacks
+    scopeService.onStatusChange((scopeId, newStatus) => {
+        if (workflowEngine.isTerminalStatus(newStatus))
+            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, config.dispatch.staleTimeoutMinutes);
+    // 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 = [];
+    // 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, config.dispatch.staleTimeoutMinutes);
+    }, 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 = {
+        id: projectId,
+        config,
+        db,
+        workflowEngine,
+        emitter,
+        scopeCache,
+        scopeService,
+        eventService,
+        gateService,
+        deployService,
+        sprintService,
+        sprintOrchestrator,
+        batchOrchestrator,
+        readinessService,
+        workflowService,
+        gitService,
+        githubService,
+        telemetryService,
+        telemetryRouter,
+        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/dist/server/server/project-emitter.js

@@ -0,0 +1,41 @@
+/**
+ * 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 {
+    io;
+    projectId;
+    constructor(io, projectId) {
+        this.io = io;
+        this.projectId = projectId;
+    }
+    /** Emit an event to this project's room and the all-projects room. */
+    emit(event, ...args) {
+        // 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, 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() {
+        return this.io;
+    }
+    /** Get the project ID this emitter is scoped to. */
+    getProjectId() {
+        return this.projectId;
+    }
+}