@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/dist/ui.js

@@ -0,0 +1,254 @@
+import "./chunk-MLKGABMK.js";
+
+// src/ui-surface.ts
+function loader(def) {
+  return def;
+}
+function action(def) {
+  return def;
+}
+function page(def) {
+  return def;
+}
+function widget(def) {
+  return def;
+}
+
+// src/ui-error.ts
+var TRANSIENT_UI_ERROR_CODES = /* @__PURE__ */ new Set(["CONTAINER_STARTING"]);
+var UiError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "UiError";
+    this.code = code;
+  }
+};
+function isUiError(value) {
+  return value instanceof UiError;
+}
+function isTransientUiError(err) {
+  return isUiError(err) && TRANSIENT_UI_ERROR_CODES.has(err.code);
+}
+
+// src/ui/index.ts
+var stub = (() => {
+  throw new Error(
+    "@yourrealm/sdk/ui has no runtime in this environment. Render functions are bundled by realm-sdk and execute inside the Home iframe."
+  );
+});
+var h = stub;
+var Fragment = stub;
+var Badge = stub;
+var Button = stub;
+var buttonVariants = stub;
+var Card = stub;
+var CardAction = stub;
+var CardContent = stub;
+var CardDescription = stub;
+var CardFooter = stub;
+var CardHeader = stub;
+var CardTitle = stub;
+var Checkbox = stub;
+var Combobox = stub;
+var EmptyState = stub;
+var Dialog = stub;
+var DialogClose = stub;
+var DialogContent = stub;
+var DialogDescription = stub;
+var DialogFooter = stub;
+var DialogHeader = stub;
+var DialogOverlay = stub;
+var DialogTitle = stub;
+var DialogTrigger = stub;
+var Input = stub;
+var Label = stub;
+var LineChart = stub;
+var AreaChart = stub;
+var Page = stub;
+var PieChart = stub;
+var Separator = stub;
+var Sheet = stub;
+var SheetClose = stub;
+var SheetContent = stub;
+var SheetDescription = stub;
+var SheetFooter = stub;
+var SheetHeader = stub;
+var SheetTitle = stub;
+var SheetTrigger = stub;
+var Skeleton = stub;
+var Switch = stub;
+var Table = stub;
+var TableBody = stub;
+var TableCell = stub;
+var TableHead = stub;
+var TableHeader = stub;
+var TableRow = stub;
+var TablePagination = stub;
+var useTableView = stub;
+var TimeAgo = stub;
+var timeago = stub;
+var Tooltip = stub;
+var TooltipContent = stub;
+var TooltipProvider = stub;
+var TooltipTrigger = stub;
+var ArrowsClockwiseIcon = stub;
+var ArrowSquareOutIcon = stub;
+var CheckBoldIcon = stub;
+var CheckCircleIcon = stub;
+var CheckIcon = stub;
+var ClipboardIcon = stub;
+var ClockIcon = stub;
+var CloudArrowDownIcon = stub;
+var CubeIcon = stub;
+var DownloadSimpleIcon = stub;
+var EnvelopeIcon = stub;
+var EyeIcon = stub;
+var FadersIcon = stub;
+var FolderOpenIcon = stub;
+var FolderSimpleIcon = stub;
+var GearIcon = stub;
+var GiftIcon = stub;
+var GithubLogoIcon = stub;
+var GlobeIcon = stub;
+var GraphicsCardIcon = stub;
+var HandshakeIcon = stub;
+var HardDrivesIcon = stub;
+var HouseIcon = stub;
+var InfoIcon = stub;
+var KeyIcon = stub;
+var LightbulbIcon = stub;
+var ListChecksIcon = stub;
+var LockIcon = stub;
+var MagnifyingGlassIcon = stub;
+var PackageIcon = stub;
+var PlugIcon = stub;
+var PlusIcon = stub;
+var PulseIcon = stub;
+var QuestionIcon = stub;
+var RocketLaunchIcon = stub;
+var ShareNetworkIcon = stub;
+var ShieldIcon = stub;
+var SidebarIcon = stub;
+var SignOutIcon = stub;
+var StackIcon = stub;
+var StarIcon = stub;
+var TerminalWindowIcon = stub;
+var TrashIcon = stub;
+var UserIcon = stub;
+var WarningIcon = stub;
+var WarningOctagonIcon = stub;
+var XBoldIcon = stub;
+var XIcon = stub;
+export {
+  AreaChart,
+  ArrowSquareOutIcon,
+  ArrowsClockwiseIcon,
+  Badge,
+  Button,
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+  CheckBoldIcon,
+  CheckCircleIcon,
+  CheckIcon,
+  Checkbox,
+  ClipboardIcon,
+  ClockIcon,
+  CloudArrowDownIcon,
+  Combobox,
+  CubeIcon,
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogTitle,
+  DialogTrigger,
+  DownloadSimpleIcon,
+  EmptyState,
+  EnvelopeIcon,
+  EyeIcon,
+  FadersIcon,
+  FolderOpenIcon,
+  FolderSimpleIcon,
+  Fragment,
+  GearIcon,
+  GiftIcon,
+  GithubLogoIcon,
+  GlobeIcon,
+  GraphicsCardIcon,
+  HandshakeIcon,
+  HardDrivesIcon,
+  HouseIcon,
+  InfoIcon,
+  Input,
+  KeyIcon,
+  Label,
+  LightbulbIcon,
+  LineChart,
+  ListChecksIcon,
+  LockIcon,
+  MagnifyingGlassIcon,
+  PackageIcon,
+  Page,
+  PieChart,
+  PlugIcon,
+  PlusIcon,
+  PulseIcon,
+  QuestionIcon,
+  RocketLaunchIcon,
+  Separator,
+  ShareNetworkIcon,
+  Sheet,
+  SheetClose,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+  SheetTrigger,
+  ShieldIcon,
+  SidebarIcon,
+  SignOutIcon,
+  Skeleton,
+  StackIcon,
+  StarIcon,
+  Switch,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TablePagination,
+  TableRow,
+  TerminalWindowIcon,
+  TimeAgo,
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+  TrashIcon,
+  UiError,
+  UserIcon,
+  WarningIcon,
+  WarningOctagonIcon,
+  XBoldIcon,
+  XIcon,
+  action,
+  buttonVariants,
+  h,
+  isTransientUiError,
+  isUiError,
+  loader,
+  page,
+  timeago,
+  useTableView,
+  widget
+};

package/dist/worker-protocol.js

@@ -0,0 +1,89 @@
+import {
+  PLATFORM_INGRESS_PORTS,
+  REALM_APP_DIR_GID,
+  REALM_SILO_DIR,
+  dependsOnEdgeSchema,
+  ingressInputSchema,
+  isManagedSiloPath,
+  isPreparedAppDir,
+  managedSiloPath,
+  nodeVersionSchema,
+  readNodeVersion,
+  readUpdateFiles,
+  scopeBindSource,
+  shortNodeVersion,
+  siloReclaimCommand,
+  siloSetupCommand,
+  siloWidenCommand,
+  wireServiceSchema,
+  workerAppSchema,
+  workerStateSchema
+} from "./chunk-67BDAMYX.js";
+import {
+  MANAGEMENT_NET,
+  REALM_HOME_PROXY_CONTAINER_PATH,
+  REALM_HOME_PROXY_DIR,
+  REALM_LOGS_DIR,
+  REALM_LOGS_MOUNT,
+  REALM_LOGS_SOCKET,
+  REALM_SPAWN_DIR,
+  REALM_STATS_DIR,
+  REALM_STATS_MOUNT,
+  REALM_STATS_SOCKET,
+  SILO_NET_PREFIX,
+  UNTRUSTED_NET,
+  homeProxyAppDir,
+  homeProxyMount,
+  homeProxySocketPath,
+  isSiloNetwork,
+  siloNetwork,
+  spawnArtifactsPath,
+  spawnMounts,
+  spawnScratchPath,
+  spawnSocketDir,
+  spawnSocketPath
+} from "./chunk-VHTUSZUX.js";
+import "./chunk-MLKGABMK.js";
+export {
+  MANAGEMENT_NET,
+  PLATFORM_INGRESS_PORTS,
+  REALM_APP_DIR_GID,
+  REALM_HOME_PROXY_CONTAINER_PATH,
+  REALM_HOME_PROXY_DIR,
+  REALM_LOGS_DIR,
+  REALM_LOGS_MOUNT,
+  REALM_LOGS_SOCKET,
+  REALM_SILO_DIR,
+  REALM_SPAWN_DIR,
+  REALM_STATS_DIR,
+  REALM_STATS_MOUNT,
+  REALM_STATS_SOCKET,
+  SILO_NET_PREFIX,
+  UNTRUSTED_NET,
+  dependsOnEdgeSchema,
+  homeProxyAppDir,
+  homeProxyMount,
+  homeProxySocketPath,
+  ingressInputSchema,
+  isManagedSiloPath,
+  isPreparedAppDir,
+  isSiloNetwork,
+  managedSiloPath,
+  nodeVersionSchema,
+  readNodeVersion,
+  readUpdateFiles,
+  scopeBindSource,
+  shortNodeVersion,
+  siloNetwork,
+  siloReclaimCommand,
+  siloSetupCommand,
+  siloWidenCommand,
+  spawnArtifactsPath,
+  spawnMounts,
+  spawnScratchPath,
+  spawnSocketDir,
+  spawnSocketPath,
+  wireServiceSchema,
+  workerAppSchema,
+  workerStateSchema
+};

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@yourrealm/sdk",
+  "version": "0.0.0-alpha.1378.ce03c8dc",
+  "description": "The Realm SDK: createApp, the r.* permission factories, the ui surface, the realm-sdk CLI and test harness.",
+  "license": "AGPL-3.0-only WITH Classpath-exception-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/benjick/holden.git",
+    "directory": "packages/sdk"
+  },
+  "bin": {
+    "realm-sdk": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__snapshots__",
+    "LICENSE-EXCEPTION",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./docker": {
+      "types": "./src/docker.ts",
+      "default": "./dist/docker.js"
+    },
+    "./services": {
+      "types": "./src/services/index.ts",
+      "default": "./dist/services.js"
+    },
+    "./ui": {
+      "types": "./src/ui/index.ts",
+      "default": "./dist/ui.js"
+    },
+    "./preact": {
+      "types": "./src/preact/index.ts",
+      "default": "./dist/preact.js"
+    },
+    "./jsx-runtime": {
+      "types": "./src/jsx-runtime/index.ts",
+      "default": "./dist/jsx-runtime.js"
+    },
+    "./service-url": {
+      "types": "./src/service-url.ts",
+      "default": "./dist/service-url.js"
+    },
+    "./runtime/docker/ingress": {
+      "types": "./src/runtime/docker/ingress/index.ts",
+      "default": "./dist/ingress.js"
+    },
+    "./worker-protocol": {
+      "types": "./src/worker-protocol/index.ts",
+      "default": "./dist/worker-protocol.js"
+    },
+    "./test": {
+      "types": "./src/test/index.ts",
+      "default": "./dist/test.js"
+    },
+    "./ui/tokens.css": "./src/ui/tokens.css"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ark-ui/react": "^5.36.1",
+    "@jitl/quickjs-wasmfile-release-asyncify": "^0.32.0",
+    "@playwright/test": "1.58.0",
+    "@preact/signals": "^2.5.0",
+    "@tailwindcss/cli": "^4.2.2",
+    "@tanstack/react-query": "^5.62.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "esbuild": "^0.27.4",
+    "next-themes": "^0.4.6",
+    "playwright-core": "1.58.0",
+    "preact": "^10.27.2",
+    "preact-render-to-string": "^6.6.7",
+    "quickjs-emscripten-core": "^0.32.0",
+    "react": "npm:@preact/compat@^18.3.2",
+    "react-dom": "npm:@preact/compat@^18.3.2",
+    "react-icons": "^5.5.0",
+    "shiki": "^4.0.2",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.2",
+    "typescript": "^5",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@std/assert": "npm:@jsr/std__assert@^1",
+    "@std/path": "npm:@jsr/std__path@^1",
+    "@std/tar": "npm:@jsr/std__tar@^0.1",
+    "@std/testing": "npm:@jsr/std__testing@^1",
+    "@local/docker": "0.1.0",
+    "@local/logger": "0.1.0",
+    "@yourrealm/noise": "0.1.0"
+  },
+  "scripts": {
+    "typecheck": "deno check",
+    "test": "deno test --allow-all src/ integration/",
+    "test:integration": "deno test --allow-all integration-docker/",
+    "build:npm": "deno run -A build.ts"
+  }
+}

package/src/app-icon.ts

@@ -0,0 +1,74 @@
+// App icons — the tagged string an author writes as `router.icon`, and the
+// one https URL it is fetched from. Pure string logic, no host globals at
+// module load, so it rides both the default entry (authors get the type) and
+// the `@yourrealm/sdk/compile` barrel (Home gets the schema and the resolver).
+
+import { z } from "zod";
+
+/**
+ * A routed service's icon: a key in one of the two icon packs, or an https
+ * URL to an svg/png/webp/jpeg. A bare key is not accepted — the pack is
+ * always named, so the source of every icon is explicit.
+ */
+export type AppIcon =
+  | `dashboard-icons:${string}` // homarr-labs/dashboard-icons
+  | `selfhst:${string}` // selfhst/icons
+  | `https://${string}`;
+
+/** Pack prefix → the GitHub repo jsDelivr serves the svg out of. */
+const PACK_REPOS: Record<string, string> = {
+  "dashboard-icons": "homarr-labs/dashboard-icons",
+  selfhst: "selfhst/icons",
+};
+
+// A pack key is a filename in that repo's `svg/` directory. Lowercase, and
+// no slash, so a key can't walk out of the directory or carry a query.
+const PACK_KEY_RE = /^[a-z0-9][a-z0-9._-]*$/;
+
+// Rejects whitespace and the quoting/markup characters that would let a URL
+// break out of the attribute or JSON it ends up in.
+const URL_UNSAFE_RE = /[\s"'<>\\`]/;
+
+const FORM_MESSAGE = 'icon must be "dashboard-icons:<key>", "selfhst:<key>" or an https:// URL';
+
+/**
+ * The single place a spec is read. Both `iconSourceUrl` and `appIconSchema`
+ * go through it, so what validates and what resolves cannot drift.
+ */
+function parseIcon(spec: string): { url: string } | { error: string } {
+  for (const [prefix, repo] of Object.entries(PACK_REPOS)) {
+    if (!spec.startsWith(`${prefix}:`)) continue;
+    const key = spec.slice(prefix.length + 1);
+    if (!PACK_KEY_RE.test(key)) {
+      return {
+        error: `${prefix} key must be lowercase and match ${PACK_KEY_RE.source}`,
+      };
+    }
+    return { url: `https://cdn.jsdelivr.net/gh/${repo}/svg/${key}.svg` };
+  }
+  if (spec.startsWith("https://")) {
+    const rest = spec.slice("https://".length);
+    if (rest === "") return { error: "https icon URL must have a host" };
+    if (URL_UNSAFE_RE.test(rest))
+      return { error: "https icon URL must not contain whitespace or quotes" };
+    return { url: spec };
+  }
+  return { error: FORM_MESSAGE };
+}
+
+/** The https URL an icon spec is fetched from. Throws on a malformed spec. */
+export function iconSourceUrl(spec: AppIcon): string {
+  const parsed = parseIcon(spec);
+  if ("error" in parsed) throw new Error(parsed.error);
+  return parsed.url;
+}
+
+/**
+ * Runtime guard for the same three forms the `AppIcon` type describes, so a
+ * realm.ts that dodges the type (a cast, a computed string) still fails at
+ * resolve rather than reaching Home's icon cache.
+ */
+export const appIconSchema = z.string().superRefine((spec, ctx) => {
+  const parsed = parseIcon(spec);
+  if ("error" in parsed) ctx.addIssue({ code: "custom", message: parsed.error });
+}) as unknown as z.ZodType<AppIcon>;

package/src/apply.ts

@@ -0,0 +1,52 @@
+import type { Deferred, Ref } from "./ref.ts";
+import { deferredRef } from "./ref.ts";
+
+/**
+ * Recursively swap every `Ref<string>` in `T` for `string`. Applied to
+ * the input of an `apply()` callback so the user sees resolved strings
+ * wherever a sync ref sat in the original value. Deferred refs are
+ * forbidden inside `apply()`'s input by the wire schema, so they don't
+ * appear here.
+ */
+export type Resolved<T> =
+  T extends Ref<string>
+    ? string
+    : T extends string | number | boolean | bigint | null | undefined
+      ? T
+      : T extends readonly (infer U)[]
+        ? readonly Resolved<U>[]
+        : T extends object
+          ? { [K in keyof T]: Resolved<T[K]> }
+          : T;
+
+type DeferredFn = (input: unknown) => string;
+
+function registry(): DeferredFn[] {
+  const g = globalThis as Record<string, unknown>;
+  let fns = g.__realm_deferred_fns as DeferredFn[] | undefined;
+  if (!fns) {
+    fns = [];
+    g.__realm_deferred_fns = fns;
+  }
+  return fns;
+}
+
+/**
+ * Apply `fn` to the resolved version of `input`. The bundle registers
+ * `fn` at registration order and returns a `Deferred<string>` carrying
+ * the id + raw input. The Home walker resolves every sync ref inside
+ * `input`, then re-runs the bundle in a second sandbox call to invoke
+ * `fn` with resolved values and splice the returned string into the
+ * final state.
+ *
+ * The return type `Deferred<string>` is deliberately distinct from
+ * `Ref<string>` — `interpolate` only accepts the latter, so passing an
+ * `apply()` result into a template is a type error. Move affix logic
+ * into the callback instead: `apply(input, s => \`prefix-${s}\`)`.
+ */
+export function apply<T>(input: T, fn: (resolved: Resolved<T>) => string): Deferred<string> {
+  const fns = registry();
+  const id = fns.length;
+  fns.push(fn as DeferredFn);
+  return deferredRef({ kind: "deferred", id, input });
+}