orbital-command 0.3.0 → 1.0.0

package/dist/server/server/uninstall.js

@@ -0,0 +1,195 @@
+/**
+ * Uninstall logic — extracted from init.ts for focused maintainability.
+ */
+import fs from 'fs';
+import path from 'path';
+import { loadManifest } from './manifest.js';
+import { removeAllOrbitalHooks } from './settings-sync.js';
+import { unregisterProject } from './global-config.js';
+import { TEMPLATES_DIR, cleanEmptyDirs, listTemplateFiles, } from './init.js';
+export function runUninstall(projectRoot, options = {}) {
+    const { dryRun = false, keepConfig = false } = options;
+    const claudeDir = path.join(projectRoot, '.claude');
+    console.log(`\nOrbital Command — uninstall${dryRun ? ' (dry run)' : ''}`);
+    console.log(`Project root: ${projectRoot}\n`);
+    const manifest = loadManifest(projectRoot);
+    // Fall back to legacy uninstall if no manifest
+    if (!manifest) {
+        console.log('  No manifest found — falling back to legacy uninstall.');
+        runLegacyUninstall(projectRoot);
+        return;
+    }
+    // Compute what to remove vs preserve
+    const toRemove = [];
+    const toPreserve = [];
+    for (const [filePath, record] of Object.entries(manifest.files)) {
+        if (record.origin === 'user') {
+            toPreserve.push(filePath);
+        }
+        else if (record.status === 'modified' || record.status === 'outdated') {
+            toPreserve.push(filePath);
+        }
+        else {
+            toRemove.push(filePath);
+        }
+    }
+    if (dryRun) {
+        console.log('  Files to REMOVE:');
+        for (const f of toRemove)
+            console.log(`    ${f}`);
+        if (toPreserve.length > 0) {
+            console.log('  Files to PRESERVE:');
+            for (const f of toPreserve)
+                console.log(`    ${f} (${manifest.files[f].origin}/${manifest.files[f].status})`);
+        }
+        console.log(`\n  Would also remove: settings hooks, generated artifacts, config files, gitignore entries`);
+        console.log(`  No changes made. Run without --dry-run to apply.`);
+        return;
+    }
+    // 1. Remove _orbital hooks from settings.local.json
+    const settingsPath = path.join(claudeDir, 'settings.local.json');
+    const removedHooks = removeAllOrbitalHooks(settingsPath);
+    console.log(`  Removed  ${removedHooks} orbital hook registrations`);
+    // 2. Delete template files (synced + pinned, not modified or user-owned)
+    let filesRemoved = 0;
+    for (const filePath of toRemove) {
+        const absPath = path.join(claudeDir, filePath);
+        if (fs.existsSync(absPath)) {
+            fs.unlinkSync(absPath);
+            filesRemoved++;
+        }
+    }
+    console.log(`  Removed  ${filesRemoved} template files`);
+    if (toPreserve.length > 0) {
+        console.log(`  Preserved ${toPreserve.length} user/modified files`);
+    }
+    // 3. Clean up empty directories
+    for (const dir of ['hooks', 'skills', 'agents', 'config/workflows', 'quick', 'anti-patterns']) {
+        const dirPath = path.join(claudeDir, dir);
+        if (fs.existsSync(dirPath))
+            cleanEmptyDirs(dirPath);
+    }
+    // 4. Remove generated artifacts
+    for (const artifact of manifest.generatedArtifacts) {
+        const artifactPath = path.join(claudeDir, artifact);
+        if (fs.existsSync(artifactPath)) {
+            fs.unlinkSync(artifactPath);
+            console.log(`  Removed  .claude/${artifact}`);
+        }
+    }
+    // 5. Remove template-sourced config files
+    const configFiles = [
+        'config/agent-triggers.json',
+        'config/workflow.json',
+        'lessons-learned.md',
+    ];
+    for (const file of configFiles) {
+        const filePath = path.join(claudeDir, file);
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+            console.log(`  Removed  .claude/${file}`);
+        }
+    }
+    // Remove config/workflows/ directory entirely
+    const workflowsDir = path.join(claudeDir, 'config', 'workflows');
+    if (fs.existsSync(workflowsDir)) {
+        fs.rmSync(workflowsDir, { recursive: true, force: true });
+        console.log(`  Removed  .claude/config/workflows/`);
+    }
+    // 6. Remove gitignore entries
+    removeGitignoreEntries(projectRoot, manifest.gitignoreEntries);
+    console.log(`  Cleaned  .gitignore`);
+    // 7. Deregister from global registry
+    if (unregisterProject(projectRoot)) {
+        console.log(`  Removed  project from ~/.orbital/config.json`);
+    }
+    // 8. Remove orbital config and manifest (unless --keep-config)
+    if (!keepConfig) {
+        const toClean = ['orbital.config.json', 'orbital-manifest.json', 'orbital-sync.json'];
+        for (const file of toClean) {
+            const filePath = path.join(claudeDir, file);
+            if (fs.existsSync(filePath))
+                fs.unlinkSync(filePath);
+        }
+        // Remove backups directory
+        const backupsDir = path.join(claudeDir, '.orbital-backups');
+        if (fs.existsSync(backupsDir))
+            fs.rmSync(backupsDir, { recursive: true, force: true });
+        console.log(`  Removed  orbital config and manifest`);
+    }
+    else {
+        // Still remove the manifest — it's invalid after uninstall
+        const manifestPath = path.join(claudeDir, 'orbital-manifest.json');
+        if (fs.existsSync(manifestPath))
+            fs.unlinkSync(manifestPath);
+        console.log(`  Kept     orbital.config.json (--keep-config)`);
+    }
+    // Clean up remaining empty directories
+    for (const dir of ['config', 'quick', 'anti-patterns', 'review-verdicts']) {
+        const dirPath = path.join(claudeDir, dir);
+        if (fs.existsSync(dirPath))
+            cleanEmptyDirs(dirPath);
+    }
+    const total = removedHooks + filesRemoved;
+    console.log(`\nUninstall complete. ${total} items removed.`);
+    if (toPreserve.length > 0) {
+        console.log(`Note: ${toPreserve.length} user/modified files were preserved.`);
+    }
+    console.log(`Note: scopes/ and .claude/orbital-events/ were preserved.\n`);
+}
+// ─── Helpers ────────────────────────────────────────────────
+/** Legacy uninstall for projects without a manifest (backward compat). */
+function runLegacyUninstall(projectRoot) {
+    const claudeDir = path.join(projectRoot, '.claude');
+    // Remove orbital hooks from settings.local.json
+    const settingsPath = path.join(claudeDir, 'settings.local.json');
+    const removedHooks = removeAllOrbitalHooks(settingsPath);
+    console.log(`  Removed  ${removedHooks} orbital hook registrations`);
+    // Delete hooks/skills/agents that match template files
+    for (const dir of ['hooks', 'skills', 'agents']) {
+        const templateDir = listTemplateFiles(path.join(TEMPLATES_DIR, dir), path.join(claudeDir, dir));
+        let removed = 0;
+        for (const f of templateDir) {
+            if (fs.existsSync(f)) {
+                fs.unlinkSync(f);
+                removed++;
+            }
+        }
+        const dirPath = path.join(claudeDir, dir);
+        if (fs.existsSync(dirPath))
+            cleanEmptyDirs(dirPath);
+        console.log(`  Removed  ${removed} ${dir} files`);
+    }
+    console.log(`\nLegacy uninstall complete.`);
+    console.log(`Note: scopes/ and .claude/orbital-events/ were preserved.\n`);
+}
+/** Remove Orbital-added entries from .gitignore. */
+function removeGitignoreEntries(projectRoot, entries) {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    if (!fs.existsSync(gitignorePath))
+        return;
+    let content = fs.readFileSync(gitignorePath, 'utf-8');
+    const marker = '# Orbital Command';
+    const markerIdx = content.indexOf(marker);
+    if (markerIdx !== -1) {
+        const before = content.slice(0, markerIdx).replace(/\n+$/, '');
+        const after = content.slice(markerIdx);
+        const lines = after.split('\n');
+        let endIdx = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].trim();
+            if (i === 0) {
+                endIdx = i + 1;
+                continue;
+            }
+            if (line === '' || entries.includes(line)) {
+                endIdx = i + 1;
+                continue;
+            }
+            break;
+        }
+        const remaining = lines.slice(endIdx).join('\n');
+        content = before + (remaining ? '\n' + remaining : '') + '\n';
+        fs.writeFileSync(gitignorePath, content, 'utf-8');
+    }
+}

package/dist/server/server/update.js

@@ -0,0 +1,212 @@
+/**
+ * Template update logic — extracted from init.ts for focused maintainability.
+ */
+import fs from 'fs';
+import path from 'path';
+import { loadManifest, saveManifest, buildTemplateInventory, refreshFileStatuses, templateFileRecord, safeBackupFile, safeCopyTemplate, reverseRemapPath, } from './manifest.js';
+import { needsLegacyMigration, migrateFromLegacy } from './migrate-legacy.js';
+import { computeUpdatePlan, loadRenameMap, formatPlan, getFilesToBackup } from './update-planner.js';
+import { syncSettingsHooks, getTemplateChecksum } from './settings-sync.js';
+import { migrateConfig } from './config-migrator.js';
+import { validate, formatValidationReport } from './validator.js';
+import { createBackup } from './manifest.js';
+import { TEMPLATES_DIR, ensureDir, cleanEmptyDirs, chmodScripts, writeManifest, generateIndexMd, seedGlobalPrimitives, getPackageVersion, } from './init.js';
+export function runUpdate(projectRoot, options = {}) {
+    const { dryRun = false } = options;
+    const claudeDir = path.join(projectRoot, '.claude');
+    const newVersion = getPackageVersion();
+    console.log(`\nOrbital Command — update${dryRun ? ' (dry run)' : ''}`);
+    console.log(`Project root: ${projectRoot}\n`);
+    // 1. Load or create manifest (auto-migrate legacy installs)
+    let manifest = loadManifest(projectRoot);
+    if (!manifest) {
+        if (needsLegacyMigration(projectRoot)) {
+            console.log('  Migrating from legacy install...');
+            const result = migrateFromLegacy(projectRoot, TEMPLATES_DIR, newVersion);
+            console.log(`  Migrated ${result.synced} synced, ${result.modified} modified, ${result.userOwned} user-owned files`);
+            if (result.importedPins > 0)
+                console.log(`  Imported ${result.importedPins} pinned files from orbital-sync.json`);
+            manifest = loadManifest(projectRoot);
+        }
+        if (!manifest) {
+            console.log('  No manifest found. Run `orbital` first.');
+            return;
+        }
+    }
+    const oldVersion = manifest.packageVersion;
+    // 1b. Refresh file statuses so outdated vs modified is accurate
+    refreshFileStatuses(manifest, claudeDir);
+    // 2. Compute update plan
+    const renameMap = loadRenameMap(TEMPLATES_DIR, oldVersion, newVersion);
+    const plan = computeUpdatePlan({
+        templatesDir: TEMPLATES_DIR,
+        claudeDir,
+        manifest,
+        newVersion,
+        renameMap,
+    });
+    // 3. Dry-run mode — print plan and exit
+    if (dryRun) {
+        console.log(formatPlan(plan, oldVersion, newVersion));
+        return;
+    }
+    if (plan.isEmpty && oldVersion === newVersion) {
+        console.log('  Everything up to date. No changes needed.');
+    }
+    // 4. Create backup of files that will be modified
+    const filesToBackup = getFilesToBackup(plan);
+    if (filesToBackup.length > 0) {
+        const backupDir = createBackup(claudeDir, filesToBackup);
+        if (backupDir) {
+            console.log(`  Backup   ${filesToBackup.length} files → ${path.relative(claudeDir, backupDir)}/`);
+        }
+    }
+    // 5. Execute plan
+    const templateInventory = buildTemplateInventory(TEMPLATES_DIR);
+    // 5a. Handle renames
+    for (const { from, to } of plan.toRename) {
+        const fromPath = path.join(claudeDir, from);
+        const toPath = path.join(claudeDir, to);
+        const toDir = path.dirname(toPath);
+        if (!fs.existsSync(toDir))
+            fs.mkdirSync(toDir, { recursive: true });
+        if (fs.existsSync(fromPath)) {
+            safeBackupFile(fromPath);
+            const stat = fs.lstatSync(fromPath);
+            if (stat.isSymbolicLink()) {
+                const target = fs.readlinkSync(fromPath);
+                fs.unlinkSync(fromPath);
+                fs.symlinkSync(target, toPath);
+            }
+            else {
+                fs.renameSync(fromPath, toPath);
+            }
+        }
+        const record = manifest.files[from];
+        if (record) {
+            delete manifest.files[from];
+            const newHash = templateInventory.get(to);
+            manifest.files[to] = { ...record, templateHash: newHash, installedHash: newHash || record.installedHash };
+        }
+        console.log(`  RENAME  ${from} → ${to}`);
+    }
+    // 5b. Add new files
+    for (const filePath of plan.toAdd) {
+        const templateHash = templateInventory.get(filePath);
+        if (!templateHash)
+            continue;
+        const destPath = path.join(claudeDir, filePath);
+        const destDir = path.dirname(destPath);
+        if (!fs.existsSync(destDir))
+            fs.mkdirSync(destDir, { recursive: true });
+        copyTemplateFile(filePath, destPath);
+        manifest.files[filePath] = templateFileRecord(templateHash);
+        console.log(`  ADD     ${filePath}`);
+    }
+    // 5c. Update changed synced/outdated files
+    for (const filePath of plan.toUpdate) {
+        const templateHash = templateInventory.get(filePath);
+        if (!templateHash)
+            continue;
+        const destPath = path.join(claudeDir, filePath);
+        safeBackupFile(destPath);
+        copyTemplateFile(filePath, destPath);
+        manifest.files[filePath] = templateFileRecord(templateHash);
+        console.log(`  UPDATE  ${filePath}`);
+    }
+    // 5d. Remove deleted files
+    for (const filePath of plan.toRemove) {
+        const absPath = path.join(claudeDir, filePath);
+        if (fs.existsSync(absPath)) {
+            safeBackupFile(absPath);
+            fs.unlinkSync(absPath);
+        }
+        delete manifest.files[filePath];
+        console.log(`  REMOVE  ${filePath}`);
+    }
+    // 5e. Update pinned/modified file records (record new template hash without touching file)
+    for (const { file, reason, newTemplateHash } of plan.toSkip) {
+        if (manifest.files[file]) {
+            manifest.files[file].templateHash = newTemplateHash;
+        }
+        if (reason === 'modified') {
+            console.log(`  SKIP    ${file} (user modified)`);
+        }
+        else {
+            console.log(`  SKIP    ${file} (pinned)`);
+        }
+    }
+    // 5f. Clean up empty directories
+    for (const dir of ['hooks', 'skills', 'agents', 'config/workflows']) {
+        const dirPath = path.join(claudeDir, dir);
+        if (fs.existsSync(dirPath))
+            cleanEmptyDirs(dirPath);
+    }
+    // 6. Bidirectional settings hook sync
+    const settingsTarget = path.join(claudeDir, 'settings.local.json');
+    const settingsSrc = path.join(TEMPLATES_DIR, 'settings-hooks.json');
+    const syncResult = syncSettingsHooks(settingsTarget, settingsSrc, manifest.settingsHooksChecksum, renameMap);
+    if (!syncResult.skipped) {
+        console.log(`  Settings +${syncResult.added} -${syncResult.removed} hooks (${syncResult.updated} renamed)`);
+        manifest.settingsHooksChecksum = getTemplateChecksum(settingsSrc);
+    }
+    // 7. Config migrations
+    const configPath = path.join(claudeDir, 'orbital.config.json');
+    const migrationResult = migrateConfig(configPath, manifest.appliedMigrations);
+    if (migrationResult.applied.length > 0) {
+        manifest.appliedMigrations.push(...migrationResult.applied);
+        console.log(`  Config   ${migrationResult.applied.length} migration(s) applied`);
+    }
+    if (migrationResult.defaultsFilled.length > 0) {
+        console.log(`  Config   ${migrationResult.defaultsFilled.length} default(s) filled`);
+    }
+    // 8. Regenerate derived artifacts (always)
+    const workflowManifestOk = writeManifest(claudeDir);
+    console.log(`  ${workflowManifestOk ? 'Updated' : 'Skipped'}  .claude/config/workflow-manifest.sh`);
+    const indexContent = generateIndexMd(projectRoot, claudeDir);
+    fs.writeFileSync(path.join(claudeDir, 'INDEX.md'), indexContent, 'utf8');
+    console.log(`  Updated  .claude/INDEX.md`);
+    // 9. Update agent-triggers.json (template-managed)
+    const triggersSrc = path.join(TEMPLATES_DIR, 'config', 'agent-triggers.json');
+    const triggersDest = path.join(claudeDir, 'config', 'agent-triggers.json');
+    if (fs.existsSync(triggersSrc)) {
+        fs.copyFileSync(triggersSrc, triggersDest);
+        console.log(`  Updated  .claude/config/agent-triggers.json`);
+    }
+    // 10. Update scope template
+    const scopeTemplateSrc = path.join(TEMPLATES_DIR, 'scopes', '_template.md');
+    const scopeTemplateDest = path.join(projectRoot, 'scopes', '_template.md');
+    if (fs.existsSync(scopeTemplateSrc)) {
+        ensureDir(path.join(projectRoot, 'scopes'));
+        fs.copyFileSync(scopeTemplateSrc, scopeTemplateDest);
+    }
+    // 11. Make hook scripts executable
+    chmodScripts(path.join(claudeDir, 'hooks'));
+    // 12. Refresh global primitives
+    seedGlobalPrimitives();
+    // 13. Update manifest metadata
+    manifest.previousPackageVersion = oldVersion;
+    manifest.packageVersion = newVersion;
+    manifest.updatedAt = new Date().toISOString();
+    saveManifest(projectRoot, manifest);
+    // 14. Validate
+    const report = validate(projectRoot, newVersion);
+    if (report.errors > 0) {
+        console.log(`\n  Validation: ${report.errors} errors found`);
+        console.log(formatValidationReport(report));
+    }
+    const totalChanges = plan.toAdd.length + plan.toUpdate.length + plan.toRemove.length + plan.toRename.length;
+    console.log(`\nUpdate complete. ${totalChanges} file changes, ${plan.toSkip.length} skipped.\n`);
+}
+// ─── Helpers ────────────────────────────────────────────────
+function copyTemplateFile(claudeRelPath, destPath) {
+    const templateRelPath = reverseRemapPath(claudeRelPath);
+    const srcPath = path.join(TEMPLATES_DIR, templateRelPath);
+    if (!fs.existsSync(srcPath)) {
+        throw new Error(`Template file not found: ${templateRelPath}`);
+    }
+    const destDir = path.dirname(destPath);
+    if (!fs.existsSync(destDir))
+        fs.mkdirSync(destDir, { recursive: true });
+    safeCopyTemplate(srcPath, destPath);
+}

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

@@ -140,17 +140,18 @@ export function resolveDispatchesByDispatchId(db, io, dispatchId, outcome = 'aba
     resolveDispatchEvent(db, io, row.id, outcome);
     return [row.id];
 }
-/** Fallback age threshold for dispatches without a linked PID (10 minutes). */
-const STALE_AGE_MS = 10 * 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))
@@ -231,8 +232,9 @@ export function getActiveScopeIds(db, scopeService, engine) {
  *  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();
+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'

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/route-helpers.js

@@ -8,3 +8,40 @@ 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 });
+        }
+    });
+}