orbital-command 0.2.0 → 0.3.0

package/dist/server/server/validator.js

@@ -0,0 +1,230 @@
+/**
+ * Validation module for the Orbital Command primitive system.
+ *
+ * Checks cross-references between manifest, settings.local.json,
+ * workflow.json, and files on disk. Ensures internal consistency.
+ */
+import fs from 'fs';
+import path from 'path';
+import { loadManifest } from './manifest.js';
+import { validateHookPaths } from './settings-sync.js';
+/**
+ * Run all validation checks on a project. Returns a structured report.
+ */
+export function validate(projectRoot, packageVersion) {
+    const results = [];
+    const claudeDir = path.join(projectRoot, '.claude');
+    // 1. Check manifest exists
+    const manifest = loadManifest(projectRoot);
+    if (!manifest) {
+        results.push({
+            severity: 'warning',
+            message: 'No orbital-manifest.json found — run `orbital update` to create one',
+        });
+        // Can't do further manifest checks without a manifest
+        return buildReport(results);
+    }
+    // 2. Manifest file existence — every template file should exist on disk
+    for (const [relPath, record] of Object.entries(manifest.files)) {
+        const absPath = path.join(claudeDir, relPath);
+        if (!fs.existsSync(absPath)) {
+            results.push({
+                severity: 'error',
+                message: 'Manifest references missing file',
+                file: relPath,
+                detail: `Origin: ${record.origin}, Status: ${record.status}`,
+            });
+        }
+    }
+    // 3. Untracked files — files on disk not in manifest
+    for (const dir of ['hooks', 'skills', 'agents']) {
+        const dirPath = path.join(claudeDir, dir);
+        if (!fs.existsSync(dirPath))
+            continue;
+        walkDir(dirPath, dir, (relPath) => {
+            if (!manifest.files[relPath]) {
+                results.push({
+                    severity: 'warning',
+                    message: 'Untracked file in managed directory',
+                    file: relPath,
+                    detail: 'Not in manifest — may be orphaned or user-created',
+                });
+            }
+        });
+    }
+    // 4. Settings hook file existence
+    const settingsPath = path.join(claudeDir, 'settings.local.json');
+    const brokenHooks = validateHookPaths(settingsPath, projectRoot);
+    for (const command of brokenHooks) {
+        results.push({
+            severity: 'error',
+            message: 'Settings hook references missing file',
+            detail: command,
+        });
+    }
+    // 5. Workflow integrity
+    const workflowPath = path.join(claudeDir, 'config', 'workflow.json');
+    if (fs.existsSync(workflowPath)) {
+        validateWorkflow(workflowPath, claudeDir, results);
+    }
+    // 6. Config schema check (basic — just verify it parses)
+    const configPath = path.join(claudeDir, 'orbital.config.json');
+    if (fs.existsSync(configPath)) {
+        try {
+            JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            results.push({
+                severity: 'error',
+                message: 'orbital.config.json is malformed JSON',
+                file: 'orbital.config.json',
+            });
+        }
+    }
+    else {
+        results.push({
+            severity: 'warning',
+            message: 'orbital.config.json not found',
+        });
+    }
+    // 7. Version consistency
+    if (manifest.packageVersion !== packageVersion) {
+        results.push({
+            severity: 'warning',
+            message: 'Manifest version mismatch — run `orbital update`',
+            detail: `Manifest: ${manifest.packageVersion}, Package: ${packageVersion}`,
+        });
+    }
+    // 8. Generated artifacts exist
+    for (const artifact of manifest.generatedArtifacts) {
+        const artifactPath = path.join(claudeDir, artifact);
+        if (!fs.existsSync(artifactPath)) {
+            results.push({
+                severity: 'warning',
+                message: 'Generated artifact missing',
+                file: artifact,
+                detail: 'Will be regenerated on next update',
+            });
+        }
+    }
+    return buildReport(results);
+}
+/**
+ * Format a validation report for CLI output.
+ */
+export function formatValidationReport(report) {
+    const lines = [];
+    lines.push('Orbital Command — validation report\n');
+    if (report.results.length === 0) {
+        lines.push('  All checks passed.\n');
+        return lines.join('\n');
+    }
+    // Group by severity
+    const grouped = {
+        error: [],
+        warning: [],
+        info: [],
+    };
+    for (const r of report.results) {
+        grouped[r.severity].push(r);
+    }
+    for (const severity of ['error', 'warning', 'info']) {
+        const items = grouped[severity];
+        if (items.length === 0)
+            continue;
+        const label = severity === 'error' ? 'ERRORS' : severity === 'warning' ? 'WARNINGS' : 'INFO';
+        lines.push(`  ${label}:`);
+        for (const item of items) {
+            const file = item.file ? ` [${item.file}]` : '';
+            const detail = item.detail ? ` — ${item.detail}` : '';
+            lines.push(`    ${item.message}${file}${detail}`);
+        }
+        lines.push('');
+    }
+    lines.push(`  Summary: ${report.errors} errors, ${report.warnings} warnings, ${report.info} info`);
+    return lines.join('\n');
+}
+// ─── Internal Helpers ───────────────────────────────────────
+/** Recursively walk a directory, calling fn with relative paths. */
+function walkDir(dirPath, prefix, fn) {
+    if (!fs.existsSync(dirPath))
+        return;
+    for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const absPath = path.join(dirPath, entry.name);
+        const relPath = `${prefix}/${entry.name}`;
+        // Follow symlinks: use stat() to check if target is a directory
+        const stat = fs.statSync(absPath);
+        if (stat.isDirectory()) {
+            walkDir(absPath, relPath, fn);
+        }
+        else {
+            fn(relPath);
+        }
+    }
+}
+/** Validate workflow.json hook targets and edge commands. */
+function validateWorkflow(workflowPath, claudeDir, results) {
+    let workflow;
+    try {
+        workflow = JSON.parse(fs.readFileSync(workflowPath, 'utf-8'));
+    }
+    catch {
+        results.push({
+            severity: 'error',
+            message: 'workflow.json is malformed JSON',
+            file: 'config/workflow.json',
+        });
+        return;
+    }
+    // Check hook targets
+    const hooks = workflow.hooks;
+    if (Array.isArray(hooks)) {
+        for (const hook of hooks) {
+            if (!hook.target)
+                continue;
+            // Resolve hook target relative to project root (targets use .claude/ prefix)
+            const targetPath = path.resolve(path.dirname(claudeDir), hook.target);
+            if (!fs.existsSync(targetPath)) {
+                results.push({
+                    severity: 'error',
+                    message: 'Workflow hook references missing script',
+                    file: 'config/workflow.json',
+                    detail: `Hook "${hook.id || 'unknown'}": ${hook.target}`,
+                });
+            }
+        }
+    }
+    // Check edge commands reference existing skills
+    const edges = workflow.edges;
+    if (Array.isArray(edges)) {
+        for (const edge of edges) {
+            if (!edge.command)
+                continue;
+            // Extract skill name from command like "/skill-name {id}"
+            const match = edge.command.match(/^\/([a-z-]+)/);
+            if (!match)
+                continue;
+            const skillName = match[1];
+            const skillPath = path.join(claudeDir, 'skills', skillName, 'SKILL.md');
+            if (!fs.existsSync(skillPath)) {
+                results.push({
+                    severity: 'warning',
+                    message: 'Workflow edge references unknown skill',
+                    file: 'config/workflow.json',
+                    detail: `Edge "${edge.from}" → "${edge.to}": ${edge.command}`,
+                });
+            }
+        }
+    }
+}
+/** Build a report with counts from a list of results. */
+function buildReport(results) {
+    return {
+        results,
+        errors: results.filter(r => r.severity === 'error').length,
+        warnings: results.filter(r => r.severity === 'warning').length,
+        info: results.filter(r => r.severity === 'info').length,
+    };
+}

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

@@ -0,0 +1,63 @@
+import chokidar from 'chokidar';
+import path from 'path';
+import fs from 'fs';
+import { GLOBAL_PRIMITIVES_DIR } from '../global-config.js';
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('global-watcher');
+/**
+ * Watch ~/.orbital/primitives/ for changes and propagate to synced projects.
+ *
+ * On file change: copies to all synced projects' .claude/ directories.
+ * On file create: copies to projects with auto-sync policy.
+ * On file delete: removes from synced projects, preserves overrides.
+ */
+export function startGlobalWatcher(syncService, io) {
+    if (!fs.existsSync(GLOBAL_PRIMITIVES_DIR)) {
+        log.info('Global primitives directory does not exist, skipping watcher');
+        return null;
+    }
+    const watcher = chokidar.watch(GLOBAL_PRIMITIVES_DIR, {
+        ignored: [/(^|[/\\])\../, /\.tmp$/, /\.sync-tmp$/],
+        persistent: true,
+        ignoreInitial: true,
+        depth: 10,
+        awaitWriteFinish: { stabilityThreshold: 300, pollInterval: 100 },
+    });
+    function relativePath(absPath) {
+        return path.relative(GLOBAL_PRIMITIVES_DIR, absPath);
+    }
+    watcher.on('change', (filePath) => {
+        const rel = relativePath(filePath);
+        log.info('Global primitive changed', { file: rel });
+        const result = syncService.propagateGlobalChange(rel);
+        io.to('all-projects').emit('sync:file:updated', {
+            relativePath: rel,
+            projects: result.updated,
+        });
+    });
+    watcher.on('add', (filePath) => {
+        const rel = relativePath(filePath);
+        log.info('Global primitive added', { file: rel });
+        const result = syncService.handleNewGlobalFile(rel);
+        io.to('all-projects').emit('sync:file:created', {
+            relativePath: rel,
+            autoSynced: result.updated,
+            pending: result.skipped,
+        });
+    });
+    watcher.on('unlink', (filePath) => {
+        const rel = relativePath(filePath);
+        log.info('Global primitive deleted', { file: rel });
+        const result = syncService.handleGlobalFileDeletion(rel);
+        io.to('all-projects').emit('sync:file:deleted', {
+            relativePath: rel,
+            removed: result.removed,
+            preserved: result.preserved,
+        });
+    });
+    watcher.on('error', (err) => {
+        log.error('Global watcher error', { error: String(err) });
+    });
+    log.info('Global primitives watcher started', { dir: GLOBAL_PRIMITIVES_DIR });
+    return watcher;
+}

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

@@ -11,22 +11,37 @@ export function startScopeWatcher(scopesDir, scopeService) {
     });
     watcher
         .on('add', (filePath) => {
-        if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath))
-            return;
-        log.info('Scope added', { file: path.basename(filePath) });
-        scopeService.updateFromFile(filePath);
+        try {
+            if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath))
+                return;
+            log.debug('Scope added', { file: path.basename(filePath) });
+            scopeService.updateFromFile(filePath);
+        }
+        catch (err) {
+            log.error('Scope watcher add failed', { file: path.basename(filePath), error: String(err) });
+        }
     })
         .on('change', (filePath) => {
-        if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath))
-            return;
-        log.debug('Scope changed', { file: path.basename(filePath) });
-        scopeService.updateFromFile(filePath);
+        try {
+            if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath))
+                return;
+            log.debug('Scope changed', { file: path.basename(filePath) });
+            scopeService.updateFromFile(filePath);
+        }
+        catch (err) {
+            log.error('Scope watcher change failed', { file: path.basename(filePath), error: String(err) });
+        }
     })
         .on('unlink', (filePath) => {
-        if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath))
-            return;
-        log.info('Scope removed', { file: path.basename(filePath) });
-        scopeService.removeByFilePath(filePath);
+        try {
+            if (!filePath.endsWith('.md') || scopeService.isSuppressed(filePath))
+                return;
+            log.info('Scope removed', { file: path.basename(filePath) });
+            scopeService.removeByFilePath(filePath);
+        }
+        catch (err) {
+            log.error('Scope watcher unlink failed', { file: path.basename(filePath), error: String(err) });
+        }
     })
         .on('error', (err) => log.error('Scope watcher error', { error: String(err) }));
     return watcher;

package/dist/server/server/wizard/config-editor.js

@@ -0,0 +1,237 @@
+/**
+ * Interactive config editor — `orbital config`
+ */
+import fs from 'fs';
+import path from 'path';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { WORKFLOW_PRESETS } from './types.js';
+export async function runConfigEditor(projectRoot, packageVersion, args) {
+    const subcommand = args[0];
+    // Non-interactive: orbital config show
+    if (subcommand === 'show') {
+        const config = loadProjectConfig(projectRoot);
+        if (!config) {
+            console.error('No config found. Run `orbital init` first.');
+            process.exit(1);
+        }
+        console.log(JSON.stringify(config, null, 2));
+        return;
+    }
+    // Non-interactive: orbital config set <key> <value>
+    if (subcommand === 'set') {
+        const key = args[1];
+        const value = args[2];
+        if (!key || value === undefined) {
+            console.error('Usage: orbital config set <key> <value>');
+            process.exit(1);
+        }
+        setConfigValue(projectRoot, key, value);
+        return;
+    }
+    // Interactive mode
+    const config = loadProjectConfig(projectRoot);
+    if (!config) {
+        p.log.error('No config found. Run `orbital init` first.');
+        process.exit(1);
+    }
+    p.intro(`${pc.bgCyan(pc.black(' Orbital Config '))} ${pc.dim(`v${packageVersion}`)}`);
+    // If a section was specified, jump directly to it
+    if (subcommand === 'project') {
+        await editProjectSection(projectRoot, config);
+    }
+    else if (subcommand === 'workflow') {
+        await editWorkflowSection(projectRoot);
+    }
+    else if (subcommand === 'global') {
+        await editGlobalSection();
+    }
+    else {
+        // Show interactive menu
+        const section = await p.select({
+            message: 'What would you like to configure?',
+            options: [
+                { value: 'project', label: 'Project', hint: 'name, ports, build commands' },
+                { value: 'workflow', label: 'Workflow', hint: 'switch preset, view lists' },
+                { value: 'global', label: 'Global', hint: 'registered projects' },
+            ],
+        });
+        if (p.isCancel(section)) {
+            p.cancel('Config cancelled.');
+            return;
+        }
+        if (section === 'project')
+            await editProjectSection(projectRoot, config);
+        else if (section === 'workflow')
+            await editWorkflowSection(projectRoot);
+        else if (section === 'global')
+            await editGlobalSection();
+    }
+    p.outro('Configuration updated.');
+}
+// ─── Section Editors ────────────────────────────────────────────
+async function editProjectSection(projectRoot, config) {
+    const name = await p.text({
+        message: 'Project name',
+        defaultValue: config.projectName || '',
+        placeholder: config.projectName || '',
+    });
+    if (p.isCancel(name))
+        return;
+    const serverPort = await p.text({
+        message: 'Server port',
+        defaultValue: String(config.serverPort || 4444),
+        placeholder: String(config.serverPort || 4444),
+        validate: (val) => {
+            const n = Number(val);
+            if (isNaN(n) || n < 1 || n > 65535)
+                return 'Must be a valid port (1-65535)';
+            return undefined;
+        },
+    });
+    if (p.isCancel(serverPort))
+        return;
+    const clientPort = await p.text({
+        message: 'Client port',
+        defaultValue: String(config.clientPort || 4445),
+        placeholder: String(config.clientPort || 4445),
+        validate: (val) => {
+            const n = Number(val);
+            if (isNaN(n) || n < 1 || n > 65535)
+                return 'Must be a valid port (1-65535)';
+            return undefined;
+        },
+    });
+    if (p.isCancel(clientPort))
+        return;
+    config.projectName = name;
+    config.serverPort = Number(serverPort);
+    config.clientPort = Number(clientPort);
+    saveProjectConfig(projectRoot, config);
+    p.log.success('Project config saved.');
+}
+async function editWorkflowSection(projectRoot) {
+    const workflowPath = path.join(projectRoot, '.claude', 'config', 'workflow.json');
+    let currentPreset = 'unknown';
+    if (fs.existsSync(workflowPath)) {
+        try {
+            const wf = JSON.parse(fs.readFileSync(workflowPath, 'utf8'));
+            currentPreset = wf.name || 'Custom';
+            const lists = (wf.lists || []).map((l) => l.label).join(' → ');
+            p.note(`Current: ${pc.cyan(currentPreset)}\nLists:   ${lists}`, 'Active Workflow');
+        }
+        catch { /* show selector anyway */ }
+    }
+    const switchPreset = await p.confirm({
+        message: 'Switch to a different preset?',
+        initialValue: false,
+    });
+    if (p.isCancel(switchPreset) || !switchPreset)
+        return;
+    const preset = await p.select({
+        message: 'Choose a workflow preset',
+        options: WORKFLOW_PRESETS.map(wp => ({
+            value: wp.value,
+            label: wp.label,
+            hint: wp.hint,
+        })),
+    });
+    if (p.isCancel(preset))
+        return;
+    // Find and copy the preset
+    // Walk up to find templates dir
+    const templatesDir = findTemplatesDir();
+    if (!templatesDir) {
+        p.log.error('Could not locate templates directory.');
+        return;
+    }
+    const presetPath = path.join(templatesDir, 'presets', `${preset}.json`);
+    if (fs.existsSync(presetPath)) {
+        fs.copyFileSync(presetPath, workflowPath);
+        p.log.success(`Switched to ${preset} workflow.`);
+    }
+    else {
+        p.log.error(`Preset file not found: ${preset}.json`);
+    }
+}
+async function editGlobalSection() {
+    const homedir = process.env.HOME || process.env.USERPROFILE || '~';
+    const registryPath = path.join(homedir, '.orbital', 'config.json');
+    if (!fs.existsSync(registryPath)) {
+        p.log.info('No global registry found. Run `orbital init` in a project first.');
+        return;
+    }
+    try {
+        const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+        const projects = registry.projects || [];
+        if (projects.length === 0) {
+            p.log.info('No projects registered.');
+            return;
+        }
+        const rows = projects.map((proj) => {
+            const exists = fs.existsSync(proj.path);
+            const status = proj.enabled ? (exists ? pc.green('active') : pc.yellow('offline')) : pc.dim('disabled');
+            return `  ${pc.cyan(String(proj.id).padEnd(20))} ${status.padEnd(20)} ${proj.path}`;
+        });
+        p.note(rows.join('\n'), `Registered Projects (${projects.length})`);
+    }
+    catch {
+        p.log.error('Could not read global registry.');
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────
+function loadProjectConfig(projectRoot) {
+    const configPath = path.join(projectRoot, '.claude', 'orbital.config.json');
+    if (!fs.existsSync(configPath))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveProjectConfig(projectRoot, config) {
+    const configPath = path.join(projectRoot, '.claude', 'orbital.config.json');
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+function setConfigValue(projectRoot, key, value) {
+    const config = loadProjectConfig(projectRoot);
+    if (!config) {
+        console.error('No config found. Run `orbital init` first.');
+        process.exit(1);
+    }
+    // Parse value: try number, then boolean, then string
+    let parsed = value;
+    if (value === 'true')
+        parsed = true;
+    else if (value === 'false')
+        parsed = false;
+    else if (value === 'null')
+        parsed = null;
+    else if (!isNaN(Number(value)) && value !== '')
+        parsed = Number(value);
+    // Support dot notation for nested keys
+    const keys = key.split('.');
+    let target = config;
+    for (let i = 0; i < keys.length - 1; i++) {
+        if (typeof target[keys[i]] !== 'object' || target[keys[i]] === null) {
+            target[keys[i]] = {};
+        }
+        target = target[keys[i]];
+    }
+    target[keys[keys.length - 1]] = parsed;
+    saveProjectConfig(projectRoot, config);
+    console.log(`Set ${key} = ${JSON.stringify(parsed)}`);
+}
+function findTemplatesDir() {
+    // Walk up from this file to find templates/
+    let dir = path.dirname(new URL(import.meta.url).pathname);
+    for (let i = 0; i < 5; i++) {
+        const candidate = path.join(dir, 'templates');
+        if (fs.existsSync(candidate))
+            return candidate;
+        dir = path.resolve(dir, '..');
+    }
+    return null;
+}

package/dist/server/server/wizard/detect.js

@@ -0,0 +1,96 @@
+/**
+ * Environment and state detection for the wizard.
+ */
+import fs from 'fs';
+import path from 'path';
+const ORBITAL_HOME = path.join(process.env.HOME || process.env.USERPROFILE || '~', '.orbital');
+export { ORBITAL_HOME };
+export function isInteractiveTerminal() {
+    return !!(process.stdout.isTTY && !process.env.CI);
+}
+export function isOrbitalSetupDone() {
+    return fs.existsSync(path.join(ORBITAL_HOME, 'config.json'));
+}
+export function buildSetupState(packageVersion) {
+    return {
+        packageVersion,
+        isFirstTime: !isOrbitalSetupDone(),
+        linkedProjects: [],
+    };
+}
+export function buildProjectState(projectRoot, packageVersion) {
+    const projectConfigExists = fs.existsSync(path.join(projectRoot, '.claude', 'orbital.config.json'));
+    return {
+        projectRoot,
+        isProjectInitialized: projectConfigExists,
+        packageVersion,
+    };
+}
+export function detectProjectName(projectRoot) {
+    return path.basename(projectRoot)
+        .replace(/[-_]+/g, ' ')
+        .replace(/\b\w/g, c => c.toUpperCase());
+}
+export function detectCommands(projectRoot) {
+    const commands = {
+        typeCheck: null,
+        lint: null,
+        build: null,
+        test: null,
+    };
+    const pkgJsonPath = path.join(projectRoot, 'package.json');
+    if (!fs.existsSync(pkgJsonPath))
+        return commands;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+        const scripts = pkg.scripts || {};
+        if (scripts.typecheck || scripts['type-check']) {
+            commands.typeCheck = `npm run ${scripts.typecheck ? 'typecheck' : 'type-check'}`;
+        }
+        if (scripts.lint)
+            commands.lint = 'npm run lint';
+        if (scripts.build)
+            commands.build = 'npm run build';
+        if (scripts.test)
+            commands.test = 'npm run test';
+    }
+    catch { /* ignore malformed package.json */ }
+    return commands;
+}
+export function detectPortConflict(serverPort) {
+    const registryPath = path.join(ORBITAL_HOME, 'config.json');
+    if (!fs.existsSync(registryPath))
+        return null;
+    try {
+        const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+        for (const project of registry.projects || []) {
+            const configPath = path.join(project.path, '.claude', 'orbital.config.json');
+            if (!fs.existsSync(configPath))
+                continue;
+            try {
+                const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+                if (config.serverPort === serverPort)
+                    return project.name;
+            }
+            catch { /* skip unreadable configs */ }
+        }
+    }
+    catch { /* skip unreadable registry */ }
+    return null;
+}
+export function isValidProjectPath(p) {
+    const resolved = p.startsWith('~')
+        ? path.join(process.env.HOME || process.env.USERPROFILE || '~', p.slice(1))
+        : path.resolve(p);
+    if (!fs.existsSync(resolved))
+        return 'Directory does not exist';
+    if (!fs.statSync(resolved).isDirectory())
+        return 'Not a directory';
+    return undefined;
+}
+export function resolveProjectPath(p) {
+    if (p.startsWith('~')) {
+        return path.join(process.env.HOME || process.env.USERPROFILE || '~', p.slice(1));
+    }
+    return path.resolve(p);
+}