@sanity/workbench 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/core/user-applications/user-application.ts

@@ -0,0 +1,222 @@
+// eslint-disable-next-line no-restricted-imports
+import type { Resource as ProtocolResource } from "@sanity/message-protocol";
+import { z } from "zod";
+
+import {
+  AbstractApplication,
+  type AbstractApplicationType,
+  type LocalInterface,
+  LocalInterfaceSchema,
+} from "../applications/application";
+import { getSanityDomain, getSanityEnv } from "../env";
+import type { CoreAppUserApplicationManifest } from "./core-app";
+import type { ClientManifest, ServerManifest } from "./studios/schemas";
+
+/**
+ * User application ID schema, branded for type safety.
+ * @public
+ */
+export const UserApplicationId = z
+  .string()
+  .nonempty()
+  .brand("UserApplicationId");
+
+/**
+ * User application ID type, branded for type safety.
+ * @public
+ */
+export type UserApplicationId = z.output<typeof UserApplicationId>;
+
+/**
+ * Validates and brands a string as a UserApplicationId.
+ * @public
+ */
+export function brandUserApplicationId(id: string): UserApplicationId {
+  return UserApplicationId.parse(id);
+}
+
+const LocalUserApplicationBase = z.object({
+  host: z.string(),
+  port: z.number(),
+  /**
+   * Interfaces the app exposes — dock panels (`interface_type: "panel"`) and
+   * background workers (`interface_type: "worker"`), forwarded from the dev
+   * server in one list.
+   */
+  interfaces: z.array(LocalInterfaceSchema).optional(),
+  /** The `deployment.appId` from the application's `sanity.cli.ts`, when set. */
+  id: z.string().optional(),
+  /**
+   * The `api.projectId` from the application's `sanity.cli.ts`. Available
+   * synchronously at dev-server startup (no manifest extraction required), so
+   * the studio's primary project is resolvable from the very first local
+   * application event.
+   */
+  projectId: z.string().optional(),
+});
+
+/**
+ * Raw data for a local application discovered by the CLI dev server.
+ *
+ * The CLI forwards the full studio or app manifest so the workbench can
+ * derive icons, titles, workspaces and schema references the same way it
+ * does for deployed applications. The manifest shape is discriminated on
+ * `type`: studios receive a `ClientManifest`, core apps a `CoreAppUserApplicationManifest`.
+ *
+ * When set on a `UserApplication`, `isLocal` is `true` and `url`/`isFederated`
+ * honour the local dev-server instead of the deployed application's host.
+ *
+ * @public
+ */
+export const LocalUserApplication = z.discriminatedUnion("type", [
+  LocalUserApplicationBase.extend({
+    type: z.literal("studio"),
+    manifest: z.custom<ClientManifest>().optional(),
+  }),
+  LocalUserApplicationBase.extend({
+    type: z.literal("coreApp"),
+    manifest: z.custom<CoreAppUserApplicationManifest>().optional(),
+  }),
+]);
+
+/**
+ * @public
+ */
+export type LocalUserApplication = z.output<typeof LocalUserApplication>;
+
+/**
+ * @public
+ */
+export const UserApplicationBase = z.object({
+  id: UserApplicationId,
+  appHost: z.string(),
+  urlType: z.enum(["internal", "external"]),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  dashboardStatus: z.enum(["default", "disabled"]),
+  /**
+   * Interfaces the app exposes (dock panels and background workers). Not part
+   * of the manifest.
+   */
+  interfaces: z.array(LocalInterfaceSchema).optional(),
+});
+
+/**
+ * @public
+ */
+export type UserApplicationBase = z.output<typeof UserApplicationBase>;
+
+/**
+ * @public
+ */
+export const ActiveDeployment = z.object({
+  id: z.string(),
+  version: z.string(),
+  isActiveDeployment: z.boolean(),
+  userApplicationId: z.string(),
+  isAutoUpdating: z.boolean().nullable(),
+  size: z.number().nullable(),
+  deployedAt: z.string(),
+  deployedBy: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+/**
+ * @public
+ */
+export abstract class UserApplication<
+  TUserApplication extends UserApplicationBase,
+  TType extends Extract<AbstractApplicationType, "coreApp" | "studio">,
+  TProtocolResource extends ProtocolResource = Extract<
+    ProtocolResource,
+    { type: TType }
+  >,
+> extends AbstractApplication<TType, TProtocolResource> {
+  readonly application: TUserApplication;
+
+  readonly id: UserApplicationId;
+
+  /**
+   * For local applications (`isLocal === true`), the deployed application
+   * that shares the same `id` — if one was passed at construction. `null`
+   * for deployed applications or when no remote twin was provided.
+   */
+  readonly remoteApplication: this | null;
+
+  readonly #isLocal: boolean;
+
+  constructor(
+    application: TUserApplication,
+    type: TType,
+    options: {
+      isLocal?: boolean;
+      remoteApplication?: UserApplication<
+        TUserApplication,
+        TType,
+        TProtocolResource
+      > | null;
+    } = {},
+  ) {
+    super(type);
+    this.application = application;
+    this.id = brandUserApplicationId(application.id);
+    this.#isLocal = options.isLocal ?? false;
+    this.remoteApplication =
+      (options.remoteApplication as this | undefined) ?? null;
+  }
+
+  abstract get subtitle(): string | undefined;
+
+  /**
+   * Local dev servers are rendered as federated remotes; deployed applications
+   * are rendered in an iframe.
+   */
+  get isFederated(): boolean {
+    return this.isLocal;
+  }
+
+  override get isLocal(): boolean {
+    return this.#isLocal;
+  }
+
+  override get interfaces(): readonly LocalInterface[] {
+    return this.application.interfaces ?? [];
+  }
+
+  /**
+   * @returns A fully resolved URL instance for the application.
+   * For internal applications, constructs a URL using the Sanity studio domain
+   * pattern resolved from the environment at the consuming app's build time.
+   * For external applications (including local dev servers), returns the
+   * provided app host as a URL.
+   */
+  get url(): URL {
+    if (this.application.urlType === "internal") {
+      if (getSanityEnv() === "production") {
+        return new URL(`https://${this.application.appHost}.sanity.studio`);
+      }
+      return new URL(
+        `https://${this.application.appHost}.studio.${getSanityDomain()}`,
+      );
+    }
+
+    return new URL(this.application.appHost);
+  }
+
+  /**
+   * Unified manifest accessor for user applications. Resolves the most
+   * authoritative manifest available for the application, preferring the
+   * deployment manifest (`activeDeployment.manifest`) before falling back to
+   * any client-side manifest. The returned shape depends on the application
+   * type and source: studios may yield either a `ServerManifest` (deployment)
+   * or a `ClientManifest` (fallback); core apps yield a
+   * `CoreAppUserApplicationManifest`. Returns `null` when no manifest is
+   * available.
+   */
+  abstract get manifest():
+    | ClientManifest
+    | ServerManifest
+    | CoreAppUserApplicationManifest
+    | null;
+}

package/src/system/auth.machine.ts

@@ -0,0 +1,223 @@
+import {
+  type AuthState,
+  AuthStateType,
+  type CurrentUser,
+  getAuthState,
+  type LoggedInAuthState,
+  logout,
+  type SanityInstance,
+} from "@sanity/sdk";
+import { assign, fromObservable, fromPromise, setup } from "xstate";
+
+import type { OSBaseInput } from "./root.machine";
+
+/**
+ * @internal
+ */
+export interface AuthInput extends OSBaseInput {}
+
+const authStateLogic = fromObservable<AuthState, AuthInput>(
+  ({ input }) => getAuthState(input.instance).observable,
+);
+
+/**
+ * @internal
+ */
+export interface LogoutInput extends OSBaseInput {}
+
+const logoutActorLogic = fromPromise<void, LogoutInput>(async ({ input }) => {
+  await logout(input.instance);
+});
+
+type AuthContext = {
+  instance: SanityInstance;
+  token: string | null;
+  currentUser: CurrentUser | null;
+  error: unknown;
+};
+
+type AuthEvent = { type: "auth.logout" };
+
+export const authLogic = setup({
+  types: {
+    input: {} as AuthInput,
+    context: {} as AuthContext,
+    events: {} as AuthEvent,
+    tags: {} as "authenticating" | "authenticated" | "error",
+  },
+  actors: {
+    authState: authStateLogic,
+    logoutActor: logoutActorLogic,
+  },
+  delays: {
+    authTimeout: 30_000,
+  },
+  guards: {
+    isLoggedInComplete: (_, params: { state: AuthState | undefined }) =>
+      params.state?.type === AuthStateType.LOGGED_IN &&
+      Boolean((params.state as LoggedInAuthState).token) &&
+      (params.state as LoggedInAuthState).currentUser !== null,
+    isAuthState: (
+      _,
+      params: { state: AuthState | undefined; type: AuthStateType },
+    ) => params.state?.type === params.type,
+  },
+  actions: {
+    setLoggedIn: assign({
+      token: (_, params: { token: string; currentUser: CurrentUser }) =>
+        params.token,
+      currentUser: (_, params: { token: string; currentUser: CurrentUser }) =>
+        params.currentUser,
+      error: () => null,
+    }),
+    clearAuth: assign({
+      token: () => null,
+      currentUser: () => null,
+      error: () => null,
+    }),
+    setError: assign({
+      token: () => null,
+      currentUser: () => null,
+      error: (_, params: { error: unknown }) => params.error,
+    }),
+  },
+}).createMachine({
+  id: "auth",
+  initial: "init",
+  context: ({ input }) => ({
+    instance: input.instance,
+    token: null,
+    currentUser: null,
+    error: null,
+  }),
+  invoke: {
+    src: "authState",
+    input: ({ context }) => ({ instance: context.instance }),
+    onSnapshot: [
+      {
+        guard: {
+          type: "isLoggedInComplete",
+          params: ({ event }) => ({
+            state: event.snapshot.context,
+          }),
+        },
+        actions: [
+          {
+            type: "setLoggedIn",
+            params: ({ event }) => {
+              const state = event.snapshot.context as LoggedInAuthState;
+              return {
+                token: state.token,
+                currentUser: state.currentUser!,
+              };
+            },
+          },
+        ],
+        target: `.${AuthStateType.LOGGED_IN}`,
+      },
+      {
+        guard: {
+          type: "isAuthState",
+          params: ({ event }) => ({
+            state: event.snapshot.context,
+            type: AuthStateType.LOGGING_IN,
+          }),
+        },
+        actions: [{ type: "clearAuth" }],
+        target: `.${AuthStateType.LOGGING_IN}`,
+      },
+      {
+        guard: {
+          type: "isAuthState",
+          params: ({ event }) => ({
+            state: event.snapshot.context,
+            type: AuthStateType.ERROR,
+          }),
+        },
+        actions: [
+          {
+            type: "setError",
+            params: ({ event }) => ({
+              error:
+                event.snapshot.context?.type === AuthStateType.ERROR
+                  ? event.snapshot.context.error
+                  : null,
+            }),
+          },
+        ],
+        target: `.${AuthStateType.ERROR}`,
+      },
+      {
+        guard: {
+          type: "isAuthState",
+          params: ({ event }) => ({
+            state: event.snapshot.context,
+            type: AuthStateType.LOGGED_OUT,
+          }),
+        },
+        actions: [{ type: "clearAuth" }],
+        target: `.${AuthStateType.LOGGED_OUT}`,
+      },
+    ],
+  },
+  states: {
+    init: {
+      tags: ["authenticating"],
+      after: {
+        authTimeout: {
+          actions: [
+            {
+              type: "setError",
+              params: () => ({
+                error: new Error("Authentication timed out"),
+              }),
+            },
+          ],
+          target: AuthStateType.ERROR,
+        },
+      },
+    },
+    [AuthStateType.LOGGING_IN]: {
+      tags: ["authenticating"],
+      after: {
+        authTimeout: {
+          actions: [
+            {
+              type: "setError",
+              params: () => ({
+                error: new Error("Authentication timed out"),
+              }),
+            },
+          ],
+          target: AuthStateType.ERROR,
+        },
+      },
+    },
+    [AuthStateType.LOGGED_IN]: {
+      tags: ["authenticated"],
+      on: {
+        "auth.logout": { target: "logging-out" },
+      },
+    },
+    ["logging-out"]: {
+      invoke: {
+        src: "logoutActor",
+        input: ({ context }) => ({ instance: context.instance }),
+        onDone: {
+          target: AuthStateType.LOGGED_OUT,
+        },
+        onError: {
+          actions: [
+            {
+              type: "setError",
+              params: ({ event }) => ({ error: event.error }),
+            },
+          ],
+          target: AuthStateType.ERROR,
+        },
+      },
+    },
+    [AuthStateType.LOGGED_OUT]: {},
+    [AuthStateType.ERROR]: { tags: ["error"] },
+  },
+});

package/src/system/index.ts

@@ -0,0 +1,22 @@
+export type { AuthInput, LogoutInput } from "./auth.machine";
+export { ModuleShapeError } from "./remote.machine";
+export type {
+  LoadedRemoteModule,
+  RemoteError,
+  RemoteInput,
+  RemoteModuleByInterfaceType,
+  RemoteRenderOptions,
+  ServiceLoaderModule,
+} from "./remote.machine";
+export type {
+  SystemPreferencesAdapter,
+  SystemPreferencesContext,
+  SystemPreferencesEvent,
+} from "./system-preferences.machine";
+export { loadFederatedModule } from "./load-federated-module";
+export type { FederatedModuleRef } from "./load-federated-module";
+export { os, createOSOptions } from "./root.machine";
+export type {
+  TelemetryInput,
+  WorkbenchUserProperties,
+} from "./telemetry.machine";

package/src/system/inspect.ts

@@ -0,0 +1,40 @@
+import { type ActorRefLike, type InspectionEvent } from "xstate";
+
+import { logger } from "../core";
+
+// Mirrors @statelyai/inspect's ActorRefLikeWithData — the inspect
+// callback receives full Actor instances at runtime, but the type is
+// narrowed for @xstate/store compat.
+type ActorRefWithAncestry = ActorRefLike & {
+  id?: string;
+  _parent?: ActorRefWithAncestry;
+};
+
+const actorPath = (ref: ActorRefWithAncestry): string => {
+  const segments: string[] = [];
+  let current: ActorRefWithAncestry | undefined = ref;
+  while (current) {
+    segments.unshift(current.id ?? current.sessionId);
+    current = current._parent;
+  }
+  return segments.join(":");
+};
+
+/** @internal exported for testing */
+export const inspect = (event: InspectionEvent): void => {
+  const ref = event.actorRef as ActorRefWithAncestry;
+  const log = logger.child(actorPath(ref));
+
+  switch (event.type) {
+    case "@xstate.snapshot": {
+      log.debug("snapshot", event.snapshot);
+      break;
+    }
+    case "@xstate.event":
+      log.debug("event", event.event);
+      break;
+    case "@xstate.action":
+      log.debug("action", event.action);
+      break;
+  }
+};

package/src/system/load-federated-module.ts

@@ -0,0 +1,53 @@
+import { logger } from "../core/log";
+import type { FederationInstance } from "./module-federation";
+
+/**
+ * A module exposed by an application's federation remote.
+ *
+ * @public
+ */
+export interface FederatedModuleRef {
+  /**
+   * Fully-qualified module id — `${appId}/${expose}`, e.g.
+   * `studio-1/views/feed/panel` (a view component) or `studio-1/App` (the
+   * full-page view). The remote's name is its first segment.
+   */
+  moduleId: string;
+  /** The remote's `mf-manifest.json` URL (served from the app's origin). */
+  entry: string;
+}
+
+/**
+ * Register an app's federation remote (idempotent) and load one of its exposes
+ * by its fully-qualified `moduleId`. Failures propagate, so the caller drives
+ * its own error handling (e.g. a machine's error state with the original
+ * cause). For the render-empty-on-failure policy, use {@link loadFederatedModule}.
+ */
+export async function loadRemoteModule<T>(
+  instance: FederationInstance,
+  { moduleId, entry }: FederatedModuleRef,
+): Promise<T | null> {
+  // The remote name is the first segment; the expose is the remainder.
+  const name = moduleId.slice(0, moduleId.indexOf("/"));
+  instance.registerRemotes([{ name, entry }]);
+  return (await instance.loadRemote<T | null>(moduleId)) ?? null;
+}
+
+/**
+ * {@link loadRemoteModule} with the render-empty-on-failure policy: any failure
+ * resolves to `null` (and logs), so every caller handles a missing interface
+ * the same way — a panel renders empty, a worker doesn't spawn.
+ *
+ * @public
+ */
+export async function loadFederatedModule<T>(
+  instance: FederationInstance,
+  ref: FederatedModuleRef,
+): Promise<T | null> {
+  try {
+    return await loadRemoteModule<T>(instance, ref);
+  } catch (error) {
+    logger.error(`Failed to load federated module "${ref.moduleId}"`, error);
+    return null;
+  }
+}

package/src/system/module-federation.ts

@@ -0,0 +1,116 @@
+import { createInstance as createMFInstance } from "@module-federation/runtime";
+import type {
+  ModuleFederationRuntimePlugin,
+  UserOptions,
+} from "@module-federation/runtime/types";
+
+/** Make some properties of a type optional. */
+type MakeOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+/**
+ * @public
+ */
+export type FederationRemote = {
+  name: string;
+  entry: string;
+};
+
+/**
+ * @public
+ */
+export type CreateInstanceOptions = MakeOptional<
+  Pick<UserOptions, "name" | "remotes" | "shared" | "plugins">,
+  "remotes" | "plugins"
+>;
+
+/**
+ * @public
+ */
+export interface FederationInstance {
+  registerRemotes(remotes: FederationRemote[]): void;
+  loadRemote<T>(id: string): Promise<T | null>;
+}
+
+/**
+ * @public
+ */
+export function createInstance(
+  options: CreateInstanceOptions,
+): FederationInstance {
+  const instance = createMFInstance({
+    remotes: [],
+    ...options,
+  });
+
+  return {
+    registerRemotes: (remotes) =>
+      instance.registerRemotes(remotes, { force: false }),
+    loadRemote: async <T>(id: string) => {
+      let remoteModule: T | null;
+
+      try {
+        remoteModule = await instance.loadRemote<T>(id);
+      } catch (error) {
+        throw new Error(`Failed to load remote module "${id}"`, {
+          cause: error,
+        });
+      }
+
+      return remoteModule;
+    },
+  };
+}
+
+/**
+ * Forward Module Federation lifecycle events to a provided logging function
+ * from workbench.
+ *
+ * @public
+ */
+export function log(
+  onDebug: (message: string, context?: Record<string, unknown>) => void,
+): ModuleFederationRuntimePlugin {
+  const logEvent = (eventName: string, args: unknown) => {
+    // `origin` logs the whole instance, which is noisy
+    const { origin: _origin, ...data } =
+      typeof args === "object" && args !== null
+        ? (args as Record<string, unknown>)
+        : { args };
+
+    onDebug(`[Lifecycle] ${eventName}`, data);
+  };
+
+  return {
+    name: "sanity-logger",
+    beforeInit(args) {
+      logEvent("beforeInit", args);
+      return args;
+    },
+    beforeRegisterRemote(args) {
+      logEvent("beforeRegisterRemote", args);
+      return args;
+    },
+    beforePreloadRemote(args) {
+      logEvent("beforePreloadRemote", args);
+    },
+    beforeRequest(args) {
+      logEvent("beforeRequest", args);
+      return args;
+    },
+    afterResolve(args) {
+      logEvent("afterResolve", args);
+      return args;
+    },
+    onLoad(args) {
+      logEvent("onLoad", args);
+      return args;
+    },
+    loadShare(args) {
+      logEvent("loadShare", args);
+    },
+    beforeLoadShare(args) {
+      logEvent("beforeLoadShare", args);
+      return args;
+    },
+  };
+}