orbital-command 0.3.0 → 1.0.0

package/server/utils/route-helpers.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { errMsg, isValidRelativePath, inferErrorStatus, catchRoute } from './route-helpers.js';
+
+// ─── errMsg ─────────────────────────────────────────────────
+
+describe('errMsg', () => {
+  it('extracts message from Error instances', () => {
+    expect(errMsg(new Error('something broke'))).toBe('something broke');
+  });
+
+  it('converts non-Error values to strings', () => {
+    expect(errMsg('raw string')).toBe('raw string');
+    expect(errMsg(42)).toBe('42');
+    expect(errMsg(null)).toBe('null');
+    expect(errMsg(undefined)).toBe('undefined');
+  });
+});
+
+// ─── isValidRelativePath ────────────────────────────────────
+
+describe('isValidRelativePath', () => {
+  it('accepts normal relative paths', () => {
+    expect(isValidRelativePath('hooks/init.sh')).toBe(true);
+    expect(isValidRelativePath('agents/attacker/AGENT.md')).toBe(true);
+    expect(isValidRelativePath('file.txt')).toBe(true);
+  });
+
+  it('rejects directory traversal', () => {
+    expect(isValidRelativePath('../etc/passwd')).toBe(false);
+    expect(isValidRelativePath('hooks/../../secret')).toBe(false);
+  });
+
+  it('rejects absolute paths', () => {
+    expect(isValidRelativePath('/etc/passwd')).toBe(false);
+  });
+
+  it('rejects null bytes', () => {
+    expect(isValidRelativePath('file\0.txt')).toBe(false);
+  });
+});
+
+// ─── inferErrorStatus ───────────────────────────────────────
+
+describe('inferErrorStatus', () => {
+  it('returns 403 for traversal errors', () => {
+    expect(inferErrorStatus('Path traversal detected')).toBe(403);
+    expect(inferErrorStatus('directory traversal not allowed')).toBe(403);
+  });
+
+  it('returns 404 for not-found errors', () => {
+    expect(inferErrorStatus('File not found')).toBe(404);
+    expect(inferErrorStatus('ENOENT: no such file')).toBe(404);
+  });
+
+  it('returns 409 for already-exists errors', () => {
+    expect(inferErrorStatus('File already exists at path')).toBe(409);
+  });
+
+  it('returns 400 for directory errors', () => {
+    expect(inferErrorStatus('Cannot delete directory')).toBe(400);
+  });
+
+  it('returns 500 for unrecognized errors', () => {
+    expect(inferErrorStatus('something unexpected')).toBe(500);
+    expect(inferErrorStatus('')).toBe(500);
+  });
+
+  it('matches the first keyword when multiple are present', () => {
+    // "traversal" comes first in the chain, should win
+    expect(inferErrorStatus('traversal not found')).toBe(403);
+  });
+});
+
+// ─── catchRoute ─────────────────────────────────────────────
+
+describe('catchRoute', () => {
+  function createApp(handler: express.RequestHandler) {
+    const app = express();
+    app.get('/test', handler);
+    return app;
+  }
+
+  it('returns normal response when handler succeeds', async () => {
+    const app = createApp(catchRoute((_req, res) => {
+      res.json({ ok: true });
+    }));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ ok: true });
+  });
+
+  it('catches sync throws and returns 500', async () => {
+    const app = createApp(catchRoute(() => {
+      throw new Error('sync failure');
+    }));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(500);
+    expect(res.body).toEqual({ success: false, error: 'sync failure' });
+  });
+
+  it('catches async throws and returns 500', async () => {
+    const app = createApp(catchRoute(async () => {
+      throw new Error('async failure');
+    }));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(500);
+    expect(res.body).toEqual({ success: false, error: 'async failure' });
+  });
+
+  it('uses custom statusFn for error status codes', async () => {
+    const app = createApp(catchRoute(() => {
+      throw new Error('File not found at path');
+    }, inferErrorStatus));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(404);
+    expect(res.body).toEqual({ success: false, error: 'File not found at path' });
+  });
+
+  it('uses custom statusFn for traversal errors', async () => {
+    const app = createApp(catchRoute(() => {
+      throw new Error('Path traversal detected');
+    }, inferErrorStatus));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(403);
+  });
+
+  it('handles non-Error thrown values', async () => {
+    const app = createApp(catchRoute(() => {
+      // eslint-disable-next-line no-throw-literal
+      throw 'raw string error';
+    }));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(500);
+    expect(res.body).toEqual({ success: false, error: 'raw string error' });
+  });
+});

package/server/utils/route-helpers.ts

@@ -1,4 +1,5 @@
 import path from 'path';
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
 
 /** Extract a human-readable message from an unknown error value. */
 export function errMsg(err: unknown): string {
@@ -10,3 +11,40 @@ export function isValidRelativePath(p: string): boolean {
   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: string): number {
+  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<Req extends Request = any, Res extends Response = any>(
+  fn: (req: Req, res: Res, next: NextFunction) => void | Promise<void>,
+  statusFn?: (msg: string) => number,
+): RequestHandler {
+  return ((req: Req, res: Res, next: NextFunction) => {
+    try {
+      const result = fn(req, res, next);
+      if (result instanceof Promise) {
+        result.catch((err: unknown) => {
+          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 });
+    }
+  }) as unknown as RequestHandler;
+}

package/server/watchers/event-watcher.ts

@@ -8,6 +8,7 @@ import { createLogger } from '../utils/logger.js';
 const log = createLogger('event');
 
 const ARCHIVE_DIR_NAME = 'processed';
+const processingFiles = new Set<string>();
 
 /**
  * Watch .claude/orbital-events/ for new JSON event files.
@@ -81,20 +82,31 @@ function processEventFile(
   eventService: EventService,
   archiveDir: string
 ): void {
-  const event = parseEventFile(filePath);
-  if (!event) return;
+  if (processingFiles.has(filePath)) return;
+  processingFiles.add(filePath);
+  try {
+    const event = parseEventFile(filePath);
+    if (!event) return;
 
-  eventService.ingest(event);
+    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 as Error).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 as Error).message });
+    // Move to archive
+    const fileName = path.basename(filePath);
+    try {
+      fs.renameSync(filePath, path.join(archiveDir, fileName));
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOENT') return; // Already archived by concurrent handler
+      log.warn('Failed to archive event file', { file: filePath, error: (err as Error).message });
+      // If rename fails (cross-device), just delete the source
+      try { fs.unlinkSync(filePath); } catch (unlinkErr) {
+        const unlinkCode = (unlinkErr as NodeJS.ErrnoException).code;
+        if (unlinkCode !== 'ENOENT') {
+          log.warn('Failed to delete event file', { file: filePath, error: (unlinkErr as Error).message });
+        }
+      }
     }
+  } finally {
+    processingFiles.delete(filePath);
   }
 }

package/server/wizard/config-editor.ts

@@ -15,7 +15,7 @@ export async function runConfigEditor(projectRoot: string, packageVersion: strin
   if (subcommand === 'show') {
     const config = loadProjectConfig(projectRoot);
     if (!config) {
-      console.error('No config found. Run `orbital init` first.');
+      console.error('No config found. Run `orbital` first.');
       process.exit(1);
     }
     console.log(JSON.stringify(config, null, 2));
@@ -37,7 +37,7 @@ export async function runConfigEditor(projectRoot: string, packageVersion: strin
   // Interactive mode
   const config = loadProjectConfig(projectRoot);
   if (!config) {
-    p.log.error('No config found. Run `orbital init` first.');
+    p.log.error('No config found. Run `orbital` first.');
     process.exit(1);
   }
 
@@ -166,7 +166,7 @@ async function editGlobalSection(): Promise<void> {
   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.');
+    p.log.info('No global registry found. Run `orbital` in a project first.');
     return;
   }
 
@@ -210,7 +210,7 @@ function saveProjectConfig(projectRoot: string, config: Record<string, unknown>)
 function setConfigValue(projectRoot: string, key: string, value: string): void {
   const config = loadProjectConfig(projectRoot);
   if (!config) {
-    console.error('No config found. Run `orbital init` first.');
+    console.error('No config found. Run `orbital` first.');
     process.exit(1);
   }
 

package/server/wizard/doctor.ts

@@ -49,7 +49,7 @@ export async function runDoctor(projectRoot: string, packageVersion: string): Pr
       checks.push({ label: 'Global', status: pc.yellow('~/.orbital/ exists (registry unreadable)') });
     }
   } else {
-    checks.push({ label: 'Global', status: pc.dim('~/.orbital/ not found (run `orbital init` to create)') });
+    checks.push({ label: 'Global', status: pc.dim('~/.orbital/ not found (run `orbital` to create)') });
   }
 
   // 4. Project initialization
@@ -63,7 +63,7 @@ export async function runDoctor(projectRoot: string, packageVersion: string): Pr
       checks.push({ label: 'Project', status: pc.yellow('config exists but unreadable') });
     }
   } else {
-    checks.push({ label: 'Project', status: pc.dim('not initialized (run `orbital init`)') });
+    checks.push({ label: 'Project', status: pc.dim('not initialized (run `orbital`)') });
   }
 
   // 5. Workflow