miravo 0.1.4 → 0.2.1

package/src/commands/templates.ts

@@ -1,25 +1,15 @@
-import { mkdir } from "node:fs/promises";
-import { basename, join, relative, resolve } from "node:path";
-import {
-  type DiscoveredTemplateWithSource,
-  discoverTemplates,
-  loadTemplate,
-  resolveModelPath,
-} from "@miravo/core";
-import {
-  type DiscoveredTemplate,
-  MIRAVO_CONTENT_DIR_ENV,
-  MiravoError,
-  type MiravoTemplate,
-  TEMPLATE_FILE_EXTENSION,
-} from "@miravo/shared";
+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";
 
@@ -30,11 +20,7 @@ export function registerTemplatesCommand(program: Command): void {
     .command("list")
     .description("Discover and list available templates")
     .option("--dir <path>", "Additional directory to search for templates")
-    .option(
-      "--content-dir <path>",
-      "User content root with /templates and /models (env: MIRAVO_CONTENT_DIR)",
-    )
-    .action(async (options: { readonly dir?: string; readonly contentDir?: string }) => {
+    .action(async (options: { readonly dir?: string }) => {
       await templatesListAction(options);
     });
 
@@ -42,18 +28,11 @@ 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")
-    .option("--copy", "Copy template + referenced built-in models to user content directory")
-    .option(
-      "--content-dir <path>",
-      "User content root with /templates and /models (env: MIRAVO_CONTENT_DIR)",
-    )
     .action(
       async (
         idNameOrPath: string,
         options: {
           readonly raw?: boolean;
-          readonly copy?: boolean;
-          readonly contentDir?: string;
         },
       ) => {
         await templatesInspectAction(idNameOrPath, options);
@@ -63,20 +42,19 @@ export function registerTemplatesCommand(program: Command): void {
 
 interface TemplateListOptions {
   readonly dir?: string;
-  readonly contentDir?: string;
 }
 
 interface TemplateInspectOptions {
   readonly raw?: boolean;
-  readonly copy?: boolean;
-  readonly contentDir?: string;
 }
 
 async function templatesListAction(options: TemplateListOptions): Promise<void> {
   try {
-    const catalog = createCatalog(options.contentDir);
+    const catalog = createCatalog();
     const all = await catalog.listTemplates();
-    const builtinTemplates = all.filter((t) => t.source.kind === "builtin");
+    const builtinTemplates = all.filter(
+      (t) => t.source.kind === "builtin" && !isStressBenchmarkTemplate(t.id),
+    );
     const localTemplates: DiscoveredTemplateWithSource[] = all.filter(
       (t) => t.source.kind !== "builtin",
     );
@@ -164,17 +142,10 @@ async function templatesInspectAction(
   options: TemplateInspectOptions,
 ): Promise<void> {
   try {
-    const catalog = createCatalog(options.contentDir);
+    const catalog = createCatalog();
     const resolvedPath = await resolveTemplateIdentifier(idNameOrPath, catalog);
     const sourceLabel = catalog.getSourceLabel(resolvedPath);
 
-    if (options.raw && options.copy) {
-      throw new MiravoError(
-        "Cannot combine --raw with --copy.",
-        "Run either 'miravo templates inspect <template> --raw' or 'miravo templates inspect <template> --copy'.",
-      );
-    }
-
     if (options.raw) {
       const rawText = await Bun.file(resolvedPath).text();
       process.stdout.write(rawText);
@@ -183,163 +154,13 @@ async function templatesInspectAction(
 
     const template = await loadTemplate(resolvedPath);
     writeOutput(formatTemplateInspect(template, resolvedPath, sourceLabel));
-    if (options.copy) {
-      const contentDir = options.contentDir ?? Bun.env[MIRAVO_CONTENT_DIR_ENV];
-      const targetRootDir = contentDir ? resolve(contentDir) : process.cwd();
-      await copyTemplateBundle({
-        sourceTemplatePath: resolvedPath,
-        template,
-        contentRootDir: targetRootDir,
-        builtinModelsDir: catalog.getBuiltinModelsDir(),
-      });
-    }
   } catch (error) {
     handleCommandError(error);
   }
 }
 
-interface CopyTemplateBundleOptions {
-  readonly sourceTemplatePath: string;
-  readonly template: MiravoTemplate;
-  readonly contentRootDir: string;
-  readonly builtinModelsDir: string;
-}
-
-interface CopyStats {
-  created: number;
-  skipped: number;
-  warnings: number;
-}
-
-async function copyTemplateBundle(options: CopyTemplateBundleOptions): Promise<void> {
-  const { sourceTemplatePath, template, contentRootDir, builtinModelsDir } = options;
-  const templatesDir = join(contentRootDir, "templates");
-  const modelsDir = join(contentRootDir, "models");
-  try {
-    await mkdir(templatesDir, { recursive: true });
-    await mkdir(modelsDir, { recursive: true });
-  } catch (error) {
-    throw toContentWriteError(error, contentRootDir);
-  }
-
-  const stats: CopyStats = { created: 0, skipped: 0, warnings: 0 };
-
-  const targetTemplatePath = resolve(templatesDir, basename(sourceTemplatePath));
-  await copyFileWithPolicy({
-    sourcePath: sourceTemplatePath,
-    targetPath: targetTemplatePath,
-    kind: "template",
-    stats,
-    contentRootDir,
-  });
-
-  const inlineModels = new Set((template.models ?? []).map((model) => model.name));
-  const referencedModels = collectReferencedModels(template);
-
-  for (const modelName of referencedModels) {
-    if (inlineModels.has(modelName)) {
-      continue;
-    }
-
-    let sourceModelPath: string;
-    try {
-      sourceModelPath = await resolveModelPath(modelName, [builtinModelsDir]);
-    } catch {
-      configLog.warn(`Skipped model "${modelName}": built-in model not found.`);
-      stats.warnings++;
-      continue;
-    }
-    if (!sourceModelPath.startsWith(builtinModelsDir)) {
-      configLog.warn(`Skipped model "${modelName}": only built-in referenced models are copied.`);
-      stats.warnings++;
-      continue;
-    }
-
-    const targetModelPath = resolve(modelsDir, basename(sourceModelPath));
-    await copyFileWithPolicy({
-      sourcePath: sourceModelPath,
-      targetPath: targetModelPath,
-      kind: `model "${modelName}"`,
-      stats,
-      contentRootDir,
-    });
-  }
-
-  writeOutput();
-  writeOutput(`  ${colors.bold("Copy Summary:")}`);
-  writeOutput(`  root: ${colors.cyan(contentRootDir)}`);
-  writeOutput(
-    `  created: ${stats.created} · skipped: ${stats.skipped} · warnings: ${stats.warnings}`,
-  );
-}
-
-async function copyFileWithPolicy(options: {
-  readonly sourcePath: string;
-  readonly targetPath: string;
-  readonly kind: string;
-  readonly stats: CopyStats;
-  readonly contentRootDir: string;
-}): Promise<void> {
-  const { sourcePath, targetPath, kind, stats, contentRootDir } = options;
-  if (resolve(sourcePath) === resolve(targetPath)) {
-    configLog.warn(`Skipped ${kind}: source and destination are the same (${targetPath}).`);
-    stats.skipped++;
-    stats.warnings++;
-    return;
-  }
-
-  const targetExists = await Bun.file(targetPath).exists();
-  if (targetExists) {
-    configLog.warn(`Skipped ${kind}: already exists in content directory (${targetPath}).`);
-    stats.skipped++;
-    return;
-  }
-
-  const contents = await Bun.file(sourcePath).text();
-  try {
-    await Bun.write(targetPath, contents);
-  } catch (error) {
-    throw toContentWriteError(error, contentRootDir);
-  }
-  stats.created++;
-}
-
-function toContentWriteError(error: unknown, contentRootDir: string): MiravoError {
-  if (isPermissionError(error)) {
-    return new MiravoError(
-      `Cannot write to content directory "${contentRootDir}".`,
-      `Ensure "${contentRootDir}" is writable by the current user/container (for example: chmod/chown the mount, or run compose with UID/GID mapping).`,
-    );
-  }
-
-  const message = error instanceof Error ? error.message : String(error);
-  return new MiravoError(
-    `Failed to copy content into "${contentRootDir}": ${message}`,
-    "Ensure the destination path exists and is writable, then retry with --copy.",
-  );
-}
-
-function isPermissionError(error: unknown): boolean {
-  if (!error || typeof error !== "object") return false;
-  if (!("code" in error)) return false;
-  const code = (error as { code?: unknown }).code;
-  return code === "EACCES" || code === "EPERM";
-}
-
-function collectReferencedModels(template: MiravoTemplate): Set<string> {
-  const referencedModels = new Set<string>();
-  for (const area of template.areas) {
-    for (const line of area.lines) {
-      for (const twin of line.twins) {
-        referencedModels.add(twin.model);
-      }
-    }
-  }
-  return referencedModels;
-}
-
 export function formatTemplateInspect(
-  template: MiravoTemplate,
+  template: import("@miravo/shared").MiravoTemplate,
   sourcePath: string,
   sourceLabel: string,
 ): string {

package/src/index.ts

@@ -1,12 +1,13 @@
 #!/usr/bin/env bun
 import { MIRAVO_VERSION } from "@miravo/shared";
 import { Command, InvalidOptionArgumentError } from "commander";
+import { registerForkCommand } from "./commands/fork.ts";
 import { registerInjectCommand } from "./commands/inject.ts";
 import { registerModelsCommand } from "./commands/models.ts";
 import { registerStartCommand } from "./commands/start.ts";
 import { registerStatusCommand } from "./commands/status.ts";
 import { registerTemplatesCommand } from "./commands/templates.ts";
-import { configureLogger, parseLogFormat } from "./logger.ts";
+import { configureLogger, parseLogFormat, parseLogLevel } from "./logger.ts";
 
 /**
  * Create and configure the root Commander.js program.
@@ -17,11 +18,19 @@ export function createProgram(): Command {
 
   program
     .name("miravo")
-    .description("Digital Twin Engine for Industrial IoT")
+    .description("Industrial environment platform for realistic software-defined plants")
     .version(MIRAVO_VERSION, "-V, --version", "Print version")
-    .option("-v, --verbose", "Enable debug-level logging")
+    .option("-v, --verbose", "Shorthand for --log-level debug")
     .option("--silent", "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",
@@ -40,18 +49,21 @@ export function createProgram(): Command {
         verbose?: boolean;
         silent?: boolean;
         plain?: boolean;
+        logLevel?: "debug" | "info" | "warn" | "error";
         logFormat?: "pretty" | "json";
       }>();
       const cmdOpts = actionCommand.opts<{
         verbose?: boolean;
         silent?: boolean;
         plain?: boolean;
+        logLevel?: "debug" | "info" | "warn" | "error";
         logFormat?: "pretty" | "json";
       }>();
       configureLogger({
         verbose: rootOpts.verbose ?? cmdOpts.verbose,
         silent: rootOpts.silent ?? cmdOpts.silent,
         plain: rootOpts.plain ?? cmdOpts.plain,
+        logLevel: rootOpts.logLevel ?? cmdOpts.logLevel,
         logFormat: rootOpts.logFormat ?? cmdOpts.logFormat,
       });
     });
@@ -59,24 +71,46 @@ export function createProgram(): Command {
   registerStartCommand(program);
   registerModelsCommand(program);
   registerTemplatesCommand(program);
+  registerForkCommand(program);
   registerInjectCommand(program);
   registerStatusCommand(program);
-  // TODO(cli): Add `miravo completion <shell>` to generate shell completion scripts.
 
   return program;
 }
 
 // Only run when executed directly, not when imported in tests
 if (import.meta.path === Bun.main) {
-  // Import the generated manifest to trigger Bun's file embedding in compiled binaries.
+  // 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
-    await import("./_embedded-manifest.ts");
+    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
   }
-  const { prepareEmbeddedContent } = await import("@miravo/core");
-  await prepareEmbeddedContent();
   createProgram().parse();
 }

package/src/lib/admin-client.ts

@@ -0,0 +1,214 @@
+import type {
+  CommandResult,
+  EngineCommand,
+  EngineMetricsSnapshot,
+  EngineStateSnapshot,
+} from "@miravo/shared";
+import {
+  CommandResultSchema,
+  EngineMetricsSnapshotSchema,
+  EngineStateSnapshotSchema,
+  MiravoError,
+} from "@miravo/shared";
+
+const DEFAULT_ADMIN_HOST = "127.0.0.1";
+const DEFAULT_ADMIN_PORT = 8080;
+
+interface SafeParseResult<T> {
+  readonly success: boolean;
+  readonly data?: T;
+}
+
+interface SafeParseSchema<T> {
+  safeParse(value: unknown): SafeParseResult<T>;
+}
+
+interface RequestJsonOptions<T> {
+  readonly baseUrl: string;
+  readonly path: string;
+  readonly timeoutMs: number;
+  readonly schema: SafeParseSchema<T>;
+  readonly method?: "GET" | "POST";
+  readonly body?: string;
+}
+
+function normalizeAdminHost(host: string): string {
+  return host === "0.0.0.0" || host === "::" ? DEFAULT_ADMIN_HOST : host;
+}
+
+function resolveAdminUrl(adminUrl?: string): string {
+  const explicitUrl = adminUrl ?? Bun.env["MIRAVO_ADMIN_URL"];
+  if (explicitUrl && explicitUrl.trim().length > 0) {
+    return parseAdminUrl(explicitUrl);
+  }
+
+  const hostValue = Bun.env["MIRAVO_ADMIN_HOST"] ?? DEFAULT_ADMIN_HOST;
+  if (hostValue.trim().length === 0) {
+    throw new MiravoError(
+      "Invalid MIRAVO_ADMIN_HOST environment variable: value is empty.",
+      "Set MIRAVO_ADMIN_HOST to a valid host such as 127.0.0.1 or 0.0.0.0.",
+    );
+  }
+  const host = normalizeAdminHost(hostValue);
+  const portValue = Bun.env["MIRAVO_ADMIN_PORT"];
+  if (!portValue) {
+    return `http://${host}:${DEFAULT_ADMIN_PORT}`;
+  }
+
+  const parsedPort = Number(portValue);
+  if (!Number.isInteger(parsedPort) || parsedPort < 1 || parsedPort > 65535) {
+    throw new MiravoError(
+      `Invalid MIRAVO_ADMIN_PORT environment variable: "${portValue}".`,
+      "Set MIRAVO_ADMIN_PORT to a valid port number between 1 and 65535.",
+    );
+  }
+
+  return `http://${host}:${parsedPort}`;
+}
+
+function parseAdminUrl(input: string): string {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new MiravoError(
+      `Invalid admin URL: "${input}".`,
+      "Pass --admin-url with a full HTTP URL such as http://127.0.0.1:8080.",
+    );
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new MiravoError(
+      `Invalid admin URL protocol: "${url.protocol}".`,
+      "Pass an HTTP or HTTPS URL such as http://127.0.0.1:8080.",
+    );
+  }
+
+  return url.toString().replace(/\/$/, "");
+}
+
+async function requestJson<T>(options: RequestJsonOptions<T>): Promise<T> {
+  const requestUrl = new URL(options.path, `${options.baseUrl}/`).toString();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs);
+
+  try {
+    let response: Response;
+    try {
+      response = await fetch(requestUrl, {
+        method: options.method ?? "GET",
+        headers: options.body ? { "content-type": "application/json" } : undefined,
+        body: options.body,
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new MiravoError(
+          `Admin request to ${requestUrl} timed out after ${options.timeoutMs}ms.`,
+          "Check that Miravo is running and the admin URL is reachable.",
+        );
+      }
+
+      const message = error instanceof Error ? error.message : String(error);
+      throw new MiravoError(
+        `Admin request to ${requestUrl} failed: ${message}`,
+        "Check that Miravo is running and the admin URL is correct.",
+      );
+    }
+
+    const text = await response.text();
+    let parsedJson: unknown;
+    if (text.length > 0) {
+      try {
+        parsedJson = JSON.parse(text);
+      } catch {
+        throw new MiravoError(
+          `Admin server returned invalid JSON from ${requestUrl}.`,
+          "Check the Miravo admin server logs and retry.",
+        );
+      }
+    }
+
+    if (!response.ok) {
+      const details =
+        typeof parsedJson === "object" &&
+        parsedJson !== null &&
+        "message" in parsedJson &&
+        typeof (parsedJson as Record<string, unknown>)["message"] === "string"
+          ? String((parsedJson as Record<string, unknown>)["message"])
+          : `HTTP ${response.status}`;
+      const fix =
+        typeof parsedJson === "object" &&
+        parsedJson !== null &&
+        "error" in parsedJson &&
+        typeof (parsedJson as Record<string, unknown>)["error"] === "string"
+          ? String((parsedJson as Record<string, unknown>)["error"])
+          : "Check that Miravo is running and the admin request is valid.";
+      throw new MiravoError(`Admin request to ${requestUrl} failed: ${details}`, fix);
+    }
+
+    const validation = options.schema.safeParse(parsedJson);
+    if (!validation.success || validation.data === undefined) {
+      throw new MiravoError(
+        `Admin server returned an unexpected payload from ${requestUrl}.`,
+        "Check that the Miravo CLI and server are running the same version.",
+      );
+    }
+
+    return validation.data;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function getAdminMetrics(
+  adminUrl: string,
+  timeoutMs: number,
+): Promise<EngineMetricsSnapshot> {
+  return requestJson({
+    baseUrl: adminUrl,
+    path: "/metrics",
+    timeoutMs,
+    schema: EngineMetricsSnapshotSchema,
+  });
+}
+
+async function getAdminState(adminUrl: string, timeoutMs: number): Promise<EngineStateSnapshot> {
+  return requestJson({
+    baseUrl: adminUrl,
+    path: "/state",
+    timeoutMs,
+    schema: EngineStateSnapshotSchema,
+  });
+}
+
+async function getAdminSnapshot(
+  adminUrl: string,
+  timeoutMs: number,
+): Promise<{
+  readonly metrics: EngineMetricsSnapshot;
+  readonly state: EngineStateSnapshot;
+}> {
+  const [metrics, state] = await Promise.all([
+    getAdminMetrics(adminUrl, timeoutMs),
+    getAdminState(adminUrl, timeoutMs),
+  ]);
+  return { metrics, state };
+}
+
+async function executeAdminCommand(
+  adminUrl: string,
+  command: EngineCommand,
+  timeoutMs: number,
+): Promise<CommandResult> {
+  return requestJson({
+    baseUrl: adminUrl,
+    path: "/commands",
+    timeoutMs,
+    schema: CommandResultSchema,
+    method: "POST",
+    body: JSON.stringify(command),
+  });
+}
+
+export { executeAdminCommand, getAdminMetrics, getAdminSnapshot, getAdminState, resolveAdminUrl };