@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/identifiers.ts

@@ -0,0 +1,49 @@
+// Identifier validation schemas + the Network brand.
+//
+// nameSchema / domainSchema gate strings that land in container names, network
+// names, file paths, and host-match rules in the proxy config — places where a
+// hostile string could close a quote/backtick or escape into a sibling path.
+// The brand on Network keeps Docker-network handles from being confused with
+// arbitrary strings as they flow between the SDK and Home.
+
+import { z } from "zod";
+
+/**
+ * Valid service name, app ID, and realm.ts-authored identifier: lowercase
+ * alphanumeric + hyphens, must start with a letter. Stays tight because
+ * realm.ts authors choose these — we don't want a service named `123`
+ * or a realm.ts whose name is purely numeric, both of which read as
+ * suspicious / confusing in container names and config. App IDs follow
+ * the same shape: system apps use bare slugs (`logger`, `stats`, …) and
+ * user-installed apps get `${slug}-${nanoid}` minted from
+ * `createApp({ name })`.
+ */
+export const nameSchema = z
+  .string()
+  .regex(
+    /^[a-z][a-z0-9-]*$/,
+    "Must be lowercase alphanumeric with hyphens, starting with a letter",
+  );
+
+/**
+ * Valid domain name for routing rules. DNS charset only; rejects anything
+ * that could close a backtick-delimited host matcher and append a second
+ * rule.
+ */
+export const domainSchema = z.string().regex(/^[a-zA-Z0-9.*-]+$/, "Invalid domain name");
+
+/**
+ * Registry host key for the wire `registryAuth` map: hostname + optional
+ * port (`ghcr.io`, `registry-1.docker.io`, `registry.local:5000`). Mirrors
+ * the registry client's host pattern so a credential key can't smuggle a
+ * path, userinfo, scheme, or query into the place a host is expected.
+ */
+export const hostKey = z.string().regex(/^[a-zA-Z0-9.-]+(:[0-9]+)?$/, "Invalid registry host");
+
+/**
+ * Branded Docker network handle. Distinct from arbitrary strings so a
+ * raw network name can't be passed where a `joinNetworks` entry is
+ * expected (and vice versa).
+ */
+export const networkSchema = z.string().brand<"Network">();
+export type Network = z.infer<typeof networkSchema>;

package/src/index.ts

@@ -0,0 +1,66 @@
+// Author-facing SDK barrel. Realm.ts apps import from here:
+//
+//   import { createApp, r, z } from "@yourrealm/sdk";
+//   import { Postgres, Valkey } from "@yourrealm/sdk/services";
+//
+// Home-side primitives (sanitizeGrants, checkAppGrants, peer-world helpers,
+// the SerializablePermission shape, etc.) live on `@yourrealm/sdk/home`.
+// The bundler/sandbox/generator pipeline lives on `@yourrealm/sdk/compile`.
+// Both Home paths are gated off this entry so author bundles stay lean and
+// don't transitively pull esbuild or quickjs.
+
+export { createApp, createSystemApp } from "./create-app.ts";
+export type { User } from "./create-app.ts";
+export { z } from "zod";
+
+// `r` namespace — author-facing factories.
+import * as host from "./schema/host.ts";
+import * as peers from "./schema/peer.ts";
+import * as remote from "./schema/remote.ts";
+import * as home from "./schema/home.ts";
+import * as input from "./schema/inputs.ts";
+import { section, tab } from "./schema/nodes.ts";
+import { stableSecret } from "./stable-secret.ts";
+
+export const r = {
+  host,
+  peers,
+  remote,
+  home,
+  input: {
+    text: input.text,
+    secret: input.secret,
+    number: input.number,
+    boolean: input.boolean,
+    enum: input.enum_,
+  },
+  section,
+  tab,
+  stableSecret,
+} as const;
+
+// Control-plane client: a granted app calls Home through the worker's
+// home-proxy.sock. `Deno` is touched only inside the function body, so this
+// re-export stays QuickJS-safe.
+export { callHome } from "./runtime/home-client/index.ts";
+
+export { HOME_COOKIE_PREFIX } from "./home-cookie.ts";
+export type { CallHomeOpts } from "./runtime/home-client/index.ts";
+
+// realm.ts ergonomics actually used by author code.
+export { apply } from "./apply.ts";
+export { toYaml } from "./yaml.ts";
+export { toIni } from "./ini.ts";
+export { toJson } from "./json.ts";
+export { toXml } from "./xml.ts";
+export { interpolate, ref } from "./ref.ts";
+export type { Ref } from "./ref.ts";
+export { isNetworkStrategy, isVolumeStrategy } from "./schema/peer.ts";
+
+// Author types. Anything Home-only lives on `/home`.
+export type { AppIcon } from "./app-icon.ts";
+export type { PeerHostPath, RoutedAppEntry, RoutedRouter } from "./schema/peer.ts";
+
+// Identifier schemas + the Network brand.
+export { nameSchema } from "./identifiers.ts";
+export type { Network } from "./identifiers.ts";

package/src/info.ts

@@ -0,0 +1,64 @@
+// Normalization for `info` (createApp's operator-facing setup values). The
+// caller runs the author's `info` fn in the sandbox and resolves its
+// `{__realmRef}` markers; this pure step flattens the resolved dict to
+// `ResolvedInfoEntry`, in declaration order. Shared by Home's summary page
+// and the `t.compile` test harness so both produce identical panels.
+
+/**
+ * One resolved `info` entry, the shape the dashboard's Setup-details panel
+ * renders. Structurally identical to Home's `InfoPanel` island `InfoEntry`.
+ */
+export interface ResolvedInfoEntry {
+  key: string;
+  label: string;
+  value: string;
+  description?: string;
+  sensitive?: boolean;
+  copyable?: boolean;
+}
+
+/**
+ * Flatten a ref-resolved `info` dict to ordered `ResolvedInfoEntry[]`.
+ *
+ *   - A bare value (string / null) becomes `{key, label: key, value, copyable: true}`.
+ *   - A rich object carries `label ?? key`, `description`, `sensitive`, and
+ *     `copyable ?? true`.
+ *   - Any entry whose resolved value isn't a string is dropped (a `null`
+ *     service URL, or anything that didn't resolve to text).
+ */
+export function normalizeInfo(raw: Record<string, unknown> | null): ResolvedInfoEntry[] {
+  if (!raw) return [];
+  const out: ResolvedInfoEntry[] = [];
+  for (const [key, entry] of Object.entries(raw)) {
+    let value: unknown;
+    let label = key;
+    let description: string | undefined;
+    let sensitive: boolean | undefined;
+    let copyable = true;
+
+    if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+      const obj = entry as Record<string, unknown>;
+      value = obj.value;
+      if (typeof obj.label === "string") label = obj.label;
+      if (typeof obj.description === "string") description = obj.description;
+      if (typeof obj.sensitive === "boolean") sensitive = obj.sensitive;
+      if (typeof obj.copyable === "boolean") copyable = obj.copyable;
+    } else {
+      value = entry;
+    }
+
+    // Drop values that aren't strings: this is how `services.<name>` entries
+    // vanish until the install is placed and reachable.
+    if (typeof value !== "string") continue;
+
+    out.push({
+      key,
+      label,
+      value,
+      ...(description !== undefined ? { description } : {}),
+      ...(sensitive ? { sensitive } : {}),
+      copyable,
+    });
+  }
+  return out;
+}

package/src/ini.ts

@@ -0,0 +1,50 @@
+import type { Deferred, Ref } from "./ref.ts";
+import { serializeRefs } from "./serialize.ts";
+
+type IniScalar = string | number | boolean | Ref<string>;
+type IniSection = Record<string, IniScalar>;
+type IniInput = Record<string, IniScalar | IniSection>;
+
+function scalar(value: string | number | boolean): string {
+  return typeof value === "boolean" ? (value ? "true" : "false") : String(value);
+}
+
+// Emit a resolved (ref-free) tree: orphan scalar lines first, then one
+// `[section]` block per nested object. A blank line separates the orphan
+// run from the first section.
+function emitIni(value: Record<string, unknown>): string {
+  const orphans: [string, unknown][] = [];
+  const sections: [string, Record<string, unknown>][] = [];
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "object" && v !== null) {
+      sections.push([k, v as Record<string, unknown>]);
+    } else {
+      orphans.push([k, v]);
+    }
+  }
+
+  let out = "";
+  for (const [k, v] of orphans) out += `${k} = ${scalar(v as string | number | boolean)}\n`;
+  for (const [section, body] of sections) {
+    if (out.length > 0) out += "\n";
+    out += `[${section}]\n`;
+    for (const [k, v] of Object.entries(body)) {
+      out += `${k} = ${scalar(v as string | number | boolean)}\n`;
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize a flat object (orphan keys) or sectioned object (one level
+ * of nesting → `[section]` headers) to INI. Refs in values are resolved
+ * at deploy time (via `apply()`); a ref-free tree collapses to a plain
+ * string at build time.
+ *
+ * Top-level keys are either scalars (orphan lines emitted before any
+ * section) or objects (section bodies). Mixing both is legal — orphans
+ * come first.
+ */
+export function toIni(value: IniInput): string | Deferred<string> {
+  return serializeRefs(value, emitIni);
+}

package/src/json.ts

@@ -0,0 +1,14 @@
+import type { Deferred } from "./ref.ts";
+import { serializeRefs } from "./serialize.ts";
+
+/**
+ * Serialize a value to a JSON string. Refs anywhere in the tree are
+ * resolved at deploy time (via `apply()`) before `JSON.stringify` runs, so
+ * a resolved secret is escaped correctly rather than spliced raw. A
+ * ref-free value collapses to a plain string at build time.
+ *
+ *   files: { "/etc/app/config.json": toJson({ token: secretRef, port: 8080 }) }
+ */
+export function toJson<T>(value: T): string | Deferred<string> {
+  return serializeRefs(value, (resolved) => JSON.stringify(resolved));
+}

package/src/jsx-runtime/index.ts

@@ -0,0 +1,5 @@
+// `@yourrealm/sdk/jsx-runtime` — re-exports preact's automatic JSX
+// runtime (functions and the `JSX` namespace) so realm.ts authors can
+// set `jsxImportSource: "@yourrealm/sdk"` instead of `"preact"`, which
+// keeps preact out of their declared deps.
+export * from "preact/jsx-runtime";

package/src/keys.ts

@@ -0,0 +1,29 @@
+/**
+ * Hex-encode a byte array. Lowercase, two chars per byte, no separator.
+ */
+export function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Derive a per-app secret from the master derivation seed.
+ *
+ * HMAC with a JSON-array message structurally prevents canonicalization
+ * collisions - distinct (appId, name) inputs can't map to the same
+ * serialized form, which is a property string-concatenation with a colon
+ * separator never had (`appId="a", name="b:c"` collided with
+ * `appId="a:b", name="c"`).
+ */
+export async function deriveAppPassword(
+  seedKey: CryptoKey,
+  appId: string,
+  name: string,
+): Promise<string> {
+  const message = new TextEncoder().encode(
+    JSON.stringify(["derived-password", appId, name]),
+  ) as Uint8Array<ArrayBuffer>;
+  const sig = await crypto.subtle.sign("HMAC", seedKey, message);
+  return toHex(new Uint8Array(sig));
+}

package/src/mysql.ts

@@ -0,0 +1,56 @@
+import type { Ref } from "./ref.ts";
+import { interpolate as i } from "./ref.ts";
+import { Service } from "./service.ts";
+
+interface MySQLOptions {
+  majorVersion?: number;
+}
+
+export class MySQL extends Service {
+  readonly image: string;
+  readonly port = 3306;
+  readonly user = "realm";
+  readonly database = "realm";
+  private readonly _majorVersion: number;
+
+  constructor(options?: MySQLOptions) {
+    super();
+    const majorVersion = options?.majorVersion ?? 9;
+    this.image = `mysql:${majorVersion}`;
+    this._majorVersion = majorVersion;
+  }
+
+  get password(): Ref<string> {
+    return this.derived("mysql-password");
+  }
+
+  get rootPassword(): Ref<string> {
+    return this.derived("root-password");
+  }
+
+  get url(): Ref<string> {
+    return i`mysql://${this.user}:${this.password}@${this.host}:${this.port}/${this.database}`;
+  }
+
+  getServiceDefinition() {
+    return {
+      image: this.image,
+      volumes: [
+        {
+          hostPath: i`./data/${this.host}`,
+          containerPath: "/var/lib/mysql",
+          backup: { kind: "mysql-dump" as const, url: this.url, version: this._majorVersion },
+        },
+      ],
+      env: {
+        MYSQL_USER: this.user,
+        MYSQL_PASSWORD: this.password,
+        MYSQL_DATABASE: this.database,
+        MYSQL_ROOT_PASSWORD: this.rootPassword,
+      },
+      healthcheck: {
+        test: ["CMD", "mysqladmin", "ping", "-h", "localhost"],
+      },
+    };
+  }
+}

package/src/pack-build.ts

@@ -0,0 +1,108 @@
+// Build-time app packer: collect an app's source files and stitch them into the
+// shipped `// realm-file:` artifact. The relative-import closure comes off the
+// TypeScript AST, so every import form (static of any line layout, dynamic
+// `import()`, `require()`) is caught where a regex would miss some.
+//
+// It must NEVER be imported by Home: `typescript` trips Home's least-privilege
+// sandbox (ts.sys' env probe → NotCapable). Only `realm-sdk build`, `realm-sdk
+// dev`'s install panel, and tests reach for it; Home merges the raw artifact
+// with esbuild alone (see surfaces.ts).
+
+import { join } from "@std/path";
+import ts from "typescript";
+import { packFiles } from "./pack.ts";
+import { findRealmEntry, globSurfaces } from "./surfaces.ts";
+
+// Every module specifier a file imports/exports/requires, read off the real AST.
+function moduleSpecifiers(source: string, fileName: string): string[] {
+  const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const specs: string[] = [];
+  const visit = (node: ts.Node): void => {
+    if (
+      (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+      node.moduleSpecifier &&
+      ts.isStringLiteralLike(node.moduleSpecifier)
+    ) {
+      specs.push(node.moduleSpecifier.text); // static import/export ... from "x"
+    } else if (ts.isCallExpression(node)) {
+      const isDynamicImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+      const isRequire = ts.isIdentifier(node.expression) && node.expression.text === "require";
+      const arg = node.arguments[0];
+      if ((isDynamicImport || isRequire) && arg && ts.isStringLiteralLike(arg)) {
+        specs.push(arg.text); // import("x") / require("x")
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return specs;
+}
+
+// Resolve a relative specifier against the importing file's app-relative path,
+// returning the app-relative posix target — or null if it climbs out of the app
+// root. Deno requires explicit extensions, so the literal path is the file: no
+// extension guessing, no index resolution.
+function resolveRelative(fromPath: string, spec: string): string | null {
+  const dir = fromPath.includes("/") ? fromPath.slice(0, fromPath.lastIndexOf("/")) : "";
+  const stack: string[] = [];
+  for (const seg of (dir ? dir.split("/") : []).concat(spec.split("/"))) {
+    if (seg === "" || seg === ".") continue;
+    if (seg === "..") {
+      if (stack.length === 0) return null;
+      stack.pop();
+    } else {
+      stack.push(seg);
+    }
+  }
+  return stack.join("/");
+}
+
+// Discover every local source file an app is built from — the realm entry, the
+// file-based surfaces (pages/*, widgets/*), and their relative-import closure —
+// keyed by app-root-relative posix path with the entry first. Pure reads: no
+// esbuild, no temp files.
+async function collectAppFiles(appDir: string): Promise<Map<string, string>> {
+  const entry = findRealmEntry(appDir);
+  const seeds = [
+    entry,
+    ...[...(await globSurfaces(appDir, "page")), ...(await globSurfaces(appDir, "widget"))].map(
+      (f) => `${f.dir}/${f.file}`,
+    ),
+  ];
+
+  const contents = new Map<string, string>();
+  const queue = [...seeds];
+  while (queue.length > 0) {
+    const rel = queue.shift()!;
+    if (contents.has(rel)) continue;
+    let text: string;
+    try {
+      text = await Deno.readTextFile(join(appDir, rel));
+    } catch {
+      continue; // unresolvable import — bundle() surfaces it later with context
+    }
+    contents.set(rel, text);
+    for (const spec of moduleSpecifiers(text, rel)) {
+      if (!spec.startsWith("./") && !spec.startsWith("../")) continue;
+      const target = resolveRelative(rel, spec);
+      if (target && !contents.has(target)) queue.push(target);
+    }
+  }
+
+  // Entry first (so a preview leads with realm.tsx), then the rest sorted.
+  const ordered = [entry, ...[...contents.keys()].filter((p) => p !== entry).sort()];
+  return new Map(ordered.map((p) => [p, contents.get(p)!]));
+}
+
+/**
+ * Build the shipped artifact for an app: its raw source files stitched into the
+ * marker-delimited pack. No merge, no derived content — Home merges at install.
+ * A single-file app (just the entry, no surfaces or helpers) ships raw with no
+ * markers, so `isPacked` stays false and every consumer treats it as the entry.
+ * Pure reads, so this runs anywhere (incl. a sandboxed test process).
+ */
+export async function buildPackedApp(appDir: string): Promise<string> {
+  const files = await collectAppFiles(appDir);
+  if (files.size === 1) return [...files.values()][0]!;
+  return packFiles(files);
+}

package/src/pack.ts

@@ -0,0 +1,115 @@
+// Marker-delimited single-file archive for multi-file realm apps.
+//
+// A multi-file app (realm.tsx + pages/*.tsx + widgets/*.tsx + relative
+// helpers) is shipped as ONE text artifact whose chunks are delimited by
+// `// realm-file: <path>` lines:
+//
+//   // realm-file: realm.tsx
+//   <contents of realm.tsx>
+//   // realm-file: widgets/status.tsx
+//   <contents of widgets/status.tsx>
+//
+// Home stores this verbatim in one `source` text column and unpacks it into a
+// confined tmp tree at install, then runs the same merge + bundle the dev/build
+// path uses. The artifact IS the human-readable source, so the store can
+// preview it file by file and any integrity digest is over source the operator
+// can read rather than an esbuild blob.
+//
+// A single-file app is an artifact with no markers; `isPacked` is false and
+// every consumer treats the whole string as the realm entry, unchanged.
+
+const MARKER_PREFIX = "// realm-file: ";
+
+// The realm entry, in preference order. A packed app puts one of these first.
+export const REALM_ENTRIES = ["realm.tsx", "realm.ts"] as const;
+
+// A marker line at the start of a content line would be misread as a chunk
+// boundary, so on pack we slip one `\` in after `// ` (escape ladder: an
+// already-escaped line gets another `\`); unpack peels exactly one back. A
+// real boundary never carries a `\`, so the two are unambiguous.
+const ESCAPE_RE = /^(\/\/ )(\\*realm-file:)/gm;
+const UNESCAPE_RE = /^(\/\/ )(\\+realm-file:)/gm;
+
+// Boundary lines, matched at line start. `.+` is the path; greedy is fine
+// since a path never contains a newline.
+const BOUNDARY_RE = /^\/\/ realm-file: (.+)$/gm;
+
+/** A packed artifact always begins with the entry's marker at byte 0. */
+export function isPacked(source: string): boolean {
+  return source.startsWith(MARKER_PREFIX);
+}
+
+function escapeContent(content: string): string {
+  return content.replace(ESCAPE_RE, "$1\\$2");
+}
+
+function unescapeContent(content: string): string {
+  return content.replace(
+    UNESCAPE_RE,
+    (_full, slashes: string, rest: string) => slashes + rest.slice(1),
+  );
+}
+
+// A path is confined when it's a plain forward-slash relative path that can't
+// climb out of the app root: no absolute, no `..`/`.` segments, no backslash
+// (Windows-y paths + an escape vector), no empty segments.
+function assertConfinedPath(path: string): void {
+  if (path === "" || path.startsWith("/") || path.includes("\\") || path.includes("\0")) {
+    throw new Error(`realm-file: unsafe path "${path}"`);
+  }
+  for (const seg of path.split("/")) {
+    if (seg === "" || seg === "." || seg === "..") {
+      throw new Error(`realm-file: unsafe path "${path}"`);
+    }
+  }
+}
+
+/**
+ * Pack a set of files into the marker-delimited artifact. `files` is keyed by
+ * app-root-relative posix path; iteration order is preserved (callers put the
+ * realm entry first). Each chunk's content is normalized to end in a single
+ * newline so the next marker always lands at a line start.
+ */
+export function packFiles(files: Map<string, string>): string {
+  const parts: string[] = [];
+  for (const [path, content] of files) {
+    assertConfinedPath(path);
+    const normalized = content.endsWith("\n") ? content : content + "\n";
+    parts.push(MARKER_PREFIX + path + "\n" + escapeContent(normalized));
+  }
+  return parts.join("");
+}
+
+/**
+ * Unpack a marker-delimited artifact into a path → content map. Paths are
+ * confined to the app root (throws on any `..`/absolute/backslash escape).
+ * A string with no markers is returned as a single-entry map under the given
+ * `singleFileName` (default `realm.tsx`).
+ */
+export function unpackFiles(packed: string, singleFileName = "realm.tsx"): Map<string, string> {
+  if (!isPacked(packed)) {
+    return new Map([[singleFileName, packed]]);
+  }
+
+  const markers: { path: string; contentStart: number; lineStart: number }[] = [];
+  BOUNDARY_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = BOUNDARY_RE.exec(packed)) !== null) {
+    const nl = packed.indexOf("\n", m.index + m[0]!.length);
+    markers.push({
+      path: m[1]!.trim(),
+      lineStart: m.index,
+      contentStart: nl === -1 ? packed.length : nl + 1,
+    });
+  }
+
+  const files = new Map<string, string>();
+  for (let i = 0; i < markers.length; i++) {
+    const { path, contentStart } = markers[i]!;
+    assertConfinedPath(path);
+    const end = i + 1 < markers.length ? markers[i + 1]!.lineStart : packed.length;
+    if (files.has(path)) throw new Error(`realm-file: duplicate path "${path}"`);
+    files.set(path, unescapeContent(packed.slice(contentStart, end)));
+  }
+  return files;
+}