orbital-command 0.1.0

package/dist/server/server/services/scope-cache.js

@@ -0,0 +1,72 @@
+/**
+ * In-memory cache for parsed scopes.
+ * Dual-indexed: ID lookups (API, sprint orchestrator) and file-path reverse index (watcher deletions).
+ * Replaces the SQLite `scopes` table — filesystem frontmatter is the single source of truth.
+ */
+export class ScopeCache {
+    byId = new Map();
+    filePathToId = new Map();
+    /** Bulk-load all scopes (called at startup from parseAllScopes result) */
+    loadAll(scopes) {
+        this.byId.clear();
+        this.filePathToId.clear();
+        for (const scope of scopes) {
+            this.byId.set(scope.id, scope);
+            this.filePathToId.set(scope.file_path, scope.id);
+        }
+    }
+    /** Insert or update a single scope */
+    set(scope) {
+        // Clean up old file_path mapping if the scope moved directories
+        const existing = this.byId.get(scope.id);
+        if (existing && existing.file_path !== scope.file_path) {
+            this.filePathToId.delete(existing.file_path);
+        }
+        this.byId.set(scope.id, scope);
+        this.filePathToId.set(scope.file_path, scope.id);
+    }
+    /** Remove a scope by its file path (used by watcher on file deletion) */
+    removeByFilePath(filePath) {
+        const id = this.filePathToId.get(filePath);
+        if (id !== undefined) {
+            this.byId.delete(id);
+            this.filePathToId.delete(filePath);
+        }
+        return id;
+    }
+    /** Look up scope ID by file path (used before removal to stash status) */
+    idByFilePath(filePath) {
+        return this.filePathToId.get(filePath);
+    }
+    /** Check if scope exists by ID */
+    has(id) {
+        return this.byId.has(id);
+    }
+    /** Get a scope by ID */
+    getById(id) {
+        return this.byId.get(id);
+    }
+    /** Get all scopes sorted by ID */
+    getAll() {
+        return [...this.byId.values()].sort((a, b) => a.id - b.id);
+    }
+    /** Get the maximum raw scope number excluding icebox scopes (for next-ID generation).
+     *  Cache keys use encoded IDs (suffixed scopes like 047a → 1047, 075x → 9075),
+     *  but next-ID generation needs the raw scope number (047, 075, 087). */
+    maxNonIceboxId() {
+        let max = 0;
+        for (const [id, scope] of this.byId) {
+            if (scope.status === 'icebox')
+                continue;
+            // Decode: encoded IDs ≥1000 have a suffix offset — raw number is id % 1000
+            const raw = id >= 1000 ? id % 1000 : id;
+            if (raw > max)
+                max = raw;
+        }
+        return max;
+    }
+    /** Total number of cached scopes */
+    get size() {
+        return this.byId.size;
+    }
+}

package/dist/server/server/services/scope-service.js

@@ -0,0 +1,424 @@
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import { normalizeStatus, parseAllScopes, parseScopeFile, setValidStatuses } from '../parsers/scope-parser.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('scope');
+export class ScopeService {
+    cache;
+    io;
+    scopesDir;
+    engine;
+    onStatusChangeCallbacks = [];
+    activeGroupCheck = null;
+    suppressedPaths = new Set();
+    /** Stash old status when removeByFilePath fires before updateFromFile (chokidar unlink→add) */
+    recentlyRemoved = new Map();
+    constructor(cache, io, scopesDir, engine) {
+        this.cache = cache;
+        this.io = io;
+        this.scopesDir = scopesDir;
+        this.engine = engine;
+    }
+    /** Register a callback that checks if a scope is in an active group (sprint/batch).
+     *  Used to guard patch-context status changes. */
+    setActiveGroupCheck(fn) {
+        this.activeGroupCheck = fn;
+    }
+    /** Register a callback fired after every successful status update */
+    onStatusChange(cb) {
+        this.onStatusChangeCallbacks.push(cb);
+    }
+    /** Load all scopes from the filesystem into the in-memory cache */
+    syncFromFilesystem() {
+        // Push the engine's valid list IDs to the scope parser so
+        // inferStatusFromDir doesn't rely on a hardcoded set.
+        setValidStatuses(this.engine.getLists().map(l => l.id));
+        const scopes = parseAllScopes(this.scopesDir);
+        this.cache.loadAll(scopes);
+        return scopes.length;
+    }
+    /** Check if a path is suppressed from watcher processing (during programmatic moves) */
+    isSuppressed(filePath) {
+        return this.suppressedPaths.has(filePath);
+    }
+    /** Re-parse a single scope file and update the cache */
+    updateFromFile(filePath) {
+        const scope = parseScopeFile(filePath);
+        if (!scope)
+            return;
+        const previous = this.cache.getById(scope.id);
+        const previousStatus = previous?.status ?? this.recentlyRemoved.get(scope.id);
+        const existing = previous != null;
+        this.cache.set(scope);
+        this.recentlyRemoved.delete(scope.id);
+        const event = existing ? 'scope:updated' : 'scope:created';
+        this.io.emit(event, scope);
+        // Fire onStatusChange callbacks when status changed via external file move
+        // (e.g. scope-transition.sh, manual mv). This ensures batch/sprint
+        // orchestrators are notified even when the change bypasses updateStatus().
+        // Chokidar fires unlink→add for moves, so the cache entry may already be
+        // removed by removeByFilePath — check recentlyRemoved for the old status.
+        if (previousStatus != null && previousStatus !== scope.status) {
+            for (const cb of this.onStatusChangeCallbacks)
+                cb(scope.id, scope.status);
+        }
+    }
+    /** Remove a scope when its file is deleted */
+    removeByFilePath(filePath) {
+        // Stash status before removal so updateFromFile can detect external moves
+        // (chokidar fires unlink before add when a file is moved between directories)
+        const scopeId = this.cache.idByFilePath(filePath);
+        const previous = scopeId != null ? this.cache.getById(scopeId) : undefined;
+        const id = this.cache.removeByFilePath(filePath);
+        if (id !== undefined) {
+            if (previous)
+                this.recentlyRemoved.set(id, previous.status);
+            this.io.emit('scope:deleted', id);
+            // Clean up stash after a short window (if add never fires, this was a real delete)
+            setTimeout(() => this.recentlyRemoved.delete(id), 5000);
+        }
+    }
+    /** Get all scopes (already native arrays/objects — no JSON parsing needed) */
+    getAll() {
+        return this.cache.getAll();
+    }
+    /** Get a single scope by ID */
+    getById(id) {
+        return this.cache.getById(id);
+    }
+    /** Update a scope's status with transition validation.
+     *  Writes the new status to the frontmatter file and updates the cache.
+     *  @param context - caller trust level: 'patch', 'dispatch', 'event', 'bulk-sync', 'rollback' */
+    updateStatus(id, status, context = 'patch') {
+        if (!this.engine.isValidStatus(status)) {
+            return { ok: false, error: `Invalid status: '${status}'`, code: 'INVALID_STATUS' };
+        }
+        // For non-skip contexts, validate the transition
+        if (context !== 'bulk-sync' && context !== 'rollback') {
+            const current = this.cache.getById(id);
+            if (!current) {
+                return { ok: false, error: 'Scope not found', code: 'NOT_FOUND' };
+            }
+            // Guard: block manual moves for scopes in active groups (sprint/batch)
+            if (context === 'patch' && this.activeGroupCheck) {
+                const group = this.activeGroupCheck(id);
+                if (group) {
+                    return { ok: false, error: `Scope is in an active ${group.group_type} (ID: ${group.sprint_id})`, code: 'SCOPE_IN_ACTIVE_GROUP' };
+                }
+            }
+            const check = this.engine.validateTransition(current.status, status, context);
+            if (!check.ok)
+                return check;
+        }
+        // Write to filesystem via updateScopeFrontmatter (which updates cache + emits)
+        const current = context === 'bulk-sync' || context === 'rollback'
+            ? this.cache.getById(id)
+            : this.cache.getById(id); // already fetched above for validation, but may be null in bulk-sync
+        const fromStatus = current?.status ?? 'unknown';
+        const result = this.updateScopeFrontmatter(id, { status }, context);
+        if (result.ok) {
+            log.info('Status updated', { id, from: fromStatus, to: status, context });
+            for (const cb of this.onStatusChangeCallbacks)
+                cb(id, status);
+        }
+        return result;
+    }
+    /** Compute the next sequential scope ID by scanning all non-icebox scopes.
+     *  Checks both filesystem (all subdirs except icebox) and cache to prevent collisions. */
+    getNextScopeId() {
+        let maxId = 0;
+        // Scan all scope subdirectories except icebox
+        if (fs.existsSync(this.scopesDir)) {
+            for (const dir of fs.readdirSync(this.scopesDir, { withFileTypes: true })) {
+                if (!dir.isDirectory() || dir.name === 'icebox')
+                    continue;
+                const dirPath = path.join(this.scopesDir, dir.name);
+                for (const file of fs.readdirSync(dirPath)) {
+                    const m = file.match(/^(\d+)-/);
+                    if (m)
+                        maxId = Math.max(maxId, parseInt(m[1], 10));
+                }
+            }
+        }
+        // Cross-check cache (catches scopes in unexpected locations)
+        const cacheMax = this.cache.maxNonIceboxId();
+        maxId = Math.max(maxId, cacheMax);
+        return maxId + 1;
+    }
+    // ─── Idea CRUD (filesystem-backed icebox cards) ────────────
+    /** Get the next available icebox ID (starts at 501, increments from max found) */
+    getNextIceboxId() {
+        const iceboxDir = path.join(this.scopesDir, 'icebox');
+        if (!fs.existsSync(iceboxDir))
+            return 501;
+        let maxId = 500;
+        for (const file of fs.readdirSync(iceboxDir)) {
+            const m = file.match(/^(\d+)-/);
+            if (m)
+                maxId = Math.max(maxId, parseInt(m[1], 10));
+        }
+        return maxId + 1;
+    }
+    /** Find an icebox file by its ID prefix.
+     *  Matches both padded (091-) and unpadded (91-) filenames
+     *  since demoted scopes keep their 3-digit-padded names. */
+    findIdeaFile(iceboxDir, id) {
+        if (!fs.existsSync(iceboxDir))
+            return null;
+        const match = fs.readdirSync(iceboxDir).find((f) => {
+            if (!f.endsWith('.md'))
+                return false;
+            const m = f.match(/^(\d+)-/);
+            return m != null && parseInt(m[1], 10) === id;
+        });
+        return match ? path.join(iceboxDir, match) : null;
+    }
+    /** Create an icebox idea as a markdown file. IDs start at 501. */
+    createIdeaFile(title, description) {
+        const iceboxDir = path.join(this.scopesDir, 'icebox');
+        if (!fs.existsSync(iceboxDir))
+            fs.mkdirSync(iceboxDir, { recursive: true });
+        const nextId = this.getNextIceboxId();
+        const slug = title
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '')
+            .slice(0, 60);
+        const fileName = `${nextId}-${slug}.md`;
+        const filePath = path.join(iceboxDir, fileName);
+        const now = new Date().toISOString().split('T')[0];
+        const content = [
+            '---',
+            `id: ${nextId}`,
+            `title: "${title.replace(/"/g, '\\"')}"`,
+            'status: icebox',
+            `created: ${now}`,
+            `updated: ${now}`,
+            'blocked_by: []',
+            'blocks: []',
+            'tags: []',
+            '---',
+            '',
+            description || '',
+            '',
+        ].join('\n');
+        fs.writeFileSync(filePath, content, 'utf-8');
+        // Eagerly sync to cache + emit scope:created
+        this.updateFromFile(filePath);
+        log.info('Idea created', { id: nextId, title });
+        return { id: nextId, title };
+    }
+    /** Update an icebox idea's title and description by rewriting its file */
+    updateIdeaFile(id, title, description) {
+        const iceboxDir = path.join(this.scopesDir, 'icebox');
+        const filePath = this.findIdeaFile(iceboxDir, id);
+        if (!filePath)
+            return false;
+        // Preserve the original created date from existing frontmatter
+        const existing = fs.readFileSync(filePath, 'utf-8');
+        const createdMatch = existing.match(/^created:\s*(.+)$/m);
+        const created = createdMatch?.[1]?.trim() ?? new Date().toISOString().split('T')[0];
+        const now = new Date().toISOString().split('T')[0];
+        const content = [
+            '---',
+            `id: ${id}`,
+            `title: "${title.replace(/"/g, '\\"')}"`,
+            'status: icebox',
+            `created: ${created}`,
+            `updated: ${now}`,
+            'blocked_by: []',
+            'blocks: []',
+            'tags: []',
+            '---',
+            '',
+            description || '',
+            '',
+        ].join('\n');
+        fs.writeFileSync(filePath, content, 'utf-8');
+        // Watcher handles cache sync + scope:updated event
+        return true;
+    }
+    /** Delete an icebox idea by removing its file */
+    deleteIdeaFile(id) {
+        const iceboxDir = path.join(this.scopesDir, 'icebox');
+        const filePath = this.findIdeaFile(iceboxDir, id);
+        if (!filePath)
+            return false;
+        fs.unlinkSync(filePath);
+        // Eagerly remove from cache + emit scope:deleted
+        this.removeByFilePath(filePath);
+        log.info('Idea deleted', { id });
+        return true;
+    }
+    /** Promote an icebox idea to planning — assigns a proper sequential scope ID,
+     *  moves the file, and syncs cache. Returns the new scope ID. */
+    promoteIdea(id) {
+        const iceboxDir = path.join(this.scopesDir, 'icebox');
+        const oldPath = this.findIdeaFile(iceboxDir, id);
+        if (!oldPath)
+            return null;
+        // Read existing file for metadata
+        const content = fs.readFileSync(oldPath, 'utf-8');
+        const titleMatch = content.match(/^title:\s*"?([^"\n]+)"?\s*$/m);
+        const createdMatch = content.match(/^created:\s*(.+)$/m);
+        const title = titleMatch?.[1]?.trim() ?? 'Untitled';
+        const created = createdMatch?.[1]?.trim() ?? new Date().toISOString().split('T')[0];
+        // Extract body after frontmatter
+        const fmEnd = content.indexOf('---', content.indexOf('---') + 3);
+        const description = fmEnd !== -1 ? content.slice(fmEnd + 3).trim() : '';
+        // Assign the next sequential scope ID (excludes icebox items)
+        const newId = this.getNextScopeId();
+        const paddedId = String(newId).padStart(3, '0');
+        // Build slug and new path
+        const slug = title
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '')
+            .slice(0, 60);
+        const planningDir = path.join(this.scopesDir, 'planning');
+        if (!fs.existsSync(planningDir))
+            fs.mkdirSync(planningDir, { recursive: true });
+        const newFileName = `${paddedId}-${slug}.md`;
+        const newPath = path.join(planningDir, newFileName);
+        const now = new Date().toISOString().split('T')[0];
+        // Write new file with planning status and new sequential ID
+        const newContent = [
+            '---',
+            `id: ${paddedId}`,
+            `title: "${title.replace(/"/g, '\\"')}"`,
+            'status: planning',
+            `created: ${created}`,
+            `updated: ${now}`,
+            'blocked_by: []',
+            'blocks: []',
+            'tags: []',
+            '---',
+            '',
+            description || '',
+            '',
+        ].join('\n');
+        fs.writeFileSync(newPath, newContent, 'utf-8');
+        // Sync cache before deleting old file (avoids window where scope is missing)
+        this.updateFromFile(newPath);
+        fs.unlinkSync(oldPath);
+        this.removeByFilePath(oldPath);
+        const relPath = path.relative(path.resolve(this.scopesDir, '..'), newPath);
+        log.info('Idea promoted', { oldId: id, newId, title });
+        return { id: newId, filePath: relPath, title, description };
+    }
+    /** Find a scope file by its numeric ID prefix across all status directories */
+    findScopeFile(id) {
+        if (!fs.existsSync(this.scopesDir))
+            return null;
+        const paddedId = String(id).padStart(3, '0');
+        const prefixes = [`${id}-`, `${paddedId}-`];
+        for (const dir of fs.readdirSync(this.scopesDir, { withFileTypes: true })) {
+            if (!dir.isDirectory())
+                continue;
+            const dirPath = path.join(this.scopesDir, dir.name);
+            for (const file of fs.readdirSync(dirPath)) {
+                if (file.endsWith('.md') && prefixes.some((p) => file.startsWith(p))) {
+                    return path.join(dirPath, file);
+                }
+            }
+        }
+        return null;
+    }
+    /** Update a scope's frontmatter fields and write back to the .md file.
+     *  If status changes, validates the transition and moves the file to the new status directory.
+     *  @param context - transition context for validation (default 'patch') */
+    updateScopeFrontmatter(id, fields, context = 'patch') {
+        const filePath = this.findScopeFile(id);
+        if (!filePath) {
+            return { ok: false, error: 'Scope file not found', code: 'NOT_FOUND' };
+        }
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const parsed = matter(raw);
+        const today = new Date().toISOString().split('T')[0];
+        // Validate status transition before any writes
+        const newStatus = fields.status;
+        const rawOldStatus = String(parsed.data.status ?? 'planning');
+        const oldStatus = normalizeStatus(rawOldStatus);
+        let needsMove = false;
+        if (newStatus && newStatus !== oldStatus) {
+            if (!this.engine.isValidStatus(newStatus)) {
+                return { ok: false, error: `Invalid status: '${newStatus}'`, code: 'INVALID_STATUS' };
+            }
+            const check = this.engine.validateTransition(oldStatus, newStatus, context);
+            if (!check.ok)
+                return check;
+            needsMove = true;
+            // Auto-unlock spec when reverting backlog → planning
+            if (newStatus === 'planning' && oldStatus === 'backlog')
+                fields.spec_locked = false;
+        }
+        // Merge editable fields into frontmatter
+        const editableKeys = ['title', 'status', 'priority', 'effort_estimate', 'category', 'tags', 'blocked_by', 'blocks', 'spec_locked'];
+        for (const key of editableKeys) {
+            if (key in fields) {
+                const val = fields[key];
+                // Treat empty strings / null as removal (delete the key)
+                if (val === null || val === '' || val === 'none') {
+                    delete parsed.data[key];
+                }
+                else {
+                    parsed.data[key] = val;
+                }
+            }
+        }
+        parsed.data.updated = today;
+        // Normalize Date objects to YYYY-MM-DD strings to prevent matter.stringify
+        // from converting them to full ISO timestamps (gray-matter auto-parses bare dates)
+        for (const key of Object.keys(parsed.data)) {
+            const val = parsed.data[key];
+            if (val instanceof Date) {
+                parsed.data[key] = val.toISOString().split('T')[0];
+            }
+        }
+        if (!needsMove) {
+            // Simple in-place rewrite
+            fs.writeFileSync(filePath, matter.stringify(parsed.content, parsed.data), 'utf-8');
+            // Chokidar will pick this up, but eagerly sync for instant feedback
+            this.updateFromFile(filePath);
+            log.info('Frontmatter updated', { id, fields: Object.keys(fields) });
+            return { ok: true };
+        }
+        // Status change → move file to new directory
+        const targetDir = path.join(this.scopesDir, newStatus);
+        if (!fs.existsSync(targetDir))
+            fs.mkdirSync(targetDir, { recursive: true });
+        const fileName = path.basename(filePath);
+        const newPath = path.join(targetDir, fileName);
+        const newContent = matter.stringify(parsed.content, parsed.data);
+        // Suppress watcher events during programmatic move to prevent race conditions
+        this.suppressedPaths.add(filePath);
+        this.suppressedPaths.add(newPath);
+        // Update content in-place, then atomic rename (no window where file is missing)
+        fs.writeFileSync(filePath, newContent, 'utf-8');
+        fs.renameSync(filePath, newPath);
+        this.updateFromFile(newPath);
+        this.removeByFilePath(filePath);
+        // Clear suppression after watcher events have drained
+        setTimeout(() => {
+            this.suppressedPaths.delete(filePath);
+            this.suppressedPaths.delete(newPath);
+        }, 500);
+        return { ok: true, moved: true };
+    }
+    /** Approve a ghost idea — removes ghost:true from frontmatter and refreshes cache */
+    approveGhostIdea(id) {
+        const iceboxDir = path.join(this.scopesDir, 'icebox');
+        const filePath = this.findIdeaFile(iceboxDir, id);
+        if (!filePath)
+            return false;
+        const content = fs.readFileSync(filePath, 'utf-8');
+        // Remove ghost: true line from frontmatter
+        const updated = content.replace(/^ghost:\s*true\n/m, '');
+        fs.writeFileSync(filePath, updated, 'utf-8');
+        // Re-parse file to refresh cache with is_ghost=false
+        this.updateFromFile(filePath);
+        log.info('Ghost approved', { id });
+        return true;
+    }
+}