@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/ui/install/adapter.ts

@@ -0,0 +1,193 @@
+// Transport contract between the install panel and whoever's hosting it. Home
+// wraps `fetch` to its own /api/apps endpoints; `realm-sdk dev` supplies one
+// over its local dev server, and any future operator surface (Realm Cloud
+// admin, a CLI confirm step) can do the same.
+//
+// The panel does no HTTP itself — it only knows the adapter shape. Adapter
+// methods either resolve with a parsed payload or throw an
+// `InstallAdapterError` carrying a render-ready `InstallErrorShape`. Anything
+// else thrown is surfaced as a network error by the panel.
+
+import type { Grants, Violation } from "../../home.ts";
+import type { ConfigFieldTree, SerializablePermission } from "../../sandbox.ts";
+
+// ---- Deploy targets ------------------------------------------------
+
+/**
+ * One worker's id — the box a single app is pinned to. A system app
+ * has no deploy target to carry: it runs on every compatible worker by
+ * virtue of being one, so the host derives that from the source and the
+ * panel sends nothing.
+ */
+export type DeployTargets = string;
+
+// ---- Render-ready error shape ---------------------------------------
+
+export type InstallErrorShape =
+  | { kind: "violations"; violations: Violation[] }
+  | { kind: "message"; message: string }
+  | { kind: "network"; message: string };
+
+// ---- Preview + install payloads ------------------------------------
+
+/**
+ * Image posture row from the preview endpoint. `digest === null`
+ * means Home hasn't pinned this ref yet — preview is cache-only,
+ * so a brand-new ref shows as unpinned until install commits.
+ */
+export interface PreviewImage {
+  ref: string;
+  digest: string | null;
+  runsAs: string | null;
+  runsAsRoot: boolean;
+  exposes: string[];
+  volumes: string[];
+  imageCreatedAt: string | null;
+}
+
+export interface PreviewResult {
+  permissionsFlat: Record<string, SerializablePermission>;
+  configFields: ConfigFieldTree;
+  images: PreviewImage[] | null;
+  /**
+   * True when the app's resolved services declare any persistent (bind-mount)
+   * volume. Drives the "Install as template" explainer's note that apps created
+   * from a template won't keep volumes (Home strips them for preview rows). NOT
+   * the same as a `PreviewImage.volumes` (image-VOLUME) posture.
+   */
+  hasPersistentVolumes: boolean;
+  /**
+   * App kind. "single" means the app runs on one selected worker
+   * (install panel shows a single-pick). "system" means the app fans
+   * out across every compatible worker (static caption, no picker).
+   * See realm-ts/workers.mdx.
+   */
+  kind: "single" | "system";
+  /**
+   * Existing fixture values, if the host has them. `realm-sdk dev`
+   * surfaces these from `realm-sdk.dev.ts` so the panel pre-fills the
+   * form with the last install's choices, turning the install flow into
+   * an edit-and-resave flow on second visit. Home never sets these — its
+   * preview reflects "fresh install only".
+   */
+  currentConfig?: Record<string, unknown>;
+  currentGrants?: Grants;
+}
+
+export interface InstallPayload {
+  source: string;
+  /**
+   * The single app's chosen worker. Omitted for a system app — placement
+   * is derived from the source's kind, not submitted.
+   */
+  deployed?: DeployTargets;
+  config: Record<string, unknown>;
+  grants: Grants;
+  /**
+   * Upstream registry id when the source came from a known store listing
+   * (e.g. "realm/counter-fresh"). Lets the host correlate installs with
+   * their upstream entry. Absent for hand-pasted source.
+   */
+  sourceId?: string;
+  /**
+   * Install as a parked template instead of a persistent app. A template
+   * never deploys; a `builder`-scoped app (e.g. Forge) stamps
+   * `preview` children from it. Set by the panel's "Install as template"
+   * button; the deploy target the operator picks still applies, since
+   * previews inherit the template's `deployed`.
+   */
+  role?: "template";
+}
+
+// ---- Silos ----------------------------------------------------------
+
+/**
+ * A Silo row as the picker renders it. `hostPath` is always shown: it's the
+ * one field that says which bytes an operator is about to hand an app.
+ */
+export interface SiloOption {
+  id: string;
+  name: string;
+  workerId: string;
+  /** The worker's slug, for the surfaces that name the box to the operator. */
+  workerSlug: string;
+  hostPath: string;
+  containerPath: string;
+  gid: number;
+  /**
+   * The command that hands an adopted directory to this Silo's group, or null
+   * when there's nothing left to run - a Realm-managed directory (the worker
+   * prepares those) or one the operator already confirmed. Non-null means the
+   * Silo is pickable but may not be readable yet, which is what the card warns
+   * about. Computed by the host, never by the picker: an operator who follows a
+   * stale command gets a Silo that looks ready and shares nothing.
+   */
+  setupCommand: string | null;
+  /**
+   * Published service directory (name → port). Absent = unknown - the picker
+   * keeps the Silo pickable and the server's install gate stays
+   * authoritative; `{}` = genuinely memberless. Drives the require-map
+   * filtering (a Silo missing a required service renders unpickable).
+   */
+  offered?: Record<string, number>;
+}
+
+// ---- Adapter contract ----------------------------------------------
+
+export interface InstallAdapter {
+  /** Parse + schema-extract the realm.ts source. */
+  preview(source: string): Promise<PreviewResult>;
+  /** Persist the candidate app + grants. Resolves with the new app's id. */
+  install(payload: InstallPayload): Promise<{ id: string }>;
+  /**
+   * Every Silo the host knows. Fetched only when the app declares a
+   * `host.silo` permission; the picker filters to the chosen worker.
+   *
+   * Optional, and its absence is the answer to "does this host do Silos at
+   * all": a Silo is a Home record on a named worker, and `realm-sdk dev` has
+   * neither. A host that omits this gets no picker and no Silo install gate,
+   * rather than a picker stuck asking for a worker it will never offer.
+   */
+  listSilos?(): Promise<SiloOption[]>;
+  /**
+   * Create one from inside the picker. The worker comes from the deploy
+   * target the operator already picked, so it isn't asked for twice.
+   *
+   * Separately optional from `listSilos`: a host could serve a fixed set it
+   * doesn't let you add to. The picker keeps its create card out when this is
+   * absent.
+   */
+  createSilo?(input: {
+    name: string;
+    workerId: string;
+    containerPath?: string;
+    /** A directory the operator already has. Omitted = Realm makes one. */
+    hostPath?: string;
+  }): Promise<SiloOption>;
+  /**
+   * Record that the operator ran an adopted Silo's setup command, so the
+   * warning on its card retires without a trip to the Silos page.
+   *
+   * Separately optional again: a host that lists Silos it doesn't let you adopt
+   * into never needs it, and the card falls back to the warning alone.
+   */
+  acknowledgeSilo?(id: string): Promise<void>;
+  /**
+   * Called after `install` resolves, with the new app's id. The side-effect
+   * lives outside the call so the adapter owns the navigation. Home lands on
+   * the app's summary page; dev mode would mount the app's own UI in place.
+   */
+  onInstalled(appId: string): void;
+}
+
+/**
+ * Adapter-side failure carrying a parsed InstallErrorShape. The
+ * panel catches this to render the structured error. Anything else
+ * thrown from an adapter method is treated as a network error.
+ */
+export class InstallAdapterError extends Error {
+  constructor(public readonly shape: InstallErrorShape) {
+    super(shape.kind === "violations" ? "grant violations" : shape.message);
+    this.name = "InstallAdapterError";
+  }
+}

package/src/ui/install/deploy-targets-picker.tsx

@@ -0,0 +1,185 @@
+import { useSignal } from "@preact/signals";
+import { CaretDownIcon } from "../components/icons.tsx";
+import { Label } from "../components/label.tsx";
+import type { HostPermissionKind, WorkerCapability } from "../../home.ts";
+import type { DeployTargets } from "./adapter.ts";
+
+export type { DeployTargets };
+
+interface Worker {
+  id: string;
+  slug: string;
+  name: string | null;
+  capabilities?: WorkerCapability[];
+}
+
+interface DeployTargetsPickerProps {
+  workers: Worker[];
+  /**
+   * Current selection: one worker's id (single apps). `null` is
+   * "nothing picked" — the picker emits it for a single app with no
+   * choice made yet, and it's the standing value for a system app,
+   * which shows a static caption instead of a list.
+   */
+  value: DeployTargets | null;
+  onChange: (v: DeployTargets | null) => void;
+  disabled?: boolean;
+  /**
+   * App kind from the `createApp` / `createSystemApp` factory. "single"
+   * renders a radio list of workers; "system" renders a caption (no
+   * choice).
+   */
+  kind: "single" | "system";
+  /**
+   * Required host kinds the candidate app declares. Workers that don't
+   * advertise every kind are disabled in the picker. The server-side
+   * gate is the authoritative source — this is just a hint.
+   */
+  requiredKinds?: HostPermissionKind[];
+  /**
+   * Collapse to a one-line "deploys to X · Change" row once a worker is
+   * selected. The install panel sets this: the common case is one capable
+   * worker, already pre-selected, and a radio list of one is noise. With
+   * nothing selected — no workers, or none that satisfy `requiredKinds` —
+   * the list renders expanded regardless, because *why* there's no
+   * selection is the thing the operator needs to see.
+   */
+  collapsible?: boolean;
+}
+
+export function DeployTargetsPicker({
+  workers,
+  value,
+  onChange,
+  disabled,
+  kind,
+  requiredKinds,
+  collapsible,
+}: DeployTargetsPickerProps) {
+  const expanded = useSignal(false);
+  function missingFor(w: Worker): HostPermissionKind[] {
+    if (!requiredKinds || requiredKinds.length === 0) return [];
+    const caps = new Set(w.capabilities ?? []);
+    return requiredKinds.filter((k) => !caps.has(k));
+  }
+  const supportedCount = workers.filter((w) => missingFor(w).length === 0).length;
+  const showSupportHint =
+    !!requiredKinds && requiredKinds.length > 0 && supportedCount < workers.length;
+
+  if (kind === "system") {
+    return (
+      <div class="flex flex-col gap-3 rounded-2xl border border-border bg-card p-4">
+        <div class="flex flex-col gap-0.5">
+          <span class="text-sm font-bold text-foreground">Deploys to every worker</span>
+          <span class="text-xs text-muted-foreground">
+            Every current and future compatible worker runs this app.
+          </span>
+          {showSupportHint && (
+            <span class="text-xs text-muted-foreground">
+              Currently {supportedCount} of {workers.length} workers (others lack required
+              capabilities).
+            </span>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  const selected = typeof value === "string" ? value : null;
+  const pick = (workerId: string) => {
+    onChange(workerId);
+    // Picking is the whole point of expanding; fold back up so the step
+    // reads as one settled line again.
+    if (collapsible) expanded.value = false;
+  };
+
+  // The collapsed line is a toggle, not a "Change" shortcut that only appears
+  // when there's something to change: opening it on a one-worker Realm and
+  // seeing the single radio already ticked is the answer to "what did it pick
+  // for me, and did I have a say?". Hiding the control there leaves that
+  // unanswerable.
+  if (collapsible && selected !== null && !expanded.value) {
+    const w = workers.find((x) => x.id === selected);
+    return (
+      <button
+        type="button"
+        disabled={disabled}
+        onClick={() => (expanded.value = true)}
+        class="flex w-fit items-center gap-2 text-xs text-muted-foreground hover:text-foreground cursor-pointer disabled:cursor-not-allowed"
+        data-testid="deploy-target-collapsed"
+      >
+        <span>Deploys to</span>
+        <span class="font-mono font-semibold text-foreground">
+          {w?.name ?? w?.slug ?? selected}
+        </span>
+        {w?.name && <span class="font-mono">{w.slug}</span>}
+        <CaretDownIcon className="size-3" />
+      </button>
+    );
+  }
+
+  // Collapsing back needs its own affordance: re-clicking an already-checked
+  // radio fires no change event, so on a one-worker Realm the pick can't do it.
+  const canCollapse = collapsible && selected !== null;
+
+  return (
+    <div class="flex flex-col gap-3 rounded-2xl border border-border bg-card p-4">
+      <div class="flex flex-col gap-2">
+        {canCollapse ? (
+          <button
+            type="button"
+            onClick={() => (expanded.value = false)}
+            class="flex w-fit items-center gap-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground hover:text-foreground cursor-pointer"
+            data-testid="deploy-target-collapse"
+          >
+            Pick a worker
+            <CaretDownIcon className="size-3 rotate-180" />
+          </button>
+        ) : (
+          <span class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+            Pick a worker
+          </span>
+        )}
+        {workers.length === 0 ? (
+          <p class="text-xs text-muted-foreground">
+            No workers enrolled yet. Enroll one on the Workers page.
+          </p>
+        ) : (
+          workers.map((w) => {
+            const id = `target-${w.slug}`;
+            const missing = missingFor(w);
+            const unsupported = missing.length > 0;
+            const checked = selected === w.id;
+            return (
+              <div key={w.id} class="flex items-start gap-2">
+                <input
+                  type="radio"
+                  id={id}
+                  name="deploy-target-single"
+                  checked={checked}
+                  disabled={disabled || unsupported}
+                  onChange={(e) => {
+                    if ((e.target as HTMLInputElement).checked) pick(w.id);
+                  }}
+                  class="mt-1 cursor-pointer disabled:cursor-not-allowed"
+                />
+                <Label
+                  htmlFor={id}
+                  className={`text-sm font-normal ${unsupported ? "opacity-60" : ""}`}
+                >
+                  <span class="font-mono font-semibold">{w.slug}</span>
+                  {w.name && <span class="ml-2 text-muted-foreground">{w.name}</span>}
+                  {unsupported && (
+                    <span class="block text-xs text-muted-foreground">
+                      Missing: <span class="font-mono">{missing.join(", ")}</span>
+                    </span>
+                  )}
+                </Label>
+              </div>
+            );
+          })
+        )}
+      </div>
+    </div>
+  );
+}