miravo 0.6.0 → 0.6.2

package/src/commands/stop.ts

@@ -1,169 +0,0 @@
-import type { Command } from "commander";
-import { isPidAlive, probeEntryIdentity, readEntry, removeEntry } from "../lib/daemon-registry.ts";
-import { parseTimeoutSeconds } from "../lib/parse.ts";
-import { handleCommandError, writeOutput } from "../logger.ts";
-
-interface StopOptions {
-  readonly json?: boolean;
-  readonly timeout?: number;
-}
-
-export function registerStopCommand(program: Command): void {
-  program
-    .command("stop <name>")
-    .description("Stop a running background simulation")
-    .option("--json", "Machine-readable JSON output")
-    .option("--timeout <seconds>", "Shutdown timeout in seconds (default: 10)", parseTimeoutSeconds)
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo stop my-sim                     Graceful shutdown
-  $ miravo stop my-sim --timeout 30        Wait up to 30s before force kill`,
-    )
-    .action(async (name: string, options: StopOptions) => {
-      try {
-        await stopAction(name, options);
-      } catch (error) {
-        handleCommandError(error);
-      }
-    });
-}
-
-function jsonOut(obj: Record<string, unknown>): void {
-  console.log(JSON.stringify(obj, null, 2));
-}
-
-async function stopAction(name: string, options: StopOptions): Promise<void> {
-  const entry = await readEntry(name);
-  if (!entry) {
-    const msg = `Simulation "${name}" not found. Use 'miravo ps' to list running simulations.`;
-    if (options.json) {
-      jsonOut({ success: false, name, message: msg });
-    } else {
-      writeOutput(msg);
-    }
-    process.exitCode = 1;
-    return;
-  }
-
-  // Verify identity before taking any action — guards against PID reuse
-  const identity = await probeEntryIdentity(entry);
-  if (identity.status === "dead" || identity.status === "mismatch") {
-    await removeEntry(name);
-    const msg = `Simulation "${name}" was not running (stale registry entry removed).`;
-    if (options.json) {
-      jsonOut({ success: true, name, message: msg });
-    } else {
-      writeOutput(msg);
-    }
-    return;
-  }
-  if (identity.status === "unreachable") {
-    const msg = `Simulation "${name}" could not be safely verified because its admin server is unreachable while PID ${entry.pid} is still alive.`;
-    if (options.json) {
-      jsonOut({
-        success: false,
-        name,
-        message: msg,
-        error: "Retry later, or inspect the process manually before removing the registry entry.",
-      });
-    } else {
-      writeOutput(
-        `${msg} Retry later, or inspect the process manually before removing the registry entry.`,
-      );
-    }
-    process.exitCode = 1;
-    return;
-  }
-
-  // Try graceful shutdown via admin server (identity-safe — admin server belongs to this process)
-  let shutdownSent = false;
-  let canForceKill = true;
-  try {
-    const adminBase = `http://${entry.adminHost}:${entry.adminPort}`;
-    // Authenticate with session-based login
-    // Resolve password: env > default.
-    // If credential file exists, we can't reverse the hash — use "admin" as default.
-    // The server will verify against the stored hash. If the user changed their password,
-    // they need to set MIRAVO_ADMIN_PASSWORD env var for CLI access.
-    const envPassword = Bun.env["MIRAVO_ADMIN_PASSWORD"];
-    const password = envPassword && envPassword.trim().length > 0 ? envPassword : "admin";
-    const loginResponse = await fetch(`${adminBase}/auth/login`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ username: "admin", password }),
-      signal: AbortSignal.timeout(2_000),
-    });
-    const setCookie = loginResponse.ok ? loginResponse.headers.get("set-cookie") : null;
-    const cookie = setCookie ? (setCookie.split(";")[0] ?? "") : "";
-
-    const response = await fetch(`${adminBase}/shutdown`, {
-      method: "POST",
-      headers: { "content-type": "application/json", ...(cookie ? { cookie } : {}) },
-      body: JSON.stringify({ reason: "miravo stop" }),
-      signal: AbortSignal.timeout(2_000),
-    });
-    shutdownSent = response.ok;
-  } catch {
-    // Admin server unreachable — fall back to SIGTERM only if we can re-verify identity
-  }
-
-  if (!shutdownSent) {
-    try {
-      process.kill(entry.pid, "SIGTERM");
-    } catch {
-      // Process may have already exited
-    }
-  }
-
-  // Poll for process exit
-  const timeoutMs = options.timeout ?? 10_000;
-  const deadline = Date.now() + timeoutMs;
-
-  while (isPidAlive(entry.pid) && Date.now() < deadline) {
-    await Bun.sleep(500);
-  }
-
-  // After /shutdown succeeds the admin server may exit before engine.stop() finishes,
-  // so keep the verified identity from the successful request for the SIGKILL fallback.
-  if (shutdownSent) {
-    canForceKill = true;
-  }
-
-  // Force kill only if still alive and we already verified identity earlier.
-  if (isPidAlive(entry.pid) && canForceKill) {
-    try {
-      process.kill(entry.pid, "SIGKILL");
-    } catch {
-      // Ignore — process may have just exited
-    }
-    await Bun.sleep(200);
-  }
-
-  if (isPidAlive(entry.pid)) {
-    const msg = `Simulation "${name}" did not exit within the timeout.`;
-    if (options.json) {
-      jsonOut({
-        success: false,
-        name,
-        message: msg,
-        error: "Inspect the process manually and retry with a longer --timeout if needed.",
-      });
-    } else {
-      writeOutput(
-        `${msg} Inspect the process manually and retry with a longer --timeout if needed.`,
-      );
-    }
-    process.exitCode = 1;
-    return;
-  }
-
-  await removeEntry(name);
-  const msg = `Simulation "${name}" stopped.`;
-  if (options.json) {
-    jsonOut({ success: true, name, message: msg });
-  } else {
-    writeOutput(msg);
-  }
-}

package/src/commands/templates.test.ts

@@ -1,58 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { resolve } from "node:path";
-import { loadTemplate } from "@miravo/core";
-import { createTmpFileUtils } from "@miravo/core/test-tmp-utils";
-import { stripAnsi } from "consola/utils";
-import { configureLogger } from "../logger.ts";
-import { runCliCommand } from "./cli-test-setup.ts";
-import { formatTemplateInspect } from "./templates.ts";
-
-configureLogger({ quiet: true });
-
-const templatesDir = resolve(import.meta.dir, "..", "..", "..", "content", "templates");
-const { cleanupTmpDir } = createTmpFileUtils(resolve(import.meta.dir, ".tmp-test-templates"));
-
-beforeEach(() => {
-  process.exitCode = 0;
-});
-
-afterEach(async () => {
-  process.exitCode = 0;
-  await cleanupTmpDir();
-});
-
-describe("formatTemplateInspect", () => {
-  test("includes topology summary and source details", async () => {
-    const templatePath = resolve(templatesDir, "smart-factory.miravo.yaml");
-    const template = await loadTemplate(templatePath);
-
-    const raw = formatTemplateInspect(template, templatePath, "built-in");
-    const output = stripAnsi(raw);
-
-    expect(output).toContain("Smart Factory Production Line");
-    expect(output).toContain("built-in");
-    expect(output).toContain("Template ID:");
-    expect(output).toContain("smart-factory");
-    expect(output).toContain("Namespace:");
-    expect(output).toContain("Twin assignments:");
-    expect(output).toContain("Areas:");
-    expect(output).toContain("machining");
-  });
-});
-
-describe("miravo templates", () => {
-  test("templates inspect nonexistent template sets exit code 1", async () => {
-    await runCliCommand(["templates", "inspect", "nonexistent-template"]);
-    expect(process.exitCode).toBe(1);
-  });
-
-  test("templates inspect supports template ID", async () => {
-    await runCliCommand(["templates", "inspect", "smart-factory"]);
-    expect(process.exitCode).toBe(0);
-  });
-
-  test("templates list with bad directory sets exit code 1", async () => {
-    await runCliCommand(["templates", "list", "--dir", "/nonexistent/templates-dir"]);
-    expect(process.exitCode).toBe(1);
-  });
-});

package/src/commands/templates.ts

@@ -1,277 +0,0 @@
-import { basename, relative, resolve } from "node:path";
-import { type DiscoveredTemplateWithSource, discoverTemplates, loadTemplate } from "@miravo/core";
-import { type DiscoveredTemplate, MiravoError, TEMPLATE_FILE_EXTENSION } from "@miravo/shared";
-import type { Command } from "commander";
-import { colors } from "consola/utils";
-import {
-  groupTemplatesByCategory,
-  isStressBenchmarkTemplate,
-  sortTemplatesByCategoryAndName,
-} from "../lib/template-category.ts";
-import { createCatalog, resolveTemplateIdentifier } from "../lib/template-locator.ts";
-import { collectReferencedModels } from "../lib/template-utils.ts";
-import { configLog, handleCommandError, writeOutput } from "../logger.ts";
-import { formatKeyValue, formatTable } from "../output.ts";
-
-export function registerTemplatesCommand(program: Command): void {
-  const templates = program.command("templates").description("List and inspect Miravo templates");
-
-  templates
-    .command("list")
-    .description("Discover and list available templates")
-    .option("--dir <path>", "Additional directory to search for .miravo.yaml templates")
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo templates list                  List all discoverable templates`,
-    )
-    .action(async (options: { readonly dir?: string }) => {
-      await templatesListAction(options);
-    });
-
-  templates
-    .command("inspect <idNameOrPath>")
-    .description("Show detailed information about a template by id, name, or path")
-    .option("--raw", "Dump the raw YAML file to stdout")
-    .addHelpText(
-      "after",
-      `
-Examples:
-  $ miravo templates inspect water-treatment  Show template details
-  $ miravo templates inspect water-treatment --raw  Dump raw YAML`,
-    )
-    .action(
-      async (
-        idNameOrPath: string,
-        options: {
-          readonly raw?: boolean;
-        },
-      ) => {
-        await templatesInspectAction(idNameOrPath, options);
-      },
-    );
-}
-
-interface TemplateListOptions {
-  readonly dir?: string;
-}
-
-interface TemplateInspectOptions {
-  readonly raw?: boolean;
-}
-
-async function templatesListAction(options: TemplateListOptions): Promise<void> {
-  try {
-    const catalog = createCatalog();
-    const all = await catalog.listTemplates();
-    const builtinTemplates = all.filter(
-      (t) => t.source.kind === "builtin" && !isStressBenchmarkTemplate(t.id),
-    );
-    const localTemplates: DiscoveredTemplateWithSource[] = all.filter(
-      (t) => t.source.kind !== "builtin",
-    );
-    const localPaths = new Set(localTemplates.map((t) => t.path));
-
-    if (options.dir) {
-      const resolvedDir = resolve(options.dir);
-      const { existsSync, statSync } = await import("node:fs");
-      if (!existsSync(resolvedDir) || !statSync(resolvedDir).isDirectory()) {
-        throw new MiravoError(
-          `Templates directory not found: "${resolvedDir}"`,
-          "Check the path passed to --dir. Ensure the directory exists.",
-        );
-      }
-      const extraTemplates = await discoverTemplates(resolvedDir);
-      for (const extra of extraTemplates) {
-        if (!localPaths.has(extra.path)) {
-          localPaths.add(extra.path);
-          localTemplates.push({ ...extra, source: { kind: "cwd", path: resolvedDir } });
-        }
-      }
-    }
-
-    if (builtinTemplates.length === 0 && localTemplates.length === 0) {
-      configLog.info("No templates found.");
-      return;
-    }
-
-    const headers = {
-      id: colors.dim("ID"),
-      name: colors.dim("Name"),
-      areas: colors.dim("Areas"),
-      assignments: colors.dim("Assignments"),
-      models: colors.dim("Models"),
-      inline: colors.dim("Inline"),
-      twins: colors.dim("Twins"),
-    };
-
-    const renderTemplateTable = (templates: readonly DiscoveredTemplate[]): string =>
-      formatTable(
-        headers,
-        templates.map((template) => ({
-          id: colors.bold(template.id),
-          name: colors.cyan(template.name),
-          areas: String(template.areaCount),
-          assignments: String(template.twinAssignmentCount),
-          models: String(template.uniqueModelCount),
-          inline: String(template.inlineModelCount),
-          twins: String(template.totalTwinCount),
-        })),
-      );
-
-    const renderSection = (label: string, templates: readonly DiscoveredTemplate[]): void => {
-      if (templates.length === 0) return;
-      writeOutput();
-      writeOutput(`  ${colors.bold(`${label}:`)}`);
-      writeOutput(renderTemplateTable(templates));
-    };
-
-    const sortedBuiltinTemplates = sortTemplatesByCategoryAndName(builtinTemplates);
-    const groupedBuiltinTemplates = groupTemplatesByCategory(sortedBuiltinTemplates);
-    if (groupedBuiltinTemplates.length > 0) {
-      writeOutput();
-      writeOutput(`  ${colors.bold("Built-in:")}`);
-      groupedBuiltinTemplates.forEach((group, idx) => {
-        writeOutput(`  ${colors.dim(group.category)}`);
-        writeOutput(renderTemplateTable(group.templates));
-        if (idx < groupedBuiltinTemplates.length - 1) {
-          writeOutput();
-        }
-      });
-    }
-
-    const sortedLocalTemplates = [...localTemplates].sort((a, b) => a.name.localeCompare(b.name));
-    renderSection("Local", sortedLocalTemplates);
-
-    writeOutput();
-  } catch (error) {
-    handleCommandError(error);
-  }
-}
-
-async function templatesInspectAction(
-  idNameOrPath: string,
-  options: TemplateInspectOptions,
-): Promise<void> {
-  try {
-    const catalog = createCatalog();
-    const resolvedPath = await resolveTemplateIdentifier(idNameOrPath, catalog);
-    const sourceLabel = catalog.getSourceLabel(resolvedPath);
-
-    if (options.raw) {
-      const rawText = await Bun.file(resolvedPath).text();
-      process.stdout.write(rawText);
-      return;
-    }
-
-    const template = await loadTemplate(resolvedPath);
-    writeOutput(formatTemplateInspect(template, resolvedPath, sourceLabel));
-  } catch (error) {
-    handleCommandError(error);
-  }
-}
-
-export function formatTemplateInspect(
-  template: import("@miravo/shared").MiravoTemplate,
-  sourcePath: string,
-  sourceLabel: string,
-): string {
-  const lines: string[] = [];
-
-  if (template.description) {
-    lines.push(
-      `  ${colors.cyan(colors.bold(template.name))} ${colors.dim("\u2014")} ${template.description}`,
-    );
-  } else {
-    lines.push(`  ${colors.cyan(colors.bold(template.name))}`);
-  }
-  lines.push("");
-
-  const totalLineCount = template.areas.reduce((sum, area) => sum + area.lines.length, 0);
-  const twinAssignmentCount = template.areas.reduce(
-    (sum, area) => sum + area.lines.reduce((lineSum, line) => lineSum + line.twins.length, 0),
-    0,
-  );
-  const totalTwinCount = template.areas.reduce(
-    (sum, area) =>
-      sum +
-      area.lines.reduce(
-        (lineSum, line) => lineSum + line.twins.reduce((t, twin) => t + twin.count, 0),
-        0,
-      ),
-    0,
-  );
-
-  const referencedModels = collectReferencedModels(template);
-
-  const namespace = template.namespace
-    ? "enterprise" in template.namespace
-      ? `${template.namespace.enterprise}/${template.namespace.site}`
-      : template.namespace.prefix
-    : colors.dim("none");
-
-  const protocols = template.protocols
-    ? Object.keys(template.protocols).join(", ")
-    : colors.dim("none");
-  const relPath = relative(process.cwd(), sourcePath);
-  const templateId = basename(sourcePath, TEMPLATE_FILE_EXTENSION);
-
-  const settings = template.settings;
-  const settingsSummary = settings
-    ? `tick ${settings.tick_interval_ms}ms · speed ${settings.time_multiplier}x${settings.seed !== undefined ? ` · seed ${settings.seed}` : ""}`
-    : colors.dim("defaults");
-
-  lines.push(
-    formatKeyValue([
-      [colors.dim("Source"), `${sourceLabel} ${colors.gray(`(${relPath})`)}`],
-      [colors.dim("Template ID"), colors.bold(templateId)],
-      [colors.dim("Namespace"), namespace],
-      [colors.dim("Areas"), String(template.areas.length)],
-      [colors.dim("Lines"), String(totalLineCount)],
-      [colors.dim("Twin assignments"), String(twinAssignmentCount)],
-      [colors.dim("Total twins"), String(totalTwinCount)],
-      [colors.dim("Referenced models"), String(referencedModels.size)],
-      [colors.dim("Inline models"), String(template.models?.length ?? 0)],
-      [colors.dim("Protocols"), protocols],
-      [colors.dim("Settings"), settingsSummary],
-    ]),
-  );
-
-  lines.push("");
-  lines.push(`  ${colors.bold("Areas:")}`);
-  lines.push(
-    formatTable(
-      {
-        area: colors.dim("Area"),
-        lines: colors.dim("Lines"),
-        assignments: colors.dim("Assignments"),
-        twins: colors.dim("Twins"),
-        models: colors.dim("Models"),
-      },
-      template.areas.map((area) => {
-        const assignments = area.lines.reduce((sum, line) => sum + line.twins.length, 0);
-        const twins = area.lines.reduce(
-          (sum, line) => sum + line.twins.reduce((acc, twin) => acc + twin.count, 0),
-          0,
-        );
-        const modelNames = new Set<string>();
-        for (const line of area.lines) {
-          for (const twin of line.twins) {
-            modelNames.add(twin.model);
-          }
-        }
-
-        return {
-          area: area.name,
-          lines: String(area.lines.length),
-          assignments: String(assignments),
-          twins: String(twins),
-          models: [...modelNames].join(", "),
-        };
-      }),
-    ),
-  );
-
-  return lines.join("\n");
-}

package/src/index.ts

@@ -1,166 +0,0 @@
-#!/usr/bin/env bun
-import { MIRAVO_VERSION } from "@miravo/shared";
-import { Command, InvalidOptionArgumentError } from "commander";
-import { registerAdapterCommand } from "./commands/adapter.ts";
-import { registerApplyCommand } from "./commands/apply.ts";
-import { registerCleanupCommand } from "./commands/cleanup.ts";
-import { registerExportCommand } from "./commands/export.ts";
-import { registerForkCommand } from "./commands/fork.ts";
-import { registerInjectCommand } from "./commands/inject.ts";
-import { registerLoadCommand } from "./commands/load.ts";
-import { registerLogsCommand } from "./commands/logs.ts";
-import { registerModelsCommand } from "./commands/models.ts";
-import { registerPauseCommand, registerResumeCommand } from "./commands/pause.ts";
-import { registerEnvironmentsCommand } from "./commands/platforms.ts";
-import { registerPsCommand } from "./commands/ps.ts";
-import { registerRemoveCommand } from "./commands/remove.ts";
-import { registerResetCommand } from "./commands/reset.ts";
-import { registerRmCommand } from "./commands/rm.ts";
-import { registerSpawnCommand } from "./commands/spawn.ts";
-import { registerSpeedCommand } from "./commands/speed.ts";
-import { registerStartCommand } from "./commands/start/index.ts";
-import { registerStatusCommand } from "./commands/status.ts";
-import { registerStopCommand } from "./commands/stop.ts";
-import { registerTemplatesCommand } from "./commands/templates.ts";
-import { configureLogger, parseLogFormat, parseLogLevel, writeOutput } from "./logger.ts";
-
-/**
- * Create and configure the root Commander.js program.
- * Exported for testing — tests call createProgram() without triggering parse().
- */
-export function createProgram(): Command {
-  const program = new Command();
-
-  program
-    .name("miravo")
-    .description("Industrial environment platform for realistic software-defined plants")
-    .version(MIRAVO_VERSION, "-V, --version", "Print version")
-    .helpOption("-h, --help", "Show help for command")
-    .addHelpCommand("help [command]", "Show help for command")
-    .option("-v, --verbose", "Shorthand for --log-level debug")
-    .option("-q, --quiet", "Suppress all output except errors")
-    .option("--plain", "Use stable plain-text output (no ANSI styling)")
-    .option("--log-level <level>", "Log level: debug | info | warn | error", (value: string) => {
-      try {
-        return parseLogLevel(value);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new InvalidOptionArgumentError(message);
-      }
-    })
-    .option(
-      "--log-format <format>",
-      "Log format: pretty | json",
-      (value: string) => {
-        try {
-          return parseLogFormat(value);
-        } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          throw new InvalidOptionArgumentError(message);
-        }
-      },
-      "pretty",
-    )
-    .addHelpText("afterAll", "\nDocs: https://miravo.dev/docs")
-    .action(() => {
-      writeOutput(`miravo v${MIRAVO_VERSION} — Industrial environment platform
-
-Quick start:
-  $ miravo start                    Start with auto-detected template
-  $ miravo status                   View simulation dashboard
-  $ miravo ps                       List background simulations
-
-Run miravo --help for all commands.
-Docs: https://miravo.dev/docs`);
-    })
-    .hook("preAction", (_thisCommand, actionCommand) => {
-      const rootOpts = program.opts<{
-        verbose?: boolean;
-        quiet?: boolean;
-        plain?: boolean;
-        logLevel?: "debug" | "info" | "warn" | "error";
-        logFormat?: "pretty" | "json";
-      }>();
-      const cmdOpts = actionCommand.opts<{
-        verbose?: boolean;
-        quiet?: boolean;
-        plain?: boolean;
-        logLevel?: "debug" | "info" | "warn" | "error";
-        logFormat?: "pretty" | "json";
-      }>();
-      configureLogger({
-        verbose: rootOpts.verbose ?? cmdOpts.verbose,
-        quiet: rootOpts.quiet ?? cmdOpts.quiet,
-        plain: rootOpts.plain ?? cmdOpts.plain,
-        logLevel: rootOpts.logLevel ?? cmdOpts.logLevel,
-        logFormat: rootOpts.logFormat ?? cmdOpts.logFormat,
-      });
-    });
-
-  // Simulation lifecycle
-  registerStartCommand(program);
-  registerStatusCommand(program);
-  registerPsCommand(program);
-  registerStopCommand(program);
-  registerLogsCommand(program);
-  registerRmCommand(program);
-
-  // Runtime control
-  registerSpawnCommand(program);
-  registerRemoveCommand(program);
-  registerPauseCommand(program);
-  registerResumeCommand(program);
-  registerSpeedCommand(program);
-  registerLoadCommand(program);
-  registerResetCommand(program);
-  registerInjectCommand(program);
-  registerAdapterCommand(program);
-  registerExportCommand(program);
-  registerApplyCommand(program);
-  registerCleanupCommand(program);
-  registerEnvironmentsCommand(program);
-
-  // Content discovery
-  registerModelsCommand(program);
-  registerTemplatesCommand(program);
-  registerForkCommand(program);
-
-  return program;
-}
-
-// Only run when executed directly, not when imported in tests
-if (import.meta.path === Bun.main) {
-  // In compiled binaries, extract embedded content to a temp directory so
-  // ContentCatalog's filesystem-based discovery can find built-in models/templates.
-  // The manifest only exists during `bun run build:standalone`; the catch is a no-op in dev.
-  try {
-    // @ts-expect-error — file is generated at build time and does not exist in source tree
-    const manifest = await import("./_embedded-manifest.ts");
-    const { modelPaths, templatePaths } = manifest as {
-      modelPaths: string[];
-      templatePaths: string[];
-    };
-    const { basename, join } = await import("node:path");
-    const { tmpdir } = await import("node:os");
-    const { mkdirSync } = await import("node:fs");
-    const { registerEmbeddedContentDir } = await import("@miravo/core");
-
-    const contentDir = join(tmpdir(), "miravo-embedded");
-    const modelsDir = join(contentDir, "models");
-    const templatesDir = join(contentDir, "templates");
-    mkdirSync(modelsDir, { recursive: true });
-    mkdirSync(templatesDir, { recursive: true });
-
-    for (const p of modelPaths) {
-      await Bun.write(join(modelsDir, basename(p)), Bun.file(p));
-    }
-    for (const p of templatePaths) {
-      await Bun.write(join(templatesDir, basename(p)), Bun.file(p));
-    }
-
-    registerEmbeddedContentDir(contentDir);
-  } catch {
-    // Not a compiled binary or manifest not present — expected in dev mode
-  }
-  createProgram().parse();
-}