orbital-command 0.2.0 → 0.3.0

package/dist/server/server/update-planner.js

@@ -0,0 +1,279 @@
+/**
+ * Update planner — computes a structured diff between the current manifest
+ * and the new template set. Produces an UpdatePlan that can be executed
+ * or printed as a dry-run.
+ */
+import fs from 'fs';
+import path from 'path';
+import { buildTemplateInventory } from './manifest.js';
+// ─── Version Comparison ─────────────────────────────────────
+/** Parse a semver string into [major, minor, patch]. Returns null if invalid. */
+function parseSemver(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return null;
+    return [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])];
+}
+/** Compare two semver strings. Returns -1, 0, or 1. */
+function compareSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb)
+        return 0;
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] < pb[i])
+            return -1;
+        if (pa[i] > pb[i])
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Load and chain rename maps between two versions.
+ * Returns Map<oldPath, newPath> with all renames chained.
+ */
+export function loadRenameMap(templatesDir, fromVersion, toVersion) {
+    const renamesPath = path.join(templatesDir, 'migrations', 'renames.json');
+    if (!fs.existsSync(renamesPath))
+        return new Map();
+    let rawMap;
+    try {
+        rawMap = JSON.parse(fs.readFileSync(renamesPath, 'utf-8'));
+    }
+    catch {
+        return new Map();
+    }
+    // Collect all applicable rename entries, ordered by target version
+    const applicable = [];
+    for (const [range, renames] of Object.entries(rawMap)) {
+        const parts = range.split('->');
+        if (parts.length !== 2)
+            continue;
+        const [from, to] = parts.map(s => s.trim());
+        if (!parseSemver(from) || !parseSemver(to))
+            continue;
+        // Include if: from > fromVersion (hasn't been applied) AND to <= toVersion
+        if (compareSemver(from, fromVersion) <= 0 || compareSemver(to, toVersion) > 0)
+            continue;
+        applicable.push({ to, renames });
+    }
+    // Sort by target version ascending
+    applicable.sort((a, b) => compareSemver(a.to, b.to));
+    // Chain renames: if A→B in v1 and B→C in v2, result is A→C
+    const chained = new Map();
+    for (const { renames } of applicable) {
+        for (const [oldPath, newPath] of Object.entries(renames)) {
+            // Check if oldPath is itself a rename target from a previous version
+            let originalPath = oldPath;
+            for (const [prevOld, prevNew] of chained) {
+                if (prevNew === oldPath) {
+                    originalPath = prevOld;
+                    chained.delete(prevOld);
+                    break;
+                }
+            }
+            chained.set(originalPath, newPath);
+        }
+    }
+    return chained;
+}
+/**
+ * Compute the update plan by diffing manifest against current templates.
+ * Does NOT modify any files — pure computation.
+ */
+export function computeUpdatePlan(options) {
+    const { templatesDir, claudeDir, manifest, newVersion } = options;
+    const renameMap = options.renameMap ??
+        loadRenameMap(templatesDir, manifest.packageVersion, newVersion);
+    const templateInventory = buildTemplateInventory(templatesDir);
+    const toAdd = [];
+    const toUpdate = [];
+    const toRemove = [];
+    const toRename = [];
+    const toSkip = [];
+    // Build reverse rename map: newPath → oldPath
+    const reverseRenames = new Map();
+    for (const [oldPath, newPath] of renameMap) {
+        reverseRenames.set(newPath, oldPath);
+    }
+    // 1. Check each template file against the manifest
+    for (const [templatePath, templateHash] of templateInventory) {
+        // Is this file the target of a rename?
+        const oldPath = reverseRenames.get(templatePath);
+        if (oldPath && manifest.files[oldPath]) {
+            toRename.push({ from: oldPath, to: templatePath });
+            continue;
+        }
+        const record = manifest.files[templatePath];
+        if (!record) {
+            // New file — not in manifest at all
+            toAdd.push(templatePath);
+            continue;
+        }
+        if (record.origin === 'user') {
+            // A user file occupies a path that now conflicts with a template.
+            // Skip it and warn. This is an unusual edge case.
+            toSkip.push({ file: templatePath, reason: 'modified', newTemplateHash: templateHash });
+            continue;
+        }
+        if (record.status === 'pinned') {
+            // Update the template hash in manifest but don't touch the file
+            toSkip.push({ file: templatePath, reason: 'pinned', newTemplateHash: templateHash });
+            continue;
+        }
+        if (record.status === 'modified') {
+            // User modified a template file — skip it
+            toSkip.push({ file: templatePath, reason: 'modified', newTemplateHash: templateHash });
+            continue;
+        }
+        if (record.status === 'outdated') {
+            // File content doesn't match template but user hasn't edited it — safe to update
+            toUpdate.push(templatePath);
+            continue;
+        }
+        // synced file — update only if template changed since last sync
+        if (record.templateHash !== templateHash) {
+            toUpdate.push(templatePath);
+        }
+        // else: already up to date
+    }
+    // 2. Check for files in manifest that are no longer in templates
+    for (const [filePath, record] of Object.entries(manifest.files)) {
+        if (record.origin !== 'template')
+            continue;
+        // Skip if it's in the template inventory (already handled above)
+        if (templateInventory.has(filePath))
+            continue;
+        // Skip if it's the old side of a rename (will be handled in rename step)
+        if (renameMap.has(filePath))
+            continue;
+        toRemove.push(filePath);
+    }
+    // 3. Compute settings hook changes
+    const settingsChanges = computeSettingsChanges(claudeDir, templatesDir);
+    // 4. Check for pending config migrations (placeholder — computed by config-migrator)
+    const pendingMigrations = [];
+    const isEmpty = toAdd.length === 0 &&
+        toUpdate.length === 0 &&
+        toRemove.length === 0 &&
+        toRename.length === 0 &&
+        settingsChanges.hooksToAdd.length === 0 &&
+        settingsChanges.hooksToRemove.length === 0 &&
+        pendingMigrations.length === 0;
+    return {
+        toAdd,
+        toUpdate,
+        toRemove,
+        toRename,
+        toSkip,
+        settingsChanges,
+        pendingMigrations,
+        isEmpty,
+    };
+}
+// ─── Settings Changes ───────────────────────────────────────
+/** Compute which _orbital hooks need to be added or removed from settings.local.json. */
+function computeSettingsChanges(claudeDir, templatesDir) {
+    const settingsPath = path.join(claudeDir, 'settings.local.json');
+    const templatePath = path.join(templatesDir, 'settings-hooks.json');
+    if (!fs.existsSync(templatePath)) {
+        return { hooksToAdd: [], hooksToRemove: [] };
+    }
+    // Extract all hook commands from the template
+    const newCommands = extractHookCommands(templatePath);
+    // Extract all _orbital hook commands from current settings
+    const currentCommands = new Set();
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            if (settings.hooks) {
+                for (const groups of Object.values(settings.hooks)) {
+                    for (const group of groups) {
+                        for (const hook of group.hooks || []) {
+                            if (hook._orbital)
+                                currentCommands.add(hook.command);
+                        }
+                    }
+                }
+            }
+        }
+        catch { /* malformed settings */ }
+    }
+    const hooksToAdd = [...newCommands].filter(c => !currentCommands.has(c));
+    const hooksToRemove = [...currentCommands].filter(c => !newCommands.has(c));
+    return { hooksToAdd, hooksToRemove };
+}
+/** Extract all hook command strings from a settings-hooks.json template. */
+function extractHookCommands(templatePath) {
+    const commands = new Set();
+    try {
+        const template = JSON.parse(fs.readFileSync(templatePath, 'utf-8'));
+        if (template.hooks) {
+            for (const groups of Object.values(template.hooks)) {
+                for (const group of groups) {
+                    for (const hook of group.hooks || []) {
+                        if (hook.command)
+                            commands.add(hook.command);
+                    }
+                }
+            }
+        }
+    }
+    catch { /* malformed template */ }
+    return commands;
+}
+// ─── Plan Formatting ────────────────────────────────────────
+/** Format an update plan as a human-readable string for dry-run output. */
+export function formatPlan(plan, oldVersion, newVersion) {
+    const lines = [];
+    lines.push(`Orbital Command — update plan (dry run)\n`);
+    lines.push(`Package version: ${oldVersion} → ${newVersion}\n`);
+    if (plan.isEmpty) {
+        lines.push('  Everything up to date. No changes needed.\n');
+        return lines.join('\n');
+    }
+    for (const file of plan.toAdd) {
+        lines.push(`  ADD     ${file}`);
+    }
+    for (const file of plan.toUpdate) {
+        lines.push(`  UPDATE  ${file}`);
+    }
+    for (const { from, to } of plan.toRename) {
+        lines.push(`  RENAME  ${from} → ${to}`);
+    }
+    for (const file of plan.toRemove) {
+        lines.push(`  REMOVE  ${file}`);
+    }
+    for (const { file, reason } of plan.toSkip) {
+        lines.push(`  SKIP    ${file} (${reason})`);
+    }
+    if (plan.settingsChanges.hooksToAdd.length > 0 || plan.settingsChanges.hooksToRemove.length > 0) {
+        lines.push('');
+        lines.push(`  SETTINGS  hooks to add: ${plan.settingsChanges.hooksToAdd.length}, to remove: ${plan.settingsChanges.hooksToRemove.length}`);
+    }
+    if (plan.pendingMigrations.length > 0) {
+        lines.push(`  CONFIG    migrations: ${plan.pendingMigrations.length}`);
+    }
+    lines.push('');
+    lines.push('  REGEN   INDEX.md, workflow-manifest.sh');
+    lines.push('');
+    lines.push('No changes made. Run without --dry-run to apply.');
+    return lines.join('\n');
+}
+/**
+ * Get the list of files that need to be backed up before executing a plan.
+ * These are files that will be overwritten or deleted.
+ */
+export function getFilesToBackup(plan) {
+    const files = [];
+    for (const file of plan.toUpdate) {
+        files.push(file);
+    }
+    for (const file of plan.toRemove) {
+        files.push(file);
+    }
+    for (const { from } of plan.toRename) {
+        files.push(from);
+    }
+    return files;
+}

package/dist/server/server/utils/cc-hooks-parser.js

@@ -1,4 +1,6 @@
 import { readFileSync } from 'node:fs';
+import { createLogger } from './logger.js';
+const log = createLogger('config');
 const CC_HOOK_EVENTS = ['SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse'];
 function extractScriptPath(command) {
     // Strip "$CLAUDE_PROJECT_DIR"/ prefix and quotes
@@ -17,6 +19,7 @@ export function parseCcHooks(settingsPath) {
         raw = readFileSync(settingsPath, 'utf-8');
     }
     catch {
+        log.debug('Settings file not found', { path: settingsPath });
         return [];
     }
     const settings = JSON.parse(raw);

package/dist/server/server/utils/cc-hooks-parser.test.js

@@ -0,0 +1,86 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { parseCcHooks } from './cc-hooks-parser.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+describe('parseCcHooks', () => {
+    let tmpFile;
+    function writeSettings(data) {
+        tmpFile = path.join(os.tmpdir(), `test-settings-${Date.now()}.json`);
+        fs.writeFileSync(tmpFile, JSON.stringify(data));
+        return tmpFile;
+    }
+    afterEach(() => {
+        if (tmpFile && fs.existsSync(tmpFile))
+            fs.unlinkSync(tmpFile);
+    });
+    it('parses all 4 event types', () => {
+        const file = writeSettings({
+            hooks: {
+                SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/init.sh', statusMessage: 'Initializing' }] }],
+                SessionEnd: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/end.sh' }] }],
+                PreToolUse: [{ matcher: 'Edit', hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/guard.sh', statusMessage: 'Checking' }] }],
+                PostToolUse: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/log.sh' }] }],
+            },
+        });
+        const hooks = parseCcHooks(file);
+        expect(hooks).toHaveLength(4);
+        expect(hooks.map(h => h.event)).toEqual(['SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse']);
+    });
+    it('extracts script path stripping $CLAUDE_PROJECT_DIR', () => {
+        const file = writeSettings({
+            hooks: {
+                SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/init-session.sh' }] }],
+            },
+        });
+        const hooks = parseCcHooks(file);
+        expect(hooks[0].scriptPath).toBe('.claude/hooks/init-session.sh');
+        expect(hooks[0].scriptName).toBe('init-session.sh');
+    });
+    it('derives ID from script filename', () => {
+        const file = writeSettings({
+            hooks: {
+                SessionStart: [{ hooks: [{ type: 'command', command: '$CLAUDE_PROJECT_DIR/.claude/hooks/init-session.sh' }] }],
+            },
+        });
+        const hooks = parseCcHooks(file);
+        expect(hooks[0].id).toBe('init-session');
+    });
+    it('extracts matcher from group', () => {
+        const file = writeSettings({
+            hooks: {
+                PreToolUse: [{ matcher: 'Edit', hooks: [{ type: 'command', command: 'test.sh' }] }],
+            },
+        });
+        const hooks = parseCcHooks(file);
+        expect(hooks[0].matcher).toBe('Edit');
+    });
+    it('sets matcher to null when absent', () => {
+        const file = writeSettings({
+            hooks: {
+                SessionStart: [{ hooks: [{ type: 'command', command: 'test.sh' }] }],
+            },
+        });
+        const hooks = parseCcHooks(file);
+        expect(hooks[0].matcher).toBeNull();
+    });
+    it('skips non-command entries', () => {
+        const file = writeSettings({
+            hooks: {
+                SessionStart: [{ hooks: [
+                            { type: 'command', command: 'test.sh' },
+                            { type: 'url', command: 'https://example.com' },
+                        ] }],
+            },
+        });
+        const hooks = parseCcHooks(file);
+        expect(hooks).toHaveLength(1);
+    });
+    it('returns empty array for file not found', () => {
+        expect(parseCcHooks('/tmp/nonexistent-settings.json')).toEqual([]);
+    });
+    it('returns empty array when no hooks key in settings', () => {
+        const file = writeSettings({ other: 'config' });
+        expect(parseCcHooks(file)).toEqual([]);
+    });
+});

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,34 +117,31 @@ 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;
+/** Fallback age threshold for dispatches without a linked PID (10 minutes). */
+const 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. */
@@ -146,6 +195,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,10 +226,11 @@ 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. */
+ *  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) {
     const cutoff = new Date(Date.now() - STALE_AGE_MS).toISOString();
     // Single query on events only — split by cache status
@@ -215,6 +266,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 +283,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 +353,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;