miravo 0.6.0 → 0.6.2

package/src/lib/parse.test.ts

@@ -1,123 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { InvalidArgumentError } from "commander";
-import {
-  parseDurationMs,
-  parseNonNegativeInt,
-  parsePort,
-  parsePositiveFloat,
-  parsePositiveInt,
-} from "./parse.ts";
-
-describe("parsePositiveInt", () => {
-  test("parses valid positive integers", () => {
-    expect(parsePositiveInt("1")).toBe(1);
-    expect(parsePositiveInt("42")).toBe(42);
-    expect(parsePositiveInt("1883")).toBe(1883);
-  });
-
-  test("rejects zero", () => {
-    expect(() => parsePositiveInt("0")).toThrow(InvalidArgumentError);
-  });
-
-  test("rejects negative numbers", () => {
-    expect(() => parsePositiveInt("-5")).toThrow(InvalidArgumentError);
-  });
-
-  test("rejects non-numeric strings", () => {
-    expect(() => parsePositiveInt("abc")).toThrow(InvalidArgumentError);
-    expect(() => parsePositiveInt("")).toThrow(InvalidArgumentError);
-  });
-
-  test("rejects decimals and partial strings", () => {
-    expect(() => parsePositiveInt("1.5")).toThrow(InvalidArgumentError);
-    expect(() => parsePositiveInt("42.9")).toThrow(InvalidArgumentError);
-    expect(() => parsePositiveInt("42ms")).toThrow(InvalidArgumentError);
-    expect(() => parsePositiveInt("1e9")).toThrow(InvalidArgumentError);
-    expect(() => parsePositiveInt("1.5abc")).toThrow(InvalidArgumentError);
-  });
-
-  test("rejects Infinity", () => {
-    expect(() => parsePositiveInt("Infinity")).toThrow(InvalidArgumentError);
-  });
-});
-
-describe("parseNonNegativeInt", () => {
-  test("accepts zero", () => {
-    expect(parseNonNegativeInt("0")).toBe(0);
-  });
-
-  test("accepts positive integers", () => {
-    expect(parseNonNegativeInt("42")).toBe(42);
-  });
-
-  test("rejects negative numbers", () => {
-    expect(() => parseNonNegativeInt("-1")).toThrow(InvalidArgumentError);
-  });
-
-  test("rejects non-numeric strings", () => {
-    expect(() => parseNonNegativeInt("abc")).toThrow(InvalidArgumentError);
-  });
-
-  test("rejects partial strings and scientific notation", () => {
-    expect(() => parseNonNegativeInt("42ms")).toThrow(InvalidArgumentError);
-    expect(() => parseNonNegativeInt("1e9")).toThrow(InvalidArgumentError);
-    expect(() => parseNonNegativeInt("1.5abc")).toThrow(InvalidArgumentError);
-  });
-});
-
-describe("parsePositiveFloat", () => {
-  test("parses valid positive floats", () => {
-    expect(parsePositiveFloat("1.5")).toBe(1.5);
-    expect(parsePositiveFloat("0.1")).toBe(0.1);
-    expect(parsePositiveFloat("10")).toBe(10);
-    expect(parsePositiveFloat("1e3")).toBe(1000);
-  });
-
-  test("rejects zero", () => {
-    expect(() => parsePositiveFloat("0")).toThrow(InvalidArgumentError);
-  });
-
-  test("rejects negative numbers", () => {
-    expect(() => parsePositiveFloat("-0.5")).toThrow(InvalidArgumentError);
-  });
-
-  test("rejects non-numeric strings", () => {
-    expect(() => parsePositiveFloat("abc")).toThrow(InvalidArgumentError);
-  });
-
-  test("rejects Infinity", () => {
-    expect(() => parsePositiveFloat("Infinity")).toThrow(InvalidArgumentError);
-  });
-});
-
-describe("parsePort", () => {
-  test("accepts valid ports", () => {
-    expect(parsePort("1")).toBe(1);
-    expect(parsePort("80")).toBe(80);
-    expect(parsePort("1883")).toBe(1883);
-    expect(parsePort("65535")).toBe(65535);
-  });
-
-  test("rejects invalid ports", () => {
-    expect(() => parsePort("0")).toThrow(InvalidArgumentError);
-    expect(() => parsePort("-1")).toThrow(InvalidArgumentError);
-    expect(() => parsePort("65536")).toThrow(InvalidArgumentError);
-    expect(() => parsePort("abc")).toThrow(InvalidArgumentError);
-    expect(() => parsePort("1.5")).toThrow(InvalidArgumentError);
-  });
-});
-
-describe("parseDurationMs", () => {
-  test("accepts positive durations up to one hour", () => {
-    expect(parseDurationMs("1")).toBe(1);
-    expect(parseDurationMs("5000")).toBe(5000);
-    expect(parseDurationMs("3600000")).toBe(3_600_000);
-  });
-
-  test("rejects out-of-range durations", () => {
-    expect(() => parseDurationMs("0")).toThrow(InvalidArgumentError);
-    expect(() => parseDurationMs("3600001")).toThrow(InvalidArgumentError);
-    expect(() => parseDurationMs("-1")).toThrow(InvalidArgumentError);
-    expect(() => parseDurationMs("1.5")).toThrow(InvalidArgumentError);
-  });
-});

package/src/lib/parse.ts

@@ -1,87 +0,0 @@
-/**
- * CLI option parsers that throw Commander's InvalidArgumentError on bad input.
- * Commander catches these and shows a user-friendly error with the flag name.
- */
-import { InvalidArgumentError } from "commander";
-
-/** Maximum allowed millisecond duration for CLI timer options (1 hour). */
-const MAX_DURATION_MS = 3_600_000;
-
-function parseStrictUnsignedInteger(value: string, label: string): number {
-  const trimmed = value.trim();
-  if (!/^\d+$/.test(trimmed)) {
-    throw new InvalidArgumentError(`Expected ${label}, got "${value}".`);
-  }
-
-  const n = Number(trimmed);
-  if (!Number.isFinite(n) || !Number.isInteger(n)) {
-    throw new InvalidArgumentError(`Expected ${label}, got "${value}".`);
-  }
-  return n;
-}
-
-/** Parse a string as a positive integer (> 0). */
-export function parsePositiveInt(value: string): number {
-  const n = parseStrictUnsignedInteger(value, "a positive integer");
-  if (n <= 0) {
-    throw new InvalidArgumentError(`Expected a positive integer, got "${value}".`);
-  }
-  return n;
-}
-
-/** Parse a string as a non-negative integer (>= 0). Useful for seeds. */
-export function parseNonNegativeInt(value: string): number {
-  const n = parseStrictUnsignedInteger(value, "a non-negative integer");
-  if (n < 0) {
-    throw new InvalidArgumentError(`Expected a non-negative integer, got "${value}".`);
-  }
-  return n;
-}
-
-/** Parse a string as a positive float (> 0). */
-export function parsePositiveFloat(value: string): number {
-  const trimmed = value.trim();
-  const n = Number(trimmed);
-  if (trimmed.length === 0 || !Number.isFinite(n) || n <= 0) {
-    throw new InvalidArgumentError(`Expected a positive number, got "${value}".`);
-  }
-  return n;
-}
-
-/** Parse a string as a valid network port (1–65535). */
-export function parsePort(value: string): number {
-  const n = parseStrictUnsignedInteger(value, "a port number (1–65535)");
-  if (n < 1 || n > 65_535) {
-    throw new InvalidArgumentError(`Expected a port number (1–65535), got "${value}".`);
-  }
-  return n;
-}
-
-/** Parse a string as a positive millisecond duration up to 1 hour. */
-export function parseDurationMs(value: string): number {
-  const n = parseStrictUnsignedInteger(value, `a duration in milliseconds (1–${MAX_DURATION_MS})`);
-  if (n < 1 || n > MAX_DURATION_MS) {
-    throw new InvalidArgumentError(
-      `Expected a duration in milliseconds (1–${MAX_DURATION_MS}), got "${value}".`,
-    );
-  }
-  return n;
-}
-
-/** Maximum allowed timeout in seconds (1 hour). */
-const MAX_TIMEOUT_SECONDS = 3_600;
-
-/**
- * Parse a string as a timeout in seconds and return milliseconds.
- * Accepts positive numbers (integers or decimals). The result is rounded to
- * the nearest millisecond.
- */
-export function parseTimeoutSeconds(value: string): number {
-  const n = parsePositiveFloat(value);
-  if (n > MAX_TIMEOUT_SECONDS) {
-    throw new InvalidArgumentError(
-      `Expected a timeout in seconds (max ${MAX_TIMEOUT_SECONDS}), got "${value}".`,
-    );
-  }
-  return Math.round(n * 1_000);
-}

package/src/lib/resolve-simulation.test.ts

@@ -1,118 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import {
-  CONTROL_TOPIC_WILDCARD_METRICS,
-  controlTopicCmd,
-  controlTopicCmdResult,
-  controlTopicMetrics,
-  controlTopicState,
-} from "@miravo/shared";
-import type { SimulationResolverClient } from "./resolve-simulation.ts";
-import { discoverRunningSimulations, resolveTargetSimulation } from "./resolve-simulation.ts";
-
-type MessageHandler = Parameters<SimulationResolverClient["on"]>[1];
-
-class MockResolverClient implements SimulationResolverClient {
-  readonly subscriptions = new Set<string>();
-  #handlers = new Set<MessageHandler>();
-
-  subscribe(topic: string, _options: { qos: 0 }, callback?: (error?: Error | null) => void): void {
-    this.subscriptions.add(topic);
-    callback?.(null);
-  }
-
-  unsubscribe(topic: string): void {
-    this.subscriptions.delete(topic);
-  }
-
-  on(_event: "message", handler: MessageHandler): void {
-    this.#handlers.add(handler);
-  }
-
-  off(_event: "message", handler: MessageHandler): void {
-    this.#handlers.delete(handler);
-  }
-
-  emitMessage(topic: string, payload = "{}"): void {
-    const buffer = Buffer.from(payload, "utf8");
-    for (const handler of this.#handlers) {
-      handler(topic, buffer);
-    }
-  }
-}
-
-describe("resolveTargetSimulation", () => {
-  test("returns explicit --name directly without discovery", async () => {
-    const client = new MockResolverClient();
-    const resolved = await resolveTargetSimulation(client, {
-      name: "north-plant",
-      timeoutMs: 20,
-      brokerUrl: "mqtt://127.0.0.1:1883",
-    });
-
-    expect(client.subscriptions.size).toBe(0);
-    expect(resolved.simulationName).toBe("north-plant");
-    expect(resolved.topics.metrics).toBe(controlTopicMetrics("north-plant"));
-    expect(resolved.topics.state).toBe(controlTopicState("north-plant"));
-    expect(resolved.topics.cmd).toBe(controlTopicCmd("north-plant"));
-    expect(resolved.topics.cmdResult).toBe(controlTopicCmdResult("north-plant"));
-  });
-
-  test("fails when no simulation is discovered", async () => {
-    const client = new MockResolverClient();
-    await expect(
-      resolveTargetSimulation(client, {
-        timeoutMs: 10,
-        brokerUrl: "mqtt://127.0.0.1:1883",
-      }),
-    ).rejects.toThrow("No running simulations found");
-  });
-
-  test("auto-targets when exactly one simulation is discovered", async () => {
-    const client = new MockResolverClient();
-    setTimeout(() => {
-      client.emitMessage("$miravo/north-plant/metrics", '{"ok":true}');
-    }, 2);
-
-    const resolved = await resolveTargetSimulation(client, {
-      timeoutMs: 20,
-      brokerUrl: "mqtt://127.0.0.1:1883",
-    });
-
-    expect(resolved.simulationName).toBe("north-plant");
-    expect(resolved.topics.metrics).toBe("$miravo/north-plant/metrics");
-  });
-
-  test("fails when multiple simulations are discovered", async () => {
-    const client = new MockResolverClient();
-    setTimeout(() => {
-      client.emitMessage("$miravo/north-plant/metrics", '{"ok":true}');
-      client.emitMessage("$miravo/south-plant/metrics", '{"ok":true}');
-    }, 2);
-
-    await expect(
-      resolveTargetSimulation(client, {
-        timeoutMs: 20,
-        brokerUrl: "mqtt://127.0.0.1:1883",
-      }),
-    ).rejects.toThrow("Multiple running simulations found");
-  });
-});
-
-describe("discoverRunningSimulations", () => {
-  test("subscribes to metrics wildcard and returns discovered simulation names", async () => {
-    const client = new MockResolverClient();
-    setTimeout(() => {
-      client.emitMessage("$miravo/line-a/metrics", '{"ok":true}');
-      client.emitMessage("$miravo/line-b/metrics", '{"ok":true}');
-      client.emitMessage("$miravo/line-a/metrics", '{"ok":true}');
-    }, 2);
-
-    const discovered = await discoverRunningSimulations(client, {
-      timeoutMs: 20,
-      brokerUrl: "mqtt://127.0.0.1:1883",
-    });
-
-    expect(discovered).toEqual(["line-a", "line-b"]);
-    expect(client.subscriptions.has(CONTROL_TOPIC_WILDCARD_METRICS)).toBe(false);
-  });
-});

package/src/lib/resolve-simulation.ts

@@ -1,181 +0,0 @@
-import {
-  CONTROL_TOPIC_WILDCARD_METRICS,
-  controlTopicCmd,
-  controlTopicCmdResult,
-  controlTopicMetrics,
-  controlTopicState,
-  MiravoError,
-  SimulationNameSchema,
-} from "@miravo/shared";
-
-interface SimulationTopics {
-  readonly metrics: string;
-  readonly state: string;
-  readonly cmd: string;
-  readonly cmdResult: string;
-}
-
-interface ResolvedTargetSimulation {
-  readonly simulationName: string;
-  readonly topics: SimulationTopics;
-}
-
-interface ResolveTargetSimulationOptions {
-  readonly name?: string;
-  readonly timeoutMs: number;
-  readonly brokerUrl: string;
-}
-
-type MessageHandler = (topic: string, payload: Buffer, ...extra: unknown[]) => void;
-
-interface SimulationResolverClient {
-  subscribe(topic: string, options: { qos: 0 }, callback?: (error?: Error | null) => void): unknown;
-  unsubscribe(topic: string): unknown;
-  on(event: "message", handler: MessageHandler): unknown;
-  off(event: "message", handler: MessageHandler): unknown;
-}
-
-function buildSimulationTopics(simulationName: string): SimulationTopics {
-  return {
-    metrics: controlTopicMetrics(simulationName),
-    state: controlTopicState(simulationName),
-    cmd: controlTopicCmd(simulationName),
-    cmdResult: controlTopicCmdResult(simulationName),
-  };
-}
-
-function validateSimulationName(name: string, source: string): string {
-  const parsed = SimulationNameSchema.safeParse(name);
-  if (!parsed.success) {
-    throw new MiravoError(
-      `Invalid simulation name "${name}" from ${source}.`,
-      "Use lowercase letters, numbers, and hyphens. Example: --name north-plant.",
-    );
-  }
-  return parsed.data;
-}
-
-function extractSimulationNameFromTopic(topic: string): string | null {
-  const name = topic.split("/")[1];
-  if (!name || name.length === 0) return null;
-  const validated = SimulationNameSchema.safeParse(name);
-  if (!validated.success) return null;
-  return validated.data;
-}
-
-async function discoverRunningSimulations(
-  client: SimulationResolverClient,
-  options: { readonly timeoutMs: number; readonly brokerUrl: string },
-): Promise<readonly string[]> {
-  const { timeoutMs } = options;
-  const simulations = new Set<string>();
-
-  return new Promise((resolve, reject) => {
-    let settled = false;
-
-    const cleanup = (): void => {
-      if (timer) {
-        clearTimeout(timer);
-      }
-      client.off("message", handler);
-      try {
-        client.unsubscribe(CONTROL_TOPIC_WILDCARD_METRICS);
-      } catch {
-        // Ignore unsubscribe errors during cleanup.
-      }
-    };
-
-    const finish = (fn: () => void): void => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      fn();
-    };
-
-    const handler: MessageHandler = (topic) => {
-      if (!topic.startsWith("$miravo/")) return;
-      const name = extractSimulationNameFromTopic(topic);
-      if (!name) return;
-      simulations.add(name);
-    };
-
-    const timer = setTimeout(() => {
-      finish(() => {
-        resolve([...simulations].sort((a, b) => a.localeCompare(b)));
-      });
-    }, timeoutMs);
-
-    client.on("message", handler);
-
-    try {
-      client.subscribe(CONTROL_TOPIC_WILDCARD_METRICS, { qos: 0 }, (error) => {
-        if (!error) return;
-        finish(() => {
-          reject(
-            new MiravoError(
-              `Failed to subscribe to simulation discovery topic "${CONTROL_TOPIC_WILDCARD_METRICS}".`,
-              `Check broker ACLs for ${options.brokerUrl} and allow read access to $miravo topics.`,
-            ),
-          );
-        });
-      });
-    } catch {
-      finish(() => {
-        reject(
-          new MiravoError(
-            `Failed to subscribe to simulation discovery topic "${CONTROL_TOPIC_WILDCARD_METRICS}".`,
-            `Check broker ACLs for ${options.brokerUrl} and allow read access to $miravo topics.`,
-          ),
-        );
-      });
-    }
-  });
-}
-
-async function resolveTargetSimulation(
-  client: SimulationResolverClient,
-  options: ResolveTargetSimulationOptions,
-): Promise<ResolvedTargetSimulation> {
-  if (options.name !== undefined) {
-    const simulationName = validateSimulationName(options.name, "--name");
-    return {
-      simulationName,
-      topics: buildSimulationTopics(simulationName),
-    };
-  }
-
-  const discovered = await discoverRunningSimulations(client, {
-    timeoutMs: options.timeoutMs,
-    brokerUrl: options.brokerUrl,
-  });
-
-  if (discovered.length === 0) {
-    throw new MiravoError(
-      `No running simulations found on broker ${options.brokerUrl}.`,
-      "Start a simulation first with 'miravo start', or pass --name if metrics are not retained.",
-    );
-  }
-
-  if (discovered.length > 1) {
-    throw new MiravoError(
-      `Multiple running simulations found: ${discovered.join(", ")}.`,
-      "Specify one with --name <name>.",
-    );
-  }
-
-  const simulationName = discovered[0];
-  if (!simulationName) {
-    throw new MiravoError(
-      "Failed to resolve simulation name from discovery results.",
-      "Specify a simulation explicitly with --name <name>.",
-    );
-  }
-
-  return {
-    simulationName,
-    topics: buildSimulationTopics(simulationName),
-  };
-}
-
-export type { SimulationResolverClient };
-export { discoverRunningSimulations, resolveTargetSimulation };

package/src/lib/session-store.ts

@@ -1,110 +0,0 @@
-/**
- * Server-side session store — in-memory sessions with 24h TTL.
- *
- * Sessions are created on successful login and validated on every request.
- * Cookie helpers handle Set-Cookie header construction and parsing.
- */
-
-// ---------------------------------------------------------------------------
-// Session types
-// ---------------------------------------------------------------------------
-
-export interface Session {
-  readonly id: string;
-  readonly username: string;
-  readonly createdAt: number;
-}
-
-export interface SessionStore {
-  /** Create a new session for the given username. */
-  create(username: string): Session;
-  /** Validate a session ID. Returns the session or null if expired/missing. */
-  validate(sessionId: string): Session | null;
-  /** Destroy a specific session. */
-  destroy(sessionId: string): void;
-  /** Clear all sessions (used on server stop). */
-  clear(): void;
-}
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const SESSION_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
-const SESSION_TTL_SECONDS = 24 * 60 * 60;
-const COOKIE_NAME = "miravo_session";
-const SWEEP_THRESHOLD = 50;
-
-// ---------------------------------------------------------------------------
-// Session store
-// ---------------------------------------------------------------------------
-
-export function createSessionStore(): SessionStore {
-  const sessions = new Map<string, Session>();
-
-  function sweepExpired(): void {
-    const now = Date.now();
-    for (const [id, s] of sessions) {
-      if (now - s.createdAt > SESSION_TTL_MS) sessions.delete(id);
-    }
-  }
-
-  return {
-    create(username: string): Session {
-      if (sessions.size >= SWEEP_THRESHOLD) sweepExpired();
-      const session: Session = {
-        id: crypto.randomUUID(),
-        username,
-        createdAt: Date.now(),
-      };
-      sessions.set(session.id, session);
-      return session;
-    },
-
-    validate(sessionId: string): Session | null {
-      const session = sessions.get(sessionId);
-      if (!session) return null;
-      if (Date.now() - session.createdAt > SESSION_TTL_MS) {
-        sessions.delete(sessionId);
-        return null;
-      }
-      return session;
-    },
-
-    destroy(sessionId: string): void {
-      sessions.delete(sessionId);
-    },
-
-    clear(): void {
-      sessions.clear();
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Cookie helpers
-// ---------------------------------------------------------------------------
-
-/** Build a Set-Cookie header value for a new session. */
-export function buildSessionCookie(sessionId: string): string {
-  return `${COOKIE_NAME}=${sessionId}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${SESSION_TTL_SECONDS}`;
-}
-
-/** Build a Set-Cookie header value that clears the session cookie. */
-export function buildClearCookie(): string {
-  return `${COOKIE_NAME}=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0`;
-}
-
-/** Extract the session ID from the Cookie header of a request. Returns null if absent. */
-export function extractSessionId(request: Request): string | null {
-  const header = request.headers.get("cookie");
-  if (!header) return null;
-  for (const part of header.split(";")) {
-    const [key, ...rest] = part.split("=");
-    if (key?.trim() === COOKIE_NAME) {
-      const value = rest.join("=").trim();
-      if (value.length > 0) return value;
-    }
-  }
-  return null;
-}