orbital-command 0.1.0

package/dist/server/server/utils/terminal-launcher.js

@@ -0,0 +1,388 @@
+import { promisify } from 'util';
+import { createHash } from 'crypto';
+import { execFile as execFileCb } from 'child_process';
+import fsSync from 'fs';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { getConfig } from '../config.js';
+import { createLogger } from './logger.js';
+const log = createLogger('terminal');
+const execFileAsync = promisify(execFileCb);
+// ─── iTerm2 Dynamic Profiles ────────────────────────────────
+const DYNAMIC_PROFILES_DIR = path.join(os.homedir(), 'Library', 'Application Support', 'iTerm2', 'DynamicProfiles');
+/** Convert a hex color (#rrggbb) to iTerm2's color dictionary format. */
+function hexToItermColor(hex) {
+    const r = parseInt(hex.slice(1, 3), 16) / 255;
+    const g = parseInt(hex.slice(3, 5), 16) / 255;
+    const b = parseInt(hex.slice(5, 7), 16) / 255;
+    return { 'Red Component': r, 'Green Component': g, 'Blue Component': b, 'Alpha Component': 1, 'Color Space': 'sRGB' };
+}
+/** Derive a stable, hex-only UUID from a prefix + category string. */
+function deriveGuid(prefix, category) {
+    const hash = createHash('md5').update(`${prefix}-${category}`).digest('hex');
+    return [
+        hash.slice(0, 8),
+        hash.slice(8, 12),
+        '4' + hash.slice(13, 16),
+        '8' + hash.slice(17, 20),
+        hash.slice(20, 32),
+    ].join('-').toUpperCase();
+}
+/** Maps each window category to candidate workflow column IDs (first match wins). */
+const CATEGORY_COLUMN_CANDIDATES = [
+    { category: 'Scoping', columnIds: ['planning', 'backlog'] },
+    { category: 'Planning', columnIds: ['backlog', 'planning'] },
+    { category: 'Implementing', columnIds: ['implementing', 'in-progress'] },
+    { category: 'Reviewing', columnIds: ['review'] },
+    { category: 'Deploying', columnIds: ['production', 'main', 'dev', 'completed', 'done'] },
+];
+const FALLBACK_HEX = '#6B7280'; // neutral gray if no column match
+function profilesFilename(prefix) {
+    return `${prefix.toLowerCase()}-dispatch-profiles.json`;
+}
+function buildProfiles(colorMap) {
+    const prefix = getConfig().terminal.profilePrefix;
+    return {
+        Profiles: CATEGORY_COLUMN_CANDIDATES.map(({ category }) => ({
+            Name: `${prefix}-${category}`,
+            Guid: deriveGuid(prefix, category),
+            'Dynamic Profile Parent Name': 'Default',
+            'Custom Window Title': category,
+            'Use Custom Window Title': true,
+            'Allow Title Setting': false,
+            'Title Components': 1, // 1 = Session Name (not Job Name)
+            'Badge Text': category,
+            'Tab Color': hexToItermColor(colorMap.get(category) ?? FALLBACK_HEX),
+            'Use Tab Color': true,
+        })),
+    };
+}
+/** Resolve tab colors from the active workflow's column hex values. */
+function resolveColorMap(engine) {
+    const colors = new Map();
+    for (const { category, columnIds } of CATEGORY_COLUMN_CANDIDATES) {
+        for (const colId of columnIds) {
+            const list = engine.getList(colId);
+            if (list) {
+                colors.set(category, list.hex);
+                break;
+            }
+        }
+    }
+    return colors;
+}
+/** Write iTerm2 Dynamic Profiles for each workflow category.
+ *  Derives tab colors from the active workflow's column definitions.
+ *  Idempotent — safe to call on every server startup. */
+export async function ensureDynamicProfiles(engine) {
+    try {
+        await fs.mkdir(DYNAMIC_PROFILES_DIR, { recursive: true });
+        const prefix = getConfig().terminal.profilePrefix;
+        const filePath = path.join(DYNAMIC_PROFILES_DIR, profilesFilename(prefix));
+        const colorMap = resolveColorMap(engine);
+        // Write tmp file outside DynamicProfiles/ — iTerm2 watches that dir and reads ALL files
+        const tmpPath = path.join(os.tmpdir(), profilesFilename(prefix) + '.tmp');
+        await fs.writeFile(tmpPath, JSON.stringify(buildProfiles(colorMap), null, 2));
+        await fs.copyFile(tmpPath, filePath);
+        await fs.unlink(tmpPath).catch(() => { });
+    }
+    catch (err) {
+        log.warn('Failed to write iTerm2 dynamic profiles', { error: err.message });
+    }
+}
+/** Maps a WindowCategory to its iTerm2 profile name. */
+function profileNameForCategory(category) {
+    return `${getConfig().terminal.profilePrefix}-${category}`;
+}
+/** Ordered array — maps command prefixes to window categories */
+const COMMAND_WINDOW_MAP = [
+    ['/scope-post-review', 'Reviewing'],
+    ['/scope-pre-review', 'Planning'],
+    ['/scope-verify', 'Reviewing'],
+    ['/scope-create', 'Planning'],
+    ['/scope-implement', 'Implementing'],
+    ['/git-commit', 'Deploying'],
+    ['/git-staging', 'Deploying'],
+    ['/git-production', 'Deploying'],
+    ['/git-main', 'Deploying'],
+];
+export function commandToWindowCategory(command) {
+    for (const [prefix, category] of COMMAND_WINDOW_MAP) {
+        if (command.startsWith(prefix))
+            return category;
+    }
+    return null;
+}
+/** In-memory registry: category → iTerm2 window ID (stable integer). Resets on server restart. */
+const windowRegistry = new Map();
+/**
+ * Escape a string for use inside $'...' ANSI-C quoting.
+ * Handles backslash, single-quote, and newline characters.
+ */
+export function escapeForAnsiC(text) {
+    return text
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t')
+        .replace(/\0/g, '\\0')
+        .replace(/\x07/g, '\\a')
+        .replace(/\x08/g, '\\b')
+        .replace(/\x0C/g, '\\f')
+        .replace(/\x1B/g, '\\e')
+        .replace(/\x0B/g, '\\v');
+}
+/**
+ * Launch a command in a new iTerm2 window.
+ *
+ * Opens a window with the user's default profile (which sources their shell
+ * profile, so PATH includes `claude`), then sends the command via `write text`.
+ * This is more reliable than `command "..."` which replaces the shell process
+ * and can't interpret builtins like `cd` or operators like `&&`.
+ */
+export async function launchInTerminal(command) {
+    const escaped = command.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    await execFileAsync('osascript', [
+        '-e', 'tell application "iTerm2"',
+        '-e', '  create window with default profile',
+        '-e', '  delay 0.5',
+        '-e', '  tell current session of current window',
+        '-e', `    write text "${escaped}"`,
+        '-e', '  end tell',
+        '-e', 'end tell',
+    ]);
+}
+/**
+ * Create a new iTerm2 window, run a command, and return the window ID.
+ * The window ID is a stable integer that persists for the window's lifetime.
+ * Tab name is set via AppleScript session `name` (immune to app title changes).
+ * Window title is locked via Dynamic Profile (`Allow Title Setting: false`).
+ */
+async function createWindowWithCommand(command, category, tabName) {
+    const escaped = command.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const tabLabel = (tabName ?? category).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const profile = profileNameForCategory(category);
+    try {
+        const { stdout } = await execFileAsync('osascript', [
+            '-e', 'tell application "iTerm2"',
+            '-e', `  create window with profile "${profile}"`,
+            '-e', '  delay 0.5',
+            '-e', '  set newWindow to current window',
+            '-e', '  tell current session of newWindow',
+            '-e', `    set name to "${tabLabel}"`,
+            '-e', `    write text "${escaped}"`,
+            '-e', '  end tell',
+            '-e', '  return id of newWindow',
+            '-e', 'end tell',
+        ]);
+        return parseInt(stdout.trim(), 10);
+    }
+    catch {
+        // Profile missing — fall back to default profile
+        const { stdout } = await execFileAsync('osascript', [
+            '-e', 'tell application "iTerm2"',
+            '-e', '  create window with default profile',
+            '-e', '  delay 0.5',
+            '-e', '  set newWindow to current window',
+            '-e', '  tell current session of newWindow',
+            '-e', `    set name to "${tabLabel}"`,
+            '-e', `    write text "${escaped}"`,
+            '-e', '  end tell',
+            '-e', '  return id of newWindow',
+            '-e', 'end tell',
+        ]);
+        return parseInt(stdout.trim(), 10);
+    }
+}
+/**
+ * Create a new tab in an existing iTerm2 window (identified by ID) and run a command.
+ * Returns false if the window no longer exists (user closed it).
+ */
+async function createTabInWindow(windowId, command, category, tabName) {
+    const escaped = command.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const profile = profileNameForCategory(category);
+    const nameLines = tabName
+        ? ['-e', `      set name to "${tabName.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`]
+        : [];
+    try {
+        await execFileAsync('osascript', [
+            '-e', 'tell application "iTerm2"',
+            '-e', `  set targetWindow to window id ${windowId}`,
+            '-e', '  tell targetWindow',
+            '-e', `    set newTab to (create tab with profile "${profile}")`,
+            '-e', '    tell current session of newTab',
+            ...nameLines,
+            '-e', `      write text "${escaped}"`,
+            '-e', '    end tell',
+            '-e', '  end tell',
+            '-e', 'end tell',
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Route a dispatch to a categorized iTerm2 window.
+ * Groups commands by workflow stage (Scoping, Planning, Implementing, Reviewing, Deploying)
+ * so multiple dispatches of the same type open as tabs in one window.
+ *
+ * Falls back to launchInTerminal() for unmapped commands.
+ */
+export async function launchInCategorizedTerminal(command, fullCmd, tabName) {
+    const category = commandToWindowCategory(command);
+    if (!category) {
+        await launchInTerminal(fullCmd);
+        return;
+    }
+    // Try reusing an existing window for this category
+    const existingId = windowRegistry.get(category);
+    if (existingId !== undefined) {
+        const added = await createTabInWindow(existingId, fullCmd, category, tabName ?? undefined);
+        if (added)
+            return;
+        // Window was closed — clear stale entry and fall through to create new
+        windowRegistry.delete(category);
+    }
+    // Create a new categorized window
+    const newId = await createWindowWithCommand(fullCmd, category, tabName ?? undefined);
+    windowRegistry.set(category, newId);
+}
+// ─── Session Naming ──────────────────────────────────────────
+const COMMAND_STEP_MAP = {
+    '/scope-implement': 'Implementation',
+    '/scope-post-review': 'Post-Review',
+    '/scope-pre-review': 'Pre-Review',
+    '/scope-verify': 'Verify',
+    '/scope-create': 'Creation',
+    '/git-commit': 'Commit',
+    '/git-dev': 'Merge-Dev',
+    '/git-staging': 'PR-Staging',
+    '/git-production': 'PR-Production',
+    '/git-main': 'Push-Main',
+};
+/** Title-Case slug: "Hook & Event Foundation" → "Hook-Event-Foundation" */
+function slugifySessionName(title, maxLen = 40) {
+    return title
+        .replace(/[^a-zA-Z0-9\s]/g, '') // strip non-alphanumeric
+        .trim()
+        .split(/\s+/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join('-')
+        .slice(0, maxLen);
+}
+/** Maps command prefix to step label */
+function commandToStep(command) {
+    for (const [prefix, step] of Object.entries(COMMAND_STEP_MAP)) {
+        if (command.startsWith(prefix))
+            return step;
+    }
+    return 'Session';
+}
+/** Builds "079-Hook-Event-Foundation-Implementation" from parts */
+export function buildSessionName(parts) {
+    const step = commandToStep(parts.command);
+    if (parts.scopeId == null) {
+        // No scope context — return step-only name for known commands, null for unknown
+        return step !== 'Session' ? step : null;
+    }
+    const paddedId = String(parts.scopeId).padStart(3, '0');
+    if (!parts.title)
+        return `${paddedId}-${step}`;
+    const slug = slugifySessionName(parts.title);
+    return `${paddedId}-${slug}-${step}`;
+}
+/**
+ * Derive the sessions-index.json path for a project.
+ * Claude Code encodes the project path by replacing `/` with `-`.
+ * The leading `/` naturally becomes the leading `-` in the directory name.
+ */
+function getSessionsIndexPath(projectRoot) {
+    const encoded = projectRoot.replace(/\//g, '-');
+    return path.join(os.homedir(), '.claude', 'projects', encoded, 'sessions-index.json');
+}
+/** Rename a session in sessions-index.json by UUID.
+ *  Updates existing entry or adds a new one if not found. */
+export async function renameSession(projectRoot, sessionId, name) {
+    const indexPath = getSessionsIndexPath(projectRoot);
+    try {
+        const raw = await fs.readFile(indexPath, 'utf-8');
+        const index = JSON.parse(raw);
+        const existing = index.entries.find((e) => e.sessionId === sessionId);
+        if (existing) {
+            existing.summary = name;
+        }
+        else {
+            // Entry not in index — add it so the name shows up in the Claude UI
+            index.entries.push({ sessionId, fileMtime: Date.now(), summary: name });
+        }
+        const tmpPath = indexPath + '.tmp';
+        await fs.writeFile(tmpPath, JSON.stringify(index, null, 2));
+        await fs.rename(tmpPath, indexPath);
+    }
+    catch {
+        // Index file not readable — skip silently
+    }
+}
+// ─── PID-based Session Discovery ─────────────────────────────
+/** Directory where init-session.sh stores PID→UUID mapping files */
+function getSessionPidDir(projectRoot) {
+    return path.join(projectRoot, '.claude', 'metrics', '.session-ids');
+}
+/** Snapshot current PID files before launching a new session */
+export function snapshotSessionPids(projectRoot) {
+    const dir = getSessionPidDir(projectRoot);
+    try {
+        return new Set(fsSync.readdirSync(dir).map((f) => f.split('-')[0]));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Poll for a new PID file that wasn't in the pre-launch snapshot.
+ *  Returns the PID and session UUID, or null if no new session appeared. */
+export async function discoverNewSession(projectRoot, beforePidSet) {
+    const dir = getSessionPidDir(projectRoot);
+    const pollInterval = 500;
+    const maxWait = 15_000;
+    const deadline = Date.now() + maxWait;
+    while (Date.now() < deadline) {
+        try {
+            const current = fsSync.readdirSync(dir);
+            for (const entry of current) {
+                const pidStr = entry.split('-')[0];
+                if (/^\d+$/.test(pidStr) && !beforePidSet.has(pidStr)) {
+                    const pid = parseInt(pidStr, 10);
+                    // Verify the PID is alive (not a stale leftover)
+                    try {
+                        process.kill(pid, 0);
+                        const sessionId = fsSync.readFileSync(path.join(dir, entry), 'utf-8').trim();
+                        return { pid, sessionId };
+                    }
+                    catch {
+                        // Dead PID or unreadable file, skip
+                    }
+                }
+            }
+        }
+        catch {
+            // Directory not readable — retry
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    return null;
+}
+/** Check if a session PID is still running.
+ *  process.kill(pid, 0) sends no signal but checks existence. */
+export function isSessionPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/server/server/utils/worktree-manager.js

@@ -0,0 +1,98 @@
+import { execFile as execFileCb } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs/promises';
+import path from 'path';
+const execFile = promisify(execFileCb);
+export async function createWorktree(projectRoot, scopeId) {
+    const wtPath = path.join(projectRoot, '.worktrees', `scope-${scopeId}`);
+    const branch = `feat/scope-${scopeId}`;
+    await execFile('git', ['worktree', 'add', wtPath, '-b', branch], { cwd: projectRoot });
+    // Ensure scopes/ and .claude/ are in .gitignore (for user projects)
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    try {
+        const content = await fs.readFile(gitignorePath, 'utf-8');
+        const lines = content.split('\n');
+        const toAdd = [];
+        if (!lines.some((l) => l.trim() === 'scopes/'))
+            toAdd.push('scopes/');
+        if (!lines.some((l) => l.trim() === '.claude/'))
+            toAdd.push('.claude/');
+        if (toAdd.length > 0) {
+            await fs.appendFile(gitignorePath, '\n' + toAdd.join('\n') + '\n');
+        }
+    }
+    catch {
+        // .gitignore doesn't exist — create it
+        await fs.writeFile(gitignorePath, 'scopes/\n.claude/\n');
+    }
+    // Remove real scopes/ and .claude/ from worktree (git checkout creates them if tracked)
+    const scopesWt = path.join(wtPath, 'scopes');
+    const claudeWt = path.join(wtPath, '.claude');
+    try {
+        await fs.rm(scopesWt, { recursive: true, force: true });
+    }
+    catch { /* ok */ }
+    try {
+        await fs.rm(claudeWt, { recursive: true, force: true });
+    }
+    catch { /* ok */ }
+    // Create symlinks
+    await fs.symlink(path.join(projectRoot, 'scopes'), scopesWt);
+    await fs.symlink(path.join(projectRoot, '.claude'), claudeWt);
+    return { path: wtPath, branch, scopeId };
+}
+export async function removeWorktree(projectRoot, scopeId) {
+    const wtPath = path.join(projectRoot, '.worktrees', `scope-${scopeId}`);
+    const branch = `feat/scope-${scopeId}`;
+    try {
+        await execFile('git', ['worktree', 'remove', wtPath, '--force'], { cwd: projectRoot });
+    }
+    catch { /* worktree may already be gone */ }
+    try {
+        await execFile('git', ['branch', '-d', branch], { cwd: projectRoot });
+    }
+    catch { /* branch may not exist or not be merged */ }
+}
+export async function listWorktrees(projectRoot) {
+    const { stdout } = await execFile('git', ['worktree', 'list', '--porcelain'], { cwd: projectRoot });
+    const results = [];
+    let currentPath = '';
+    let currentBranch = '';
+    for (const line of stdout.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            currentPath = line.slice(9);
+        }
+        else if (line.startsWith('branch ')) {
+            currentBranch = line.slice(7);
+        }
+        else if (line === '' && currentPath) {
+            const match = currentPath.match(/scope-(\d+)$/);
+            if (match) {
+                results.push({ path: currentPath, branch: currentBranch, scopeId: parseInt(match[1]) });
+            }
+            currentPath = '';
+            currentBranch = '';
+        }
+    }
+    if (currentPath) {
+        const match = currentPath.match(/scope-(\d+)$/);
+        if (match) {
+            results.push({ path: currentPath, branch: currentBranch, scopeId: parseInt(match[1]) });
+        }
+    }
+    return results;
+}
+export async function cleanupStaleWorktrees(projectRoot) {
+    const worktrees = await listWorktrees(projectRoot);
+    let cleaned = 0;
+    for (const wt of worktrees) {
+        try {
+            await fs.access(wt.path);
+        }
+        catch {
+            await removeWorktree(projectRoot, wt.scopeId);
+            cleaned++;
+        }
+    }
+    return cleaned;
+}

package/dist/server/server/watchers/event-watcher.js

@@ -0,0 +1,81 @@
+import chokidar from 'chokidar';
+import path from 'path';
+import fs from 'fs';
+import { parseEventFile } from '../parsers/event-parser.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('event');
+const ARCHIVE_DIR_NAME = 'processed';
+/**
+ * Watch .claude/orbital-events/ for new JSON event files.
+ * On startup, processes any existing unprocessed events.
+ * After processing, moves files to a /processed subdirectory.
+ */
+export function startEventWatcher(eventsDir, eventService) {
+    // Ensure directories exist
+    fs.mkdirSync(eventsDir, { recursive: true });
+    const archiveDir = path.join(eventsDir, ARCHIVE_DIR_NAME);
+    fs.mkdirSync(archiveDir, { recursive: true });
+    // Process existing unprocessed events on startup
+    processExistingEvents(eventsDir, eventService, archiveDir);
+    // Watch for new events
+    // NOTE: The events dir is inside .claude/ (dotfile directory).
+    // chokidar uses picomatch internally which skips dotfiles by default.
+    // We must watch the directory directly and filter in the handler.
+    const watcher = chokidar.watch(eventsDir, {
+        ignored: [new RegExp(ARCHIVE_DIR_NAME)],
+        persistent: true,
+        ignoreInitial: true,
+        depth: 0,
+    });
+    watcher.on('error', (err) => log.error('Event watcher error', { error: String(err) }));
+    watcher.on('add', (filePath) => {
+        if (!filePath.endsWith('.json'))
+            return;
+        // Small delay to ensure file write is complete
+        setTimeout(() => {
+            processEventFile(filePath, eventService, archiveDir);
+        }, 100);
+    });
+    return watcher;
+}
+function processExistingEvents(eventsDir, eventService, archiveDir) {
+    try {
+        const files = fs.readdirSync(eventsDir).filter((f) => f.endsWith('.json'));
+        if (files.length === 0)
+            return;
+        log.info('Processing queued events', { count: files.length });
+        // Sort by filename (UUID-based, so roughly chronological)
+        files.sort();
+        for (const file of files) {
+            const filePath = path.join(eventsDir, file);
+            processEventFile(filePath, eventService, archiveDir);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'ENOENT') {
+            log.error('Event watcher startup error', { error: err.message });
+        }
+    }
+}
+function processEventFile(filePath, eventService, archiveDir) {
+    const event = parseEventFile(filePath);
+    if (!event)
+        return;
+    eventService.ingest(event);
+    // Move to archive
+    const fileName = path.basename(filePath);
+    try {
+        fs.renameSync(filePath, path.join(archiveDir, fileName));
+    }
+    catch (err) {
+        log.warn('Failed to archive event file', { file: filePath, error: err.message });
+        // If rename fails (cross-device), just delete the source
+        try {
+            fs.unlinkSync(filePath);
+        }
+        catch (unlinkErr) {
+            log.warn('Failed to delete event file', { file: filePath, error: unlinkErr.message });
+        }
+    }
+}

package/dist/server/server/watchers/scope-watcher.js

@@ -0,0 +1,33 @@
+import chokidar from 'chokidar';
+import path from 'path';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('scope');
+export function startScopeWatcher(scopesDir, scopeService) {
+    const watcher = chokidar.watch(scopesDir, {
+        ignored: [/(^|[/\\])\../, /node_modules/, /_template\.md$/],
+        persistent: true,
+        ignoreInitial: true,
+        depth: 2, // scopes/completed/*.md
+    });
+    watcher
+        .on('add', (filePath) => {
+        if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath))
+            return;
+        log.info('Scope added', { file: path.basename(filePath) });
+        scopeService.updateFromFile(filePath);
+    })
+        .on('change', (filePath) => {
+        if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath))
+            return;
+        log.debug('Scope changed', { file: path.basename(filePath) });
+        scopeService.updateFromFile(filePath);
+    })
+        .on('unlink', (filePath) => {
+        if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath))
+            return;
+        log.info('Scope removed', { file: path.basename(filePath) });
+        scopeService.removeByFilePath(filePath);
+    })
+        .on('error', (err) => log.error('Scope watcher error', { error: String(err) }));
+    return watcher;
+}

package/dist/server/shared/api-types.js

@@ -0,0 +1,5 @@
+// ─── Shared API Types ────────────────────────────────────────
+//
+// Types shared between server and client. Single source of truth for
+// enums/unions that were previously duplicated across layers.
+export {};