orbital-command 0.2.0 → 1.0.0

package/server/routes/git-routes.ts

@@ -108,5 +108,82 @@ export function createGitRoutes({ gitService, githubService, engine }: GitRoutes
     }
   });
 
+  // ─── GitHub Auth Flow ──────────────────────────────────────
+
+  router.post('/github/connect', async (req, res) => {
+    try {
+      const { method, token } = req.body as { method?: string; token?: string };
+      if (method === 'pat' && token) {
+        const result = await githubService.connectWithToken(token);
+        res.json(result);
+      } else {
+        const result = await githubService.connectOAuth();
+        res.json(result);
+      }
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to connect', details: String(err) });
+    }
+  });
+
+  router.get('/github/auth-status', async (_req, res) => {
+    try {
+      const status = await githubService.getAuthStatus();
+      res.json(status);
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to check auth', details: String(err) });
+    }
+  });
+
+  router.post('/github/disconnect', async (_req, res) => {
+    try {
+      const result = await githubService.disconnect();
+      res.json(result);
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to disconnect', details: String(err) });
+    }
+  });
+
+  // ─── GitHub CI Checks ──────────────────────────────────────
+
+  router.get('/github/checks/:ref', async (req, res) => {
+    try {
+      const checks = await githubService.getCheckRuns(req.params.ref);
+      res.json(checks);
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to get checks', details: String(err) });
+    }
+  });
+
+  // ─── Git Health Metrics ────────────────────────────────────
+
+  router.get('/git/health', async (_req, res) => {
+    try {
+      // Get PR ages for health calculation
+      let prAges: number[] = [];
+      try {
+        const prs = await githubService.getOpenPRs();
+        const now = Date.now();
+        prAges = prs.map(pr => Math.round((now - new Date(pr.createdAt).getTime()) / (1000 * 60 * 60 * 24)));
+      } catch { /* ok — GitHub may not be connected */ }
+
+      const health = await gitService.getHealthMetrics(prAges);
+      res.json(health);
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to get health metrics', details: String(err) });
+    }
+  });
+
+  // ─── Git Activity Series ───────────────────────────────────
+
+  router.get('/git/activity', async (req, res) => {
+    try {
+      const days = Number(req.query.days) || 30;
+      const activity = await gitService.getActivitySeries(days);
+      res.json(activity);
+    } catch (err) {
+      res.status(500).json({ error: 'Failed to get activity', details: String(err) });
+    }
+  });
+
   return router;
 }

package/server/routes/manifest-routes.ts

@@ -0,0 +1,388 @@
+/**
+ * REST API routes for the manifest-based primitive management system.
+ * Exposes status, validation, update, pin/unpin, reset, and diff operations.
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { execFileSync } from 'child_process';
+import { Router } from 'express';
+import {
+  loadManifest,
+  saveManifest,
+  hashFile,
+  computeFileStatus,
+  refreshFileStatuses,
+  summarizeManifest,
+  reverseRemapPath,
+  safeBackupFile,
+  safeCopyTemplate,
+  safeRestoreFile,
+} from '../manifest.js';
+import { validate } from '../validator.js';
+import { computeUpdatePlan, loadRenameMap } from '../update-planner.js';
+import { runInit, runUpdate } from '../init.js';
+import { needsLegacyMigration, migrateFromLegacy } from '../migrate-legacy.js';
+import type { Emitter } from '../project-emitter.js';
+import { errMsg, isValidRelativePath } from '../utils/route-helpers.js';
+
+// ─── Types ──────────────────────────────────────────────────
+
+interface ManifestRouteDeps {
+  projectRoot: string;
+  templatesDir: string;
+  packageVersion: string;
+  io: Emitter;
+}
+
+
+// ─── Route Factory ──────────────────────────────────────────
+
+export function createManifestRoutes({
+  projectRoot,
+  templatesDir,
+  packageVersion,
+  io,
+}: ManifestRouteDeps): Router {
+  const router = Router();
+  const claudeDir = path.join(projectRoot, '.claude');
+
+  // ─── GET /manifest/status — summary overview ────────────
+
+  router.get('/manifest/status', (_req, res) => {
+    try {
+      const manifest = loadManifest(projectRoot);
+
+      if (!manifest) {
+        return res.json({
+          success: true,
+          data: {
+            exists: false,
+            packageVersion,
+            installedVersion: '',
+            needsUpdate: true,
+            preset: '',
+            files: { total: 0, synced: 0, modified: 0, pinned: 0, userOwned: 0, byType: {} },
+            lastUpdated: '',
+          },
+        });
+      }
+
+      refreshFileStatuses(manifest, claudeDir);
+      const summary = summarizeManifest(manifest);
+
+      res.json({
+        success: true,
+        data: {
+          exists: true,
+          packageVersion,
+          installedVersion: manifest.packageVersion,
+          needsUpdate: manifest.packageVersion !== packageVersion,
+          preset: manifest.preset,
+          files: summary,
+          lastUpdated: manifest.updatedAt,
+        },
+      });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  // ─── GET /manifest/files — file inventory ───────────────
+
+  router.get('/manifest/files', (_req, res) => {
+    try {
+      const manifest = loadManifest(projectRoot);
+      if (!manifest) {
+        return res.json({ success: true, data: [] });
+      }
+
+      refreshFileStatuses(manifest, claudeDir);
+
+      const files = Object.entries(manifest.files).map(([filePath, record]) => ({
+        path: filePath,
+        origin: record.origin,
+        status: record.status,
+        templateHash: record.templateHash,
+        installedHash: record.installedHash,
+        pinnedAt: record.pinnedAt,
+        pinnedReason: record.pinnedReason,
+        hasPrev: fs.existsSync(path.join(claudeDir, filePath + '.prev')),
+      }));
+
+      res.json({ success: true, data: files });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  // ─── GET /manifest/validate — run validation ────────────
+
+  router.get('/manifest/validate', (_req, res) => {
+    try {
+      const report = validate(projectRoot, packageVersion);
+      res.json({ success: true, data: report });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  // ─── POST /manifest/init — initialize manifest ───────────
+
+  router.post('/manifest/init', (_req, res) => {
+    try {
+      // If manifest already exists, just return success
+      if (loadManifest(projectRoot)) {
+        return res.json({ success: true, message: 'Already initialized' });
+      }
+
+      // If legacy install exists, migrate it
+      if (needsLegacyMigration(projectRoot)) {
+        migrateFromLegacy(projectRoot, templatesDir, packageVersion);
+        io.emit('manifest:changed', { action: 'initialized' });
+        return res.json({ success: true });
+      }
+
+      // No existing install at all — run full init
+      runInit(projectRoot, { force: false });
+      io.emit('manifest:changed', { action: 'initialized' });
+      res.json({ success: true });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  // ─── POST /manifest/update — run update or dry-run ──────
+
+  router.post('/manifest/update', (req, res) => {
+    const { dryRun = true } = req.body as { dryRun?: boolean };
+
+    try {
+      // Ensure manifest exists (migrate legacy if needed)
+      let manifest = loadManifest(projectRoot);
+      if (!manifest && needsLegacyMigration(projectRoot)) {
+        migrateFromLegacy(projectRoot, templatesDir, packageVersion);
+        manifest = loadManifest(projectRoot);
+      }
+
+      if (!manifest) {
+        return res.status(400).json({ success: false, error: 'No manifest. Run orbital first.' });
+      }
+
+      if (dryRun) {
+        refreshFileStatuses(manifest, claudeDir);
+        const renameMap = loadRenameMap(templatesDir, manifest.packageVersion, packageVersion);
+        const plan = computeUpdatePlan({
+          templatesDir,
+          claudeDir,
+          manifest,
+          newVersion: packageVersion,
+          renameMap,
+        });
+        return res.json({ success: true, data: plan });
+      }
+
+      // Execute actual update
+      runUpdate(projectRoot, { dryRun: false });
+      io.emit('manifest:changed', { action: 'updated' });
+      res.json({ success: true });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  // ─── POST /manifest/pin — pin a file ───────────────────
+
+  router.post('/manifest/pin', (req, res) => {
+    const { file, reason } = req.body as { file: string; reason?: string };
+    if (!file || !isValidRelativePath(file)) {
+      return res.status(400).json({ success: false, error: 'Valid file path required' });
+    }
+
+    try {
+      const manifest = loadManifest(projectRoot);
+      if (!manifest) return res.status(400).json({ success: false, error: 'No manifest' });
+
+      const record = manifest.files[file];
+      if (!record) return res.status(404).json({ success: false, error: 'File not tracked' });
+      if (record.origin === 'user') return res.status(400).json({ success: false, error: 'Cannot pin user-owned file' });
+
+      record.status = 'pinned';
+      record.pinnedAt = new Date().toISOString();
+      if (reason) record.pinnedReason = reason;
+
+      saveManifest(projectRoot, manifest);
+      io.emit('manifest:changed', { action: 'pinned', file });
+      res.json({ success: true });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  // ─── POST /manifest/unpin — unpin a file ────────────────
+
+  router.post('/manifest/unpin', (req, res) => {
+    const { file } = req.body as { file: string };
+    if (!file || !isValidRelativePath(file)) {
+      return res.status(400).json({ success: false, error: 'Valid file path required' });
+    }
+
+    try {
+      const manifest = loadManifest(projectRoot);
+      if (!manifest) return res.status(400).json({ success: false, error: 'No manifest' });
+
+      const record = manifest.files[file];
+      if (!record || record.status !== 'pinned') {
+        return res.status(400).json({ success: false, error: 'File is not pinned' });
+      }
+
+      // Clear pinned state before recomputing status
+      record.status = 'synced';
+      delete record.pinnedAt;
+      delete record.pinnedReason;
+
+      const absPath = path.join(claudeDir, file);
+      if (fs.existsSync(absPath)) {
+        const currentHash = hashFile(absPath);
+        record.status = computeFileStatus(record, currentHash);
+      }
+
+      saveManifest(projectRoot, manifest);
+      io.emit('manifest:changed', { action: 'unpinned', file });
+      res.json({ success: true });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  // ─── POST /manifest/reset — reset file to template ──────
+
+  router.post('/manifest/reset', (req, res) => {
+    const { file } = req.body as { file: string };
+    if (!file || !isValidRelativePath(file)) {
+      return res.status(400).json({ success: false, error: 'Valid file path required' });
+    }
+
+    try {
+      const manifest = loadManifest(projectRoot);
+      if (!manifest) return res.status(400).json({ success: false, error: 'No manifest' });
+
+      const record = manifest.files[file];
+      if (!record || record.origin !== 'template') {
+        return res.status(400).json({ success: false, error: 'Not a template file' });
+      }
+
+      // Resolve template source path
+      const templateRelPath = reverseRemapPath(file);
+      const templatePath = path.join(templatesDir, templateRelPath);
+      if (!fs.existsSync(templatePath)) {
+        return res.status(404).json({ success: false, error: 'Template file not found' });
+      }
+
+      const localPath = path.join(claudeDir, file);
+
+      // Back up current version so user can revert (symlink-safe)
+      safeBackupFile(localPath);
+
+      // Copy template to destination (skips if symlink)
+      safeCopyTemplate(templatePath, localPath);
+
+      const newHash = hashFile(localPath);
+      record.status = 'synced';
+      record.templateHash = newHash;
+      record.installedHash = newHash;
+      delete record.pinnedAt;
+      delete record.pinnedReason;
+
+      saveManifest(projectRoot, manifest);
+      io.emit('manifest:changed', { action: 'reset', file });
+      res.json({ success: true });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  // ─── POST /manifest/revert — restore file from .prev backup ──
+
+  router.post('/manifest/revert', (req, res) => {
+    const { file } = req.body as { file: string };
+    if (!file || !isValidRelativePath(file)) {
+      return res.status(400).json({ success: false, error: 'Valid file path required' });
+    }
+
+    try {
+      const manifest = loadManifest(projectRoot);
+      if (!manifest) return res.status(400).json({ success: false, error: 'No manifest' });
+
+      const record = manifest.files[file];
+      if (!record) return res.status(404).json({ success: false, error: 'File not tracked' });
+
+      const localPath = path.join(claudeDir, file);
+
+      if (!safeRestoreFile(localPath)) {
+        return res.status(404).json({ success: false, error: 'No previous version available' });
+      }
+
+      // Recompute status — file may now be a symlink or regular file
+      if (fs.existsSync(localPath)) {
+        const stat = fs.lstatSync(localPath);
+        if (stat.isSymbolicLink()) {
+          record.status = 'synced'; // restored symlink points at template
+        } else {
+          const currentHash = hashFile(localPath);
+          record.installedHash = currentHash;
+          record.status = computeFileStatus(record, currentHash);
+        }
+      } else {
+        record.status = 'missing';
+      }
+
+      saveManifest(projectRoot, manifest);
+      io.emit('manifest:changed', { action: 'reverted', file });
+      res.json({ success: true });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  // ─── GET /manifest/diff — diff template vs local ─────────
+
+  router.get('/manifest/diff', (req, res) => {
+    const file = req.query.file as string;
+    if (!file || !isValidRelativePath(file)) {
+      return res.status(400).json({ success: false, error: 'Valid file path required' });
+    }
+
+    try {
+      const templateRelPath = reverseRemapPath(file);
+      const rawTemplatePath = path.join(templatesDir, templateRelPath);
+      // Resolve symlinks so git diff compares file content, not symlink metadata
+      const templatePath = fs.existsSync(rawTemplatePath) ? fs.realpathSync(rawTemplatePath) : rawTemplatePath;
+      const localPath = path.join(claudeDir, file);
+
+      if (!fs.existsSync(templatePath)) {
+        return res.status(404).json({ success: false, error: 'Template file not found' });
+      }
+      if (!fs.existsSync(localPath)) {
+        return res.status(404).json({ success: false, error: 'Local file not found' });
+      }
+
+      let diff = '';
+      try {
+        diff = execFileSync('git', ['diff', '--no-index', '--', templatePath, localPath], {
+          encoding: 'utf-8',
+        });
+      } catch (e: unknown) {
+        // git diff exits 1 when files differ
+        const err = e as { stdout?: string };
+        diff = err.stdout || 'Files differ';
+      }
+
+      res.json({ success: true, data: { diff } });
+    } catch (err) {
+      res.status(500).json({ success: false, error: errMsg(err) });
+    }
+  });
+
+  return router;
+}

package/server/routes/scope-routes.ts

@@ -1,27 +1,34 @@
 import { Router } from 'express';
 import { spawn } from 'child_process';
 import type Database from 'better-sqlite3';
-import type { Server } from 'socket.io';
+import type { Emitter } from '../project-emitter.js';
 import type { ScopeService } from '../services/scope-service.js';
 import type { ReadinessService } from '../services/readiness-service.js';
 import type { WorkflowEngine } from '../../shared/workflow-engine.js';
-import { launchInTerminal, escapeForAnsiC, buildSessionName, snapshotSessionPids, discoverNewSession, renameSession } from '../utils/terminal-launcher.js';
+import { launchInTerminal, escapeForAnsiC, shellQuote, buildSessionName, snapshotSessionPids, discoverNewSession, renameSession } from '../utils/terminal-launcher.js';
 import { resolveDispatchEvent, linkPidToDispatch } from '../utils/dispatch-utils.js';
-import { getConfig } from '../config.js';
+import { buildClaudeFlags, buildEnvVarPrefix } from '../utils/flag-builder.js';
+import type { OrbitalConfig } from '../config.js';
 import { createLogger } from '../utils/logger.js';
 
 const log = createLogger('dispatch');
 
 interface ScopeRouteDeps {
   db: Database.Database;
-  io: Server;
+  io: Emitter;
   scopeService: ScopeService;
   readinessService: ReadinessService;
   projectRoot: string;
+  projectName: string;
   engine: WorkflowEngine;
+  config: OrbitalConfig;
 }
 
-export function createScopeRoutes({ db, io, scopeService, readinessService, projectRoot, engine }: ScopeRouteDeps): Router {
+function isValidSlug(slug: string): boolean {
+  return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(slug) && slug.length <= 80;
+}
+
+export function createScopeRoutes({ db, io, scopeService, readinessService, projectRoot, projectName, engine, config }: ScopeRouteDeps): Router {
   const router = Router();
 
   // ─── Scope CRUD ──────────────────────────────────────────
@@ -67,7 +74,7 @@ export function createScopeRoutes({ db, io, scopeService, readinessService, proj
 
   router.patch('/scopes/:id', (req, res) => {
     const id = Number(req.params.id);
-    const result = scopeService.updateScopeFrontmatter(id, req.body);
+    const result = scopeService.updateFields(id, req.body);
     if (!result.ok) {
       const code = result.code === 'NOT_FOUND' ? 404 : 400;
       res.status(code).json({ error: result.error, code: result.code });
@@ -89,14 +96,15 @@ export function createScopeRoutes({ db, io, scopeService, readinessService, proj
     res.status(201).json(idea);
   });
 
-  router.patch('/ideas/:id', (req, res) => {
-    const id = Number(req.params.id);
+  router.patch('/ideas/:slug', (req, res) => {
+    const { slug } = req.params;
+    if (!isValidSlug(slug)) { res.status(400).json({ error: 'Invalid slug' }); return; }
     const { title, description } = req.body as { title?: string; description?: string };
     if (!title?.trim()) {
       res.status(400).json({ error: 'title is required' });
       return;
     }
-    const updated = scopeService.updateIdeaFile(id, title.trim(), (description ?? '').trim());
+    const updated = scopeService.updateIdeaFile(slug, title.trim(), (description ?? '').trim());
     if (!updated) {
       res.status(404).json({ error: 'Idea not found' });
       return;
@@ -104,9 +112,10 @@ export function createScopeRoutes({ db, io, scopeService, readinessService, proj
     res.json({ ok: true });
   });
 
-  router.delete('/ideas/:id', (req, res) => {
-    const id = Number(req.params.id);
-    const deleted = scopeService.deleteIdeaFile(id);
+  router.delete('/ideas/:slug', (req, res) => {
+    const { slug } = req.params;
+    if (!isValidSlug(slug)) { res.status(400).json({ error: 'Invalid slug' }); return; }
+    const deleted = scopeService.deleteIdeaFile(slug);
     if (!deleted) {
       res.status(404).json({ error: 'Idea not found' });
       return;
@@ -114,9 +123,13 @@ export function createScopeRoutes({ db, io, scopeService, readinessService, proj
     res.json({ ok: true });
   });
 
-  router.post('/ideas/:id/promote', async (req, res) => {
-    const ideaId = Number(req.params.id);
-    const result = scopeService.promoteIdea(ideaId);
+  router.post('/ideas/:slug/promote', async (req, res) => {
+    const { slug } = req.params;
+    if (!isValidSlug(slug)) { res.status(400).json({ error: 'Invalid slug' }); return; }
+    const entryPoint = engine.getEntryPoint();
+    const targets = engine.getValidTargets(entryPoint.id);
+    const promoteTarget = targets[0] ?? 'planning';
+    const result = scopeService.promoteIdea(slug, promoteTarget);
     if (!result) {
       res.status(404).json({ error: 'Idea not found' });
       return;
@@ -125,9 +138,6 @@ export function createScopeRoutes({ db, io, scopeService, readinessService, proj
     const scopeId = result.id;
 
     // Read command from workflow edge config (user-overridable)
-    const entryPoint = engine.getEntryPoint();
-    const targets = engine.getValidTargets(entryPoint.id);
-    const promoteTarget = targets[0] ?? 'planning';
     const edge = engine.findEdge(entryPoint.id, promoteTarget);
     const edgeCommand = edge ? engine.buildCommand(edge, scopeId) : null;
     const command = edgeCommand ?? `/scope-create ${String(scopeId).padStart(3, '0')}`;
@@ -151,7 +161,9 @@ export function createScopeRoutes({ db, io, scopeService, readinessService, proj
     });
 
     const escaped = escapeForAnsiC(command);
-    const fullCmd = `cd '${projectRoot}' && claude --dangerously-skip-permissions $'${escaped}'`;
+    const flagsStr = buildClaudeFlags(config.claude.dispatchFlags);
+    const envPrefix = buildEnvVarPrefix(config.dispatch.envVars);
+    const fullCmd = `cd '${shellQuote(projectRoot)}' && ${envPrefix}ORBITAL_DISPATCH_ID='${shellQuote(eventId)}' claude ${flagsStr} $'${escaped}'`;
 
     const promoteSessionName = buildSessionName({ scopeId, title: result.title, command });
     const promoteBeforePids = snapshotSessionPids(projectRoot);
@@ -184,18 +196,15 @@ export function createScopeRoutes({ db, io, scopeService, readinessService, proj
     }
     surpriseInProgress = true;
 
-    const nextIdStart = scopeService.getNextIceboxId();
     const today = new Date().toISOString().split('T')[0];
-    const idRange = Array.from({ length: 5 }, (_, i) => nextIdStart + i);
 
-    const prompt = `You are analyzing the ${getConfig().projectName} codebase to suggest feature ideas. Your ONLY job is to create markdown files.
+    const prompt = `You are analyzing the ${projectName} codebase to suggest feature ideas. Your ONLY job is to create markdown files.
 
 Create exactly 3 idea files in the scopes/icebox/ directory. Each file must use this EXACT format:
 
-File: scopes/icebox/{ID}-{kebab-slug}.md
+File: scopes/icebox/{kebab-slug}.md
 
 ---
-id: {ID}
 title: "{title}"
 status: icebox
 ghost: true
@@ -208,13 +217,12 @@ tags: []
 
 {2-3 sentence description of the feature, what problem it solves, and a rough approach.}
 
-Use these IDs: ${idRange[0]}, ${idRange[1]}, ${idRange[2]}
-
 Rules:
 - Focus on practical improvements: performance, UX, security, developer experience, monitoring, or reliability
 - Be specific and actionable — not vague architectural rewrites
 - Keep descriptions concise (2-3 sentences max)
-- Filenames must be {ID}-{kebab-case-slug}.md
+- Filenames must be {kebab-case-slug}.md (NO numeric prefix)
+- Do NOT include an id field in frontmatter
 - The ghost: true field is required in frontmatter
 - Do NOT create any other files or make any other changes`;
 
@@ -244,9 +252,10 @@ Rules:
     res.json({ ok: true, status: 'generating' });
   });
 
-  router.post('/ideas/:id/approve', (req, res) => {
-    const id = Number(req.params.id);
-    const approved = scopeService.approveGhostIdea(id);
+  router.post('/ideas/:slug/approve', (req, res) => {
+    const { slug } = req.params;
+    if (!isValidSlug(slug)) { res.status(400).json({ error: 'Invalid slug' }); return; }
+    const approved = scopeService.approveGhostIdea(slug);
     if (!approved) {
       res.status(404).json({ error: 'Ghost idea not found' });
       return;