orbital-command 0.2.0 → 1.0.0

package/dist/server/server/migrate-legacy.js

@@ -0,0 +1,229 @@
+/**
+ * Legacy migration — creates an orbital-manifest.json for projects
+ * that were initialized before the manifest system existed.
+ *
+ * Classifies existing files as synced/modified/user-owned by comparing
+ * their content hashes against the current template set.
+ */
+import fs from 'fs';
+import path from 'path';
+import { loadManifest, saveManifest, createManifest, hashFile, buildTemplateInventory, templateFileRecord, userFileRecord, isSelfHosting, getSymlinkTarget, } from './manifest.js';
+// ─── Constants ──────────────────────────────────────────────
+/** Directories that contain managed primitives */
+const MANAGED_DIRS = ['hooks', 'skills', 'agents'];
+/** Gitignore entries that Orbital adds */
+const GITIGNORE_ENTRIES = [
+    'scopes/',
+    '.claude/orbital/',
+    '.claude/orbital-events/',
+    '.claude/config/workflow-manifest.sh',
+];
+/**
+ * Detect whether a project needs legacy migration.
+ * Returns true if it has an orbital config but no manifest.
+ */
+export function needsLegacyMigration(projectRoot) {
+    const claudeDir = path.join(projectRoot, '.claude');
+    const hasConfig = fs.existsSync(path.join(claudeDir, 'orbital.config.json'));
+    const hasManifest = loadManifest(projectRoot) !== null;
+    return hasConfig && !hasManifest;
+}
+/**
+ * Create a manifest for an existing project that was initialized
+ * before the manifest system. Classifies every file in .claude/
+ * managed directories.
+ */
+export function migrateFromLegacy(projectRoot, templatesDir, packageVersion) {
+    const claudeDir = path.join(projectRoot, '.claude');
+    // If manifest already exists, skip
+    if (loadManifest(projectRoot) !== null) {
+        return { migrated: false, synced: 0, modified: 0, userOwned: 0, importedPins: 0 };
+    }
+    // Read existing config to get preset info
+    const preset = readPresetFromConfig(claudeDir);
+    // Read existing templateVersion from config, fall back to packageVersion
+    const configVersion = readTemplateVersion(claudeDir) || packageVersion;
+    const manifest = createManifest(configVersion, preset);
+    const selfHosting = isSelfHosting(projectRoot);
+    // Build template inventory (what files the current package ships)
+    const templateInventory = buildTemplateInventory(templatesDir);
+    let synced = 0;
+    let modified = 0;
+    let userOwned = 0;
+    // Walk managed directories and classify each file
+    for (const dir of MANAGED_DIRS) {
+        const dirPath = path.join(claudeDir, dir);
+        if (!fs.existsSync(dirPath))
+            continue;
+        walkDir(dirPath, dir, (relPath, absPath) => {
+            const templateHash = templateInventory.get(relPath);
+            if (templateHash) {
+                // File matches a known template path
+                if (selfHosting) {
+                    const symlinkTarget = getSymlinkTarget(claudeDir, relPath);
+                    if (symlinkTarget) {
+                        manifest.files[relPath] = {
+                            ...templateFileRecord(templateHash, symlinkTarget),
+                        };
+                        synced++;
+                        return;
+                    }
+                }
+                const fileHash = hashFile(absPath);
+                if (fileHash === templateHash) {
+                    manifest.files[relPath] = templateFileRecord(templateHash);
+                    synced++;
+                }
+                else {
+                    manifest.files[relPath] = {
+                        origin: 'template',
+                        status: 'modified',
+                        templateHash,
+                        installedHash: fileHash,
+                    };
+                    modified++;
+                }
+            }
+            else {
+                // File doesn't match any template — user-created
+                const fileHash = hashFile(absPath);
+                manifest.files[relPath] = userFileRecord(fileHash);
+                userOwned++;
+            }
+        });
+    }
+    // Also classify non-managed template files (quick/, anti-patterns/, config/, etc.)
+    classifyNonManagedFiles(claudeDir, templateInventory, manifest, selfHosting);
+    // Import from orbital-sync.json if it exists (override → pinned)
+    const importedPins = importFromSyncManifest(claudeDir, manifest);
+    // Record gitignore entries
+    manifest.gitignoreEntries = [...GITIGNORE_ENTRIES];
+    // Record settings hooks checksum
+    const settingsHooksPath = path.join(templatesDir, 'settings-hooks.json');
+    if (fs.existsSync(settingsHooksPath)) {
+        manifest.settingsHooksChecksum = hashFile(settingsHooksPath);
+    }
+    saveManifest(projectRoot, manifest);
+    return { migrated: true, synced, modified, userOwned, importedPins };
+}
+// ─── Internal Helpers ───────────────────────────────────────
+/** Recursively walk a directory, calling fn with relative and absolute paths. */
+function walkDir(dirPath, prefix, fn) {
+    if (!fs.existsSync(dirPath))
+        return;
+    for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const absPath = path.join(dirPath, entry.name);
+        const relPath = `${prefix}/${entry.name}`;
+        // Follow symlinks: use stat() to check if target is a directory
+        const stat = fs.statSync(absPath);
+        if (stat.isDirectory()) {
+            walkDir(absPath, relPath, fn);
+        }
+        else {
+            fn(relPath, absPath);
+        }
+    }
+}
+/** Classify template files outside hooks/skills/agents (quick/, anti-patterns/, config/, etc.) */
+function classifyNonManagedFiles(claudeDir, templateInventory, manifest, selfHosting) {
+    const nonManagedDirs = ['quick', 'anti-patterns', 'config'];
+    for (const dir of nonManagedDirs) {
+        const dirPath = path.join(claudeDir, dir);
+        if (!fs.existsSync(dirPath))
+            continue;
+        walkDir(dirPath, dir, (relPath, absPath) => {
+            const templateHash = templateInventory.get(relPath);
+            if (!templateHash)
+                return; // Not a template file, skip
+            if (selfHosting) {
+                const symlinkTarget = getSymlinkTarget(claudeDir, relPath);
+                if (symlinkTarget) {
+                    manifest.files[relPath] = templateFileRecord(templateHash, symlinkTarget);
+                    return;
+                }
+            }
+            const fileHash = hashFile(absPath);
+            if (fileHash === templateHash) {
+                manifest.files[relPath] = templateFileRecord(templateHash);
+            }
+            else {
+                manifest.files[relPath] = {
+                    origin: 'template',
+                    status: 'modified',
+                    templateHash,
+                    installedHash: fileHash,
+                };
+            }
+        });
+    }
+    // Top-level template files
+    const topLevel = ['lessons-learned.md'];
+    for (const file of topLevel) {
+        const filePath = path.join(claudeDir, file);
+        const templateHash = templateInventory.get(file);
+        if (!templateHash || !fs.existsSync(filePath))
+            continue;
+        const fileHash = hashFile(filePath);
+        if (fileHash === templateHash) {
+            manifest.files[file] = templateFileRecord(templateHash);
+        }
+        else {
+            manifest.files[file] = {
+                origin: 'template',
+                status: 'modified',
+                templateHash,
+                installedHash: fileHash,
+            };
+        }
+    }
+}
+/** Import pin information from the legacy orbital-sync.json manifest. */
+function importFromSyncManifest(claudeDir, manifest) {
+    const syncManifestPath = path.join(claudeDir, 'orbital-sync.json');
+    if (!fs.existsSync(syncManifestPath))
+        return 0;
+    let imported = 0;
+    try {
+        const raw = fs.readFileSync(syncManifestPath, 'utf-8');
+        const syncManifest = JSON.parse(raw);
+        for (const [relPath, record] of Object.entries(syncManifest.files)) {
+            if (record.mode === 'override' && manifest.files[relPath]) {
+                manifest.files[relPath].status = 'pinned';
+                manifest.files[relPath].pinnedAt = record.overriddenAt || new Date().toISOString();
+                manifest.files[relPath].pinnedReason = record.reason || 'Imported from orbital-sync.json override';
+                imported++;
+            }
+        }
+    }
+    catch {
+        // Malformed sync manifest — skip import
+    }
+    return imported;
+}
+/** Read the preset name from orbital.config.json, defaulting to "default". */
+function readPresetFromConfig(claudeDir) {
+    try {
+        const workflowPath = path.join(claudeDir, 'config', 'workflow.json');
+        if (fs.existsSync(workflowPath)) {
+            const workflow = JSON.parse(fs.readFileSync(workflowPath, 'utf-8'));
+            if (workflow.name)
+                return workflow.name.toLowerCase().replace(/\s+/g, '-');
+        }
+    }
+    catch { /* fall through */ }
+    return 'default';
+}
+/** Read the templateVersion from orbital.config.json. */
+function readTemplateVersion(claudeDir) {
+    try {
+        const configPath = path.join(claudeDir, 'orbital.config.json');
+        if (fs.existsSync(configPath)) {
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+            return config.templateVersion || null;
+        }
+    }
+    catch { /* fall through */ }
+    return null;
+}

package/dist/server/server/parsers/event-parser.js

@@ -32,7 +32,10 @@ export function parseEventFile(filePath) {
         };
     }
     catch (err) {
-        log.warn('Failed to parse event file', { file: filePath, error: err.message });
+        const code = err.code;
+        if (code !== 'ENOENT') {
+            log.warn('Failed to parse event file', { file: filePath, error: err.message });
+        }
         return null;
     }
 }

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

@@ -0,0 +1,117 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { parseEventFile } from './event-parser.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+describe('parseEventFile', () => {
+    let tmpFile;
+    function writeEvent(data) {
+        tmpFile = path.join(os.tmpdir(), `test-event-${Date.now()}-${Math.random().toString(36).slice(2)}.json`);
+        fs.writeFileSync(tmpFile, JSON.stringify(data));
+        return tmpFile;
+    }
+    afterEach(() => {
+        if (tmpFile && fs.existsSync(tmpFile))
+            fs.unlinkSync(tmpFile);
+    });
+    // ─── Full format parsing ─────────────────────────────────
+    describe('full format (top-level fields)', () => {
+        it('extracts all fields correctly', () => {
+            const file = writeEvent({
+                id: 'evt-1', type: 'SCOPE_STATUS_CHANGED', scope_id: 42,
+                session_id: 'sess-abc', agent: 'architect',
+                data: { from: 'backlog', to: 'implementing' },
+                timestamp: '2026-04-08T10:00:00Z',
+            });
+            const result = parseEventFile(file);
+            expect(result).not.toBeNull();
+            expect(result.id).toBe('evt-1');
+            expect(result.type).toBe('SCOPE_STATUS_CHANGED');
+            expect(result.scope_id).toBe(42);
+            expect(result.session_id).toBe('sess-abc');
+            expect(result.agent).toBe('architect');
+            expect(result.data).toEqual({ from: 'backlog', to: 'implementing' });
+        });
+        it('preserves data payload as-is', () => {
+            const file = writeEvent({
+                id: 'evt-2', type: 'CUSTOM', timestamp: '2026-04-08T10:00:00Z',
+                data: { nested: { deep: true }, arr: [1, 2, 3] },
+            });
+            const result = parseEventFile(file);
+            expect(result.data).toEqual({ nested: { deep: true }, arr: [1, 2, 3] });
+        });
+    });
+    // ─── Minimal format parsing ──────────────────────────────
+    describe('minimal format (fields in data)', () => {
+        it('extracts scope_id and session_id from data', () => {
+            const file = writeEvent({
+                id: 'evt-3', type: 'AGENT_STARTED', timestamp: '2026-04-08T10:00:00Z',
+                data: { scope_id: 99, session_id: 'sess-xyz' },
+            });
+            const result = parseEventFile(file);
+            expect(result.scope_id).toBe(99);
+            expect(result.session_id).toBe('sess-xyz');
+        });
+        it('extracts agent from data.agents[0]', () => {
+            const file = writeEvent({
+                id: 'evt-4', type: 'AGENT_COMPLETED', timestamp: '2026-04-08T10:00:00Z',
+                data: { agents: ['attacker', 'chaos'] },
+            });
+            const result = parseEventFile(file);
+            expect(result.agent).toBe('attacker');
+        });
+    });
+    // ─── Field fallback priority ─────────────────────────────
+    describe('field fallback priority', () => {
+        it('top-level scope_id wins over data.scope_id', () => {
+            const file = writeEvent({
+                id: 'evt-5', type: 'TEST', timestamp: 'now',
+                scope_id: 10, data: { scope_id: 20 },
+            });
+            expect(parseEventFile(file).scope_id).toBe(10);
+        });
+        it('top-level agent wins over data.agent', () => {
+            const file = writeEvent({
+                id: 'evt-6', type: 'TEST', timestamp: 'now',
+                agent: 'top', data: { agent: 'nested' },
+            });
+            expect(parseEventFile(file).agent).toBe('top');
+        });
+        it('data.agent wins over data.agents[0]', () => {
+            const file = writeEvent({
+                id: 'evt-7', type: 'TEST', timestamp: 'now',
+                data: { agent: 'single', agents: ['array-first'] },
+            });
+            expect(parseEventFile(file).agent).toBe('single');
+        });
+    });
+    // ─── Edge cases ──────────────────────────────────────────
+    describe('edge cases', () => {
+        it('empty string scope_id falls through to data', () => {
+            const file = writeEvent({
+                id: 'evt-8', type: 'TEST', timestamp: 'now',
+                scope_id: '', data: { scope_id: 42 },
+            });
+            expect(parseEventFile(file).scope_id).toBe(42);
+        });
+        it('null scope_id with no data fallback returns null', () => {
+            const file = writeEvent({
+                id: 'evt-9', type: 'TEST', timestamp: 'now',
+                scope_id: null, data: {},
+            });
+            expect(parseEventFile(file).scope_id).toBeNull();
+        });
+        it('returns null for malformed JSON', () => {
+            tmpFile = path.join(os.tmpdir(), `test-bad-${Date.now()}.json`);
+            fs.writeFileSync(tmpFile, '{ not valid json');
+            expect(parseEventFile(tmpFile)).toBeNull();
+        });
+        it('returns null for missing required fields', () => {
+            const file = writeEvent({ id: 'evt-10' }); // missing type and timestamp
+            expect(parseEventFile(file)).toBeNull();
+        });
+        it('returns null for non-existent file', () => {
+            expect(parseEventFile('/tmp/nonexistent-event-file.json')).toBeNull();
+        });
+    });
+});

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

@@ -45,31 +45,68 @@ export const STATUS_MAP = {
 export function normalizeStatus(raw) {
     return STATUS_MAP[raw] ?? raw;
 }
+/** Generate a stable positive integer hash from a string (for synthetic icebox IDs) */
+function slugHash(s) {
+    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) {
-    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)
+    try {
+        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;
+        // 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;
+        // Try YAML frontmatter first
+        let frontmatter;
+        let markdownBody;
+        try {
+            ({ data: frontmatter, content: markdownBody } = matter(content));
+        }
+        catch (err) {
+            log.warn('Skipping scope with malformed YAML frontmatter', { file: filePath, error: err.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;
     }
-    // Try YAML frontmatter first
-    const { data: frontmatter, content: markdownBody } = matter(content);
-    if (frontmatter && Object.keys(frontmatter).length > 0) {
-        return parseFrontmatterScope(frontmatter, markdownBody, filePath, fileId, dirName);
+    catch (err) {
+        log.warn('Failed to parse scope file', { file: filePath, error: err.message });
+        return null;
     }
-    // Fallback: extract from markdown structure
-    return parseMarkdownScope(content, filePath, fileId, dirName);
 }
 function parseFrontmatterScope(fm, body, filePath, fallbackId, dirName) {
     // Prefer filename-derived ID (includes suffix encoding) over frontmatter
@@ -92,6 +129,7 @@ function parseFrontmatterScope(fm, body, filePath, fallbackId, dirName) {
         raw_content: body.trim(),
         sessions: parseSessions(fm.sessions),
         is_ghost: fm.ghost === true,
+        favourite: fm.favourite === true,
     };
 }
 function parseMarkdownScope(content, filePath, id, dirName) {
@@ -126,6 +164,7 @@ function parseMarkdownScope(content, filePath, id, dirName) {
         raw_content: content,
         sessions: {},
         is_ghost: false,
+        favourite: false,
     };
 }
 /** Map filename suffix (a-d, X) to a thousands-digit offset for unique IDs */
@@ -145,7 +184,7 @@ let validDirStatuses = null;
 export function setValidStatuses(statuses) {
     validDirStatuses = new Set(statuses);
 }
-function inferStatusFromDir(dirName) {
+export function inferStatusFromDir(dirName) {
     if (validDirStatuses) {
         return validDirStatuses.has(dirName) ? dirName : 'planning';
     }
@@ -164,25 +203,32 @@ export function parseAllScopes(scopesDir) {
         const entries = fs.readdirSync(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                scanDir(fullPath);
+            try {
+                if (entry.isDirectory()) {
+                    scanDir(fullPath);
+                }
+                else if (entry.name.endsWith('.md') && !entry.name.startsWith('_')) {
+                    const parsed = parseScopeFile(fullPath);
+                    if (parsed)
+                        scopes.push(parsed);
+                }
             }
-            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.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();
-    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 scopes.sort((a, b) => a.id - b.id);
+        return true;
+    });
+    return deduped.sort((a, b) => a.id - b.id);
 }