orbital-command 0.2.0 → 1.0.0

package/server/migrate-legacy.ts

@@ -0,0 +1,290 @@
+/**
+ * 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';
+import type { OrbitalManifest } from './manifest-types.js';
+import type { OrbitalSyncManifest } from './services/sync-types.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',
+];
+
+// ─── Migration ──────────────────────────────────────────────
+
+export interface LegacyMigrationResult {
+  migrated: boolean;
+  synced: number;
+  modified: number;
+  userOwned: number;
+  importedPins: number;
+}
+
+/**
+ * Detect whether a project needs legacy migration.
+ * Returns true if it has an orbital config but no manifest.
+ */
+export function needsLegacyMigration(projectRoot: string): boolean {
+  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: string,
+  templatesDir: string,
+  packageVersion: string,
+): LegacyMigrationResult {
+  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: string,
+  prefix: string,
+  fn: (relPath: string, absPath: string) => void,
+): void {
+  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: string,
+  templateInventory: Map<string, string>,
+  manifest: OrbitalManifest,
+  selfHosting: boolean,
+): void {
+  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: string,
+  manifest: OrbitalManifest,
+): number {
+  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) as OrbitalSyncManifest;
+
+    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: string): string {
+  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: string): string | null {
+  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/server/parsers/event-parser.test.ts

@@ -0,0 +1,135 @@
+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: string;
+
+  function writeEvent(data: Record<string, unknown>): string {
+    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/server/parsers/event-parser.ts

@@ -46,7 +46,10 @@ export function parseEventFile(filePath: string): RawEvent | null {
       timestamp: String(parsed.timestamp),
     };
   } catch (err) {
-    log.warn('Failed to parse event file', { file: filePath, error: (err as Error).message });
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT') {
+      log.warn('Failed to parse event file', { file: filePath, error: (err as Error).message });
+    }
     return null;
   }
 }