@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/cli/build-install-panel.ts

@@ -0,0 +1,90 @@
+// `realm-sdk build-install-panel --out <dir>` — esbuild the install panel entry
+// into `install-panel.js`, alongside `runtime.js` from `build-runtime`. CSS is
+// shared: runtime.css's Tailwind scan already covers `packages/sdk/src/ui/install/*`.
+//
+// `realm-sdk dev` builds both bundles into one temp dir on first boot and serves
+// them at `/runtime.js` + `/install-panel.js`; the `/install` HTML shell loads
+// runtime.css (no per-surface CSS) and mounts the panel.
+
+import { resolve } from "@std/path";
+import { sdkDir } from "../pkg-root.ts";
+
+const ENTRY = resolve(sdkDir(import.meta.url), "src/ui-runtime/install-entry.tsx");
+
+interface BuildOpts {
+  outDir: string;
+}
+
+async function buildJs(outDir: string): Promise<void> {
+  const cmd = new Deno.Command("esbuild", {
+    args: [
+      ENTRY,
+      "--bundle",
+      `--outfile=${outDir}/install-panel.js`,
+      "--format=esm",
+      "--platform=browser",
+      "--target=es2020",
+      "--main-fields=module,main",
+      "--jsx=automatic",
+      "--jsx-import-source=preact",
+      // preact/compat keeps Ark UI's react adapter pointing at preact —
+      // same set of aliases the runtime build uses.
+      "--alias:react=preact/compat",
+      "--alias:react-dom=preact/compat",
+      "--alias:react/jsx-runtime=preact/jsx-runtime",
+      '--define:process.env.NODE_ENV="production"',
+      "--minify",
+    ],
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const { code, stderr } = await cmd.output();
+  if (code !== 0) {
+    const err = new TextDecoder().decode(stderr);
+    throw new Error(`esbuild install-panel failed:\n${err}`);
+  }
+}
+
+async function buildInstallPanel(opts: BuildOpts): Promise<void> {
+  const outDir = resolve(Deno.cwd(), opts.outDir);
+  await Deno.mkdir(outDir, { recursive: true });
+  await buildJs(outDir);
+  const jsStat = await Deno.stat(`${outDir}/install-panel.js`);
+  console.log(
+    `install-panel → ${outDir}: install-panel.js (${(jsStat.size / 1024).toFixed(1)} KB)`,
+  );
+}
+
+export async function runBuildInstallPanel(args: string[]): Promise<number> {
+  let outDir = "./ui-runtime";
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--out" || a === "-o") {
+      const next = args[i + 1];
+      if (!next) {
+        console.error("--out requires a directory argument");
+        return 2;
+      }
+      outDir = next;
+      i++;
+      continue;
+    }
+    if (a === "--help" || a === "-h") {
+      console.log(`Usage: realm-sdk build-install-panel [--out DIR]
+
+Builds the install panel entry (install-panel.js) into DIR.
+DIR defaults to ./ui-runtime (relative to the current directory).
+`);
+      return 0;
+    }
+    console.error(`Unknown flag: ${a}`);
+    return 2;
+  }
+  try {
+    await buildInstallPanel({ outDir });
+    return 0;
+  } catch (err) {
+    console.error((err as Error).message);
+    return 1;
+  }
+}

package/src/cli/build-runtime.ts

@@ -0,0 +1,133 @@
+// `realm-sdk build-runtime --out <dir>` — build the iframe runtime (preact +
+// hooks + @yourrealm/sdk/ui components + zod + the SDK's authoring surface)
+// into a single ESM bundle plus the matching tailwind CSS.
+//
+// The shell HTML's importmap maps every external a surface bundle declares —
+// `@yourrealm/sdk`, `@yourrealm/sdk/ui`, `@yourrealm/sdk/preact`,
+// `@yourrealm/sdk/jsx-runtime`, `@yourrealm/sdk/services`, `zod` — to this one
+// URL, and the browser dedupes by URL so every surface shares one instance.
+//
+// Home calls this at build time to populate `static/ui-runtime/`; `realm-sdk
+// dev` calls it once into a temp dir on first boot. Both outputs are
+// byte-identical for a given source tree.
+
+import { resolve } from "@std/path";
+import { sdkDir } from "../pkg-root.ts";
+import { findTailwindBin } from "../tailwind-bin.ts";
+
+const SDK_DIR = sdkDir(import.meta.url);
+const ENTRY = resolve(SDK_DIR, "src/ui-runtime/index.ts");
+const CSS_ENTRY = resolve(SDK_DIR, "src/ui-runtime/runtime.css");
+
+interface BuildOpts {
+  outDir: string;
+  /**
+   * Where to resolve `node_modules/.bin/tailwindcss` from. The SDK
+   * package has `tailwindcss` as a devDependency so the binary lives at
+   * `packages/sdk/node_modules/.bin/tailwindcss` after `pnpm install`.
+   * Walking up from the script handles both monorepo dev and any future
+   * "ship the runtime as a JSR artifact" setup.
+   */
+  workspaceRoot?: string;
+}
+
+async function buildJs(outDir: string): Promise<void> {
+  const cmd = new Deno.Command("esbuild", {
+    args: [
+      ENTRY,
+      "--bundle",
+      `--outfile=${outDir}/runtime.js`,
+      "--format=esm",
+      "--platform=browser",
+      "--target=es2020",
+      "--main-fields=module,main",
+      "--jsx=automatic",
+      "--jsx-import-source=@yourrealm/sdk",
+      // preact/compat keeps Ark UI's react adapter pointing at preact;
+      // bundle it so component imports of "react" resolve to compat.
+      "--alias:react=preact/compat",
+      "--alias:react-dom=preact/compat",
+      "--alias:react/jsx-runtime=preact/jsx-runtime",
+      // Preact has process.env.NODE_ENV branches; pick prod once for the
+      // runtime so dev-only warnings don't ship.
+      '--define:process.env.NODE_ENV="production"',
+      "--minify",
+    ],
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const { code, stderr } = await cmd.output();
+  if (code !== 0) {
+    const err = new TextDecoder().decode(stderr);
+    throw new Error(`esbuild ui-runtime failed:\n${err}`);
+  }
+}
+
+async function buildCss(outDir: string, tailwindBin: string, cwd: string): Promise<void> {
+  const cmd = new Deno.Command(tailwindBin, {
+    args: ["--input", CSS_ENTRY, "--output", `${outDir}/runtime.css`, "--minify"],
+    cwd,
+    stdout: "piped",
+    stderr: "piped",
+  });
+  const { code, stderr } = await cmd.output();
+  if (code !== 0) {
+    const err = new TextDecoder().decode(stderr);
+    throw new Error(`tailwindcss ui-runtime failed:\n${err}`);
+  }
+}
+
+async function buildRuntime(opts: BuildOpts): Promise<void> {
+  const outDir = resolve(Deno.cwd(), opts.outDir);
+  await Deno.mkdir(outDir, { recursive: true });
+  // Resolve tailwind's bin from the SDK package dir, so the search starts next
+  // to the runtime sources rather than at the caller's cwd.
+  const searchStart = opts.workspaceRoot ?? SDK_DIR;
+  const tailwindBin = findTailwindBin(searchStart);
+  // Tailwind resolves `@import "@yourrealm/sdk/ui/tokens.css"` via node_modules
+  // from cwd, so the cwd is the SDK package dir where `@yourrealm/sdk` (self)
+  // is in scope.
+  const tailwindCwd = SDK_DIR;
+  await Promise.all([buildJs(outDir), buildCss(outDir, tailwindBin, tailwindCwd)]);
+  const [jsStat, cssStat] = await Promise.all([
+    Deno.stat(`${outDir}/runtime.js`),
+    Deno.stat(`${outDir}/runtime.css`),
+  ]);
+  console.log(
+    `ui-runtime → ${outDir}: runtime.js (${(jsStat.size / 1024).toFixed(1)} KB) + runtime.css (${(cssStat.size / 1024).toFixed(1)} KB)`,
+  );
+}
+
+export async function runBuildRuntime(args: string[]): Promise<number> {
+  let outDir = "./ui-runtime";
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--out" || a === "-o") {
+      const next = args[i + 1];
+      if (!next) {
+        console.error("--out requires a directory argument");
+        return 2;
+      }
+      outDir = next;
+      i++;
+      continue;
+    }
+    if (a === "--help" || a === "-h") {
+      console.log(`Usage: realm-sdk build-runtime [--out DIR]
+
+Builds the iframe runtime (runtime.js + runtime.css) into DIR.
+DIR defaults to ./ui-runtime (relative to the current directory).
+`);
+      return 0;
+    }
+    console.error(`Unknown flag: ${a}`);
+    return 2;
+  }
+  try {
+    await buildRuntime({ outDir });
+    return 0;
+  } catch (err) {
+    console.error((err as Error).message);
+    return 1;
+  }
+}

package/src/cli/build.ts

@@ -0,0 +1,63 @@
+// `realm-sdk build [--app DIR] [--out FILE]` — pack a multi-file app
+// (realm.tsx + pages/*.tsx + widgets/*.tsx + relative helpers) into the single
+// marker-delimited artifact Home ingests. Each file is preserved verbatim under
+// a `// realm-file: <path>` marker, so the store can preview it file by file and
+// any integrity digest is over readable source. Home unpacks + merges + bundles
+// at install. Writes to FILE, or stdout when --out is omitted.
+//
+// Collecting the file set lives in ../pack-build.ts (shared with `realm-sdk
+// dev`'s install panel); this file is the CLI shell plus a fail-fast merge +
+// bundle + eval.
+
+import { dirname, resolve } from "@std/path";
+import { bundle } from "../bundle.ts";
+import { buildPackedApp } from "../pack-build.ts";
+import { extractSchema } from "../sandbox.ts";
+
+export async function runBuild(args: string[]): Promise<number> {
+  let appDir = Deno.cwd();
+  let out: string | null = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") {
+      console.log(
+        "Usage: realm-sdk build [--app DIR] [--out FILE]\n\n" +
+          "Pack realm.tsx + pages/*.tsx + widgets/*.tsx into one marker-\n" +
+          "delimited artifact. Writes to FILE, or stdout when --out is omitted.",
+      );
+      return 0;
+    } else if (args[i] === "--app" || args[i] === "--out") {
+      const flag = args[i];
+      const value = args[++i];
+      if (value === undefined) {
+        console.error(`${flag} requires a value`);
+        return 1;
+      }
+      if (flag === "--app") appDir = resolve(value);
+      else out = resolve(value);
+    }
+  }
+
+  try {
+    const packed = await buildPackedApp(appDir);
+
+    // Fail fast: prove the packed artifact bundles AND evaluates before handing
+    // it over. bundle() runs the exact merge + bundle Home does at install, and
+    // extractSchema evaluates the module top-level, so an inline `ui:` block
+    // colliding with file-based surfaces (attachSurfaces throws) is caught here,
+    // near the author, not at install on the operator.
+    const bundledCode = await bundle(packed);
+    await extractSchema(bundledCode);
+
+    if (out) {
+      await Deno.mkdir(dirname(out), { recursive: true });
+      await Deno.writeTextFile(out, packed);
+      console.error(`Built ${out}.`);
+    } else {
+      console.log(packed);
+    }
+    return 0;
+  } catch (err) {
+    console.error(`build failed: ${(err as Error).message}`);
+    return 1;
+  }
+}

package/src/cli/dev.ts

@@ -0,0 +1,107 @@
+// `realm-sdk dev [path]` — boot the realm.ts(x) at `path` locally and serve
+// every `ui:` surface on a hot-reloading HTTP server: the local mirror of what
+// Home does in production, docker compose up + iframe shell + loader proxy, all
+// driven by one realm.ts on disk.
+//
+// With no positional arg it looks for `realm.tsx` then `realm.ts` in the current
+// directory; default port is 7100. All the lifting happens in `dev/server.ts`.
+
+import { resolve } from "@std/path";
+import { startDevServer } from "../dev/server.ts";
+
+const HELP = `Usage: realm-sdk dev [path] [--port N]
+
+Boots the realm.ts(x) at \`path\` (defaults to \`./realm.tsx\` then
+\`./realm.ts\`) and serves its ui surfaces on http://localhost:7100.
+File changes trigger a recompile and an iframe reload.
+
+Options:
+  --port N       Listen on port N (default: 7100).
+`;
+
+interface ParsedArgs {
+  /** Explicit positional path, or null when defaulting to cwd discovery. */
+  realmFile: string | null;
+  port: number;
+}
+
+function parseArgs(args: string[]): ParsedArgs | null {
+  let port = 7100;
+  let positional: string | null = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--help" || a === "-h") return null;
+    if (a === "--port" || a === "-p") {
+      const next = args[i + 1];
+      if (!next) {
+        console.error("--port requires a number");
+        Deno.exit(2);
+      }
+      const n = Number(next);
+      if (!Number.isFinite(n) || n <= 0 || n > 65535) {
+        console.error(`invalid port: ${next}`);
+        Deno.exit(2);
+      }
+      port = n;
+      i++;
+      continue;
+    }
+    if (a.startsWith("-")) {
+      console.error(`Unknown flag: ${a}`);
+      Deno.exit(2);
+    }
+    if (positional !== null) {
+      console.error("expected at most one positional argument (the realm.ts path)");
+      Deno.exit(2);
+    }
+    positional = a;
+  }
+  return { realmFile: positional !== null ? resolve(positional) : null, port };
+}
+
+function existsSync(path: string): boolean {
+  try {
+    Deno.statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveRealmFile(parsed: ParsedArgs): string | null {
+  if (parsed.realmFile !== null) {
+    return existsSync(parsed.realmFile) ? parsed.realmFile : null;
+  }
+  // No positional arg — look for realm.tsx then realm.ts in cwd. tsx
+  // first because the rebrand examples + counter-fresh use it.
+  for (const candidate of ["realm.tsx", "realm.ts"]) {
+    const path = resolve(candidate);
+    if (existsSync(path)) return path;
+  }
+  return null;
+}
+
+export async function runDev(args: string[]): Promise<number> {
+  const parsed = parseArgs(args);
+  if (parsed === null) {
+    console.log(HELP);
+    return 0;
+  }
+  const realmFile = resolveRealmFile(parsed);
+  if (realmFile === null) {
+    if (parsed.realmFile !== null) {
+      console.error(`Cannot read ${parsed.realmFile}`);
+    } else {
+      console.error(
+        `No realm.tsx or realm.ts in ${Deno.cwd()} — pass an explicit path or cd into an app directory.`,
+      );
+    }
+    return 1;
+  }
+  // The cwd anchors the file watcher and the dev fixture lookup. The realm.ts
+  // can live anywhere; the watcher just needs a parent directory.
+  const cwd = resolve(realmFile, "..");
+
+  await startDevServer({ cwd, port: parsed.port, realmFile });
+  return 0;
+}

package/src/cli/down.ts

@@ -0,0 +1,60 @@
+// `realm-sdk down` — tears down any compose stacks the harness left
+// running. Stacks are tagged with `com.realm.test=true`; we look up
+// every container with that label, group by compose project name, and
+// run `docker compose -p <project> down -v` per project.
+
+import { z } from "zod";
+
+async function listTestProjects(): Promise<string[]> {
+  const cmd = new Deno.Command("docker", {
+    args: ["ps", "-a", "--filter", "label=com.realm.test=true", "--format", "{{json .}}"],
+    stdout: "piped",
+    stderr: "inherit",
+  });
+  const { code, stdout } = await cmd.output();
+  if (code !== 0) throw new Error(`docker ps failed (exit ${code})`);
+
+  const projects = new Set<string>();
+  const text = new TextDecoder().decode(stdout);
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    const row = z.object({ Labels: z.string().optional() }).parse(JSON.parse(line));
+    const labels = row.Labels ?? "";
+    const match = labels.match(/com\.docker\.compose\.project=([^,]+)/);
+    if (match) projects.add(match[1]!);
+  }
+  return [...projects];
+}
+
+async function tearDown(project: string): Promise<number> {
+  console.log(`Tearing down ${project}...`);
+  const cmd = new Deno.Command("docker", {
+    args: ["compose", "-p", project, "down", "-v"],
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  const { code } = await cmd.output();
+  return code;
+}
+
+export async function runDown(_args: string[]): Promise<number> {
+  let projects: string[];
+  try {
+    projects = await listTestProjects();
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  if (projects.length === 0) {
+    console.log("No realm-sdk test stacks running.");
+    return 0;
+  }
+
+  let exitCode = 0;
+  for (const project of projects) {
+    const code = await tearDown(project);
+    if (code !== 0) exitCode = code;
+  }
+  return exitCode;
+}

package/src/cli/main.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env -S deno run --allow-all
+// `realm-sdk` CLI dispatcher. Subcommands are named modules in this directory,
+// each exporting a `run(args)` that returns the process exit code; subcommand
+// selection, error formatting and the exit code stay here.
+
+import { runTest } from "./test.ts";
+import { runDown } from "./down.ts";
+import { runValidate } from "./validate.ts";
+import { runBuild } from "./build.ts";
+import { runBuildRuntime } from "./build-runtime.ts";
+import { runDev } from "./dev.ts";
+
+const HELP = `Usage: realm-sdk <command> [args]
+
+Commands:
+  test           Run realm.ts tests (compile tier; pass --e2e for boot tests).
+  down           Tear down any test stacks left running (com.realm.test=true).
+  validate       Parse a realm.ts and report compile errors without a fixture.
+  build          Collapse realm.tsx + pages/*.tsx + widgets/*.tsx into one source.
+  build-runtime  Build the iframe runtime (runtime.js + runtime.css) into a directory.
+  dev            Boot the app locally and serve its ui surfaces with hot reload.
+
+Run \`realm-sdk <command> --help\` for command-specific options.
+`;
+
+async function main(): Promise<number> {
+  const [cmd, ...rest] = Deno.args;
+  switch (cmd) {
+    case undefined:
+    case "--help":
+    case "-h":
+    case "help":
+      console.log(HELP);
+      return 0;
+    case "test":
+      return await runTest(rest);
+    case "down":
+      return await runDown(rest);
+    case "validate":
+      return await runValidate(rest);
+    case "build":
+      return await runBuild(rest);
+    case "build-runtime":
+      return await runBuildRuntime(rest);
+    case "dev":
+      return await runDev(rest);
+    default:
+      console.error(`Unknown command: ${cmd}\n`);
+      console.error(HELP);
+      return 2;
+  }
+}
+
+if (import.meta.main) {
+  Deno.exit(await main());
+}

package/src/cli/test.ts

@@ -0,0 +1,61 @@
+// `realm-sdk test` — discovers `*.test.ts` from the working directory and runs
+// them under `deno test`. The harness inside each test file drives compile/boot
+// via `Realm.describe`; the CLI only invokes deno test with the right flags.
+//
+// Flag handling is deliberately thin:
+//   --e2e               Intercepted. Sets REALM_TEST_E2E=1 so `t.boot` runs
+//                       (default skipped) and strips the flag.
+//   everything else     Forwarded to `deno test` as-is.
+//   args after `--`     Forwarded to the test script. Snapshot regen lives
+//                       here: `realm-sdk test -- --update`.
+
+interface TestArgs {
+  e2e: boolean;
+  denoArgs: string[];
+  scriptArgs: string[];
+}
+
+function parseArgs(args: string[]): TestArgs {
+  const denoArgs: string[] = [];
+  const scriptArgs: string[] = [];
+  let e2e = false;
+  let sawSeparator = false;
+
+  for (const arg of args) {
+    if (sawSeparator) {
+      scriptArgs.push(arg);
+      continue;
+    }
+    if (arg === "--") {
+      sawSeparator = true;
+      continue;
+    }
+    if (arg === "--e2e") {
+      e2e = true;
+      continue;
+    }
+    denoArgs.push(arg);
+  }
+  return { e2e, denoArgs, scriptArgs };
+}
+
+export async function runTest(args: string[]): Promise<number> {
+  const { e2e, denoArgs, scriptArgs } = parseArgs(args);
+
+  const env: Record<string, string> = {};
+  if (e2e) env["REALM_TEST_E2E"] = "1";
+
+  const cliArgs = ["test", "--allow-all", ...denoArgs];
+  if (scriptArgs.length > 0) cliArgs.push("--", ...scriptArgs);
+
+  const cmd = new Deno.Command("deno", {
+    args: cliArgs,
+    env,
+    stdout: "inherit",
+    stderr: "inherit",
+    stdin: "inherit",
+  });
+
+  const { code } = await cmd.output();
+  return code;
+}

package/src/cli/validate.ts

@@ -0,0 +1,37 @@
+// `realm-sdk validate [path]` — bundles the realm.ts at `path` (default
+// `./realm.ts`) and runs `extractSchema` to surface eval/syntax/blocked
+// import errors. No fixture is required; this is the "is the source
+// well-formed" check intended for CI gates and editor watchers.
+
+import { resolve } from "@std/path";
+import { bundle } from "../bundle.ts";
+import { extractSchema } from "../sandbox.ts";
+import { RealmCompileError, formatIssue } from "../errors.ts";
+
+export async function runValidate(args: string[]): Promise<number> {
+  const target = resolve(args[0] ?? "realm.ts");
+
+  let source: string;
+  try {
+    source = await Deno.readTextFile(target);
+  } catch (err) {
+    console.error(`Cannot read ${target}: ${err instanceof Error ? err.message : err}`);
+    return 1;
+  }
+
+  try {
+    const bundled = await bundle(source);
+    await extractSchema(bundled);
+  } catch (err) {
+    if (err instanceof RealmCompileError) {
+      console.error(`${target}:`);
+      for (const issue of err.issues) console.error(`  - ${formatIssue(issue)}`);
+      return 1;
+    }
+    console.error(`${target}: ${err instanceof Error ? err.message : err}`);
+    return 1;
+  }
+
+  console.log(`${target}: ok`);
+  return 0;
+}