@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/devtools.ts

@@ -0,0 +1,1143 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { type CommandContext, type CommandResult } from "./registry";
+
+type DevtoolsFormat = "text" | "json";
+type PanelStatus = "ok" | "warn";
+type DevtoolsPanelName = "explain" | "waterfall" | "performance" | "realtime" | "auth";
+
+interface DevtoolsOptions {
+  inputPath: string;
+  format: DevtoolsFormat;
+  selectedPanels: readonly DevtoolsPanelName[];
+  maxWaterfallBlockingMs: number;
+  maxLagP95Ms: number;
+  maxDropRatio: number;
+  minRouteScore: number;
+}
+
+interface PanelIssue {
+  code: string;
+  message: string;
+}
+
+interface DevtoolsExplainPanel {
+  name: "explain";
+  status: PanelStatus;
+  module: string;
+  queries: number;
+  actions: number;
+  realtimeQueries: number;
+  warnings: readonly string[];
+  authCoverage: {
+    queryAuth: readonly string[];
+    actionAuth: readonly string[];
+    missingQueryAuth: number;
+    missingActionAuth: number;
+  };
+  issues: readonly PanelIssue[];
+}
+
+interface WaterfallPhase {
+  name: string;
+  durationMs: number;
+}
+
+interface WaterfallOperation {
+  name: string;
+  kind: string;
+  startMs: number;
+  durationMs: number;
+  blocking: boolean;
+}
+
+interface DevtoolsWaterfallPanel {
+  name: "waterfall";
+  status: PanelStatus;
+  requestId?: string;
+  operations: number;
+  totalDurationMs: number;
+  sequentialOperations: number;
+  parallelOperations: number;
+  blockingOverThreshold: number;
+  longestOperation?: {
+    name: string;
+    kind: string;
+    durationMs: number;
+  };
+  phases: readonly WaterfallPhase[];
+  issues: readonly PanelIssue[];
+}
+
+interface PerformanceRouteScore {
+  route: string;
+  score: number;
+  jsBytes: number;
+  payloadBytes: number;
+  lcpMs: number;
+  notes: readonly string[];
+}
+
+interface DevtoolsPerformancePanel {
+  name: "performance";
+  status: PanelStatus;
+  averageScore: number;
+  minimumScore: number;
+  routes: readonly PerformanceRouteScore[];
+  issues: readonly PanelIssue[];
+}
+
+interface RealtimeSubscriptionSummary {
+  tag: string;
+  channel: string;
+  state: string;
+  authScope: string;
+}
+
+interface DevtoolsRealtimePanel {
+  name: "realtime";
+  status: PanelStatus;
+  connectionState: string;
+  eventsPerSecond: number;
+  lagP95Ms: number;
+  droppedRatio: number;
+  activeSubscriptions: number;
+  authScopedSubscriptions: Record<string, number>;
+  subscriptions: readonly RealtimeSubscriptionSummary[];
+  issues: readonly PanelIssue[];
+}
+
+interface DevtoolsAuthPanel {
+  name: "auth";
+  status: PanelStatus;
+  sessionStatus: string;
+  routeAuth: string;
+  userId?: string;
+  role?: string;
+  permissions: readonly string[];
+  tokenExpiresInSec?: number;
+  issues: readonly PanelIssue[];
+}
+
+type DevtoolsPanel =
+  | DevtoolsExplainPanel
+  | DevtoolsWaterfallPanel
+  | DevtoolsPerformancePanel
+  | DevtoolsRealtimePanel
+  | DevtoolsAuthPanel;
+
+interface DevtoolsReport {
+  mode: "devtools";
+  schemaVersion: 1;
+  projectRoot: string;
+  inputPath: string;
+  status: PanelStatus;
+  selectedPanels: readonly DevtoolsPanelName[];
+  panels: readonly DevtoolsPanel[];
+}
+
+const VALID_PANELS: readonly DevtoolsPanelName[] = [
+  "explain",
+  "waterfall",
+  "performance",
+  "realtime",
+  "auth",
+];
+
+const DEFAULT_MAX_WATERFALL_BLOCKING_MS = 120;
+const DEFAULT_MAX_LAG_P95_MS = 250;
+const DEFAULT_MAX_DROP_RATIO = 0.05;
+const DEFAULT_MIN_ROUTE_SCORE = 80;
+
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function isCommandResult(value: unknown): value is CommandResult {
+  const source = toRecord(value);
+  return Boolean(source && typeof source.exitCode === "number");
+}
+
+function parseNonNegativeNumber(raw: string | undefined, flag: string): number | CommandResult {
+  if (!raw) {
+    return {
+      exitCode: 2,
+      stderr: `aurora devtools: ${flag} requires a numeric value`,
+    };
+  }
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return {
+      exitCode: 2,
+      stderr: `aurora devtools: ${flag} must be a non-negative number`,
+    };
+  }
+
+  return parsed;
+}
+
+function parsePanelSelection(raw: string | undefined): readonly DevtoolsPanelName[] | CommandResult {
+  if (!raw) {
+    return {
+      exitCode: 2,
+      stderr: "aurora devtools: --panel requires one or more panel names",
+    };
+  }
+
+  const tokens = raw
+    .split(",")
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+
+  if (tokens.length === 0) {
+    return {
+      exitCode: 2,
+      stderr: "aurora devtools: --panel requires one or more panel names",
+    };
+  }
+
+  const unique = new Set<DevtoolsPanelName>();
+  for (const token of tokens) {
+    if (!VALID_PANELS.includes(token as DevtoolsPanelName)) {
+      return {
+        exitCode: 2,
+        stderr:
+          `aurora devtools: invalid panel '${token}'. ` +
+          `Expected one of ${VALID_PANELS.join(", ")}`,
+      };
+    }
+
+    unique.add(token as DevtoolsPanelName);
+  }
+
+  return [...unique];
+}
+
+function parseDevtoolsOptions(args: ReadonlyArray<string>): DevtoolsOptions | CommandResult {
+  const selected = new Set<DevtoolsPanelName>();
+  const options: DevtoolsOptions = {
+    inputPath: "",
+    format: "text",
+    selectedPanels: VALID_PANELS,
+    maxWaterfallBlockingMs: DEFAULT_MAX_WATERFALL_BLOCKING_MS,
+    maxLagP95Ms: DEFAULT_MAX_LAG_P95_MS,
+    maxDropRatio: DEFAULT_MAX_DROP_RATIO,
+    minRouteScore: DEFAULT_MIN_ROUTE_SCORE,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--input") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr: "aurora devtools: --input requires a path value",
+        };
+      }
+
+      options.inputPath = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--format") {
+      const value = args[i + 1];
+      if (!value) {
+        return {
+          exitCode: 2,
+          stderr: "aurora devtools: --format requires 'text' or 'json'",
+        };
+      }
+
+      if (value !== "text" && value !== "json") {
+        return {
+          exitCode: 2,
+          stderr: `aurora devtools: invalid format '${value}'. Expected 'text' or 'json'`,
+        };
+      }
+
+      options.format = value;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--panel") {
+      const parsedPanels = parsePanelSelection(args[i + 1]);
+      if (isCommandResult(parsedPanels)) {
+        return parsedPanels;
+      }
+
+      for (const panel of parsedPanels) {
+        selected.add(panel);
+      }
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--max-waterfall-blocking-ms") {
+      const parsed = parseNonNegativeNumber(args[i + 1], "--max-waterfall-blocking-ms");
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+      options.maxWaterfallBlockingMs = parsed;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--max-lag-p95-ms") {
+      const parsed = parseNonNegativeNumber(args[i + 1], "--max-lag-p95-ms");
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+      options.maxLagP95Ms = parsed;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--max-drop-ratio") {
+      const parsed = parseNonNegativeNumber(args[i + 1], "--max-drop-ratio");
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+      options.maxDropRatio = parsed;
+      i += 1;
+      continue;
+    }
+
+    if (arg === "--min-route-score") {
+      const parsed = parseNonNegativeNumber(args[i + 1], "--min-route-score");
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+      options.minRouteScore = parsed;
+      i += 1;
+      continue;
+    }
+
+    return {
+      exitCode: 2,
+      stderr: `aurora devtools: unknown option '${arg}'`,
+    };
+  }
+
+  if (!options.inputPath) {
+    return {
+      exitCode: 2,
+      stderr: "aurora devtools: --input is required",
+    };
+  }
+
+  if (selected.size > 0) {
+    options.selectedPanels = [...selected];
+  }
+
+  return options;
+}
+
+function readInputJson(inputPath: string, context: CommandContext): unknown | CommandResult {
+  const absolutePath = resolve(context.cwd, inputPath);
+  let raw = "";
+
+  try {
+    raw = readFileSync(absolutePath, "utf8");
+  } catch {
+    return {
+      exitCode: 1,
+      stderr: `aurora devtools: unable to read input at ${inputPath}`,
+    };
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {
+      exitCode: 1,
+      stderr: `aurora devtools: invalid json input at ${inputPath}`,
+    };
+  }
+}
+
+function parseOptionalString(
+  source: Record<string, unknown>,
+  fields: ReadonlyArray<string>,
+): string | undefined {
+  for (const field of fields) {
+    const value = source[field];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+
+  return undefined;
+}
+
+function parseOptionalNumber(
+  source: Record<string, unknown>,
+  fields: ReadonlyArray<string>,
+): number | undefined {
+  for (const field of fields) {
+    const value = source[field];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+function parseRequiredString(
+  source: Record<string, unknown>,
+  fields: ReadonlyArray<string>,
+  label: string,
+): string {
+  const parsed = parseOptionalString(source, fields);
+  if (!parsed) {
+    throw new Error(`${label} is required`);
+  }
+
+  return parsed;
+}
+
+function parseRequiredNonNegativeNumber(
+  source: Record<string, unknown>,
+  fields: ReadonlyArray<string>,
+  label: string,
+): number {
+  const parsed = parseOptionalNumber(source, fields);
+  if (parsed === undefined || parsed < 0) {
+    throw new Error(`${label} must be a non-negative number`);
+  }
+
+  return parsed;
+}
+
+function parseStringArray(raw: unknown): string[] {
+  if (typeof raw === "string") {
+    return raw.trim().length > 0 ? [raw.trim()] : [];
+  }
+
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+
+  const deduped = new Set<string>();
+  for (const value of raw) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      deduped.add(value.trim());
+    }
+  }
+
+  return [...deduped];
+}
+
+function parseFieldValueAsString(raw: unknown): string | undefined {
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return raw.trim();
+  }
+
+  const source = toRecord(raw);
+  if (!source) {
+    return undefined;
+  }
+
+  const value = source.value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+
+  return undefined;
+}
+
+function buildExplainPanel(rawPanel: unknown): DevtoolsExplainPanel {
+  const source = toRecord(rawPanel);
+  if (!source) {
+    throw new Error("panel 'explain' must be an object");
+  }
+
+  const modulePath = parseOptionalString(source, ["module", "modulePath"]) ?? "unknown";
+  const queryEntries = Array.isArray(source.queries) ? source.queries : [];
+  const actionEntries = Array.isArray(source.actions) ? source.actions : [];
+  const warnings = parseStringArray(source.warnings);
+
+  let realtimeQueries = 0;
+  let missingQueryAuth = 0;
+  let missingActionAuth = 0;
+  const queryAuth = new Set<string>();
+  const actionAuth = new Set<string>();
+
+  for (const entry of queryEntries) {
+    const record = toRecord(entry);
+    if (!record) {
+      continue;
+    }
+
+    const auth = parseFieldValueAsString(record.auth);
+    if (auth) {
+      queryAuth.add(auth);
+    } else {
+      missingQueryAuth += 1;
+    }
+
+    const realtime = parseFieldValueAsString(record.realtime);
+    if (realtime && realtime !== "none") {
+      realtimeQueries += 1;
+    }
+  }
+
+  for (const entry of actionEntries) {
+    const record = toRecord(entry);
+    if (!record) {
+      continue;
+    }
+
+    const auth = parseFieldValueAsString(record.auth);
+    if (auth) {
+      actionAuth.add(auth);
+    } else {
+      missingActionAuth += 1;
+    }
+  }
+
+  const issues: PanelIssue[] = [];
+  if (warnings.length > 0) {
+    issues.push({
+      code: "EXPLAIN_WARNINGS_PRESENT",
+      message: `explain snapshot includes ${warnings.length} warning(s)`,
+    });
+  }
+  if (missingQueryAuth > 0) {
+    issues.push({
+      code: "QUERY_AUTH_MISSING",
+      message: `${missingQueryAuth} query entry(ies) missing auth visibility`,
+    });
+  }
+  if (missingActionAuth > 0) {
+    issues.push({
+      code: "ACTION_AUTH_MISSING",
+      message: `${missingActionAuth} action entry(ies) missing auth visibility`,
+    });
+  }
+
+  return {
+    name: "explain",
+    status: issues.length > 0 ? "warn" : "ok",
+    module: modulePath,
+    queries: queryEntries.length,
+    actions: actionEntries.length,
+    realtimeQueries,
+    warnings,
+    authCoverage: {
+      queryAuth: [...queryAuth].sort(),
+      actionAuth: [...actionAuth].sort(),
+      missingQueryAuth,
+      missingActionAuth,
+    },
+    issues,
+  };
+}
+
+function parseWaterfallPhase(raw: unknown, index: number): WaterfallPhase {
+  const source = toRecord(raw);
+  if (!source) {
+    throw new Error(`waterfall.phases[${index}] must be an object`);
+  }
+
+  return {
+    name: parseRequiredString(source, ["name", "phase"], `waterfall.phases[${index}].name`),
+    durationMs: parseRequiredNonNegativeNumber(
+      source,
+      ["durationMs", "duration", "ms"],
+      `waterfall.phases[${index}].durationMs`,
+    ),
+  };
+}
+
+function parseWaterfallOperation(raw: unknown, index: number): WaterfallOperation {
+  const source = toRecord(raw);
+  if (!source) {
+    throw new Error(`waterfall.operations[${index}] must be an object`);
+  }
+
+  const kind = parseOptionalString(source, ["kind", "type"]) ?? "unknown";
+  const isBlockingByDefault = kind === "query" || kind === "action";
+
+  return {
+    name: parseRequiredString(source, ["name", "operation"], `waterfall.operations[${index}].name`),
+    kind,
+    startMs: parseRequiredNonNegativeNumber(
+      source,
+      ["startMs", "start", "startedAtMs"],
+      `waterfall.operations[${index}].startMs`,
+    ),
+    durationMs: parseRequiredNonNegativeNumber(
+      source,
+      ["durationMs", "duration", "ms"],
+      `waterfall.operations[${index}].durationMs`,
+    ),
+    blocking:
+      typeof source.blocking === "boolean"
+        ? source.blocking
+        : isBlockingByDefault,
+  };
+}
+
+function buildWaterfallPanel(
+  rawPanel: unknown,
+  options: DevtoolsOptions,
+): DevtoolsWaterfallPanel {
+  const source = toRecord(rawPanel);
+  if (!source) {
+    throw new Error("panel 'waterfall' must be an object");
+  }
+
+  const rawOperations = Array.isArray(source.operations) ? source.operations : [];
+  const operations = rawOperations.map((entry, index) => parseWaterfallOperation(entry, index));
+  const sortedOperations = [...operations].sort((left, right) => {
+    if (left.startMs !== right.startMs) {
+      return left.startMs - right.startMs;
+    }
+    return left.name.localeCompare(right.name);
+  });
+  const phases = Array.isArray(source.phases)
+    ? source.phases.map((phase, index) => parseWaterfallPhase(phase, index))
+    : [];
+
+  const issues: PanelIssue[] = [];
+  if (sortedOperations.length === 0) {
+    issues.push({
+      code: "NO_OPERATIONS",
+      message: "waterfall panel requires at least one operation",
+    });
+  }
+
+  let sequentialOperations = 0;
+  let parallelOperations = 0;
+  for (let index = 1; index < sortedOperations.length; index += 1) {
+    const previous = sortedOperations[index - 1];
+    const current = sortedOperations[index];
+    const previousEnd = previous.startMs + previous.durationMs;
+    if (current.startMs >= previousEnd) {
+      sequentialOperations += 1;
+    } else {
+      parallelOperations += 1;
+    }
+  }
+
+  const blockingOverThreshold = sortedOperations.filter(
+    (operation) => operation.blocking && operation.durationMs > options.maxWaterfallBlockingMs,
+  ).length;
+  if (blockingOverThreshold > 0) {
+    issues.push({
+      code: "BLOCKING_OPERATION_SLOW",
+      message:
+        `${blockingOverThreshold} blocking operation(s) exceed ` +
+        `${options.maxWaterfallBlockingMs}ms`,
+    });
+  }
+
+  if (sequentialOperations > parallelOperations && sortedOperations.length >= 3) {
+    issues.push({
+      code: "SEQUENTIAL_CHAIN_DETECTED",
+      message: "sequential operations dominate request timeline",
+    });
+  }
+
+  const minStart = sortedOperations[0]?.startMs ?? 0;
+  const maxEnd = sortedOperations.reduce(
+    (latest, operation) => Math.max(latest, operation.startMs + operation.durationMs),
+    minStart,
+  );
+  const totalDurationMs = maxEnd - minStart;
+
+  const longestOperation = sortedOperations.reduce<WaterfallOperation | undefined>(
+    (longest, operation) => {
+      if (!longest || operation.durationMs > longest.durationMs) {
+        return operation;
+      }
+
+      return longest;
+    },
+    undefined,
+  );
+
+  return {
+    name: "waterfall",
+    status: issues.length > 0 ? "warn" : "ok",
+    requestId: parseOptionalString(source, ["requestId", "request"]),
+    operations: sortedOperations.length,
+    totalDurationMs,
+    sequentialOperations,
+    parallelOperations,
+    blockingOverThreshold,
+    longestOperation: longestOperation
+      ? {
+          name: longestOperation.name,
+          kind: longestOperation.kind,
+          durationMs: longestOperation.durationMs,
+        }
+      : undefined,
+    phases,
+    issues,
+  };
+}
+
+function computeRouteScore(
+  jsBytes: number,
+  payloadBytes: number,
+  lcpMs: number,
+): number {
+  const jsPenalty = Math.max(0, jsBytes - 50_000) / 5_000;
+  const payloadPenalty = Math.max(0, payloadBytes - 4_000) / 500;
+  const lcpPenalty = Math.max(0, lcpMs - 250) / 35;
+  const score = 100 - (jsPenalty + payloadPenalty + lcpPenalty);
+  return Math.round(Math.max(0, Math.min(100, score)));
+}
+
+function buildPerformancePanel(
+  rawPanel: unknown,
+  options: DevtoolsOptions,
+): DevtoolsPerformancePanel {
+  const source = toRecord(rawPanel);
+  if (!source) {
+    throw new Error("panel 'performance' must be an object");
+  }
+
+  const rawRoutes = Array.isArray(source.routes) ? source.routes : [];
+  const routes: PerformanceRouteScore[] = rawRoutes.map((entry, index) => {
+    const routeSource = toRecord(entry);
+    if (!routeSource) {
+      throw new Error(`performance.routes[${index}] must be an object`);
+    }
+
+    const route = parseRequiredString(routeSource, ["route", "path"], `performance.routes[${index}].route`);
+    const jsBytes = parseRequiredNonNegativeNumber(
+      routeSource,
+      ["jsBytes", "bundleBytes", "bundle"],
+      `performance.routes[${index}].jsBytes`,
+    );
+    const payloadBytes = parseRequiredNonNegativeNumber(
+      routeSource,
+      ["payloadBytes", "dataBytes", "payload"],
+      `performance.routes[${index}].payloadBytes`,
+    );
+    const lcpMs = parseRequiredNonNegativeNumber(
+      routeSource,
+      ["lcpMs", "lcp", "lcpEstimateMs"],
+      `performance.routes[${index}].lcpMs`,
+    );
+
+    const notes: string[] = [];
+    if (jsBytes > 150_000) {
+      notes.push("large bundle");
+    }
+    if (payloadBytes > 20_000) {
+      notes.push("large payload");
+    }
+    if (lcpMs > 700) {
+      notes.push("slow LCP");
+    }
+
+    return {
+      route,
+      score: computeRouteScore(jsBytes, payloadBytes, lcpMs),
+      jsBytes,
+      payloadBytes,
+      lcpMs,
+      notes,
+    };
+  });
+
+  const issues: PanelIssue[] = [];
+  if (routes.length === 0) {
+    issues.push({
+      code: "NO_ROUTES",
+      message: "performance panel requires routes[]",
+    });
+  }
+
+  const lowRoutes = routes.filter((route) => route.score < options.minRouteScore);
+  if (lowRoutes.length > 0) {
+    issues.push({
+      code: "ROUTE_SCORE_BELOW_MIN",
+      message:
+        `${lowRoutes.length} route(s) below score ${options.minRouteScore}: ` +
+        `${lowRoutes.map((route) => route.route).join(", ")}`,
+    });
+  }
+
+  const averageScore =
+    routes.length === 0
+      ? 0
+      : Math.round(routes.reduce((total, route) => total + route.score, 0) / routes.length);
+  const minimumScore =
+    routes.length === 0
+      ? 0
+      : routes.reduce((lowest, route) => Math.min(lowest, route.score), routes[0]?.score ?? 0);
+
+  return {
+    name: "performance",
+    status: issues.length > 0 ? "warn" : "ok",
+    averageScore,
+    minimumScore,
+    routes,
+    issues,
+  };
+}
+
+function buildRealtimePanel(
+  rawPanel: unknown,
+  options: DevtoolsOptions,
+): DevtoolsRealtimePanel {
+  const source = toRecord(rawPanel);
+  if (!source) {
+    throw new Error("panel 'realtime' must be an object");
+  }
+
+  const connectionState = parseOptionalString(source, ["connectionState", "state"]) ?? "unknown";
+  const eventsPerSecond =
+    parseOptionalNumber(source, ["eventsPerSecond", "deliveredRps", "rps"]) ?? 0;
+  const lagP95Ms = parseOptionalNumber(source, ["lagP95Ms", "p95"]) ?? 0;
+  const droppedRatio = parseOptionalNumber(source, ["droppedRatio", "dropRatio"]) ?? 0;
+
+  const rawSubscriptions = Array.isArray(source.subscriptions) ? source.subscriptions : [];
+  const subscriptions: RealtimeSubscriptionSummary[] = rawSubscriptions.map((entry, index) => {
+    const subscription = toRecord(entry);
+    if (!subscription) {
+      throw new Error(`realtime.subscriptions[${index}] must be an object`);
+    }
+
+    const tag = parseRequiredString(
+      subscription,
+      ["tag", "topic"],
+      `realtime.subscriptions[${index}].tag`,
+    );
+
+    return {
+      tag,
+      channel: parseOptionalString(subscription, ["channel"]) ?? "-",
+      state: parseOptionalString(subscription, ["state"]) ?? "active",
+      authScope: parseOptionalString(subscription, ["authScope", "auth", "scope"]) ?? "unscoped",
+    };
+  });
+
+  const authScopedSubscriptions: Record<string, number> = {};
+  for (const subscription of subscriptions) {
+    authScopedSubscriptions[subscription.authScope] =
+      (authScopedSubscriptions[subscription.authScope] ?? 0) + 1;
+  }
+
+  const activeSubscriptions = subscriptions.filter((subscription) => subscription.state === "active").length;
+  const unscopedSubscriptions = subscriptions.filter(
+    (subscription) => subscription.authScope === "unscoped",
+  ).length;
+
+  const issues: PanelIssue[] = [];
+  if (connectionState !== "connected") {
+    issues.push({
+      code: "CONNECTION_UNSTABLE",
+      message: `connection state is '${connectionState}'`,
+    });
+  }
+  if (lagP95Ms > options.maxLagP95Ms) {
+    issues.push({
+      code: "LAG_P95_EXCEEDED",
+      message: `lag p95 ${lagP95Ms}ms exceeds ${options.maxLagP95Ms}ms`,
+    });
+  }
+  if (droppedRatio > options.maxDropRatio) {
+    issues.push({
+      code: "DROP_RATIO_EXCEEDED",
+      message: `drop ratio ${droppedRatio.toFixed(4)} exceeds ${options.maxDropRatio.toFixed(4)}`,
+    });
+  }
+  if (unscopedSubscriptions > 0) {
+    issues.push({
+      code: "SUBSCRIPTION_AUTH_SCOPE_MISSING",
+      message: `${unscopedSubscriptions} subscription(s) missing auth scope`,
+    });
+  }
+
+  return {
+    name: "realtime",
+    status: issues.length > 0 ? "warn" : "ok",
+    connectionState,
+    eventsPerSecond,
+    lagP95Ms,
+    droppedRatio,
+    activeSubscriptions,
+    authScopedSubscriptions,
+    subscriptions,
+    issues,
+  };
+}
+
+function buildAuthPanel(rawPanel: unknown): DevtoolsAuthPanel {
+  const source = toRecord(rawPanel);
+  if (!source) {
+    throw new Error("panel 'auth' must be an object");
+  }
+
+  const sessionStatus = parseOptionalString(source, ["sessionStatus", "session"]) ?? "missing";
+  const routeAuth = parseOptionalString(source, ["routeAuth", "requiredAuth"]) ?? "public";
+  const userId = parseOptionalString(source, ["userId", "user"]);
+  const role = parseOptionalString(source, ["role"]);
+  const permissions = parseStringArray(source.permissions).sort();
+  const tokenExpiresInSec = parseOptionalNumber(source, ["tokenExpiresInSec", "ttlSeconds"]);
+
+  const issues: PanelIssue[] = [];
+  const isPublicRoute = routeAuth === "public" || routeAuth === "none";
+  if (!isPublicRoute && sessionStatus !== "active") {
+    issues.push({
+      code: "ROUTE_AUTH_SESSION_MISMATCH",
+      message: `route requires '${routeAuth}' auth but session is '${sessionStatus}'`,
+    });
+  }
+  if (sessionStatus === "active" && !role) {
+    issues.push({
+      code: "ROLE_MISSING",
+      message: "active session is missing role visibility",
+    });
+  }
+  if (tokenExpiresInSec !== undefined && tokenExpiresInSec < 300) {
+    issues.push({
+      code: "TOKEN_EXPIRING_SOON",
+      message: `token expires in ${Math.trunc(tokenExpiresInSec)} seconds`,
+    });
+  }
+
+  return {
+    name: "auth",
+    status: issues.length > 0 ? "warn" : "ok",
+    sessionStatus,
+    routeAuth,
+    userId,
+    role,
+    permissions,
+    tokenExpiresInSec,
+    issues,
+  };
+}
+
+function buildPanel(
+  panelName: DevtoolsPanelName,
+  payload: Record<string, unknown>,
+  options: DevtoolsOptions,
+): DevtoolsPanel {
+  const rawPanel = payload[panelName];
+  if (rawPanel === undefined) {
+    throw new Error(`panel '${panelName}' input is missing from payload`);
+  }
+
+  if (panelName === "explain") {
+    return buildExplainPanel(rawPanel);
+  }
+  if (panelName === "waterfall") {
+    return buildWaterfallPanel(rawPanel, options);
+  }
+  if (panelName === "performance") {
+    return buildPerformancePanel(rawPanel, options);
+  }
+  if (panelName === "realtime") {
+    return buildRealtimePanel(rawPanel, options);
+  }
+  return buildAuthPanel(rawPanel);
+}
+
+function buildDevtoolsReport(
+  options: DevtoolsOptions,
+  context: CommandContext,
+): DevtoolsReport | CommandResult {
+  const payload = readInputJson(options.inputPath, context);
+  if (isCommandResult(payload)) {
+    return payload;
+  }
+
+  const source = toRecord(payload);
+  if (!source) {
+    return {
+      exitCode: 1,
+      stderr: "aurora devtools: input payload must be an object",
+    };
+  }
+
+  const schemaVersion = source.schemaVersion;
+  if (schemaVersion !== 1) {
+    return {
+      exitCode: 1,
+      stderr: `aurora devtools: unsupported schemaVersion ${String(schemaVersion)}; expected 1`,
+    };
+  }
+
+  const panels: DevtoolsPanel[] = [];
+  try {
+    for (const panelName of options.selectedPanels) {
+      panels.push(buildPanel(panelName, source, options));
+    }
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stderr: `aurora devtools: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  const status: PanelStatus = panels.some((panel) => panel.status === "warn") ? "warn" : "ok";
+  return {
+    mode: "devtools",
+    schemaVersion: 1,
+    projectRoot: context.cwd,
+    inputPath: options.inputPath,
+    status,
+    selectedPanels: options.selectedPanels,
+    panels,
+  };
+}
+
+function renderIssues(issues: readonly PanelIssue[]): string[] {
+  if (issues.length === 0) {
+    return ["issues: none"];
+  }
+
+  const lines = ["issues:"];
+  for (const issue of issues) {
+    lines.push(`- [${issue.code}] ${issue.message}`);
+  }
+  return lines;
+}
+
+function renderPanelText(panel: DevtoolsPanel): string[] {
+  if (panel.name === "explain") {
+    return [
+      "[explain]",
+      `status: ${panel.status}`,
+      `module: ${panel.module}`,
+      `queries: ${panel.queries}`,
+      `actions: ${panel.actions}`,
+      `realtime_queries: ${panel.realtimeQueries}`,
+      `query_auth: ${panel.authCoverage.queryAuth.join(",") || "-"}`,
+      `action_auth: ${panel.authCoverage.actionAuth.join(",") || "-"}`,
+      `missing_query_auth: ${panel.authCoverage.missingQueryAuth}`,
+      `missing_action_auth: ${panel.authCoverage.missingActionAuth}`,
+      `warnings: ${panel.warnings.length}`,
+      ...renderIssues(panel.issues),
+    ];
+  }
+
+  if (panel.name === "waterfall") {
+    return [
+      "[waterfall]",
+      `status: ${panel.status}`,
+      `request_id: ${panel.requestId ?? "-"}`,
+      `operations: ${panel.operations}`,
+      `total_duration_ms: ${panel.totalDurationMs}`,
+      `sequential_operations: ${panel.sequentialOperations}`,
+      `parallel_operations: ${panel.parallelOperations}`,
+      `blocking_over_threshold: ${panel.blockingOverThreshold}`,
+      `longest_operation: ${panel.longestOperation?.name ?? "-"} ` +
+        `(${panel.longestOperation?.kind ?? "-"}, ${panel.longestOperation?.durationMs ?? 0}ms)`,
+      `phases: ${panel.phases.length}`,
+      ...renderIssues(panel.issues),
+    ];
+  }
+
+  if (panel.name === "performance") {
+    const lines = [
+      "[performance]",
+      `status: ${panel.status}`,
+      `average_score: ${panel.averageScore}`,
+      `minimum_score: ${panel.minimumScore}`,
+      `routes: ${panel.routes.length}`,
+      "route_scores:",
+    ];
+    for (const route of panel.routes) {
+      lines.push(
+        `- ${route.route} score=${route.score} js_bytes=${route.jsBytes} ` +
+          `payload_bytes=${route.payloadBytes} lcp_ms=${route.lcpMs} notes=${route.notes.join("|") || "-"}`,
+      );
+    }
+    lines.push(...renderIssues(panel.issues));
+    return lines;
+  }
+
+  if (panel.name === "realtime") {
+    const scopeSummary = Object.entries(panel.authScopedSubscriptions)
+      .sort((left, right) => left[0].localeCompare(right[0]))
+      .map(([scope, count]) => `${scope}:${count}`)
+      .join(",");
+    return [
+      "[realtime]",
+      `status: ${panel.status}`,
+      `connection_state: ${panel.connectionState}`,
+      `events_per_second: ${panel.eventsPerSecond.toFixed(2)}`,
+      `lag_p95_ms: ${panel.lagP95Ms}`,
+      `dropped_ratio: ${panel.droppedRatio.toFixed(4)}`,
+      `active_subscriptions: ${panel.activeSubscriptions}`,
+      `auth_scoped_subscriptions: ${scopeSummary || "-"}`,
+      `subscriptions: ${panel.subscriptions.length}`,
+      ...renderIssues(panel.issues),
+    ];
+  }
+
+  return [
+    "[auth]",
+    `status: ${panel.status}`,
+    `session_status: ${panel.sessionStatus}`,
+    `route_auth: ${panel.routeAuth}`,
+    `user_id: ${panel.userId ?? "-"}`,
+    `role: ${panel.role ?? "-"}`,
+    `permissions: ${panel.permissions.join(",") || "-"}`,
+    `token_expires_in_sec: ${panel.tokenExpiresInSec ?? "-"}`,
+    ...renderIssues(panel.issues),
+  ];
+}
+
+function renderDevtoolsText(report: DevtoolsReport): string {
+  const lines = [
+    "aurora devtools report",
+    `project_root: ${report.projectRoot}`,
+    `input_path: ${report.inputPath}`,
+    `status: ${report.status}`,
+    `panels: ${report.selectedPanels.join(",")}`,
+  ];
+
+  for (const panel of report.panels) {
+    lines.push("");
+    lines.push(...renderPanelText(panel));
+  }
+
+  return lines.join("\n");
+}
+
+export function runDevtoolsCommand(
+  args: ReadonlyArray<string>,
+  context: CommandContext,
+): CommandResult {
+  const options = parseDevtoolsOptions(args);
+  if (isCommandResult(options)) {
+    return options;
+  }
+
+  const report = buildDevtoolsReport(options, context);
+  if (isCommandResult(report)) {
+    return report;
+  }
+
+  const exitCode = report.status === "warn" ? 1 : 0;
+  if (options.format === "json") {
+    return {
+      exitCode,
+      stdout: JSON.stringify(report, null, 2),
+    };
+  }
+
+  return {
+    exitCode,
+    stdout: renderDevtoolsText(report),
+  };
+}