@mostra/sdk 0.0.0-stage → 0.2.0

package/src/runtime.ts

@@ -0,0 +1,179 @@
+/**
+ * Which runtime a host runs (RT-01, D85). In order:
+ *
+ * 1. `bundle`, a directory the caller names (the SDK's option), then `MOSTRA_BUNDLE`;
+ * 2. `MOSTRA_RUNTIME_BIN`, a `mostra-runtime` entry run with this process's Node (tests and
+ *    development);
+ * 3. the bundle this package itself sits in (the CLI inside a bundle);
+ * 4. the bundle this package's release pins (`bundles.json`), from the cache or downloaded;
+ * 5. a development checkout's built runtime beside this package.
+ *
+ * Anything a bundle supplies is checked first: its setup marker must match it, or setup runs.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { BundlePins, createDiagnostic, RpcError } from "@mostra/protocol";
+import { type InstallProgress, installPinned } from "./bundle/cache.ts";
+import {
+  type Bundle,
+  type Environment,
+  readBundle,
+  readSetup,
+  type SetupStep,
+  setupBundle,
+} from "./bundle/setup.ts";
+import { bundlePlatform } from "./platform.ts";
+import { packageRoot } from "./version.ts";
+
+/** A runtime to spawn: the Node.js to run it with and its entry points. */
+export interface Runtime {
+  /** How it was found. */
+  readonly source: "bundle" | "override" | "development";
+  /** The Node.js executable: the bundle's own, or this process's for the others. */
+  readonly node: string;
+  /** `mostra-runtime`'s entry (`host`, `daemon`, `service`). */
+  readonly runtimeEntry: string;
+  /** The `mostra` CLI's entry, when this runtime has one. */
+  readonly cliEntry?: string;
+  /** The bundle, when the runtime is one. */
+  readonly bundle?: Bundle;
+}
+
+/** Options of {@link resolveRuntime}. */
+export interface RuntimeOptions {
+  /** An extracted bundle to use, ahead of everything else. */
+  readonly bundle?: string | undefined;
+  /** The environment: `MOSTRA_BUNDLE`, `MOSTRA_RUNTIME_BIN`, the cache's variables. */
+  readonly env?: Environment | undefined;
+  /** Gives up a download or setup. */
+  readonly signal?: AbortSignal | undefined;
+  /** Progress of a download or setup, for a person waiting (the CLI prints it on stderr). */
+  readonly onProgress?: ((progress: InstallProgress) => void) | undefined;
+}
+
+/**
+ * Where the pins are read from: `<package>/dist/bundles.json`, which the release writes before
+ * publishing. `MOSTRA_TEST_BUNDLE_PINS` names another file only for a package that runs from a
+ * development checkout (its real path outside any `node_modules`), where the tests use it: an
+ * installed copy (npm's `node_modules`, or a bundle's `lib/node_modules`) ignores it, so a
+ * variable leaked into a user's environment can't swap the pins npm's provenance covers (Opus
+ * review finding 8).
+ */
+export function pinsFile(env: Environment, root: string): string {
+  const override = env["MOSTRA_TEST_BUNDLE_PINS"];
+  const installed = root.split(sep).includes("node_modules");
+  return override && !installed ? override : join(root, "dist", "bundles.json");
+}
+
+/** The pins this build carries: `dist/bundles.json` (a test override applies only in a development checkout). */
+export function readPins(env: Environment): BundlePins | undefined {
+  const file = pinsFile(env, packageRoot());
+  if (!existsSync(file)) return undefined;
+  let data: unknown;
+  try {
+    data = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    data = undefined; // not JSON (or unreadable): the same refusal as a file of the wrong shape
+  }
+  const parsed = BundlePins.safeParse(data);
+  if (!parsed.success) {
+    throw new RpcError(
+      createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", {
+        message: `${file} isn't a release's bundle pins.`,
+      }),
+    );
+  }
+  return parsed.data;
+}
+
+/** The bundle this package was installed into, if any: `<root>/lib/node_modules/@mostra/sdk`. */
+export function enclosingBundle(): string | undefined {
+  const root = resolve(packageRoot(), "..", "..", "..", "..");
+  return existsSync(join(root, "bundle.json")) &&
+    existsSync(join(root, "lib", "node_modules", "@mostra", "sdk"))
+    ? root
+    : undefined;
+}
+
+/** The runtime described by a bundle, once it is set up. */
+async function fromBundle(root: string, options: RuntimeOptions): Promise<Runtime> {
+  let bundle = await readBundle(resolve(root));
+  if (!(await readSetup(bundle))) {
+    await setupBundle(bundle.root, {
+      env: options.env,
+      signal: options.signal,
+      onStep: (step: SetupStep) => options.onProgress?.({ step }),
+    });
+    bundle = await readBundle(bundle.root);
+  }
+  return runtimeOf(bundle);
+}
+
+/** A bundle's entry points as a runtime. */
+export function runtimeOf(bundle: Bundle): Runtime {
+  const { root, info } = bundle;
+  return {
+    source: "bundle",
+    node: join(root, info.node.path),
+    runtimeEntry: join(root, info.entries.runtime),
+    cliEntry: join(root, info.entries.cli),
+    bundle,
+  };
+}
+
+/** A development checkout's runtime: `packages/runtime/dist/bin.js` beside this package. */
+function development(): Runtime | undefined {
+  const root = packageRoot();
+  const entry = resolve(root, "..", "runtime", "dist", "bin.js");
+  if (!existsSync(entry)) return undefined;
+  const cli = resolve(root, "..", "cli", "dist", "bin.js");
+  return {
+    source: "development",
+    node: process.execPath,
+    runtimeEntry: entry,
+    ...(existsSync(cli) ? { cliEntry: cli } : {}),
+  };
+}
+
+/**
+ * Finds the runtime to spawn, downloading and setting up the pinned bundle when nothing nearer
+ * exists. Throws `MOSTRA_PLATFORM_UNSUPPORTED`, `MOSTRA_ENV_RUNTIME_MISSING` (a
+ * `MOSTRA_RUNTIME_BIN` that doesn't exist), `MOSTRA_ENV_BUNDLE_UNAVAILABLE`,
+ * `MOSTRA_ENV_BUNDLE_INVALID` or `MOSTRA_ENV_BUNDLE_DOWNLOAD_FAILED`.
+ */
+export async function resolveRuntime(options: RuntimeOptions = {}): Promise<Runtime> {
+  const env = options.env ?? process.env;
+  const named = options.bundle ?? (env["MOSTRA_BUNDLE"] || undefined);
+  if (named !== undefined) return fromBundle(named, { ...options, env });
+  const override = env["MOSTRA_RUNTIME_BIN"];
+  if (override) {
+    if (!existsSync(override)) {
+      throw new RpcError(
+        createDiagnostic("MOSTRA_ENV_RUNTIME_MISSING", {
+          message: `MOSTRA_RUNTIME_BIN names ${override}, which doesn't exist.`,
+        }),
+      );
+    }
+    return { source: "override", node: process.execPath, runtimeEntry: override };
+  }
+  const enclosing = enclosingBundle();
+  if (enclosing !== undefined) return fromBundle(enclosing, { ...options, env });
+  const pins = readPins(env);
+  if (pins !== undefined) {
+    const bundle = await installPinned(pins, {
+      env,
+      platform: bundlePlatform(),
+      signal: options.signal,
+      onProgress: options.onProgress,
+    });
+    return runtimeOf(bundle);
+  }
+  const checkout = development();
+  if (checkout !== undefined) return checkout;
+  throw new RpcError(
+    createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", {
+      message:
+        "This build of @mostra/sdk pins no runtime bundle and has no runtime beside it; set MOSTRA_BUNDLE to an extracted bundle.",
+    }),
+  );
+}

package/src/setup-main.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * `mostra-setup [--root <bundle>]`: makes an extracted runtime bundle ready (D142). It checks every
+ * file against `files.json`, fetches the pinned verify browser and writes `.mostra-setup.json`.
+ * The bundle's `bin/mostra-setup` runs it for the bundle it sits in; the Rust crate (WP-12) and
+ * anyone who extracts an archive by hand run it once. It prints one JSON line on stdout,
+ * `{ "status": "ok", "bundle": { … } }` or `{ "status": "failed", "diagnostic": { … } }` (exit 3),
+ * and its progress on stderr.
+ */
+import { parseArgs } from "node:util";
+import { createDiagnostic, RpcError } from "@mostra/protocol";
+import { setupBundle } from "./bundle/setup.ts";
+import { enclosingBundle } from "./runtime.ts";
+
+const STEPS = { files: "Checking the bundle's files", browser: "Fetching the verify browser" };
+
+async function main(): Promise<number> {
+  const { values } = parseArgs({ options: { root: { type: "string" } }, strict: true });
+  const root = values.root ?? enclosingBundle();
+  if (root === undefined) {
+    throw new RpcError(
+      createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", {
+        message: "mostra-setup isn't inside a runtime bundle; pass --root <bundle directory>.",
+      }),
+    );
+  }
+  const marker = await setupBundle(root, {
+    onStep: (step) => process.stderr.write(`mostra-setup: ${STEPS[step]}…\n`),
+  });
+  process.stdout.write(`${JSON.stringify({ status: "ok", bundle: { root, ...marker } })}\n`);
+  return 0;
+}
+
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error: unknown) => {
+    const diagnostic =
+      error instanceof RpcError
+        ? error.diagnostic
+        : createDiagnostic("MOSTRA_HOST_INTERNAL_ERROR", {
+            message: `mostra-setup failed: ${(error as Error).message}`,
+          });
+    process.stdout.write(`${JSON.stringify({ status: "failed", diagnostic })}\n`);
+    process.stderr.write(`mostra-setup: ${diagnostic.message}\n`);
+    process.exitCode = 3;
+  },
+);

package/src/version.ts

@@ -0,0 +1,38 @@
+/** The SDK's own package: its root directory and its release. */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+let found: { readonly root: string; readonly version: string } | undefined;
+
+function own(): { readonly root: string; readonly version: string } {
+  if (found) return found;
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as {
+        name?: string;
+        version?: string;
+      };
+      if (manifest.name === "@mostra/sdk" && manifest.version) {
+        found = { root: dir, version: manifest.version };
+        return found;
+      }
+    } catch {
+      // Keep looking upwards.
+    }
+    const parent = dirname(dir);
+    if (parent === dir) throw new Error("Couldn't find @mostra/sdk's package.json.");
+    dir = parent;
+  }
+}
+
+/** This SDK's release: the client version an SDK host reports by default. */
+export function sdkVersion(): string {
+  return own().version;
+}
+
+/** The SDK package's directory; `dist/bundles.json` lives under it in a release. */
+export function packageRoot(): string {
+  return own().root;
+}