orbital-command 0.2.0 → 1.0.0

package/dist/server/server/utils/dispatch-utils.js

@@ -1,6 +1,6 @@
 import { isSessionPidAlive } from './terminal-launcher.js';
 import { createLogger } from './logger.js';
-const log = createLogger('dispatch');
+const log = createLogger('dispatch-utils');
 /** Mark a DISPATCH event as resolved and emit socket notification. */
 export function resolveDispatchEvent(db, io, eventId, outcome, error) {
     const row = db.prepare('SELECT data, scope_id FROM events WHERE id = ?')
@@ -24,6 +24,58 @@ export function resolveDispatchEvent(db, io, eventId, outcome, error) {
         outcome,
     });
 }
+/** Auto-revert scope status when a dispatch is abandoned, if the forward edge
+ *  has autoRevert=true and the scope is still at the dispatch target.
+ *  Safe: only reverts if the scope hasn't been moved since the dispatch.
+ *  Returns true if revert was successful. */
+function autoRevertAbandonedScope(scopeService, engine, scopeId, data) {
+    try {
+        const transition = data.transition;
+        if (!transition?.from || !transition?.to)
+            return false;
+        const scope = scopeService.getById(scopeId);
+        // Only revert if scope is still at the dispatch target (hasn't been moved)
+        if (!scope || scope.status !== transition.to)
+            return false;
+        const edge = engine.findEdge(transition.from, transition.to);
+        if (!edge?.autoRevert)
+            return false;
+        const result = scopeService.updateStatus(scopeId, transition.from, 'rollback');
+        if (!result.ok)
+            return false;
+        log.info('Auto-reverted abandoned dispatch', {
+            scopeId, from: transition.to, to: transition.from,
+        });
+        return true;
+    }
+    catch (err) {
+        log.error('Auto-revert failed', { scopeId, error: String(err) });
+        return false;
+    }
+}
+/** Attempt auto-revert for an abandoned dispatch and clear the abandoned state if successful.
+ *  Loads the dispatch event data, tries auto-revert, and re-resolves as 'completed' if the
+ *  scope was successfully reverted. Returns true if auto-revert + clear succeeded. */
+export function tryAutoRevertAndClear(db, io, scopeService, engine, eventId) {
+    const row = db.prepare('SELECT data, scope_id FROM events WHERE id = ?')
+        .get(eventId);
+    if (!row || row.scope_id == null)
+        return false;
+    let data;
+    try {
+        data = JSON.parse(row.data);
+    }
+    catch {
+        return false;
+    }
+    const reverted = autoRevertAbandonedScope(scopeService, engine, row.scope_id, data);
+    if (reverted) {
+        // Clear the abandoned state so getAbandonedScopeIds won't return this scope
+        resolveDispatchEvent(db, io, eventId, 'completed');
+        log.info('Cleared abandoned dispatch after auto-revert', { eventId, scope_id: row.scope_id });
+    }
+    return reverted;
+}
 /** Resolve all unresolved DISPATCH events for a given scope */
 export function resolveActiveDispatchesForScope(db, io, scopeId, outcome) {
     const rows = db.prepare(`SELECT id FROM events
@@ -65,43 +117,41 @@ export function linkPidToDispatch(db, eventId, pid) {
 /** Resolve all unresolved DISPATCH events linked to a specific PID.
  *  Called when a SESSION_END event is received, indicating the Claude session
  *  process has exited and its dispatches should be cleared.
- *
- *  NOTE: Does NOT revert scope status. Skills like /scope-implement intentionally
- *  keep scopes at the transition target (e.g. "implementing") after completion.
- *  Reverting on session end was destroying completed work and deleting scope files. */
-export function resolveDispatchesByPid(db, io, pid) {
+ *  Returns the resolved event IDs so callers can attempt auto-revert. */
+export function resolveDispatchesByPid(db, io, pid, outcome = 'abandoned') {
     const rows = db.prepare(`SELECT id FROM events
      WHERE type = 'DISPATCH'
        AND JSON_EXTRACT(data, '$.resolved') IS NULL
        AND JSON_EXTRACT(data, '$.pid') = ?`).all(pid);
     for (const row of rows) {
-        resolveDispatchEvent(db, io, row.id, 'abandoned');
+        resolveDispatchEvent(db, io, row.id, outcome);
     }
-    return rows.length;
+    return rows.map(r => r.id);
 }
 /** Resolve all unresolved DISPATCH events linked to a specific dispatch ID.
  *  Called when a SESSION_END event includes dispatch_id from ORBITAL_DISPATCH_ID env var.
- *  Defaults to 'abandoned' — successful completions emit AGENT_COMPLETED first
- *  which resolves via inferScopeStatus as 'completed'. */
-export function resolveDispatchesByDispatchId(db, io, dispatchId) {
+ *  Outcome depends on how the session ended: normal_exit → completed, otherwise → abandoned.
+ *  Returns the resolved event IDs so callers can attempt auto-revert. */
+export function resolveDispatchesByDispatchId(db, io, dispatchId, outcome = 'abandoned') {
     const row = db.prepare(`SELECT id FROM events
      WHERE id = ? AND type = 'DISPATCH' AND JSON_EXTRACT(data, '$.resolved') IS NULL`).get(dispatchId);
     if (!row)
-        return 0;
-    resolveDispatchEvent(db, io, row.id, 'abandoned');
-    return 1;
+        return [];
+    resolveDispatchEvent(db, io, row.id, outcome);
+    return [row.id];
 }
-/** Fallback age threshold for dispatches without a linked PID (30 minutes). */
-const STALE_AGE_MS = 30 * 60 * 1000;
+/** Default fallback age threshold for dispatches without a linked PID (10 minutes). */
+const DEFAULT_STALE_AGE_MS = 10 * 60 * 1000;
 /** Get all scope IDs that have actively running DISPATCH events.
  *  Uses PID liveness (process.kill(pid, 0)) when available, falls back to
  *  age-based heuristic for legacy dispatches without a linked PID. */
-export function getActiveScopeIds(db, scopeService, engine) {
+export function getActiveScopeIds(db, scopeService, engine, staleTimeoutMinutes) {
     const rows = db.prepare(`SELECT scope_id, data FROM events
      WHERE type = 'DISPATCH'
        AND scope_id IS NOT NULL
        AND JSON_EXTRACT(data, '$.resolved') IS NULL`).all();
-    const cutoff = new Date(Date.now() - STALE_AGE_MS).toISOString();
+    const staleMs = staleTimeoutMinutes != null ? staleTimeoutMinutes * 60 * 1000 : DEFAULT_STALE_AGE_MS;
+    const cutoff = new Date(Date.now() - staleMs).toISOString();
     const active = new Set();
     for (const row of rows) {
         if (active.has(row.scope_id))
@@ -146,6 +196,7 @@ export function getActiveScopeIds(db, scopeService, engine) {
             batchData = JSON.parse(batchRow.data);
         }
         catch {
+            log.warn('Skipping unparseable batch dispatch event data', { data: batchRow.data });
             continue;
         }
         const scopeIds = batchData.scope_ids;
@@ -176,12 +227,14 @@ export function getActiveScopeIds(db, scopeService, engine) {
  *  3. No linked PID and dispatch older than STALE_AGE_MS (fallback)
  *  Called once at startup and periodically to clean up unresolved dispatches.
  *
- *  NOTE: Does NOT revert scope status. Skills like /scope-implement intentionally
- *  keep scopes at the transition target after completion. Auto-reverting was
- *  destroying completed work and deleting scope files. Users can manually
- *  move scopes back from the dashboard if needed. */
-export function resolveStaleDispatches(db, io, scopeService, engine) {
-    const cutoff = new Date(Date.now() - STALE_AGE_MS).toISOString();
+ *  When a dispatch is abandoned, auto-reverts scope status if the forward edge
+ *  has autoRevert=true AND the scope is still at the dispatch target. This allows
+ *  safe recovery for edges like backlog→implementing where the session crashed
+ *  before doing meaningful work. Edges without autoRevert leave the scope in place
+ *  for manual recovery from the dashboard. */
+export function resolveStaleDispatches(db, io, scopeService, engine, staleTimeoutMinutes) {
+    const staleMs = staleTimeoutMinutes != null ? staleTimeoutMinutes * 60 * 1000 : DEFAULT_STALE_AGE_MS;
+    const cutoff = new Date(Date.now() - staleMs).toISOString();
     // Single query on events only — split by cache status
     const rows = db.prepare(`SELECT id, scope_id, data, timestamp FROM events
      WHERE type = 'DISPATCH'
@@ -215,6 +268,8 @@ export function resolveStaleDispatches(db, io, scopeService, engine) {
         }
         if (isStale) {
             resolveDispatchEvent(db, io, row.id, 'abandoned');
+            // Try auto-revert; if successful, clear the abandoned state
+            tryAutoRevertAndClear(db, io, scopeService, engine, row.id);
             resolved++;
         }
     }
@@ -230,6 +285,7 @@ export function resolveStaleDispatches(db, io, scopeService, engine) {
             batchData = JSON.parse(batchRow.data);
         }
         catch {
+            log.warn('Skipping unparseable batch dispatch event data', { eventId: batchRow.id });
             continue;
         }
         const scopeIds = batchData.scope_ids;
@@ -299,6 +355,9 @@ export function getAbandonedScopeIds(db, scopeService, engine, activeScopeIds) {
         const resolved = data.resolved;
         const fromStatus = transition?.from ?? null;
         const abandonedAt = resolved?.at ?? row.timestamp;
+        // Defense-in-depth: skip scopes already at their pre-dispatch status (already reverted)
+        if (fromStatus && scope.status === fromStatus)
+            continue;
         result.push({ scope_id: row.scope_id, from_status: fromStatus, abandoned_at: abandonedAt });
     }
     return result;

package/dist/server/server/utils/dispatch-utils.test.js

@@ -0,0 +1,182 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { resolveDispatchEvent, resolveActiveDispatchesForScope, resolveAbandonedDispatchesForScope, linkPidToDispatch, resolveDispatchesByPid, resolveDispatchesByDispatchId, getActiveScopeIds, getAbandonedScopeIds, } from './dispatch-utils.js';
+import { createTestDb } from '../__tests__/helpers/db.js';
+import { createMockEmitter } from '../__tests__/helpers/mock-emitter.js';
+import { WorkflowEngine } from '../../shared/workflow-engine.js';
+import { CONFIG_WITH_HOOKS } from '../../shared/__fixtures__/workflow-configs.js';
+// Mock isSessionPidAlive since it checks real OS processes
+vi.mock('./terminal-launcher.js', () => ({
+    isSessionPidAlive: vi.fn().mockReturnValue(false),
+    launchInTerminal: vi.fn(),
+    buildSessionName: vi.fn(),
+    snapshotSessionPids: vi.fn().mockReturnValue([]),
+    discoverNewSession: vi.fn(),
+    renameSession: vi.fn(),
+    launchInCategorizedTerminal: vi.fn(),
+}));
+function insertDispatchEvent(db, overrides = {}) {
+    const id = overrides.id ?? `dispatch-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    const data = JSON.stringify({
+        command: '/scope-implement 1',
+        transition: { from: 'backlog', to: 'active' },
+        ...(overrides.data ?? {}),
+    });
+    db.prepare(`INSERT INTO events (id, type, scope_id, session_id, agent, data, timestamp)
+     VALUES (?, 'DISPATCH', ?, ?, NULL, ?, ?)`).run(id, overrides.scope_id ?? 1, overrides.session_id ?? 'sess-1', data, overrides.timestamp ?? new Date().toISOString());
+    return id;
+}
+describe('dispatch-utils', () => {
+    let db;
+    let cleanup;
+    let emitter;
+    let engine;
+    beforeEach(() => {
+        ({ db, cleanup } = createTestDb());
+        emitter = createMockEmitter();
+        engine = new WorkflowEngine(CONFIG_WITH_HOOKS);
+    });
+    afterEach(() => {
+        cleanup?.();
+    });
+    // ─── resolveDispatchEvent() ───────────────────────────────
+    describe('resolveDispatchEvent()', () => {
+        it('marks dispatch as resolved with outcome', () => {
+            const id = insertDispatchEvent(db);
+            resolveDispatchEvent(db, emitter, id, 'completed');
+            const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id);
+            const data = JSON.parse(row.data);
+            expect(data.resolved).toBeDefined();
+            expect(data.resolved.outcome).toBe('completed');
+            expect(data.resolved.at).toBeDefined();
+        });
+        it('emits dispatch:resolved event', () => {
+            const id = insertDispatchEvent(db);
+            resolveDispatchEvent(db, emitter, id, 'completed');
+            expect(emitter.emit).toHaveBeenCalledWith('dispatch:resolved', expect.objectContaining({ event_id: id }));
+        });
+        it('stores error message for failed dispatches', () => {
+            const id = insertDispatchEvent(db);
+            resolveDispatchEvent(db, emitter, id, 'failed', 'Timeout');
+            const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id);
+            const data = JSON.parse(row.data);
+            expect(data.resolved.outcome).toBe('failed');
+            expect(data.resolved.error).toBe('Timeout');
+        });
+    });
+    // ─── resolveActiveDispatchesForScope() ────────────────────
+    describe('resolveActiveDispatchesForScope()', () => {
+        it('resolves all unresolved dispatches for a scope', () => {
+            insertDispatchEvent(db, { id: 'd1', scope_id: 42 });
+            insertDispatchEvent(db, { id: 'd2', scope_id: 42 });
+            insertDispatchEvent(db, { id: 'd3', scope_id: 99 }); // different scope
+            resolveActiveDispatchesForScope(db, emitter, 42, 'completed');
+            const rows = db.prepare("SELECT data FROM events WHERE scope_id = 42").all();
+            for (const row of rows) {
+                const data = JSON.parse(row.data);
+                expect(data.resolved).toBeDefined();
+                expect(data.resolved.outcome).toBe('completed');
+            }
+            // Scope 99 should NOT be resolved
+            const other = db.prepare("SELECT data FROM events WHERE scope_id = 99").get();
+            expect(JSON.parse(other.data).resolved).toBeUndefined();
+        });
+        it('handles no active dispatches gracefully', () => {
+            expect(() => resolveActiveDispatchesForScope(db, emitter, 999, 'completed')).not.toThrow();
+        });
+    });
+    // ─── resolveAbandonedDispatchesForScope() ─────────────────
+    describe('resolveAbandonedDispatchesForScope()', () => {
+        it('resolves abandoned dispatches as completed', () => {
+            insertDispatchEvent(db, { scope_id: 42, data: { resolved: true, outcome: 'abandoned' } });
+            const count = resolveAbandonedDispatchesForScope(db, emitter, 42);
+            expect(count).toBeGreaterThanOrEqual(0);
+        });
+    });
+    // ─── linkPidToDispatch() ──────────────────────────────────
+    describe('linkPidToDispatch()', () => {
+        it('stores PID in event data', () => {
+            const id = insertDispatchEvent(db);
+            linkPidToDispatch(db, id, 12345);
+            const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id);
+            const data = JSON.parse(row.data);
+            expect(data.pid).toBe(12345);
+        });
+        it('handles non-existent event gracefully', () => {
+            expect(() => linkPidToDispatch(db, 'nonexistent', 12345)).not.toThrow();
+        });
+    });
+    // ─── resolveDispatchesByPid() ─────────────────────────────
+    describe('resolveDispatchesByPid()', () => {
+        it('resolves dispatches matching PID', () => {
+            const id = insertDispatchEvent(db, { scope_id: 1 });
+            linkPidToDispatch(db, id, 54321);
+            const ids = resolveDispatchesByPid(db, emitter, 54321);
+            expect(ids).toHaveLength(1);
+            expect(ids[0]).toBe(id);
+            const row = db.prepare('SELECT data FROM events WHERE id = ?').get(id);
+            expect(JSON.parse(row.data).resolved).toBeDefined();
+        });
+        it('returns empty array when no dispatches match PID', () => {
+            expect(resolveDispatchesByPid(db, emitter, 99999)).toHaveLength(0);
+        });
+    });
+    // ─── resolveDispatchesByDispatchId() ──────────────────────
+    describe('resolveDispatchesByDispatchId()', () => {
+        it('resolves single dispatch by event ID', () => {
+            const id = insertDispatchEvent(db);
+            const ids = resolveDispatchesByDispatchId(db, emitter, id);
+            expect(ids).toHaveLength(1);
+            expect(ids[0]).toBe(id);
+        });
+        it('returns empty array for non-existent dispatch', () => {
+            expect(resolveDispatchesByDispatchId(db, emitter, 'nonexistent')).toHaveLength(0);
+        });
+    });
+    // ─── getActiveScopeIds() ──────────────────────────────────
+    describe('getActiveScopeIds()', () => {
+        it('returns scope IDs with unresolved dispatches', () => {
+            insertDispatchEvent(db, { scope_id: 10 });
+            insertDispatchEvent(db, { scope_id: 20 });
+            const mockScopeService = {
+                getById: (id) => ({ id, status: 'active' }),
+            };
+            const ids = getActiveScopeIds(db, mockScopeService, engine);
+            // May return empty if dispatches are stale (PID check fails), but shouldn't throw
+            expect(Array.isArray(ids)).toBe(true);
+        });
+        it('excludes scopes in terminal status', () => {
+            insertDispatchEvent(db, { scope_id: 30 });
+            const mockScopeService = {
+                getById: (id) => ({ id, status: 'shipped' }), // terminal
+            };
+            const ids = getActiveScopeIds(db, mockScopeService, engine);
+            expect(ids).not.toContain(30);
+        });
+    });
+    // ─── getAbandonedScopeIds() ───────────────────────────────
+    describe('getAbandonedScopeIds()', () => {
+        it('returns recently abandoned scopes', () => {
+            insertDispatchEvent(db, {
+                scope_id: 50,
+                data: { resolved: true, outcome: 'abandoned', resolved_at: new Date().toISOString(), transition: { from: 'backlog', to: 'active' } },
+            });
+            const mockScopeService = {
+                getById: (id) => ({ id, status: 'active' }),
+            };
+            const abandoned = getAbandonedScopeIds(db, mockScopeService, engine);
+            expect(Array.isArray(abandoned)).toBe(true);
+        });
+        it('excludes terminal scopes', () => {
+            insertDispatchEvent(db, {
+                scope_id: 60,
+                data: { resolved: true, outcome: 'abandoned', resolved_at: new Date().toISOString(), transition: { from: 'review', to: 'shipped' } },
+            });
+            const mockScopeService = {
+                getById: (id) => ({ id, status: 'shipped' }), // terminal
+            };
+            const abandoned = getAbandonedScopeIds(db, mockScopeService, engine);
+            const ids = abandoned.map(a => a.scope_id);
+            expect(ids).not.toContain(60);
+        });
+    });
+});

package/dist/server/server/utils/flag-builder.js

@@ -0,0 +1,54 @@
+import { VALID_OUTPUT_FORMATS, validateToolName, validateEnvKey } from '../../shared/api-types.js';
+import { shellQuote } from './terminal-launcher.js';
+/**
+ * Compile a structured DispatchFlags object into a CLI flags string
+ * for the `claude` command. All parameterized values are validated
+ * and shell-quoted to prevent injection.
+ */
+export function buildClaudeFlags(flags) {
+    const parts = [];
+    // Permission mode — 'default' means no flag (use Claude's built-in default)
+    if (flags.permissionMode === 'bypass') {
+        parts.push('--dangerously-skip-permissions');
+    }
+    else if (flags.permissionMode && flags.permissionMode !== 'default') {
+        parts.push('--permission-mode', flags.permissionMode);
+    }
+    if (flags.verbose)
+        parts.push('--verbose');
+    if (flags.noMarkdown)
+        parts.push('--no-markdown');
+    if (flags.printMode)
+        parts.push('-p');
+    if (flags.outputFormat && VALID_OUTPUT_FORMATS.includes(flags.outputFormat)) {
+        parts.push('--output-format', flags.outputFormat);
+    }
+    if (flags.allowedTools.length > 0) {
+        const safe = flags.allowedTools.filter(validateToolName);
+        if (safe.length > 0)
+            parts.push('--allowedTools', safe.join(','));
+    }
+    if (flags.disallowedTools.length > 0) {
+        const safe = flags.disallowedTools.filter(validateToolName);
+        if (safe.length > 0)
+            parts.push('--disallowedTools', safe.join(','));
+    }
+    if (flags.appendSystemPrompt) {
+        const sanitized = flags.appendSystemPrompt.replace(/\n/g, '\\n');
+        parts.push('--append-system-prompt', `'${shellQuote(sanitized)}'`);
+    }
+    return parts.join(' ');
+}
+/**
+ * Build env var prefix string for dispatch commands.
+ * Keys are validated against POSIX naming rules.
+ * Returns empty string if no vars configured.
+ */
+export function buildEnvVarPrefix(envVars) {
+    const entries = Object.entries(envVars).filter(([k]) => validateEnvKey(k));
+    if (entries.length === 0)
+        return '';
+    return entries
+        .map(([k, v]) => `${k}='${v.replace(/'/g, "'\\''")}'`)
+        .join(' ') + ' ';
+}

package/dist/server/server/utils/json-fields.js

@@ -0,0 +1,14 @@
+const JSON_FIELDS = ['tags', 'blocked_by', 'blocks', 'data', 'discoveries', 'next_steps', 'details'];
+/** Parse stringified JSON fields in a database row back to objects. */
+export function parseJsonFields(row) {
+    const parsed = { ...row };
+    for (const field of JSON_FIELDS) {
+        if (typeof parsed[field] === 'string') {
+            try {
+                parsed[field] = JSON.parse(parsed[field]);
+            }
+            catch { /* keep string */ }
+        }
+    }
+    return parsed;
+}

package/dist/server/server/utils/json-fields.test.js

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { parseJsonFields } from './json-fields.js';
+describe('parseJsonFields', () => {
+    it('parses stringified JSON arrays in known fields', () => {
+        const row = { tags: '["a","b"]', blocked_by: '[1,2]', title: 'scope-1' };
+        const result = parseJsonFields(row);
+        expect(result.tags).toEqual(['a', 'b']);
+        expect(result.blocked_by).toEqual([1, 2]);
+        expect(result.title).toBe('scope-1');
+    });
+    it('parses stringified JSON objects in data field', () => {
+        const row = { data: '{"key":"val","nested":{"a":1}}' };
+        const result = parseJsonFields(row);
+        expect(result.data).toEqual({ key: 'val', nested: { a: 1 } });
+    });
+    it('handles all 7 known JSON fields', () => {
+        const row = {
+            tags: '[]', blocked_by: '[]', blocks: '[]',
+            data: '{}', discoveries: '[]', next_steps: '[]', details: '{}',
+        };
+        const result = parseJsonFields(row);
+        expect(result.tags).toEqual([]);
+        expect(result.blocked_by).toEqual([]);
+        expect(result.blocks).toEqual([]);
+        expect(result.data).toEqual({});
+        expect(result.discoveries).toEqual([]);
+        expect(result.next_steps).toEqual([]);
+        expect(result.details).toEqual({});
+    });
+    it('passes through already-parsed objects untouched', () => {
+        const tags = ['a', 'b'];
+        const row = { tags, data: { foo: 1 } };
+        const result = parseJsonFields(row);
+        expect(result.tags).toBe(tags); // same reference — not re-parsed
+        expect(result.data).toEqual({ foo: 1 });
+    });
+    it('keeps malformed JSON strings as-is without throwing', () => {
+        const row = { tags: '{broken json', data: 'not json at all', blocks: '["valid"]' };
+        const result = parseJsonFields(row);
+        expect(result.tags).toBe('{broken json');
+        expect(result.data).toBe('not json at all');
+        expect(result.blocks).toEqual(['valid']);
+    });
+    it('returns row unchanged when no JSON fields are present', () => {
+        const row = { id: 1, title: 'hello', status: 'active' };
+        const result = parseJsonFields(row);
+        expect(result).toEqual(row);
+    });
+    it('does not mutate the original row', () => {
+        const row = { tags: '["x"]', title: 'scope' };
+        const result = parseJsonFields(row);
+        expect(row.tags).toBe('["x"]'); // original unchanged
+        expect(result.tags).toEqual(['x']); // copy was parsed
+        expect(result).not.toBe(row);
+    });
+    it('handles null and undefined field values', () => {
+        const row = { tags: null, data: undefined, blocks: '["a"]' };
+        const result = parseJsonFields(row);
+        expect(result.tags).toBeNull();
+        expect(result.data).toBeUndefined();
+        expect(result.blocks).toEqual(['a']);
+    });
+    it('handles empty row', () => {
+        const result = parseJsonFields({});
+        expect(result).toEqual({});
+    });
+    it('ignores non-JSON-field strings', () => {
+        const row = { title: '["not a json field"]', tags: '["real"]' };
+        const result = parseJsonFields(row);
+        expect(result.title).toBe('["not a json field"]'); // title is not in JSON_FIELDS
+        expect(result.tags).toEqual(['real']);
+    });
+});

package/dist/server/server/utils/logger.js

@@ -24,8 +24,14 @@ const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const c = {
     reset: useColor ? '\x1b[0m' : '',
     dim: useColor ? '\x1b[2m' : '',
-    gray: useColor ? '\x1b[90m' : '',
+    green: useColor ? '\x1b[32m' : '',
+    blue: useColor ? '\x1b[34m' : '',
+    magenta: useColor ? '\x1b[35m' : '',
     cyan: useColor ? '\x1b[36m' : '',
+    white: useColor ? '\x1b[37m' : '',
+    gray: useColor ? '\x1b[90m' : '',
+    brightMagenta: useColor ? '\x1b[95m' : '',
+    brightCyan: useColor ? '\x1b[96m' : '',
     yellow: useColor ? '\x1b[33m' : '',
     red: useColor ? '\x1b[31m' : '',
 };
@@ -41,6 +47,31 @@ const LEVEL_LABEL = {
     warn: 'WARN ',
     error: 'ERROR',
 };
+// ─── Component Colors ───────────────────────────────────────
+const COMPONENT_COLOR = {
+    // Scope (green)
+    'scope': c.green, 'scope-watcher': c.green,
+    // Dispatch (magenta)
+    'dispatch': c.magenta, 'dispatch-utils': c.magenta, 'batch': c.magenta,
+    // Git (blue)
+    'git': c.blue, 'worktree': c.blue,
+    // Workflow (cyan)
+    'workflow': c.cyan, 'sprint': c.cyan,
+    // Sync / Config (yellow)
+    'sync': c.yellow, 'config': c.yellow, 'manifest': c.yellow, 'global-config': c.yellow,
+    // Events (white)
+    'event': c.white, 'event-watcher': c.white, 'global-watcher': c.white,
+    // Infrastructure (white)
+    'server': c.white, 'central': c.white, 'database': c.white,
+    'project-context': c.white, 'project-manager': c.white, 'launch': c.white,
+    // Terminal (bright magenta)
+    'terminal': c.brightMagenta,
+    // Services (bright cyan)
+    'gate': c.brightCyan, 'deploy': c.brightCyan, 'telemetry': c.brightCyan, 'version': c.brightCyan,
+};
+function componentColor(name) {
+    return COMPONENT_COLOR[name] ?? c.dim;
+}
 // ─── Formatting ─────────────────────────────────────────────
 function timestamp() {
     const d = new Date();
@@ -65,10 +96,13 @@ function formatData(data) {
 function write(level, component, msg, data) {
     if (LEVEL_VALUE[level] < LEVEL_VALUE[currentLevel])
         return;
-    const color = LEVEL_COLOR[level];
+    const lvl = LEVEL_COLOR[level];
     const label = LEVEL_LABEL[level];
     const kv = formatData(data);
-    const line = `${c.dim}${timestamp()}${c.reset} ${color}${label}${c.reset} ${c.dim}[${component}]${c.reset} ${msg}${kv}\n`;
+    const cc = componentColor(component);
+    // Message uses level color for warn/error (urgency), component color otherwise
+    const mc = (level === 'warn' || level === 'error') ? lvl : cc;
+    const line = `${c.dim}${timestamp()}${c.reset} ${lvl}${label}${c.reset} ${cc}[${component}]${c.reset} ${mc}${msg}${c.reset}${c.dim}${kv}${c.reset}\n`;
     if (level === 'warn' || level === 'error') {
         process.stderr.write(line);
     }

package/dist/server/server/utils/package-info.js

@@ -0,0 +1,30 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+const __selfDir = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve the root directory of the orbital-command package itself.
+ * Walks up from the current file until it finds package.json.
+ */
+export function getOrbitalRoot() {
+    let dir = __selfDir;
+    for (let i = 0; i < 6; i++) {
+        if (fs.existsSync(path.join(dir, 'package.json'))) {
+            return dir;
+        }
+        dir = path.dirname(dir);
+    }
+    // Fallback: assume dev layout (server/utils/ → 2 levels up)
+    return path.resolve(__selfDir, '../..');
+}
+/** Read package version from package.json in the given root, or the orbital root. */
+export function getPackageVersion(rootDir) {
+    try {
+        const dir = rootDir ?? getOrbitalRoot();
+        const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+        return pkg.version || '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/dist/server/server/utils/route-helpers.js

@@ -0,0 +1,47 @@
+import path from 'path';
+/** Extract a human-readable message from an unknown error value. */
+export function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Validate that a relative path stays within bounds (no traversal). */
+export function isValidRelativePath(p) {
+    const normalized = path.normalize(p);
+    return !normalized.startsWith('..') && !path.isAbsolute(normalized) && !normalized.includes('\0');
+}
+/** Infer an HTTP status code from an error message. */
+export function inferErrorStatus(msg) {
+    if (msg.includes('traversal'))
+        return 403;
+    if (msg.includes('ENOENT') || msg.includes('not found'))
+        return 404;
+    if (msg.includes('already exists'))
+        return 409;
+    if (msg.includes('directory'))
+        return 400;
+    return 500;
+}
+/**
+ * Wrap an Express route handler to catch thrown errors and send a JSON error response.
+ * Works with both sync and async handlers.
+ *
+ * @param fn — route handler that may throw
+ * @param statusFn — optional function to infer status from error message (defaults to 500)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function catchRoute(fn, statusFn) {
+    return ((req, res, next) => {
+        try {
+            const result = fn(req, res, next);
+            if (result instanceof Promise) {
+                result.catch((err) => {
+                    const msg = errMsg(err);
+                    res.status(statusFn ? statusFn(msg) : 500).json({ success: false, error: msg });
+                });
+            }
+        }
+        catch (err) {
+            const msg = errMsg(err);
+            res.status(statusFn ? statusFn(msg) : 500).json({ success: false, error: msg });
+        }
+    });
+}