mstro-app 0.5.0 → 0.5.5

package/server/services/websocket/quality-handlers.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Quality Handlers — WebSocket message router for quality scanning
@@ -14,15 +13,16 @@
 import { join, resolve } from 'node:path';
 import { validatePathWithinWorkingDir } from '../pathUtils.js';
 import type { HandlerContext } from './handler-context.js';
+import { estimateCodebaseSize, estimateScanMs } from './quality-eta.js';
+import { operationRegistry } from './quality-operations.js';
 import { QualityPersistence } from './quality-persistence.js';
 import { handleCodeReview } from './quality-review-agent.js';
-import { detectTools, installTools, runQualityScan } from './quality-service.js';
+import { detectTools, installTools, QualityScanAbortedError, runQualityScan } from './quality-service.js';
 import type { WebSocketMessage, WSContext } from './types.js';
 
 // ── Shared state ──────────────────────────────────────────────
 
 const persistenceCache = new Map<string, QualityPersistence>();
-const activeReviews = new Set<string>();
 
 function getPersistence(workingDir: string): QualityPersistence {
   let persistence = persistenceCache.get(workingDir);
@@ -87,10 +87,32 @@ export function handleQualityMessage(
       if (error) { sendPathError(msg.data?.path || '.', error); return; }
       const reportPath = msg.data?.path || '.';
       const persistence = getPersistence(workingDir);
+      let controller: AbortController;
+      try {
+        controller = operationRegistry.start(workingDir, reportPath, 'reviewing');
+      } catch {
+        // Look up what's actually running so the user sees the right message
+        // — clicking "Run checks" during an in-flight AI review used to surface
+        // "A scan is already running" because the error was hardcoded to the
+        // *new* op kind rather than the existing one.
+        const runningKind = operationRegistry.getKind(workingDir, reportPath);
+        const error = runningKind === 'scanning'
+          ? 'A scan is already running for this directory.'
+          : 'An AI review is already running for this directory.';
+        ctx.send(ws, { type: 'qualityError', data: { path: reportPath, error } });
+        return;
+      }
       persistence.setActiveOperation(reportPath, 'reviewing');
-      handleCodeReview(ctx, ws, reportPath, dirPath, workingDir, activeReviews, getPersistence)
-        .finally(() => persistence.clearActiveOperation(reportPath));
+      // The review agent is responsible for emitting the first progress
+      // message with an ETA; the handler just wires up the controller +
+      // persistence cleanup.
+      handleCodeReview(ctx, ws, reportPath, dirPath, workingDir, getPersistence, controller.signal)
+        .finally(() => {
+          operationRegistry.finish(workingDir, reportPath);
+          persistence.clearActiveOperation(reportPath);
+        });
     },
+    qualityCancel: () => handleCancel(ctx, msg, workingDir),
     qualityLoadState: () => handleLoadState(ctx, ws, workingDir),
     qualityClearPending: () => {
       const persistence = getPersistence(workingDir);
@@ -138,6 +160,27 @@ async function handleLoadState(
       persistence.clearPendingResults();
     }
 
+    // Reconcile orphaned active operations: anything persisted to disk that
+    // has no live `AbortController` in the registry was interrupted by a CLI
+    // restart or crash. Surface as an error so the UI clears the spinner and
+    // remove from disk so the same op doesn't keep haunting future reconnects.
+    const orphans = state.activeOperations.filter(
+      (op) => !operationRegistry.has(workingDir, op.path),
+    );
+    if (orphans.length > 0) {
+      for (const op of orphans) {
+        persistence.clearActiveOperation(op.path);
+        ctx.send(ws, {
+          type: 'qualityError',
+          data: { path: op.path, error: 'Operation interrupted — please run again.' },
+        });
+      }
+      // Reload so the response reflects the cleared ops.
+      const refreshed = persistence.loadState();
+      ctx.send(ws, { type: 'qualityStateLoaded', data: refreshed });
+      return;
+    }
+
     ctx.send(ws, { type: 'qualityStateLoaded', data: state });
   } catch (error) {
     ctx.send(ws, {
@@ -147,6 +190,30 @@ async function handleLoadState(
   }
 }
 
+function handleCancel(
+  ctx: HandlerContext,
+  msg: WebSocketMessage,
+  workingDir: string,
+): void {
+  const reportPath = msg.data?.path || '.';
+  const persistence = getPersistence(workingDir);
+  const wasRunning = operationRegistry.cancel(workingDir, reportPath);
+  // Always clear persistence — cancel for an orphan should still leave the
+  // disk clean so future reconnects don't re-emit the orphan reconciliation
+  // error.
+  persistence.clearActiveOperation(reportPath);
+  // Broadcast so every paired device sees the operation end (multi-device
+  // sync). If nothing was running we still emit so a stale spinner on a
+  // second device gets cleared by the `qualityError` handler.
+  ctx.broadcastToAll({
+    type: 'qualityError',
+    data: {
+      path: reportPath,
+      error: wasRunning ? 'Cancelled by user' : 'Operation already finished',
+    },
+  });
+}
+
 async function handleSaveDirectories(
   ctx: HandlerContext,
   ws: WSContext,
@@ -231,18 +298,90 @@ async function handleScan(
   const reportPath = msg.data?.path || '.';
   const persistence = getPersistence(workingDir);
 
+  let controller: AbortController;
+  try {
+    controller = operationRegistry.start(workingDir, reportPath, 'scanning');
+  } catch {
+    // Same reasoning as the qualityCodeReview handler above — surface the
+    // *running* op kind, not the requested one.
+    const runningKind = operationRegistry.getKind(workingDir, reportPath);
+    const error = runningKind === 'reviewing'
+      ? 'An AI review is already running for this directory.'
+      : 'A scan is already running for this directory.';
+    ctx.send(ws, { type: 'qualityError', data: { path: reportPath, error } });
+    return;
+  }
+
+  const scanStartedAt = Date.now();
+  // Pre-compute a size + ETA so the very first progress event carries an
+  // estimate. We deliberately do this *before* `setActiveOperation` so a
+  // freshly-clicked scan shows numbers immediately rather than after a
+  // file-collection round-trip.
+  let etaMs: number | undefined;
+  try {
+    const size = await estimateCodebaseSize(dirPath);
+    etaMs = estimateScanMs(size, persistence.loadHistory(), reportPath);
+  } catch {
+    // Falling back to no ETA is fine — the UI will simply hide the remaining-time chip.
+  }
+
   try {
     persistence.setActiveOperation(reportPath, 'scanning');
 
+    // Emit a "Detecting tools" frame *before* the long detect call so the
+    // user sees motion immediately on click — `detectTools` spawns one
+    // child process per ecosystem tool and can sit silent for several
+    // seconds on a cold cache.
+    ctx.send(ws, {
+      type: 'qualityScanProgress',
+      data: {
+        path: reportPath,
+        progress: { step: 'Detecting tools', current: 0, total: 8, etaMs, startedAt: scanStartedAt },
+      },
+    });
     const { tools: detectedTools } = await detectTools(dirPath);
     const installedToolNames = detectedTools.filter((t) => t.installed).map((t) => t.name);
 
-    const results = await runQualityScan(dirPath, (progress) => {
+    // Heartbeat — keeps the progress UI showing elapsed time during long
+    // sub-steps (lint/format/build) where `runQualityScan` doesn't get a
+    // chance to call the progress callback again.
+    let lastProgress: { step: string; current: number; total: number } = {
+      step: 'Detecting tools',
+      current: 0,
+      total: 8,
+    };
+    const heartbeat = setInterval(() => {
+      const elapsedSec = Math.round((Date.now() - scanStartedAt) / 1000);
       ctx.send(ws, {
         type: 'qualityScanProgress',
-        data: { path: reportPath, progress },
+        data: {
+          path: reportPath,
+          progress: { ...lastProgress, etaMs, startedAt: scanStartedAt, detail: `${elapsedSec}s elapsed` },
+        },
       });
-    }, installedToolNames);
+    }, 5_000);
+
+    let results: Awaited<ReturnType<typeof runQualityScan>>;
+    try {
+      results = await runQualityScan(dirPath, (progress) => {
+        lastProgress = progress;
+        ctx.send(ws, {
+          type: 'qualityScanProgress',
+          data: {
+            path: reportPath,
+            progress: { ...progress, etaMs, startedAt: scanStartedAt },
+          },
+        });
+      }, installedToolNames, controller.signal);
+    } finally {
+      clearInterval(heartbeat);
+    }
+
+    // Annotate the report with the wall-clock duration so subsequent scans
+    // of this directory have real history to base their ETA on. Same pattern
+    // applies for the AI review duration written by the review agent.
+    const scanDurationMs = Date.now() - scanStartedAt;
+    results.scanDurationMs = scanDurationMs;
 
     // Persist before sending — results survive if WebSocket drops
     try {
@@ -267,11 +406,17 @@ async function handleScan(
       });
     }
   } catch (error) {
+    if (error instanceof QualityScanAbortedError) {
+      // Cancellation already broadcast a `qualityError` from `handleCancel`.
+      // Don't send a second error message.
+      return;
+    }
     ctx.send(ws, {
       type: 'qualityError',
       data: { path: reportPath, error: error instanceof Error ? error.message : String(error) },
     });
   } finally {
+    operationRegistry.finish(workingDir, reportPath);
     persistence.clearActiveOperation(reportPath);
   }
 }

package/server/services/websocket/quality-linting.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { relative } from 'node:path';
 import { chunkFileList, filesByExt, runCommand, type SourceFile } from './quality-tools.js';

package/server/services/websocket/quality-operations.ts

@@ -0,0 +1,72 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Quality Operation Registry — in-process tracking of in-flight scans and
+ * code reviews so they can be cancelled (or detected as orphaned) without
+ * depending on durable state.
+ *
+ * Persistence (`.mstro/quality/active-ops.json`) survives a CLI restart but
+ * has no live `AbortController` to cancel; this registry holds the controllers
+ * for the current process. The two layers are deliberately decoupled — when a
+ * persisted op exists with no registry entry, callers know the op is orphaned.
+ */
+
+export type OperationKind = 'scanning' | 'reviewing';
+
+interface RegisteredOperation {
+  controller: AbortController;
+  kind: OperationKind;
+  startedAt: number;
+}
+
+export class OperationRegistry {
+  private readonly ops = new Map<string, RegisteredOperation>();
+
+  private key(workingDir: string, path: string): string {
+    return `${workingDir}::${path}`;
+  }
+
+  /**
+   * Reserve an operation slot and return its `AbortController`. Throws when
+   * the same `(workingDir, path)` pair is already in flight — callers should
+   * surface this to the user as "already running" rather than silently
+   * starting a second worker.
+   */
+  start(workingDir: string, path: string, kind: OperationKind): AbortController {
+    const k = this.key(workingDir, path);
+    if (this.ops.has(k)) {
+      throw new Error(`Operation already in flight: ${kind} ${path}`);
+    }
+    const controller = new AbortController();
+    this.ops.set(k, { controller, kind, startedAt: Date.now() });
+    return controller;
+  }
+
+  /**
+   * Cancel an in-flight operation. Returns `true` when an op was found and
+   * aborted, `false` when nothing was registered (the caller should still
+   * clear persistence — the op is either already finished or was orphaned).
+   */
+  cancel(workingDir: string, path: string): boolean {
+    const k = this.key(workingDir, path);
+    const op = this.ops.get(k);
+    if (!op) return false;
+    op.controller.abort();
+    return true;
+  }
+
+  finish(workingDir: string, path: string): void {
+    this.ops.delete(this.key(workingDir, path));
+  }
+
+  has(workingDir: string, path: string): boolean {
+    return this.ops.has(this.key(workingDir, path));
+  }
+
+  /** Kind of the live operation, or null when nothing is registered. */
+  getKind(workingDir: string, path: string): OperationKind | null {
+    return this.ops.get(this.key(workingDir, path))?.kind ?? null;
+  }
+}
+
+export const operationRegistry = new OperationRegistry();

package/server/services/websocket/quality-persistence.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Quality Persistence — Persists quality config, reports, and history
@@ -13,6 +12,7 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { gradeFromScore } from './quality-grading.js';
 import type { QualityResults } from './quality-service.js';
 
 // ============================================================================
@@ -46,7 +46,21 @@ export interface QualityHistoryEntry {
   grade: string;
   issueDensity?: number;
   categoryScores?: HistoryCategoryScore[];
+  dimensionScores?: {
+    security: { score: number; grade: string };
+    reliability: { score: number; grade: string };
+    maintainability: { score: number; grade: string };
+  };
   directories: HistoryDirectoryEntry[];
+  /**
+   * Wall-clock duration of the CLI scan that produced this entry, in
+   * milliseconds. Older entries persisted before the ETA rollout will not
+   * include this field, in which case the ETA estimator falls back to the
+   * heuristic until enough samples accumulate.
+   */
+  scanDurationMs?: number;
+  /** Wall-clock duration of the AI review pass, when one ran for this entry. */
+  reviewDurationMs?: number;
 }
 
 interface QualityHistory {
@@ -232,6 +246,7 @@ export class QualityPersistence {
       : undefined;
 
     const issueDensity = results.scoreBreakdown?.issueDensity;
+    const dimensionScores = extractDimensionScores(results);
 
     if (lastEntry && now.getTime() - lastTime < mergeWindow) {
       const existing = lastEntry.directories.findIndex((d) => d.path === dirPath);
@@ -242,10 +257,21 @@ export class QualityPersistence {
       }
       const totalScore = lastEntry.directories.reduce((sum, d) => sum + d.score, 0);
       lastEntry.overall = Math.round(totalScore / lastEntry.directories.length);
-      lastEntry.grade = gradeFromScore(lastEntry.overall);
+      // Preserve N/A when every directory is N/A; otherwise map averaged score
+      // back to a letter. `gradeFromScore` returns A-F only, so this is the
+      // only place the N/A signal could be lost during multi-directory merges.
+      const allNA = lastEntry.directories.every((d) => d.grade === 'N/A');
+      lastEntry.grade = allNA ? 'N/A' : gradeFromScore(lastEntry.overall);
       lastEntry.timestamp = now.toISOString();
       if (categoryScores) lastEntry.categoryScores = categoryScores;
       if (issueDensity !== undefined) lastEntry.issueDensity = issueDensity;
+      if (dimensionScores) lastEntry.dimensionScores = dimensionScores;
+      // Carry through whichever duration is present on this report. We
+      // overwrite — the latest scan/review is the most accurate sample for
+      // this directory. (Multi-dir merges within the 60s window write each
+      // dir's duration in turn; the final entry reflects the last write.)
+      if (typeof results.scanDurationMs === 'number') lastEntry.scanDurationMs = results.scanDurationMs;
+      if (typeof results.reviewDurationMs === 'number') lastEntry.reviewDurationMs = results.reviewDurationMs;
     } else {
       history.push({
         timestamp: now.toISOString(),
@@ -253,7 +279,10 @@ export class QualityPersistence {
         grade: results.grade,
         issueDensity,
         categoryScores,
+        dimensionScores,
         directories: [dirEntry],
+        scanDurationMs: results.scanDurationMs,
+        reviewDurationMs: results.reviewDurationMs,
       });
     }
 
@@ -361,10 +390,20 @@ export class QualityPersistence {
   }
 }
 
-function gradeFromScore(score: number): string {
-  if (score >= 90) return 'A';
-  if (score >= 80) return 'B';
-  if (score >= 70) return 'C';
-  if (score >= 60) return 'D';
-  return 'F';
+// Snapshot per-dimension scores when the new rating fields are present.
+// Older `QualityResults` objects (e.g., loaded from pre-redesign reports)
+// omit `dimensions`, in which case we return undefined so old history rows
+// continue to round-trip without synthesized data.
+function extractDimensionScores(results: QualityResults): QualityHistoryEntry['dimensionScores'] | undefined {
+  if (!results.dimensions) return undefined;
+  const byName = new Map(results.dimensions.map((d) => [d.name, d]));
+  const sec = byName.get('security');
+  const rel = byName.get('reliability');
+  const maint = byName.get('maintainability');
+  if (!sec || !rel || !maint) return undefined;
+  return {
+    security: { score: sec.score, grade: sec.grade },
+    reliability: { score: rel.score, grade: rel.grade },
+    maintainability: { score: maint.score, grade: maint.grade },
+  };
 }