orbital-command 0.3.0 → 1.0.1

package/server/uninstall.ts

@@ -0,0 +1,214 @@
+/**
+ * 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';
+
+// ─── Uninstall ──────────────────────────────────────────────
+
+export interface UninstallOptions {
+  dryRun?: boolean;
+  keepConfig?: boolean;
+}
+
+export function runUninstall(projectRoot: string, options: UninstallOptions = {}): void {
+  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: string[] = [];
+  const toPreserve: string[] = [];
+
+  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: string): void {
+  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: string, entries: string[]): void {
+  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/server/update.ts

@@ -0,0 +1,263 @@
+/**
+ * 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';
+
+// ─── Update ─────────────────────────────────────────────────
+
+export interface UpdateOptions {
+  dryRun?: boolean;
+  force?: boolean;
+}
+
+export function runUpdate(projectRoot: string, options: UpdateOptions = {}): void {
+  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: string, destPath: string): void {
+  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/server/utils/dispatch-utils.ts

@@ -208,13 +208,13 @@ export function resolveDispatchesByDispatchId(
   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: Database.Database, scopeService: ScopeService, engine: WorkflowEngine): number[] {
+export function getActiveScopeIds(db: Database.Database, scopeService: ScopeService, engine: WorkflowEngine, staleTimeoutMinutes?: number): number[] {
   const rows = db.prepare(
     `SELECT scope_id, data FROM events
      WHERE type = 'DISPATCH'
@@ -222,7 +222,8 @@ export function getActiveScopeIds(db: Database.Database, scopeService: ScopeServ
        AND JSON_EXTRACT(data, '$.resolved') IS NULL`,
   ).all() as Array<{ scope_id: number; data: string }>;
 
-  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<number>();
 
   for (const row of rows) {
@@ -310,8 +311,9 @@ export function getActiveScopeIds(db: Database.Database, scopeService: ScopeServ
  *  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: Database.Database, io: Emitter, scopeService: ScopeService, engine: WorkflowEngine): number {
-  const cutoff = new Date(Date.now() - STALE_AGE_MS).toISOString();
+export function resolveStaleDispatches(db: Database.Database, io: Emitter, scopeService: ScopeService, engine: WorkflowEngine, staleTimeoutMinutes?: number): number {
+  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(

package/server/utils/flag-builder.ts

@@ -0,0 +1,56 @@
+import type { DispatchFlags } from '../../shared/api-types.js';
+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: DispatchFlags): string {
+  const parts: string[] = [];
+
+  // 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: Record<string, string>): string {
+  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/server/utils/json-fields.test.ts

@@ -0,0 +1,83 @@
+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/server/utils/json-fields.ts

@@ -0,0 +1,14 @@
+const JSON_FIELDS = ['tags', 'blocked_by', 'blocks', 'data', 'discoveries', 'next_steps', 'details'];
+
+export type Row = Record<string, unknown>;
+
+/** Parse stringified JSON fields in a database row back to objects. */
+export function parseJsonFields(row: Row): Row {
+  const parsed = { ...row };
+  for (const field of JSON_FIELDS) {
+    if (typeof parsed[field] === 'string') {
+      try { parsed[field] = JSON.parse(parsed[field] as string); } catch { /* keep string */ }
+    }
+  }
+  return parsed;
+}