@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/peer-registry.ts

@@ -0,0 +1,121 @@
+// Per-kind Home-side mechanics for peer permissions.
+//
+// Each peer factory carries its kind + hooks as non-enumerable symbol
+// properties (set by makePeerable / tagPeerable). The runtime registry is
+// derived from a namespace import (`derivePeerRegistry(peers)`), not a
+// mutable module-scoped table.
+
+import type { z } from "zod";
+import type { Network } from "./identifiers.ts";
+import type { HomeApp, HomeService } from "./resolve.ts";
+import type { Builder } from "./shared.ts";
+import {
+  tagPermissionMeta,
+  type PermissionMeta,
+  type PermissionMetaTagged,
+} from "./permission-meta.ts";
+
+// Loose constraint used inside this module. The closed
+// `PeerPermissionKind` is derived in permissions.ts — see
+// host-registry.ts for the same pattern.
+type PeerKindShape = `peers.${string}`;
+
+export interface AllowedProvider {
+  appId: string;
+  serviceKey: string;
+}
+
+/**
+ * Per-kind Home-side mechanics. Each hook covers a different consumer of
+ * peer data:
+ *
+ *   - extract / resolve: feed extractPeerEntries / resolvePeerValue.
+ *     `resolve` receives the consumer's descriptor data; presence-only
+ *     peers ignore the second arg.
+ *   - extractNetworks / extractPeerVolumes / extractAllowedProvider:
+ *     feed Home graph.ts when computing per-app allowed networks /
+ *     volumes / providers
+ *   - producerPredicate: feeds Home merge.ts when wiring depends_on edges
+ *
+ * Every peer permission requires an admin grant — there is no "ungated"
+ * shortcut. Consumers that haven't been granted resolve to an empty list.
+ */
+export interface PeerHooks<TInput = unknown, TEntry = unknown, TValue = unknown> {
+  extract(appId: string, state: HomeApp): TEntry[];
+  resolve(entries: TEntry[], data: TInput): TValue;
+  extractNetworks?(entry: TEntry): Network | undefined;
+  extractPeerVolumes?(entry: TEntry): string | undefined;
+  extractAllowedProvider?(entry: TEntry): AllowedProvider | undefined;
+  producerPredicate?(svc: HomeService): boolean;
+}
+
+const PEER_KIND = Symbol("realm.peer.kind");
+const PEER_HOOKS = Symbol("realm.peer.hooks");
+
+export interface Peerable<K extends PeerKindShape = PeerKindShape, V = unknown> {
+  readonly [PEER_KIND]: K;
+  readonly [PEER_HOOKS]: PeerHooks<unknown, unknown, V>;
+}
+
+function isPeerable(value: unknown): value is Peerable {
+  return (
+    (typeof value === "function" || (typeof value === "object" && value !== null)) &&
+    PEER_KIND in (value as object) &&
+    PEER_HOOKS in (value as object)
+  );
+}
+
+/** Attach kind + hooks to a factory. The tagging half of makePeerable. */
+function tagPeerable<T extends object, K extends PeerKindShape, V>(
+  target: T,
+  kind: K,
+  hooks: PeerHooks<unknown, unknown, V>,
+  meta: PermissionMeta,
+): T & Peerable<K, V> & PermissionMetaTagged<K> {
+  Object.defineProperty(target, PEER_KIND, { value: kind, enumerable: false });
+  Object.defineProperty(target, PEER_HOOKS, { value: hooks, enumerable: false });
+  return tagPermissionMeta(target, kind, meta) as T & Peerable<K, V> & PermissionMetaTagged<K>;
+}
+
+/**
+ * Bind an inner Builder (typically `basePermission`) and return a
+ * factory-builder that produces tagged peer-permission factories. Pure —
+ * no side effects on any registry. The runtime registry is derived from
+ * a namespace import via `derivePeerRegistry`.
+ *
+ * Composes with the factory mixins, mirroring `makeHostable`:
+ *
+ *   const peerable = makePeerable(basePermission);
+ *   export const routedApps = peerable("peers.routedApps", z.literal(true).default(true), {
+ *     extract, resolve, ...
+ *   });
+ */
+export function makePeerable<BaseR extends object, KindUnion extends PeerKindShape>(
+  inner: Builder<BaseR, "perm", KindUnion>,
+) {
+  return <S extends z.ZodType, TEntry, TValue, K extends KindUnion>(
+    kind: K,
+    schema: S,
+    hooks: PeerHooks<z.input<S>, TEntry, TValue>,
+    meta: PermissionMeta,
+  ) => {
+    const factory = inner(kind, schema);
+    return tagPeerable(factory, kind, hooks as PeerHooks<unknown, unknown, TValue>, meta);
+  };
+}
+
+/**
+ * Walk a namespace import (e.g. `import * as peers from "./schema/peer.ts"`)
+ * and build a kind→hooks map from every Peerable export. Non-peerable
+ * exports (types are erased; helpers like `isNetworkStrategy` are skipped)
+ * are filtered by `isPeerable`.
+ */
+export function derivePeerRegistry(
+  mod: Record<string, unknown>,
+): ReadonlyMap<PeerKindShape, PeerHooks> {
+  const reg = new Map<PeerKindShape, PeerHooks>();
+  for (const value of Object.values(mod)) {
+    if (isPeerable(value)) reg.set(value[PEER_KIND], value[PEER_HOOKS]);
+  }
+  return reg;
+}

package/src/peer-world.ts

@@ -0,0 +1,117 @@
+// Cross-app world-state aggregation for peer permissions.
+//
+// Per-kind logic lives next to the factory in schema/peer.ts (each
+// factory tagged with kind + hooks via makePeerable). This module
+// derives a kind→hooks map from the namespace import and dispatches
+// every extract / resolve / grant check through it.
+
+import * as peers from "./schema/peer.ts";
+import type { HomeApp } from "./resolve.ts";
+import type { Grant } from "./grants.ts";
+import { derivePeerRegistry, type Peerable, type PeerHooks } from "./peer-registry.ts";
+import type { PeerPermissionKind, PermissionKind } from "./permissions.ts";
+
+const REGISTRY = derivePeerRegistry(peers as Record<string, unknown>);
+
+export function peerHooks(kind: string): PeerHooks | undefined {
+  return REGISTRY.get(kind as `peers.${string}`);
+}
+
+export function peerEntries(): ReadonlyArray<readonly [PeerPermissionKind, PeerHooks]> {
+  return [...REGISTRY.entries()] as unknown as ReadonlyArray<
+    readonly [PeerPermissionKind, PeerHooks]
+  >;
+}
+
+// Derived from `typeof peers`: each Peerable<K, V> contributes
+// `{ kind: K, data: V[number] }` since every peer's `resolve` returns
+// an array of world-entry values. Adding a peer kind = one declaration
+// in schema/peer.ts; this union updates automatically. Constraint: V
+// must be array-shaped (true for all current peers).
+type PeerEntryDataMap = {
+  [N in keyof typeof peers as (typeof peers)[N] extends Peerable<infer K, unknown>
+    ? K
+    : never]: (typeof peers)[N] extends Peerable<PeerPermissionKind, infer V>
+    ? V extends readonly (infer E)[]
+      ? E
+      : never
+    : never;
+};
+
+export type WorldEntry = {
+  [K in keyof PeerEntryDataMap]: { readonly kind: K; readonly data: PeerEntryDataMap[K] };
+}[keyof PeerEntryDataMap];
+
+export type WorldState = ReadonlyArray<WorldEntry>;
+
+/** One `peers.buildApps` world entry, narrowed out of the kind union. */
+export type BuildAppWorldEntry = Extract<WorldEntry, { kind: "peers.buildApps" }>;
+
+/**
+ * Narrow a world entry to `peers.buildApps`. This guard and the type above are
+ * the only places outside schema/peer.ts that name that kind, and they exist
+ * for one deliberate special case.
+ *
+ * Build-app entries are the only ones Home unions across WORKERS. Peer worlds
+ * are otherwise assembled per worker, which would confine every
+ * build-from-source app to whichever box the (singleton) builder happens to
+ * sit on. What licenses the exception is that `buildApps` declares `extract` +
+ * `resolve` and none of the four locality hooks — `extractNetworks`,
+ * `extractPeerVolumes`, `extractAllowedProvider`, `producerPredicate`. Each of
+ * those would turn an entry into something that exists on exactly one box: a
+ * docker network to join, a host path to mount, a `shared` ref to dereference,
+ * a `depends_on` edge. With none of them present, an entry from another worker
+ * is inert data — a recipe to read, nothing to wire. Adding any of those hooks
+ * to `buildApps` would break realm-wide scope; `peer-world.test.ts` guards it.
+ *
+ * Rename-safe by construction: `e.kind` is the closed `PeerPermissionKind`
+ * union, so a stale literal here is a TS2367 comparison error and the
+ * `Extract` above collapses to `never`.
+ */
+export function isBuildAppEntry(e: WorldEntry): e is BuildAppWorldEntry {
+  return e.kind === "peers.buildApps";
+}
+
+/**
+ * Walk one app's resolved state and emit every peer-shaped contribution.
+ * Home aggregates results across all apps into a single WorldState before
+ * resolving any consumer's permission.
+ */
+export function extractPeerEntries(appId: string, state: HomeApp): WorldEntry[] {
+  const out: WorldEntry[] = [];
+  for (const [kind, hooks] of REGISTRY) {
+    for (const data of hooks.extract(appId, state)) {
+      out.push({ kind, data } as WorldEntry);
+    }
+  }
+  return out;
+}
+
+/**
+ * Given a consumer's permission kind + descriptor data, return the
+ * filtered runtime value over the aggregated world.
+ */
+export function resolvePeerValue(
+  kind: PeerPermissionKind,
+  data: unknown,
+  world: WorldState,
+): unknown {
+  const hooks = REGISTRY.get(kind);
+  if (!hooks) throw new Error(`unknown peer kind: ${kind}`);
+  const entries = world.filter((e) => e.kind === kind).map((e) => e.data);
+  return hooks.resolve(entries, data);
+}
+
+/**
+ * Did the admin grant this peer permission? Every peer kind requires an
+ * explicit grant entry at the consumer's path — there is no auto-grant.
+ */
+export function isPeerGranted(
+  name: string,
+  kind: PermissionKind,
+  grants: Record<string, Grant> | undefined,
+): boolean {
+  if (!REGISTRY.has(kind as PeerPermissionKind)) return false;
+  const g = grants?.[name];
+  return g != null && g.kind === kind;
+}

package/src/permission-meta.ts

@@ -0,0 +1,116 @@
+// Per-kind declaration metadata machinery. `PermissionMeta` is the shape
+// every permission factory carries (per-field docs on the interface below).
+// Mostly presentation, but `appKinds` is enforcement, and it lives here
+// rather than in the per-family hooks (`HostHooks` / `PeerHooks` / …)
+// because the rule is the same across all four namespaces.
+//
+// The runtime const `PERMISSION_META` is *derived* — see permissions.ts —
+// by walking the schema/{host,peer,remote,home}.ts namespace exports and
+// pulling the meta tag off each factory, which keeps the kind list and
+// presentation strings in lockstep with their declaration site.
+
+import type { IconName } from "./ui/components/icons.tsx";
+
+/** Which factory produced an app: `createApp` or `createSystemApp`. */
+export type AppKind = "single" | "system";
+
+/**
+ * Which app kinds may declare a permission. `"both"` is the common case;
+ * the two narrow values are restrictions with a reason at the declaration
+ * site.
+ *
+ * Required rather than optional-defaulting-to-both, so a new kind has to
+ * answer the question instead of inheriting the loosest answer by
+ * omission. Note the asymmetry when picking one: widening later is
+ * additive, narrowing later breaks whatever came to rely on it (the same
+ * reasoning as `assertOneSilo` in sandbox.ts), so absent a real single-app
+ * or system-app consumer, the narrow value is the safer default.
+ */
+export type AppKindScope = AppKind | "both";
+
+export interface PermissionMeta {
+  /** Short Title-Case label for UI rows (e.g. "Port", "Directory"). */
+  name: string;
+  /** Lowercase phrase used inside violation messages (e.g. "bind a host port"). */
+  phrase: string;
+  /** Tooltip-length explanation shown next to the row. */
+  helpText: string;
+  /** Icon name from `icons.tsx` (e.g. "GraphicsCardIcon", "FolderOpenIcon"). */
+  icon: IconName;
+  /** Drives danger-tinted styling on the install panel. */
+  danger?: boolean;
+  /**
+   * App kinds allowed to declare this permission. Enforced twice: the
+   * factories walk `configSchema` and throw at author time, and Home's
+   * graph verification runs the same check authoritatively (see
+   * `checkPermissionAppKinds` in security.ts).
+   */
+  appKinds: AppKindScope;
+}
+
+/** Whether `appKind` may declare a permission scoped to `scope`. */
+export function scopeAllows(scope: AppKindScope, appKind: AppKind): boolean {
+  return scope === "both" || scope === appKind;
+}
+
+// Unique symbol that brands every permission factory with its kind +
+// meta. Module-private — only this file's `tagPermissionMeta` writes it,
+// and the type-level helpers (`PermissionMetaTagged<K>`,
+// `KindOfPermission<T>`) read it back via structural inference: TS resolves
+// the property-key symbol type from this `unique symbol` declaration alone.
+const PERMISSION_META_TAG: unique symbol = Symbol("realm.permission.meta");
+
+export interface PermissionMetaTagged<K extends string = string> {
+  readonly [PERMISSION_META_TAG]: { readonly kind: K; readonly meta: PermissionMeta };
+}
+
+/**
+ * Type-level helper: extract the kind literal from a tagged factory.
+ * `KindOfPermission<typeof gpu>` resolves to `"host.gpu"`.
+ */
+export type KindOfPermission<T> = T extends PermissionMetaTagged<infer K> ? K : never;
+
+/**
+ * Attach kind + meta to a permission factory as a non-enumerable tag.
+ * Used by makeHostable / makePeerable / makeRemotable so every factory
+ * carries its meta at the declaration site, not in a hand-maintained
+ * lookup table.
+ */
+export function tagPermissionMeta<T extends object, K extends string>(
+  target: T,
+  kind: K,
+  meta: PermissionMeta,
+): T & PermissionMetaTagged<K> {
+  Object.defineProperty(target, PERMISSION_META_TAG, {
+    value: { kind, meta },
+    enumerable: false,
+  });
+  return target as T & PermissionMetaTagged<K>;
+}
+
+function isMetaTagged(value: unknown): value is PermissionMetaTagged {
+  return (
+    (typeof value === "function" || (typeof value === "object" && value !== null)) &&
+    PERMISSION_META_TAG in (value as object)
+  );
+}
+
+/**
+ * Walk one or more namespace imports (e.g. `import * as host from
+ * "./schema/host.ts"`) and build a kind → meta map from every tagged
+ * factory. Non-tagged exports are skipped.
+ */
+export function derivePermissionMeta(
+  ...modules: Array<Record<string, unknown>>
+): Record<string, PermissionMeta> {
+  const out: Record<string, PermissionMeta> = {};
+  for (const mod of modules) {
+    for (const value of Object.values(mod)) {
+      if (isMetaTagged(value)) {
+        const tag = value[PERMISSION_META_TAG];
+        out[tag.kind] = tag.meta;
+      }
+    }
+  }
+  return out;
+}

package/src/permissions.ts

@@ -0,0 +1,108 @@
+// Permission kinds + presentation meta, all *derived* by walking the
+// schema/{host,peer,remote,home}.ts namespace exports. Each factory is tagged
+// at declaration via tagPermissionMeta — that tag carries kind + meta
+// and is the single source of truth this file consumes.
+//
+// Living here (not in shared.ts) breaks what would otherwise be a
+// type-level cycle: shared.ts is imported by factory.ts which is imported
+// by the schemas, so shared.ts can't depend on the schemas.
+
+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 {
+  derivePermissionMeta,
+  scopeAllows,
+  type AppKind,
+  type PermissionMeta,
+  type KindOfPermission,
+} from "./permission-meta.ts";
+
+export type { AppKind, PermissionMeta };
+
+// ----- Type-level derivation ----------------------------------------------
+
+type KindsIn<M> = KindOfPermission<M[keyof M]>;
+
+export type HostPermissionKind = Extract<KindsIn<typeof host>, `host.${string}`>;
+export type PeerPermissionKind = Extract<KindsIn<typeof peers>, `peers.${string}`>;
+export type RemotePermissionKind = Extract<KindsIn<typeof remote>, `remote.${string}`>;
+// `home.*` is Home-resolved and never worker-advertised — like peers/remote
+// it stays out of HOST_PERMISSION_KINDS (the worker-capability gate), but it
+// carries data + a resolved value like host (see home-registry.ts).
+export type HomePermissionKind = Extract<KindsIn<typeof home>, `home.${string}`>;
+export type PermissionKind =
+  | HostPermissionKind
+  | PeerPermissionKind
+  | RemotePermissionKind
+  | HomePermissionKind;
+
+// ----- Runtime derivation -------------------------------------------------
+
+export const PERMISSION_META: Readonly<Record<PermissionKind, PermissionMeta>> =
+  derivePermissionMeta(
+    host as Record<string, unknown>,
+    peers as Record<string, unknown>,
+    remote as Record<string, unknown>,
+    home as Record<string, unknown>,
+  ) as Readonly<Record<PermissionKind, PermissionMeta>>;
+
+/**
+ * Closed set of permission kinds known at runtime. Useful for wire-format
+ * Zod schemas (`z.enum([...PERMISSION_KINDS])`) that need to validate
+ * input strings against the actual registered kinds.
+ */
+export const PERMISSION_KINDS: readonly PermissionKind[] = Object.keys(
+  PERMISSION_META,
+).sort() as PermissionKind[];
+
+/**
+ * Host-only subset of `PERMISSION_KINDS` (peers + remote + home are
+ * Home-resolved at eval and never worker-advertised).
+ */
+export const HOST_PERMISSION_KINDS: readonly HostPermissionKind[] = Object.keys(
+  derivePermissionMeta(host as Record<string, unknown>),
+).sort() as HostPermissionKind[];
+
+/**
+ * Everything a worker can advertise on the register wire: the host
+ * permission kinds, plus `host.volumes` — a capability with no permission
+ * behind it. It says whether the worker can hold persistent bind mounts at
+ * all; a worker without it is an ephemeral runtime (sandbox VM,
+ * emptyDir-only k8s) and can't run any app that mounts a volume. Which
+ * absolute paths an app may mount is a separate question, answered by
+ * grants (Silos, broker sockets), not by this capability.
+ */
+export type WorkerCapability = HostPermissionKind | "host.volumes";
+
+export const WORKER_CAPABILITIES: readonly WorkerCapability[] = [
+  ...HOST_PERMISSION_KINDS,
+  "host.volumes",
+].sort() as WorkerCapability[];
+
+/**
+ * Typed accessor — throws on unknown kinds. Use this instead of
+ * `PERMISSION_META[kind]` when you'd otherwise have to handle the
+ * `| undefined` that noUncheckedIndexedAccess forces on lookups.
+ */
+export function permissionMeta(kind: PermissionKind): PermissionMeta {
+  const meta = PERMISSION_META[kind];
+  if (!meta) {
+    throw new Error(`unknown permission kind: ${kind}`);
+  }
+  return meta;
+}
+
+/**
+ * Whether an app of `appKind` may declare a permission of `kind`.
+ *
+ * Unknown kinds pass. A kind that isn't in the derived registry can't be
+ * declared by a real factory in the first place, so the only way to reach
+ * here with one is a hand-written packed bundle, and that's `checkAppGrants`'
+ * problem — failing closed here would just report the wrong reason for it.
+ */
+export function permissionAllowsAppKind(kind: string, appKind: AppKind): boolean {
+  const meta = PERMISSION_META[kind as PermissionKind];
+  return meta ? scopeAllows(meta.appKinds, appKind) : true;
+}

package/src/pkg-root.ts

@@ -0,0 +1,34 @@
+// The SDK package directory, found by walking up from the calling module to
+// the nearest `package.json`. Source runs from `src/<...>` and the published
+// package from `dist/<name>.js`, so a fixed `..` count would name a different
+// directory in each layout; the walk names the same one in both.
+//
+// `pkgRoot` answers null rather than throwing: Home's production image stages
+// the Fresh server bundle with no `package.json` anywhere above it, and the
+// callers there only use the directory as one more place to look for a binary.
+
+import { dirname, fromFileUrl, join } from "@std/path";
+
+export function pkgRoot(moduleUrl: string): string | null {
+  if (!moduleUrl.startsWith("file:")) return null;
+  let dir = dirname(fromFileUrl(moduleUrl));
+  while (true) {
+    try {
+      Deno.statSync(join(dir, "package.json"));
+      return dir;
+    } catch {
+      // not here - keep walking
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// For the CLI builders, which read the ui-runtime sources out of the package
+// and cannot run without it.
+export function sdkDir(moduleUrl: string): string {
+  const dir = pkgRoot(moduleUrl);
+  if (dir === null) throw new Error(`the SDK package is not on disk above ${moduleUrl}`);
+  return dir;
+}

package/src/postgres.ts

@@ -0,0 +1,79 @@
+import type { Ref } from "./ref.ts";
+import { interpolate as i } from "./ref.ts";
+import { Service } from "./service.ts";
+
+/**
+ * Shared options that apply regardless of whether the caller picks the
+ * default image or overrides it.
+ */
+interface PostgresCommonOptions {
+  /**
+   * Size of `/dev/shm` (tmpfs in RAM) inside the container, in MB.
+   * Defaults to `128` - up from Docker's 64MB default. Postgres uses
+   * POSIX shared memory for parallel workers and large hash joins; the
+   * value is a cap, not a pre-allocation, so idle containers cost nothing
+   * extra.
+   */
+  shmSizeMb?: number;
+}
+
+/**
+ * Either run the default `postgres:{majorVersion}` image (in which case
+ * `image` is omitted), or override `image` to run a Postgres flavor with
+ * bundled extensions. When `image` is set, `majorVersion` becomes
+ * required so the backup container can pick the matching `pg_dump`
+ * binary - a mismatched pair fails at backup time, not at evaluate time,
+ * so we lift the check up to the type system.
+ */
+type PostgresOptions =
+  | (PostgresCommonOptions & { majorVersion?: number; image?: never })
+  | (PostgresCommonOptions & { majorVersion: number; image: string });
+
+export class Postgres extends Service {
+  readonly image: string;
+  readonly port = 5432;
+  readonly user = "realm";
+  readonly database = "realm";
+  // Underscore-prefixed to keep it off the public surface - the backup
+  // strategy is the only consumer, and output doesn't carry it.
+  private readonly _majorVersion: number;
+  private readonly _shmSizeMb: number;
+
+  constructor(options?: PostgresOptions) {
+    super();
+    const majorVersion = options?.majorVersion ?? 18;
+    this.image = options?.image ?? `postgres:${majorVersion}`;
+    this._majorVersion = majorVersion;
+    this._shmSizeMb = options?.shmSizeMb ?? 128;
+  }
+
+  get password(): Ref<string> {
+    return this.derived("postgres-password");
+  }
+
+  get url(): Ref<string> {
+    return i`postgres://${this.user}:${this.password}@${this.host}:${this.port}/${this.database}`;
+  }
+
+  getServiceDefinition() {
+    return {
+      image: this.image,
+      volumes: [
+        {
+          hostPath: i`./data/${this.host}`,
+          containerPath: "/var/lib/postgresql",
+          backup: { kind: "pg-dump" as const, url: this.url, version: this._majorVersion },
+        },
+      ],
+      env: {
+        POSTGRES_USER: this.user,
+        POSTGRES_PASSWORD: this.password,
+        POSTGRES_DB: this.database,
+      },
+      healthcheck: {
+        test: ["CMD", "pg_isready", "-U", "realm", "-d", "realm"],
+      },
+      shmSizeMb: this._shmSizeMb,
+    };
+  }
+}

package/src/preact/index.ts

@@ -0,0 +1,27 @@
+// `@yourrealm/sdk/preact` — preact hooks and JSX types for realm.ts
+// authors. realm.ts code imports from here instead of `preact/hooks`
+// directly so the iframe framework stays an SDK implementation detail.
+//
+// Same dual-pattern as `@yourrealm/sdk/ui`: this file is the type
+// contract used at authoring/typecheck time, and its values are stubs
+// that throw if invoked outside the iframe. The real hooks ship from
+// `ui-runtime/index.ts` (bundled into runtime.js), which the iframe
+// importmap routes this specifier to.
+
+import type * as _hooks from "preact/hooks";
+
+export type { ComponentChildren, JSX, VNode } from "preact";
+
+const stub = ((): never => {
+  throw new Error(
+    "@yourrealm/sdk/preact has no runtime in this environment. Hook calls are bundled by realm-sdk and execute inside the Home iframe.",
+  );
+  // deno-lint-ignore no-explicit-any
+}) as any;
+
+export const useCallback: typeof _hooks.useCallback = stub;
+export const useEffect: typeof _hooks.useEffect = stub;
+export const useMemo: typeof _hooks.useMemo = stub;
+export const useReducer: typeof _hooks.useReducer = stub;
+export const useRef: typeof _hooks.useRef = stub;
+export const useState: typeof _hooks.useState = stub;

package/src/redis.ts

@@ -0,0 +1,43 @@
+import type { Ref } from "./ref.ts";
+import { interpolate as i } from "./ref.ts";
+import { Service } from "./service.ts";
+
+interface RedisOptions {
+  version?: string;
+}
+
+export class Redis extends Service {
+  readonly image: string;
+  readonly port = 6379;
+
+  constructor(options?: RedisOptions) {
+    super();
+    this.image = `redis:${options?.version ?? "8"}`;
+  }
+
+  get password(): Ref<string> {
+    return this.derived("redis-password");
+  }
+
+  get url(): Ref<string> {
+    return i`redis://default:${this.password}@${this.host}:${this.port}/0`;
+  }
+
+  getServiceDefinition() {
+    return {
+      image: this.image,
+      volumes: [
+        {
+          hostPath: i`./data/${this.host}`,
+          containerPath: "/data",
+          backup: { kind: "valkey-save" as const, url: this.url },
+        },
+      ],
+      command: ["--requirepass", this.password],
+      env: { REDISCLI_AUTH: this.password },
+      healthcheck: {
+        test: ["CMD", "redis-cli", "PING"],
+      },
+    };
+  }
+}