@sansavision/aurora 0.1.0-alpha.20260212.4

package/src/realtime-monitor.ts

@@ -0,0 +1,389 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { type CommandContext, type CommandResult } from "./registry";
+
+type RealtimeMonitorFormat = "text" | "json";
+type RealtimeMonitorStatus = "ok" | "warn";
+
+interface RealtimeMonitorOptions {
+  inputPath: string;
+  format: RealtimeMonitorFormat;
+  maxDropRatio: number;
+  maxLagP95Ms: number;
+  minDeliveredRps?: number;
+}
+
+interface RealtimeMonitorIssue {
+  code: "DROP_RATIO_EXCEEDED" | "LAG_P95_EXCEEDED" | "DELIVERED_RPS_BELOW_MIN";
+  message: string;
+}
+
+interface RealtimeMonitorReport {
+  mode: "realtime-monitor";
+  projectRoot: string;
+  inputPath: string;
+  status: RealtimeMonitorStatus;
+  received: number;
+  delivered: number;
+  dropped: number;
+  lagP95Ms: number;
+  windowSeconds: number;
+  deliveredRps: number;
+  droppedRps: number;
+  dropRatio: number;
+  thresholds: {
+    maxDropRatio: number;
+    maxLagP95Ms: number;
+    minDeliveredRps?: number;
+  };
+  issues: RealtimeMonitorIssue[];
+}
+
+const DEFAULT_MAX_DROP_RATIO = 0.05;
+const DEFAULT_MAX_LAG_P95_MS = 250;
+const DEFAULT_WINDOW_SECONDS = 60;
+
+function parseNonNegativeNumber(raw: string | undefined, flag: string): number | CommandResult {
+  if (!raw) {
+    return {
+      exitCode: 2,
+      stderr: `aurora monitor-realtime: ${flag} requires a numeric value`,
+    };
+  }
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return {
+      exitCode: 2,
+      stderr: `aurora monitor-realtime: ${flag} must be a non-negative number`,
+    };
+  }
+
+  return parsed;
+}
+
+function parseRealtimeMonitorOptions(args: ReadonlyArray<string>): RealtimeMonitorOptions | CommandResult {
+  const options: RealtimeMonitorOptions = {
+    inputPath: "",
+    format: "text",
+    maxDropRatio: DEFAULT_MAX_DROP_RATIO,
+    maxLagP95Ms: DEFAULT_MAX_LAG_P95_MS,
+  };
+
+  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 monitor-realtime: --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 monitor-realtime: --format requires 'text' or 'json'",
+        };
+      }
+
+      if (value !== "text" && value !== "json") {
+        return {
+          exitCode: 2,
+          stderr: `aurora monitor-realtime: invalid format '${value}'. Expected 'text' or 'json'`,
+        };
+      }
+
+      options.format = value;
+      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 === "--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 === "--min-delivered-rps") {
+      const parsed = parseNonNegativeNumber(args[i + 1], "--min-delivered-rps");
+      if (typeof parsed !== "number") {
+        return parsed;
+      }
+
+      options.minDeliveredRps = parsed;
+      i += 1;
+      continue;
+    }
+
+    return {
+      exitCode: 2,
+      stderr: `aurora monitor-realtime: unknown option '${arg}'`,
+    };
+  }
+
+  if (!options.inputPath) {
+    return {
+      exitCode: 2,
+      stderr: "aurora monitor-realtime: --input is required",
+    };
+  }
+
+  return options;
+}
+
+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 getRequiredNumber(source: Record<string, unknown>, fields: ReadonlyArray<string>): number {
+  for (const field of fields) {
+    const value = source[field];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+
+  throw new Error(`missing required numeric field (${fields.join(" or ")})`);
+}
+
+function getOptionalNumber(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 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 monitor-realtime: unable to read input at ${inputPath}`,
+    };
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {
+      exitCode: 1,
+      stderr: `aurora monitor-realtime: invalid json input at ${inputPath}`,
+    };
+  }
+}
+
+function assertSupportedSchemaVersion(payload: unknown): void {
+  const source = toRecord(payload);
+  if (!source) {
+    return;
+  }
+
+  const rawSchemaVersion = source.schemaVersion;
+  if (rawSchemaVersion === undefined) {
+    return;
+  }
+
+  if (rawSchemaVersion !== 1) {
+    throw new Error(`unsupported schemaVersion ${String(rawSchemaVersion)} for realtime input; expected 1`);
+  }
+}
+
+function buildRealtimeMonitorReport(
+  options: RealtimeMonitorOptions,
+  context: CommandContext,
+): RealtimeMonitorReport | CommandResult {
+  const payload = readInputJson(options.inputPath, context);
+  if (isCommandResult(payload)) {
+    return payload;
+  }
+
+  let source: Record<string, unknown>;
+  try {
+    assertSupportedSchemaVersion(payload);
+    source = toRecord(payload) ?? {};
+    if (!toRecord(payload)) {
+      throw new Error("realtime monitor input must be an object");
+    }
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: 1,
+      stderr: `aurora monitor-realtime: ${reason}`,
+    };
+  }
+
+  try {
+    const received = getRequiredNumber(source, ["received", "rx", "totalReceived"]);
+    const delivered = getRequiredNumber(source, ["delivered", "tx", "totalDelivered"]);
+    const dropped = getRequiredNumber(source, ["dropped", "totalDropped"]);
+    const lagP95Ms = getRequiredNumber(source, ["lagP95Ms", "p95"]);
+    const windowSeconds =
+      getOptionalNumber(source, ["windowSeconds", "windowSec", "intervalSec"]) ??
+      DEFAULT_WINDOW_SECONDS;
+
+    if (windowSeconds <= 0) {
+      throw new Error("windowSeconds must be a positive number");
+    }
+
+    const dropRatio = received > 0 ? dropped / received : 0;
+    const deliveredRps = delivered / windowSeconds;
+    const droppedRps = dropped / windowSeconds;
+    const issues: RealtimeMonitorIssue[] = [];
+
+    if (dropRatio > options.maxDropRatio) {
+      issues.push({
+        code: "DROP_RATIO_EXCEEDED",
+        message:
+          `drop ratio ${dropRatio.toFixed(4)} exceeds threshold ${options.maxDropRatio.toFixed(4)}`,
+      });
+    }
+
+    if (lagP95Ms > options.maxLagP95Ms) {
+      issues.push({
+        code: "LAG_P95_EXCEEDED",
+        message: `lag p95 ${lagP95Ms}ms exceeds threshold ${options.maxLagP95Ms}ms`,
+      });
+    }
+
+    if (options.minDeliveredRps !== undefined && deliveredRps < options.minDeliveredRps) {
+      issues.push({
+        code: "DELIVERED_RPS_BELOW_MIN",
+        message:
+          `delivered rps ${deliveredRps.toFixed(4)} is below minimum ` +
+          `${options.minDeliveredRps.toFixed(4)}`,
+      });
+    }
+
+    const status: RealtimeMonitorStatus = issues.length > 0 ? "warn" : "ok";
+
+    return {
+      mode: "realtime-monitor",
+      projectRoot: context.cwd,
+      inputPath: options.inputPath,
+      status,
+      received,
+      delivered,
+      dropped,
+      lagP95Ms,
+      windowSeconds,
+      deliveredRps,
+      droppedRps,
+      dropRatio,
+      thresholds: {
+        maxDropRatio: options.maxDropRatio,
+        maxLagP95Ms: options.maxLagP95Ms,
+        minDeliveredRps: options.minDeliveredRps,
+      },
+      issues,
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode: 1,
+      stderr: `aurora monitor-realtime: ${reason}`,
+    };
+  }
+}
+
+function renderRealtimeMonitorText(report: RealtimeMonitorReport): string {
+  const lines = [
+    "aurora realtime monitor report",
+    `project_root: ${report.projectRoot}`,
+    `input_path: ${report.inputPath}`,
+    `status: ${report.status}`,
+    `received: ${report.received}`,
+    `delivered: ${report.delivered}`,
+    `dropped: ${report.dropped}`,
+    `drop_ratio: ${report.dropRatio.toFixed(4)}`,
+    `lag_p95_ms: ${report.lagP95Ms}`,
+    `window_seconds: ${report.windowSeconds}`,
+    `delivered_rps: ${report.deliveredRps.toFixed(4)}`,
+    `dropped_rps: ${report.droppedRps.toFixed(4)}`,
+    `max_drop_ratio: ${report.thresholds.maxDropRatio.toFixed(4)}`,
+    `max_lag_p95_ms: ${report.thresholds.maxLagP95Ms}`,
+  ];
+
+  if (report.thresholds.minDeliveredRps !== undefined) {
+    lines.push(`min_delivered_rps: ${report.thresholds.minDeliveredRps.toFixed(4)}`);
+  }
+
+  if (report.issues.length > 0) {
+    lines.push("issues:");
+    for (const issue of report.issues) {
+      lines.push(`- [${issue.code}] ${issue.message}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function runRealtimeMonitorCommand(
+  args: ReadonlyArray<string>,
+  context: CommandContext,
+): CommandResult {
+  const options = parseRealtimeMonitorOptions(args);
+  if ("exitCode" in options) {
+    return options;
+  }
+
+  const report = buildRealtimeMonitorReport(options, context);
+  if ("exitCode" in 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: renderRealtimeMonitorText(report),
+  };
+}

package/src/registry.ts

@@ -0,0 +1,303 @@
+import { runAnalyzeCommand } from "./analyze";
+import { runAiCommand } from "./ai";
+import { runBuildCommand } from "./build";
+import { runCreateCommand } from "./create";
+import { runCreateFeatureCommand } from "./create-feature";
+import { runCreateRouteCommand } from "./create-route";
+import { runDevCommand } from "./dev";
+import { runDevtoolsCommand } from "./devtools";
+import { runDoctorCommand } from "./doctor";
+import { runExplainCommand } from "./explain";
+import { runInitCommand } from "./init";
+import { runInspectCacheCommand } from "./inspect-cache";
+import { runQueryProfilerCommand } from "./query-profiler";
+import { runRealtimeMonitorCommand } from "./realtime-monitor";
+import { runStartCommand } from "./start";
+import { runTestCommand } from "./test";
+
+export interface CommandContext {
+  cwd: string;
+}
+
+export interface CommandResult {
+  exitCode: number;
+  stdout?: string;
+  stderr?: string;
+}
+
+export interface CommandDefinition {
+  name: string;
+  synopsis: string;
+  summary: string;
+  options?: ReadonlyArray<{ flag: string; description: string }>;
+  run: (args: ReadonlyArray<string>, context: CommandContext) => CommandResult;
+}
+
+export const commandRegistry: ReadonlyArray<CommandDefinition> = [
+  {
+    name: "create",
+    synopsis: "create <name>",
+    summary: "Create new project",
+    options: [
+      { flag: "--template", description: "Choose starter template" },
+      { flag: "--git", description: "Initialize git repo" },
+    ],
+    run: (args, context) => runCreateCommand(args, context),
+  },
+  {
+    name: "init",
+    synopsis: "init",
+    summary: "Initialize migration/adoption scaffold",
+    options: [
+      {
+        flag: "--from next|remix|sveltekit",
+        description: "Select the source framework to migrate from",
+      },
+      {
+        flag: "--mode incremental|side-by-side",
+        description: "Choose migration rollout strategy",
+      },
+      {
+        flag: "--bridge react|none",
+        description: "Generate React interop bridge helper",
+      },
+      { flag: "--out-dir <path>", description: "Output directory for migration scaffold files" },
+      { flag: "--dry-run", description: "Preview migration output without writing files" },
+      { flag: "--format text|json", description: "Choose report output format" },
+    ],
+    run: (args, context) => runInitCommand(args, context),
+  },
+  {
+    name: "dev",
+    synopsis: "dev",
+    summary: "Start development server",
+    options: [
+      { flag: "--port <n>", description: "Set dev server port" },
+      { flag: "--open", description: "Open app in browser" },
+      { flag: "--https", description: "Enable HTTPS dev mode" },
+    ],
+    run: (args, context) => runDevCommand(args, context),
+  },
+  {
+    name: "devtools",
+    synopsis: "devtools",
+    summary: "DevTools v2 panel report",
+    options: [
+      { flag: "--input <path>", description: "DevTools snapshot JSON path" },
+      { flag: "--format text|json", description: "Choose report output format" },
+      {
+        flag: "--panel explain|waterfall|performance|realtime|auth",
+        description: "Select one panel (repeat or comma-separate to select multiple)",
+      },
+      {
+        flag: "--max-waterfall-blocking-ms <n>",
+        description: "Warn threshold for blocking waterfall operations",
+      },
+      { flag: "--max-lag-p95-ms <n>", description: "Warn threshold for realtime lag p95" },
+      { flag: "--max-drop-ratio <n>", description: "Warn threshold for realtime drop ratio" },
+      { flag: "--min-route-score <n>", description: "Warn threshold for per-route performance score" },
+    ],
+    run: (args, context) => runDevtoolsCommand(args, context),
+  },
+  {
+    name: "build",
+    synopsis: "build",
+    summary: "Build for production",
+    options: [
+      {
+        flag: "--target node|edge|static",
+        description: "Choose deployment target",
+      },
+      { flag: "--analyze", description: "Generate bundle analysis during build" },
+      { flag: "--skip-audit", description: "Disable dependency vulnerability gate" },
+      {
+        flag: "--audit-severity low|moderate|high|critical",
+        description: "Fail build when vulnerabilities meet/exceed threshold",
+      },
+      {
+        flag: "--audit-report <path>",
+        description: "Override dependency audit report JSON path",
+      },
+    ],
+    run: (args, context) => runBuildCommand(args, context),
+  },
+  {
+    name: "start",
+    synopsis: "start",
+    summary: "Run production build",
+    run: (args, context) => runStartCommand(args, context),
+  },
+  {
+    name: "analyze",
+    synopsis: "analyze",
+    summary: "Bundle analysis",
+    options: [
+      { flag: "--format text|json", description: "Choose report output format" },
+      {
+        flag: "--mode bundle|cache|realtime|query|guardrails",
+        description: "Select analyze report mode",
+      },
+      { flag: "--out-dir <path>", description: "Compiler output directory" },
+      {
+        flag: "--input <path>",
+        description: "Input JSON path for cache/realtime/query modes",
+      },
+      {
+        flag: "--max-drop-ratio <n>",
+        description: "Realtime warning threshold for drop ratio",
+      },
+      {
+        flag: "--max-lag-p95-ms <n>",
+        description: "Realtime warning threshold for p95 lag",
+      },
+    ],
+    run: (args, context) => runAnalyzeCommand(args, context),
+  },
+  {
+    name: "ai",
+    synopsis: "ai <description>",
+    summary: "AI-assisted feature scaffolding",
+    options: [
+      { flag: "--format text|json", description: "Choose report output format" },
+      { flag: "--dry-run", description: "Preview inferred scaffold plan without writing files" },
+      { flag: "--name <feature-slug>", description: "Override inferred feature slug" },
+      {
+        flag: "--auth public|user|admin|permission:<name>",
+        description: "Override inferred route auth metadata",
+      },
+    ],
+    run: (args, context) => runAiCommand(args, context),
+  },
+  {
+    name: "doctor",
+    synopsis: "doctor",
+    summary: "Project health checks",
+    options: [
+      { flag: "--format text|json", description: "Choose report output format" },
+    ],
+    run: (args, context) => runDoctorCommand(args, context),
+  },
+  {
+    name: "explain",
+    synopsis: "explain <module-path>",
+    summary: "Explain inferred module behavior",
+    options: [
+      {
+        flag: "--input <path>",
+        description: "Explain snapshot JSON path",
+      },
+      {
+        flag: "--format text|json",
+        description: "Choose report output format",
+      },
+    ],
+    run: (args, context) => runExplainCommand(args, context),
+  },
+  {
+    name: "inspect-cache",
+    synopsis: "inspect-cache",
+    summary: "DevTools cache inspector",
+    options: [
+      { flag: "--input <path>", description: "Cache snapshot or cache report JSON path" },
+      { flag: "--format text|json", description: "Choose report output format" },
+      { flag: "--tag <tag>", description: "Filter entries by cache tag" },
+      { flag: "--limit <n>", description: "Cap largest_entries rows (default 20)" },
+    ],
+    run: (args, context) => runInspectCacheCommand(args, context),
+  },
+  {
+    name: "monitor-realtime",
+    synopsis: "monitor-realtime",
+    summary: "DevTools realtime monitor",
+    options: [
+      { flag: "--input <path>", description: "Realtime metrics JSON path" },
+      { flag: "--format text|json", description: "Choose report output format" },
+      { flag: "--max-drop-ratio <n>", description: "Warn threshold for dropped/received ratio" },
+      { flag: "--max-lag-p95-ms <n>", description: "Warn threshold for p95 lag in milliseconds" },
+      { flag: "--min-delivered-rps <n>", description: "Warn threshold for minimum delivered rate" },
+    ],
+    run: (args, context) => runRealtimeMonitorCommand(args, context),
+  },
+  {
+    name: "profile-query",
+    synopsis: "profile-query",
+    summary: "DevTools query profiler",
+    options: [
+      { flag: "--input <path>", description: "Query metrics JSON path" },
+      { flag: "--format text|json", description: "Choose report output format" },
+      { flag: "--max-p95-ms <n>", description: "Warn threshold for aggregate p95 query latency" },
+      { flag: "--min-cache-hit-ratio <n>", description: "Warn threshold for aggregate cache hit ratio" },
+      { flag: "--limit <n>", description: "Cap slow_queries rows (default 10)" },
+    ],
+    run: (args, context) => runQueryProfilerCommand(args, context),
+  },
+  {
+    name: "test",
+    synopsis: "test",
+    summary: "Run tests",
+    options: [
+      {
+        flag: "--template basic|saas|blog|dashboard",
+        description: "Filter e2e matrix to one template",
+      },
+      { flag: "--format text|json", description: "Choose report output format" },
+    ],
+    run: (args, context) => runTestCommand(args, context),
+  },
+  {
+    name: "create-feature",
+    synopsis: "create-feature <name>",
+    summary: "Scaffold a feature module",
+    options: [
+      {
+        flag: "--kind crud|read-only|form|dashboard|empty",
+        description: "Route scaffold pattern to pair with the feature",
+      },
+      {
+        flag: "--data database|api|none",
+        description: "Primary data source mode for generated route boilerplate",
+      },
+      {
+        flag: "--auth public|user|admin|permission:<name>",
+        description: "Route auth metadata default",
+      },
+      {
+        flag: "--route|--no-route",
+        description: "Enable/disable paired route scaffolding (default enabled)",
+      },
+      {
+        flag: "--realtime|--no-realtime",
+        description: "Enable/disable realtime boilerplate in paired route",
+      },
+    ],
+    run: (args, context) => runCreateFeatureCommand(args, context),
+  },
+  {
+    name: "create-route",
+    synopsis: "create-route <name>",
+    summary: "Scaffold a route module",
+    options: [
+      {
+        flag: "--kind crud|read-only|form|dashboard|empty",
+        description: "Choose route scaffold pattern",
+      },
+      {
+        flag: "--data database|api|none",
+        description: "Set generated data source hint metadata",
+      },
+      {
+        flag: "--auth public|user|admin|permission:<name>",
+        description: "Set generated route auth metadata",
+      },
+      {
+        flag: "--realtime|--no-realtime",
+        description: "Enable/disable realtime scaffold metadata",
+      },
+    ],
+    run: (args, context) => runCreateRouteCommand(args, context),
+  },
+];
+
+export function findCommand(name: string): CommandDefinition | undefined {
+  return commandRegistry.find((command) => command.name === name);
+}