orbital-command 0.1.0

package/server/services/github-service.ts

@@ -0,0 +1,183 @@
+import { execFile as execFileCb } from 'child_process';
+import { promisify } from 'util';
+
+// Uses execFile (not exec) — safe against shell injection
+const execFile = promisify(execFileCb);
+
+// ─── Types ──────────────────────────────────────────────────
+
+export interface GitHubStatus {
+  connected: boolean;
+  authUser: string | null;
+  repo: {
+    owner: string;
+    name: string;
+    fullName: string;
+    defaultBranch: string;
+    visibility: string;
+    url: string;
+  } | null;
+  openPRs: number;
+  error: string | null;
+}
+
+export interface PullRequestInfo {
+  number: number;
+  title: string;
+  author: string;
+  branch: string;
+  baseBranch: string;
+  state: string;
+  url: string;
+  createdAt: string;
+  scopeIds: number[];
+}
+
+// ─── Service ────────────────────────────────────────────────
+
+const CACHE_TTL = 30_000; // 30 seconds
+const SCOPE_ID_RE = /(?:scope|feat)[/-](\d+)/gi;
+
+export class GitHubService {
+  private statusCache: { data: GitHubStatus; ts: number } | null = null;
+  private prCache: { data: PullRequestInfo[]; ts: number } | null = null;
+
+  constructor(private projectRoot: string) {}
+
+  private async gh(args: string[]): Promise<string> {
+    const { stdout } = await execFile('gh', args, {
+      cwd: this.projectRoot,
+      timeout: 10_000,
+    });
+    return stdout;
+  }
+
+  private async ghAvailable(): Promise<boolean> {
+    try {
+      await execFile('which', ['gh']);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async getStatus(): Promise<GitHubStatus> {
+    if (this.statusCache && Date.now() - this.statusCache.ts < CACHE_TTL) {
+      return this.statusCache.data;
+    }
+
+    const available = await this.ghAvailable();
+    if (!available) {
+      const result: GitHubStatus = {
+        connected: false,
+        authUser: null,
+        repo: null,
+        openPRs: 0,
+        error: 'gh CLI not installed',
+      };
+      this.statusCache = { data: result, ts: Date.now() };
+      return result;
+    }
+
+    // Check auth
+    let authUser: string | null = null;
+    try {
+      const whoami = await this.gh(['api', 'user', '--jq', '.login']);
+      authUser = whoami.trim() || null;
+    } catch {
+      const result: GitHubStatus = {
+        connected: false,
+        authUser: null,
+        repo: null,
+        openPRs: 0,
+        error: 'gh not authenticated — run `gh auth login`',
+      };
+      this.statusCache = { data: result, ts: Date.now() };
+      return result;
+    }
+
+    // Get repo info
+    let repo: GitHubStatus['repo'] = null;
+    try {
+      const raw = await this.gh([
+        'repo', 'view', '--json', 'owner,name,defaultBranchRef,visibility,url',
+      ]);
+      const parsed = JSON.parse(raw);
+      repo = {
+        owner: parsed.owner?.login ?? '',
+        name: parsed.name ?? '',
+        fullName: `${parsed.owner?.login ?? ''}/${parsed.name ?? ''}`,
+        defaultBranch: parsed.defaultBranchRef?.name ?? 'main',
+        visibility: (parsed.visibility ?? 'private').toLowerCase(),
+        url: parsed.url ?? '',
+      };
+    } catch {
+      const result: GitHubStatus = {
+        connected: false,
+        authUser,
+        repo: null,
+        openPRs: 0,
+        error: 'Not a GitHub repository',
+      };
+      this.statusCache = { data: result, ts: Date.now() };
+      return result;
+    }
+
+    // Get open PR count
+    let openPRs = 0;
+    try {
+      const raw = await this.gh(['pr', 'list', '--state', 'open', '--json', 'number', '--limit', '100']);
+      const parsed = JSON.parse(raw);
+      openPRs = Array.isArray(parsed) ? parsed.length : 0;
+    } catch { /* ok */ }
+
+    const result: GitHubStatus = { connected: true, authUser, repo, openPRs, error: null };
+    this.statusCache = { data: result, ts: Date.now() };
+    return result;
+  }
+
+  async getOpenPRs(): Promise<PullRequestInfo[]> {
+    if (this.prCache && Date.now() - this.prCache.ts < CACHE_TTL) {
+      return this.prCache.data;
+    }
+
+    try {
+      const raw = await this.gh([
+        'pr', 'list', '--state', 'open', '--json',
+        'number,title,author,headRefName,baseRefName,state,url,createdAt',
+        '--limit', '30',
+      ]);
+      const parsed = JSON.parse(raw);
+
+      const prs: PullRequestInfo[] = (parsed as Array<Record<string, unknown>>).map(pr => {
+        const title = String(pr.title ?? '');
+        const branch = String(pr.headRefName ?? '');
+        const scopeIds: number[] = [];
+        const sources = `${title} ${branch}`;
+        let m: RegExpExecArray | null;
+        SCOPE_ID_RE.lastIndex = 0;
+        while ((m = SCOPE_ID_RE.exec(sources)) !== null) {
+          const id = parseInt(m[1]);
+          if (!scopeIds.includes(id)) scopeIds.push(id);
+        }
+
+        return {
+          number: Number(pr.number),
+          title,
+          author: typeof pr.author === 'object' && pr.author ? String((pr.author as Record<string, unknown>).login ?? '') : '',
+          branch,
+          baseBranch: String(pr.baseRefName ?? ''),
+          state: String(pr.state ?? ''),
+          url: String(pr.url ?? ''),
+          createdAt: String(pr.createdAt ?? ''),
+          scopeIds,
+        };
+      });
+
+      this.prCache = { data: prs, ts: Date.now() };
+      return prs;
+    } catch {
+      return [];
+    }
+  }
+}

package/server/services/readiness-service.ts

@@ -0,0 +1,250 @@
+import fs from 'fs';
+import path from 'path';
+import type { ParsedScope } from '../parsers/scope-parser.js';
+import type { ScopeService } from './scope-service.js';
+import type { GateService, GateRow } from './gate-service.js';
+import type { WorkflowEngine } from '../../shared/workflow-engine.js';
+import type { HookCategory, HookEnforcement, WorkflowEdge } from '../../shared/workflow-config.js';
+
+// ─── Types ──────────────────────────────────────────────
+
+export type HookReadiness = 'pass' | 'fail' | 'unknown';
+
+export interface HookStatus {
+  id: string;
+  label: string;
+  category: HookCategory;
+  enforcement: HookEnforcement;
+  status: HookReadiness;
+  reason: string | null;
+}
+
+export interface TransitionReadiness {
+  from: string;
+  to: string;
+  edge: WorkflowEdge;
+  hooks: HookStatus[];
+  gates: Array<{
+    gate_name: string;
+    status: string;
+    details: string | null;
+    duration_ms: number | null;
+    run_at: string;
+  }>;
+  ready: boolean;
+  blockers: string[];
+}
+
+export interface ScopeReadiness {
+  scope_id: number;
+  current_status: string;
+  transitions: TransitionReadiness[];
+}
+
+// ─── ReadinessService ───────────────────────────────────
+
+export class ReadinessService {
+  constructor(
+    private scopeService: ScopeService,
+    private gateService: GateService,
+    private engine: WorkflowEngine,
+    private projectRoot: string,
+  ) {}
+
+  getReadiness(scopeId: number): ScopeReadiness | null {
+    const scope = this.scopeService.getById(scopeId);
+    if (!scope) return null;
+
+    const targets = this.engine.getValidTargets(scope.status);
+    const transitions: TransitionReadiness[] = [];
+
+    for (const to of targets) {
+      const edge = this.engine.findEdge(scope.status, to);
+      if (!edge) continue;
+
+      // Only show forward and shortcut transitions (not backward)
+      if (edge.direction === 'backward') continue;
+
+      const hooks = this.evaluateHooks(scope, edge);
+      const gates = this.getGatesForScope(scopeId);
+      const blockers = this.computeBlockers(hooks, scope);
+
+      transitions.push({
+        from: scope.status,
+        to,
+        edge,
+        hooks,
+        gates,
+        ready: blockers.length === 0,
+        blockers,
+      });
+    }
+
+    return {
+      scope_id: scopeId,
+      current_status: scope.status,
+      transitions,
+    };
+  }
+
+  private evaluateHooks(scope: ParsedScope, edge: WorkflowEdge): HookStatus[] {
+    const hooks = this.engine.getHooksForEdge(edge.from, edge.to);
+    return hooks.map((hook) => {
+      const enforcement = this.engine.getHookEnforcement(hook);
+      const { status, reason } = this.evaluateHook(hook.id, scope, edge);
+      return {
+        id: hook.id,
+        label: hook.label,
+        category: hook.category,
+        enforcement,
+        status,
+        reason,
+      };
+    });
+  }
+
+  private evaluateHook(
+    hookId: string,
+    scope: ParsedScope,
+    edge: WorkflowEdge,
+  ): { status: HookReadiness; reason: string | null } {
+    switch (hookId) {
+      case 'session-enforcer':
+        return this.checkSessionEnforcer(scope, edge);
+      case 'review-gate-check':
+        return this.checkReviewGate(scope);
+      case 'completion-checklist':
+        return this.checkCompletionChecklist(scope);
+      case 'blocker-check':
+        return this.checkBlockers(scope);
+      case 'dependency-check':
+        return this.checkDependencies(scope);
+      case 'scope-create-gate':
+        return this.checkScopeStructure(scope);
+      case 'scope-transition':
+        return { status: 'pass', reason: 'Lifecycle hook (runs on transition)' };
+      case 'orbital-scope-update':
+      case 'scope-commit-logger':
+        return { status: 'pass', reason: 'Observer (post-transition)' };
+      default:
+        return { status: 'unknown', reason: 'No pre-check available' };
+    }
+  }
+
+  private checkSessionEnforcer(
+    scope: ParsedScope,
+    edge: WorkflowEdge,
+  ): { status: HookReadiness; reason: string | null } {
+    const targetList = this.engine.getList(edge.to);
+    const sessionKey = targetList?.sessionKey;
+    if (!sessionKey) return { status: 'pass', reason: 'No session key required' };
+
+    const sessions = scope.sessions ?? {};
+    const recorded = sessions[sessionKey];
+    if (Array.isArray(recorded) && recorded.length > 0) {
+      return { status: 'pass', reason: `Session recorded (${recorded.length} session(s))` };
+    }
+    return { status: 'fail', reason: `No '${sessionKey}' session recorded in scope frontmatter` };
+  }
+
+  private checkReviewGate(scope: ParsedScope): { status: HookReadiness; reason: string | null } {
+    const paddedId = String(scope.id).padStart(3, '0');
+    const verdictPath = path.join(this.projectRoot, '.claude', 'review-verdicts', `${paddedId}.json`);
+
+    if (!fs.existsSync(verdictPath)) {
+      return { status: 'fail', reason: 'No review verdict file found' };
+    }
+
+    try {
+      const verdict = JSON.parse(fs.readFileSync(verdictPath, 'utf-8'));
+      if (verdict.verdict === 'PASS') {
+        return { status: 'pass', reason: 'Review verdict: PASS' };
+      }
+      return { status: 'fail', reason: `Review verdict: ${verdict.verdict ?? 'unknown'}` };
+    } catch {
+      return { status: 'fail', reason: 'Failed to parse review verdict file' };
+    }
+  }
+
+  private checkCompletionChecklist(scope: ParsedScope): { status: HookReadiness; reason: string | null } {
+    const content = scope.raw_content ?? '';
+    const unchecked = (content.match(/^- \[ \]/gm) ?? []).length;
+    const checked = (content.match(/^- \[x\]/gim) ?? []).length;
+
+    if (checked + unchecked === 0) {
+      return { status: 'unknown', reason: 'No checklist items found in scope' };
+    }
+    if (unchecked > 0) {
+      return { status: 'fail', reason: `${unchecked} unchecked item(s) in DoD checklist` };
+    }
+    return { status: 'pass', reason: `All ${checked} checklist item(s) complete` };
+  }
+
+  private checkBlockers(scope: ParsedScope): { status: HookReadiness; reason: string | null } {
+    const blockedBy = scope.blocked_by ?? [];
+    if (blockedBy.length === 0) {
+      return { status: 'pass', reason: 'No blockers' };
+    }
+
+    const unresolved: number[] = [];
+    for (const blockerId of blockedBy) {
+      const blocker = this.scopeService.getById(blockerId);
+      if (blocker && !this.engine.isTerminalStatus(blocker.status)) {
+        unresolved.push(blockerId);
+      }
+    }
+
+    if (unresolved.length === 0) {
+      return { status: 'pass', reason: `All ${blockedBy.length} blocker(s) resolved` };
+    }
+    return {
+      status: 'fail',
+      reason: `Blocked by unresolved scope(s): ${unresolved.join(', ')}`,
+    };
+  }
+
+  private checkDependencies(scope: ParsedScope): { status: HookReadiness; reason: string | null } {
+    // Same check as blockers — dependency-check and blocker-check serve similar roles
+    return this.checkBlockers(scope);
+  }
+
+  private checkScopeStructure(scope: ParsedScope): { status: HookReadiness; reason: string | null } {
+    if (!scope.title || scope.title.trim() === '') {
+      return { status: 'fail', reason: 'Scope has no title' };
+    }
+    if (!scope.raw_content || scope.raw_content.trim() === '') {
+      return { status: 'fail', reason: 'Scope has no content body' };
+    }
+    return { status: 'pass', reason: 'Scope structure valid' };
+  }
+
+  private getGatesForScope(scopeId: number): GateRow[] {
+    const scoped = this.gateService.getLatestForScope(scopeId);
+    if (scoped.length > 0) return scoped;
+
+    // Fall back to global latest run if no scope-specific gates exist
+    return this.gateService.getLatestRun();
+  }
+
+  private computeBlockers(hooks: HookStatus[], scope: ParsedScope): string[] {
+    const blockers: string[] = [];
+
+    // Only guards (blockers) actually prevent transitions
+    for (const hook of hooks) {
+      if (hook.enforcement === 'blocker' && hook.status === 'fail') {
+        blockers.push(`${hook.label}: ${hook.reason}`);
+      }
+    }
+
+    // Check for unresolved scope blockers
+    const blockedBy = scope.blocked_by ?? [];
+    for (const blockerId of blockedBy) {
+      const blocker = this.scopeService.getById(blockerId);
+      if (blocker && !this.engine.isTerminalStatus(blocker.status)) {
+        blockers.push(`Blocked by scope ${blockerId} (${blocker.status})`);
+      }
+    }
+
+    return blockers;
+  }
+}

package/server/services/scope-cache.ts

@@ -0,0 +1,81 @@
+import type { ParsedScope } from '../parsers/scope-parser.js';
+
+/**
+ * In-memory cache for parsed scopes.
+ * Dual-indexed: ID lookups (API, sprint orchestrator) and file-path reverse index (watcher deletions).
+ * Replaces the SQLite `scopes` table — filesystem frontmatter is the single source of truth.
+ */
+export class ScopeCache {
+  private byId = new Map<number, ParsedScope>();
+  private filePathToId = new Map<string, number>();
+
+  /** Bulk-load all scopes (called at startup from parseAllScopes result) */
+  loadAll(scopes: ParsedScope[]): void {
+    this.byId.clear();
+    this.filePathToId.clear();
+    for (const scope of scopes) {
+      this.byId.set(scope.id, scope);
+      this.filePathToId.set(scope.file_path, scope.id);
+    }
+  }
+
+  /** Insert or update a single scope */
+  set(scope: ParsedScope): void {
+    // Clean up old file_path mapping if the scope moved directories
+    const existing = this.byId.get(scope.id);
+    if (existing && existing.file_path !== scope.file_path) {
+      this.filePathToId.delete(existing.file_path);
+    }
+    this.byId.set(scope.id, scope);
+    this.filePathToId.set(scope.file_path, scope.id);
+  }
+
+  /** Remove a scope by its file path (used by watcher on file deletion) */
+  removeByFilePath(filePath: string): number | undefined {
+    const id = this.filePathToId.get(filePath);
+    if (id !== undefined) {
+      this.byId.delete(id);
+      this.filePathToId.delete(filePath);
+    }
+    return id;
+  }
+
+  /** Look up scope ID by file path (used before removal to stash status) */
+  idByFilePath(filePath: string): number | undefined {
+    return this.filePathToId.get(filePath);
+  }
+
+  /** Check if scope exists by ID */
+  has(id: number): boolean {
+    return this.byId.has(id);
+  }
+
+  /** Get a scope by ID */
+  getById(id: number): ParsedScope | undefined {
+    return this.byId.get(id);
+  }
+
+  /** Get all scopes sorted by ID */
+  getAll(): ParsedScope[] {
+    return [...this.byId.values()].sort((a, b) => a.id - b.id);
+  }
+
+  /** Get the maximum raw scope number excluding icebox scopes (for next-ID generation).
+   *  Cache keys use encoded IDs (suffixed scopes like 047a → 1047, 075x → 9075),
+   *  but next-ID generation needs the raw scope number (047, 075, 087). */
+  maxNonIceboxId(): number {
+    let max = 0;
+    for (const [id, scope] of this.byId) {
+      if (scope.status === 'icebox') continue;
+      // Decode: encoded IDs ≥1000 have a suffix offset — raw number is id % 1000
+      const raw = id >= 1000 ? id % 1000 : id;
+      if (raw > max) max = raw;
+    }
+    return max;
+  }
+
+  /** Total number of cached scopes */
+  get size(): number {
+    return this.byId.size;
+  }
+}