@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/deep-merge.ts

@@ -0,0 +1,33 @@
+/**
+ * Deep-merge `over` on top of `base`. Plain objects recurse; everything
+ * else (scalars, arrays, `{__realmRef}` secret markers) replaces wholesale.
+ *
+ * Used to fold a `configSchema`-synthesized default shape together with
+ * saved config values, and (in the Home eval pipeline) to fold resolved
+ * permission values into the same tree so `getDesiredState` receives one
+ * unified `config` argument.
+ */
+export function deepMergeConfig(
+  base: Record<string, unknown>,
+  over: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base };
+  for (const [k, v] of Object.entries(over)) {
+    const current = out[k];
+    if (isPlainMergeableObject(v) && isPlainMergeableObject(current)) {
+      out[k] = deepMergeConfig(current as Record<string, unknown>, v as Record<string, unknown>);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function isPlainMergeableObject(v: unknown): boolean {
+  return (
+    v != null &&
+    typeof v === "object" &&
+    !Array.isArray(v) &&
+    !("__realmRef" in (v as Record<string, unknown>))
+  );
+}

package/src/dev/fixture.ts

@@ -0,0 +1,48 @@
+// `realm-sdk dev` fixture loader. The dev server compiles a realm.ts against a
+// CompileFixture (config + grants + peers) the same way the test harness does,
+// standing in for the operator's deploy form and the peer-world. The values
+// come from a `realm-sdk.dev.ts` next to the realm.ts — plain TS whose default
+// export matches `CompileFixture<typeof app>` — or from an empty fixture, so
+// apps needing neither config nor grants work with no file at all.
+
+import { resolve } from "@std/path";
+import type { CompileFixture } from "../test/types.ts";
+
+const DEV_FIXTURE_FILENAME = "realm-sdk.dev.ts";
+
+interface LoadResult {
+  fixture: CompileFixture<unknown>;
+  /** Absolute path to the loaded fixture, or null if defaults were used. */
+  source: string | null;
+}
+
+export async function loadDevFixture(cwd: string): Promise<LoadResult> {
+  const path = resolve(cwd, DEV_FIXTURE_FILENAME);
+  try {
+    await Deno.stat(path);
+  } catch {
+    // No dev fixture — fall back to empty. An app with required config or
+    // grants then fails to compile with an error pointing at writing one.
+    return {
+      fixture: { config: {} as never },
+      source: null,
+    };
+  }
+
+  // Deno resolves a dynamic import against its own URL, so the specifier is a
+  // file:// URL; the query busts the module cache so reloads see fixture edits.
+  const url = new URL(`file://${path}?t=${Date.now()}`);
+  const mod = await import(url.href);
+  const fixture = (mod.default ?? mod) as CompileFixture<unknown>;
+  return { fixture, source: path };
+}
+
+/**
+ * Stable HMAC seed string for the dev process. `compile()` runs HMAC
+ * against this; using `realm-dev:<cwd>` keeps two restarts in the same
+ * directory deterministic so passwords + `r.stableSecret(...)` values
+ * don't reshuffle on every reload.
+ */
+export function stableDevSeed(cwd: string): string {
+  return `realm-dev:${cwd}`;
+}

package/src/dev/install-handler.ts

@@ -0,0 +1,383 @@
+// Server-side handlers for the `/install` route in `realm-sdk dev`. The
+// install panel (shared with Home) reaches them through the InstallAdapter in
+// install-entry.tsx, which POSTs to `/install/api/preview` and
+// `/install/api/install`. Install returns the new DevState and stack handle for
+// server.ts to swap in; the `realm-sdk.dev.ts` write here is only persistence,
+// which the file watcher ignores. Failures throw `InstallHandlerError` carrying
+// a shape the browser adapter rehydrates as an `InstallErrorShape`.
+
+import { basename, join } from "@std/path";
+import type { Grants } from "../home.ts";
+import type { InstallErrorShape, PreviewImage, PreviewResult } from "../ui/install/adapter.ts";
+import { bundle } from "../bundle.ts";
+import {
+  extractSchema,
+  extractAppKind,
+  type ConfigField,
+  type ConfigFieldTree,
+  type SerializablePermission,
+} from "../sandbox.ts";
+import { compile } from "../test/compile.ts";
+import type { SiloFixture } from "../test/types.ts";
+import type { SiloGrants } from "../schema/host.ts";
+import { SPECULATIVE_SILO } from "../speculative-silo.ts";
+import { descriptorsToGrants } from "../grants-builder.ts";
+import { formatIssue, RealmCompileError } from "../errors.ts";
+import { loadDevFixture, stableDevSeed } from "./fixture.ts";
+import { bringUp, compileAndBundle, DevCompileError, type DevState } from "./state.ts";
+
+/**
+ * Server-side counterpart to InstallAdapterError. Thrown by handlers;
+ * `installErrorToResponse` turns it into the wire JSON shape the
+ * browser install adapter parses back via `parseInstallError`.
+ */
+export class InstallHandlerError extends Error {
+  constructor(public readonly shape: InstallErrorShape) {
+    super(shape.kind === "violations" ? "grant violations" : shape.message);
+    this.name = "InstallHandlerError";
+  }
+}
+
+export function installErrorToResponse(err: InstallHandlerError): Response {
+  if (err.shape.kind === "violations") {
+    return Response.json(
+      { error: "grant violations", violations: err.shape.violations },
+      { status: 400 },
+    );
+  }
+  return Response.json({ error: err.shape.message }, { status: 400 });
+}
+
+function toErrorShape(err: unknown): InstallErrorShape {
+  // DevCompileError carries both the flat issue list (for non-grant
+  // failures) and the raw violations (for grant failures). Prefer the
+  // structured violations shape when present so the panel renders the
+  // per-permission list — same UX as Home's POST /api/apps.
+  if (err instanceof DevCompileError) {
+    if (err.violations.length > 0) {
+      return { kind: "violations", violations: [...err.violations] };
+    }
+    const message =
+      err.issues.length === 1
+        ? formatIssue(err.issues[0]!)
+        : err.issues.map((i) => `- ${formatIssue(i)}`).join("\n");
+    return { kind: "message", message };
+  }
+  if (err instanceof RealmCompileError) {
+    const message =
+      err.issues.length === 1
+        ? formatIssue(err.issues[0]!)
+        : err.issues.map((i) => `- ${formatIssue(i)}`).join("\n");
+    return { kind: "message", message };
+  }
+  return { kind: "message", message: (err as Error).message };
+}
+
+/**
+ * Walk a config tree and synthesize defaults the same way Home's preview
+ * does: every leaf with a `default` lands in the object, optional
+ * tabs/sections stay undefined, required ones recurse in.
+ */
+function defaultConfigValues(schema: ConfigFieldTree): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, field] of Object.entries(schema) as [string, ConfigField][]) {
+    if (field.type === "permission") continue;
+    if (field.type === "tab" || field.type === "section") {
+      if (field.optional) continue;
+      out[name] = defaultConfigValues(field.fields);
+    } else if ("default" in field && field.default !== undefined) {
+      out[name] = field.default;
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether an on-disk Silo record can answer what this declaration asks for.
+ *
+ * Presence alone is not enough. `compile()` checks the same fields and throws
+ * a message about adding `hostPath` / `gid` to a `silo:` fixture, which is
+ * good advice for someone writing `realm.test.ts` and useless to an operator
+ * clicking through the install panel - they would see it as "preview images
+ * skipped", pointing at a file the panel says it owns. A half-written record
+ * falls back to the placeholder instead, which is what a missing one does.
+ */
+function satisfiesAsk(record: SiloFixture | undefined, ask: SiloGrants): boolean {
+  if (record === undefined) return false;
+  if (ask.volume !== undefined && (record.hostPath === undefined || record.gid === undefined)) {
+    return false;
+  }
+  // A require-map the record doesn't publish would fail resolution outright,
+  // and an unmet require is never the right answer at preview time - see
+  // `speculative-silo.ts`.
+  if (typeof ask.network === "object") {
+    for (const [name, port] of Object.entries(ask.network)) {
+      if (record.services?.[name] !== port) return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Point every `host.silo` declaration at a Silo the speculative compile can
+ * resolve, and return the grants and Silo records to compile against.
+ *
+ * The preview grants every permission straight off the descriptors, and a Silo
+ * is the one grant a descriptor cannot supply: the operator picks it. So the
+ * map comes back empty at that path and `sanitizeGrants` drops the grant for
+ * carrying no id, leaving the app to crash on `config.silo.volume`. Two ways
+ * out, in order of fidelity:
+ *
+ *   1. `realm-sdk.dev.ts` already describes a Silo that can satisfy the ask.
+ *      Use it - previewing against a real directory beats any placeholder.
+ *      Note the panel cannot produce this state on its own: an install writes
+ *      back only `{config, grants}` (`renderDevFixture`), never `silo:`
+ *      records, so this branch belongs to an author who hand-wrote the fixture
+ *      the way they would for `realm.test.ts`.
+ *   2. Anything else - nothing on disk, or a record that cannot answer what
+ *      this declaration asks for. Stand in a synthetic Silo built from the
+ *      same constants Home's speculative resolver uses, so both surfaces show
+ *      the operator the same placeholder.
+ *
+ * Done here rather than by teaching `compile()` a speculative mode, which
+ * would be a second place that fabricates a Silo. This way the resolver runs
+ * unmodified against a Silo record, exactly as it does for an app's own test.
+ */
+export function speculativeSiloFixture(
+  permsFlat: Record<string, SerializablePermission>,
+  grants: Grants,
+  disk: { grants?: Grants; silo?: Record<string, SiloFixture> },
+): { grants: Grants; silo: Record<string, SiloFixture> } {
+  const silo: Record<string, SiloFixture> = { ...disk.silo };
+  const out: Grants = { ...grants };
+  // Publications the stand-in must offer for a require-map to resolve. See
+  // `speculative-silo.ts` for why an unmet require is never the right answer
+  // at preview time.
+  const services: Record<string, number> = {};
+  let synthetic = false;
+
+  for (const [path, perm] of Object.entries(permsFlat)) {
+    if (perm.kind !== "host.silo") continue;
+    const bound = disk.grants?.[path];
+    const boundId =
+      bound?.kind === "host.silo" && typeof bound.data === "string" ? bound.data : undefined;
+    const ask = perm.data as SiloGrants;
+    if (boundId !== undefined && satisfiesAsk(silo[boundId], ask)) {
+      out[path] = { kind: "host.silo", data: boundId };
+      continue;
+    }
+    out[path] = { kind: "host.silo", data: SPECULATIVE_SILO.id };
+    synthetic = true;
+    if (typeof ask.network === "object") Object.assign(services, ask.network);
+  }
+
+  if (synthetic) {
+    silo[SPECULATIVE_SILO.id] = {
+      hostPath: SPECULATIVE_SILO.hostPath,
+      containerPath: SPECULATIVE_SILO.containerPath,
+      gid: SPECULATIVE_SILO.gid,
+      apiKey: SPECULATIVE_SILO.apiKey,
+      services,
+    };
+  }
+  return { grants: out, silo };
+}
+
+export async function handlePreview(
+  source: string,
+  ctx: { cwd: string; appName: string },
+): Promise<PreviewResult> {
+  let bundledCode: string;
+  try {
+    bundledCode = await bundle(source);
+  } catch (err) {
+    throw new InstallHandlerError(toErrorShape(err));
+  }
+  let extracted;
+  let kind: "single" | "system";
+  try {
+    extracted = await extractSchema(bundledCode);
+    kind = await extractAppKind(bundledCode);
+  } catch (err) {
+    throw new InstallHandlerError(toErrorShape(err));
+  }
+
+  // Read the existing fixture once. Used to pre-fill the panel (so
+  // /install on a previously-installed app turns into an edit flow)
+  // and to seed the speculative compile with realistic values.
+  const { fixture: rawFixture } = await loadDevFixture(ctx.cwd);
+  const currentConfig = rawFixture.config as Record<string, unknown> | undefined;
+  const currentGrants = rawFixture.grants as Grants | undefined;
+
+  // Speculative compile so the summary can show image cards. We grant
+  // every declared permission (mirrors Home's preview) and fill config
+  // with declared defaults. Failures are silent: the panel still shows
+  // permission + config rows; image cards just won't appear.
+  let images: PreviewImage[] | null = null;
+  let hasPersistentVolumes = false;
+  try {
+    const granted = descriptorsToGrants(extracted.permissionsFlat, {
+      enabled: new Set(Object.keys(extracted.permissionsFlat)),
+      grantValues: {},
+    });
+    const silos = speculativeSiloFixture(extracted.permissionsFlat, granted, {
+      grants: currentGrants,
+      silo: rawFixture.silo,
+    });
+    const fixture = {
+      ...rawFixture,
+      seed: rawFixture.seed ?? stableDevSeed(ctx.cwd),
+      config: defaultConfigValues(extracted.configFields) as never,
+      grants: silos.grants as never,
+      silo: silos.silo,
+    };
+    const result = await compile({ bundledCode, appName: ctx.appName, fixture });
+    if (!result.error) {
+      const refs = new Set<string>();
+      for (const svc of Object.values(result.app.services)) {
+        // `build:` services have no image ref yet — skip them.
+        if (svc.image) refs.add(svc.image);
+      }
+      hasPersistentVolumes = Object.values(result.app.services).some(
+        (s) => (s.volumes?.length ?? 0) > 0,
+      );
+      // Dev has no Home image-pin cache, so every field is null/unknown.
+      // The panel already renders that as "not yet pinned" cards.
+      images = [...refs].map(
+        (ref) =>
+          ({
+            ref,
+            digest: null,
+            runsAs: null,
+            runsAsRoot: false,
+            exposes: [],
+            volumes: [],
+            imageCreatedAt: null,
+          }) satisfies PreviewImage,
+      );
+    }
+  } catch (err) {
+    // Speculative compile failures are expected — required config blank,
+    // sandbox eval throws, etc. Leave images null and let the rest of the
+    // preview render, logging why the image cards aren't appearing.
+    console.warn(`[realm-dev] preview images skipped: ${(err as Error).message}`);
+  }
+
+  return {
+    permissionsFlat: extracted.permissionsFlat,
+    configFields: extracted.configFields,
+    images,
+    kind,
+    hasPersistentVolumes,
+    ...(currentConfig !== undefined && Object.keys(currentConfig).length > 0
+      ? { currentConfig }
+      : {}),
+    ...(currentGrants !== undefined && Object.keys(currentGrants).length > 0
+      ? { currentGrants }
+      : {}),
+  };
+}
+
+interface InstallHandlerCtx {
+  cwd: string;
+  realmFile: string;
+  tmpDir: string;
+}
+
+interface InstallPayloadRequest {
+  source: string;
+  config: Record<string, unknown>;
+  grants: Grants;
+  /** Mirror of the panel's DeployTargets. Ignored in dev (single local target). */
+  deployed?: unknown;
+}
+
+/**
+ * Render a `realm-sdk.dev.ts` source string from the install panel's
+ * `{config, grants}`. The output is the panel-managed counterpart to a
+ * hand-written dev fixture — same shape (`CompileFixture<typeof app>`),
+ * importing the local `realm.ts(x)` for type inference.
+ *
+ * `JSON.stringify(..., 2)` is sufficient as TS source: every value the
+ * panel collects (config inputs, grant data) is JSON-safe by
+ * construction (the wire shape between panel and server is JSON), and
+ * JSON object/array literals are valid TS expressions.
+ *
+ * Secrets land in plaintext here. Authors should gitignore this file
+ * if their realm.ts declares `r.input.secret(...)` fields.
+ */
+function renderDevFixture(opts: {
+  realmFileBasename: string;
+  config: Record<string, unknown>;
+  grants: Grants;
+}): string {
+  const header = [
+    "// Auto-generated by `realm-sdk dev`'s install panel. Overwritten on",
+    "// every install — if you hand-edit, run /install again with the new",
+    "// values or your edits will be clobbered. Plaintext secrets land",
+    "// here; gitignore as needed.",
+  ].join("\n");
+  return `${header}
+
+import type { CompileFixture } from "@yourrealm/sdk/test";
+import type app from "./${opts.realmFileBasename}";
+
+export default {
+  config: ${JSON.stringify(opts.config, null, 2)},
+  grants: ${JSON.stringify(opts.grants, null, 2)},
+} satisfies CompileFixture<typeof app>;
+`;
+}
+
+export async function handleInstall(
+  payload: InstallPayloadRequest,
+  ctx: InstallHandlerCtx,
+): Promise<{ state: DevState; stack: Awaited<ReturnType<typeof bringUp>> }> {
+  let next: DevState;
+  try {
+    next = await compileAndBundle({
+      cwd: ctx.cwd,
+      realmFile: ctx.realmFile,
+      override: {
+        source: payload.source,
+        config: payload.config,
+        grants: payload.grants,
+      },
+    });
+  } catch (err) {
+    throw new InstallHandlerError(toErrorShape(err));
+  }
+
+  // Order: bringUp first, then persist. If `bringUp` fails (image pull
+  // problem, compose conflict, port collision), `realm-sdk.dev.ts`
+  // stays in its pre-install state — the file watcher won't loop on a
+  // bad fixture and the operator can retry without manual rollback.
+  let stack: Awaited<ReturnType<typeof bringUp>>;
+  try {
+    stack = await bringUp(next, ctx.tmpDir);
+  } catch (err) {
+    throw new InstallHandlerError(toErrorShape(err));
+  }
+
+  // Containers are running on the new config + grants, so persist the panel's
+  // choices to realm-sdk.dev.ts for the next dev server start. Identical bytes
+  // skip the write, keeping the file watcher quiet on a no-op install.
+  const fixtureSource = renderDevFixture({
+    realmFileBasename: basename(ctx.realmFile),
+    config: payload.config,
+    grants: payload.grants,
+  });
+  const fixturePath = join(ctx.cwd, "realm-sdk.dev.ts");
+  try {
+    const existing = await Deno.readTextFile(fixturePath).catch(() => null);
+    if (existing !== fixtureSource) {
+      await Deno.writeTextFile(fixturePath, fixtureSource);
+    }
+  } catch (err) {
+    throw new InstallHandlerError({
+      kind: "message",
+      message: `failed to write realm-sdk.dev.ts: ${(err as Error).message}`,
+    });
+  }
+  return { state: next, stack };
+}