miravo 0.2.3 → 0.3.0

package/src/commands/status.test.ts

@@ -8,7 +8,9 @@ describe("miravo status", () => {
   test("command is registered with correct name and options", async () => {
     const { cmd: statusCmd } = await findCliCommand("status");
     expect(statusCmd).toBeDefined();
-    expect(statusCmd?.description()).toBe("Show status of a running simulation");
+    expect(statusCmd?.description()).toBe(
+      "Show live status, metrics, and instances of a running simulation",
+    );
 
     const optionNames = statusCmd?.options.map((o) => o.long);
     expect(optionNames).toContain("--name");

package/src/commands/status.ts

@@ -8,7 +8,7 @@ import type { Command } from "commander";
 import { colors } from "consola/utils";
 import { getAdminSnapshot, resolveAdminUrl } from "../lib/admin-client.ts";
 import { connectToBroker, disconnectClient } from "../lib/mqtt-client.ts";
-import { parseDurationMs } from "../lib/parse.ts";
+import { parseTimeoutSeconds } from "../lib/parse.ts";
 import { discoverRunningSimulations } from "../lib/resolve-simulation.ts";
 import { engineLog, handleCommandError, isPlain, writeOutput } from "../logger.ts";
 import {
@@ -39,7 +39,7 @@ interface StatusOptions {
 export function registerStatusCommand(program: Command): void {
   program
     .command("status")
-    .description("Show status of a running simulation")
+    .description("Show live status, metrics, and instances of a running simulation")
     .option("--name <name>", "Target simulation name")
     .option("--discover", "Discover running simulations and exit")
     .option("-w, --watch", "Poll the admin server and re-render on updates")
@@ -50,10 +50,16 @@ export function registerStatusCommand(program: Command): void {
       "--template <path>",
       "Path to .miravo.yaml for MQTT discovery connection info (env: MIRAVO_TEMPLATE)",
     )
-    .option(
-      "--timeout <ms>",
-      "Admin request timeout in milliseconds (default: 5000)",
-      parseDurationMs,
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo status                          Show simulation overview
+  $ miravo status -w                       Watch mode (live updates)
+  $ miravo status --instance pump-001      Detail view for one instance
+  $ miravo status --json                   Machine-readable JSON output
+  $ miravo status --discover               Find running simulations via MQTT`,
     )
     .action(async (options: StatusOptions) => {
       await statusAction(options);

package/src/commands/stop.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { DaemonRegistryEntry } from "../lib/daemon-registry.ts";
+import { readEntry, writeEntry } from "../lib/daemon-registry.ts";
+import { resetExitCode, runCliCommand } from "./cli-test-setup.ts";
+
+let testHome: string;
+const originalFetch = globalThis.fetch;
+const originalKill = process.kill;
+const forwardKill = originalKill as (pid: number, signal?: number | NodeJS.Signals) => void;
+
+function makeEntry(overrides: Partial<DaemonRegistryEntry> = {}): DaemonRegistryEntry {
+  return {
+    name: "test-sim",
+    pid: 42_424,
+    adminPort: 8080,
+    adminHost: "127.0.0.1",
+    adapters: {},
+    templatePath: "/tmp/test.miravo.yaml",
+    startedAt: "2026-03-18T10:00:00Z",
+    seed: 42,
+    runId: "run-123",
+    ...overrides,
+  };
+}
+
+beforeEach(resetExitCode);
+
+afterEach(async () => {
+  globalThis.fetch = originalFetch;
+  process.kill = originalKill;
+  delete Bun.env["MIRAVO_HOME"];
+  resetExitCode();
+  if (testHome) {
+    await rm(testHome, { recursive: true, force: true });
+  }
+});
+
+describe("miravo stop", () => {
+  test("force-kills a verified daemon after /shutdown makes /readyz disappear", async () => {
+    testHome = await mkdtemp(join(tmpdir(), "miravo-stop-test-"));
+    Bun.env["MIRAVO_HOME"] = testHome;
+
+    let alive = true;
+    process.kill = ((pid: number, signal?: number | NodeJS.Signals) => {
+      if (pid !== 42_424) {
+        return forwardKill(pid, signal);
+      }
+      if (signal === 0 || signal === undefined) {
+        if (!alive) {
+          const error = new Error("ESRCH") as NodeJS.ErrnoException;
+          error.code = "ESRCH";
+          throw error;
+        }
+        return;
+      }
+      if (signal === "SIGKILL") {
+        alive = false;
+      }
+    }) as typeof process.kill;
+
+    globalThis.fetch = (async (input, init) => {
+      const url = String(input);
+      if (url.endsWith("/readyz")) {
+        return Response.json({ status: "paused", runId: "run-123" }, { status: 503 });
+      }
+      if (url.endsWith("/shutdown")) {
+        expect(init?.method).toBe("POST");
+        return Response.json({ status: "shutting_down" }, { status: 200 });
+      }
+      throw new Error(`Unexpected fetch: ${url}`);
+    }) as typeof fetch;
+
+    await writeEntry(makeEntry());
+
+    await runCliCommand(["stop", "test-sim", "--timeout", "0.001"]);
+
+    expect(alive).toBe(false);
+    expect(await readEntry("test-sim")).toBeNull();
+    expect(process.exitCode).toBe(0);
+  });
+});

package/src/commands/stop.ts

@@ -0,0 +1,158 @@
+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 adminUrl = `http://${entry.adminHost}:${entry.adminPort}/shutdown`;
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    const adminToken = Bun.env["MIRAVO_ADMIN_TOKEN"];
+    if (adminToken) {
+      headers["authorization"] = `Bearer ${adminToken}`;
+    }
+    const response = await fetch(adminUrl, {
+      method: "POST",
+      headers,
+      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

@@ -7,7 +7,7 @@ import { configureLogger } from "../logger.ts";
 import { runCliCommand } from "./cli-test-setup.ts";
 import { formatTemplateInspect } from "./templates.ts";
 
-configureLogger({ silent: true });
+configureLogger({ quiet: true });
 
 const templatesDir = resolve(import.meta.dir, "..", "..", "..", "content", "templates");
 const { cleanupTmpDir } = createTmpFileUtils(resolve(import.meta.dir, ".tmp-test-templates"));

package/src/commands/templates.ts

@@ -20,6 +20,12 @@ export function registerTemplatesCommand(program: Command): void {
     .command("list")
     .description("Discover and list available templates")
     .option("--dir <path>", "Additional directory to search for templates")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo templates list                  List all discoverable templates`,
+    )
     .action(async (options: { readonly dir?: string }) => {
       await templatesListAction(options);
     });
@@ -28,6 +34,13 @@ export function registerTemplatesCommand(program: Command): void {
     .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,

package/src/index.ts

@@ -1,13 +1,24 @@
 #!/usr/bin/env bun
 import { MIRAVO_VERSION } from "@miravo/shared";
 import { Command, InvalidOptionArgumentError } from "commander";
+import { registerAdapterCommand } from "./commands/adapter.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 { 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.ts";
 import { registerStatusCommand } from "./commands/status.ts";
+import { registerStopCommand } from "./commands/stop.ts";
 import { registerTemplatesCommand } from "./commands/templates.ts";
-import { configureLogger, parseLogFormat, parseLogLevel } from "./logger.ts";
+import { configureLogger, parseLogFormat, parseLogLevel, writeOutput } from "./logger.ts";
 
 /**
  * Create and configure the root Commander.js program.
@@ -20,8 +31,10 @@ export function createProgram(): Command {
     .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("--silent", "Suppress all output except errors")
+    .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 {
@@ -44,36 +57,65 @@ export function createProgram(): Command {
       },
       "pretty",
     )
+    .addHelpText("afterAll", "\nDocs: https://github.com/amine-amaach/miravo")
+    .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://github.com/amine-amaach/miravo`);
+    })
     .hook("preAction", (_thisCommand, actionCommand) => {
       const rootOpts = program.opts<{
         verbose?: boolean;
-        silent?: boolean;
+        quiet?: boolean;
         plain?: boolean;
         logLevel?: "debug" | "info" | "warn" | "error";
         logFormat?: "pretty" | "json";
       }>();
       const cmdOpts = actionCommand.opts<{
         verbose?: boolean;
-        silent?: boolean;
+        quiet?: boolean;
         plain?: boolean;
         logLevel?: "debug" | "info" | "warn" | "error";
         logFormat?: "pretty" | "json";
       }>();
       configureLogger({
         verbose: rootOpts.verbose ?? cmdOpts.verbose,
-        silent: rootOpts.silent ?? cmdOpts.silent,
+        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);
+
+  // Content discovery
   registerModelsCommand(program);
   registerTemplatesCommand(program);
   registerForkCommand(program);
-  registerInjectCommand(program);
-  registerStatusCommand(program);
 
   return program;
 }

package/src/lib/admin-client.test.ts

@@ -0,0 +1,35 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { EngineCommand } from "@miravo/shared";
+import { executeAdminCommand } from "./admin-client.ts";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  delete Bun.env["MIRAVO_ADMIN_TOKEN"];
+});
+
+describe("admin-client", () => {
+  test("forwards MIRAVO_ADMIN_TOKEN on command requests", async () => {
+    Bun.env["MIRAVO_ADMIN_TOKEN"] = "secret-token";
+
+    globalThis.fetch = (async (_input, init) => {
+      expect(init?.headers).toEqual({
+        "content-type": "application/json",
+        authorization: "Bearer secret-token",
+      });
+      return Response.json({
+        success: true,
+        command: "pause",
+        correlationId: "req-1",
+        message: "paused",
+      });
+    }) as typeof fetch;
+
+    const command: EngineCommand = { type: "pause", correlationId: "req-1" };
+    const result = await executeAdminCommand("http://127.0.0.1:8080", command, 1_000);
+
+    expect(result.success).toBe(true);
+    expect(result.command).toBe("pause");
+  });
+});

package/src/lib/admin-client.ts

@@ -87,6 +87,18 @@ function parseAdminUrl(input: string): string {
   return url.toString().replace(/\/$/, "");
 }
 
+function buildRequestHeaders(body?: string): Record<string, string> | undefined {
+  const headers: Record<string, string> = {};
+  if (body) {
+    headers["content-type"] = "application/json";
+  }
+  const adminToken = Bun.env["MIRAVO_ADMIN_TOKEN"];
+  if (adminToken && adminToken.trim().length > 0) {
+    headers["authorization"] = `Bearer ${adminToken}`;
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
 async function requestJson<T>(options: RequestJsonOptions<T>): Promise<T> {
   const requestUrl = new URL(options.path, `${options.baseUrl}/`).toString();
   const controller = new AbortController();
@@ -97,7 +109,7 @@ async function requestJson<T>(options: RequestJsonOptions<T>): Promise<T> {
     try {
       response = await fetch(requestUrl, {
         method: options.method ?? "GET",
-        headers: options.body ? { "content-type": "application/json" } : undefined,
+        headers: buildRequestHeaders(options.body),
         body: options.body,
         signal: controller.signal,
       });