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

package/src/core/user-applications/studios/studio.ts

@@ -0,0 +1,533 @@
+import type { SemVer } from "semver";
+import { coerce, gt, gte, lt, rsort, valid } from "semver";
+import { z } from "zod";
+
+import type { Project } from "../../projects";
+import { UserApplication } from "../user-application";
+import {
+  type ClientManifest as ClientManifestType,
+  type ServerManifest as ServerManifestType,
+  type Workspace,
+  type StudioUserApplication,
+  ClientManifest as ClientManifestSchema,
+  ServerManifest as ServerManifestSchema,
+} from "./schemas";
+import { StudioWorkspace } from "./workspace";
+
+/**
+ * Validated manifest — accepts either a refined client manifest (with
+ * version ≥ 2 and `studioVersion` set for v3+) or a server/deployment
+ * manifest. Parsing fails when the input matches neither shape.
+ */
+const Manifest = z.union([
+  ClientManifestSchema.superRefine((data, ctx) => {
+    if (!data.version) {
+      ctx.addIssue({
+        code: "invalid_type",
+        message: "Manifest version is too old",
+        expected: "number",
+      });
+    }
+
+    if (data.version < 2) {
+      ctx.addIssue({
+        code: "invalid_value",
+        message: "Manifest version is too old",
+        values: [2, 3],
+      });
+    }
+
+    if (data.version >= 3 && !data.studioVersion) {
+      ctx.addIssue({
+        code: "invalid_type",
+        message: "Manifest version 3 or higher requires a `studioVersion`",
+        expected: "string",
+      });
+    }
+  }),
+  ServerManifestSchema,
+]);
+
+const DEFAULT_WORKSPACE_DATA = {
+  name: "default",
+  title: "Default",
+  basePath: "/",
+} as const satisfies Omit<Workspace, "projectId">;
+
+/**
+ * @public
+ */
+export class StudioApplication extends UserApplication<
+  StudioUserApplication,
+  "studio",
+  never
+> {
+  /**
+   * Returns a list of studio workspaces based on the application manifest.
+   * If there is no manifest, or alternatively it is not valid, then we create a default workspace.
+   */
+  readonly workspaces: readonly StudioWorkspace[] = [];
+
+  readonly project: Project<false, false>;
+
+  /**
+   * The projects actually referenced by this studio — the application's own
+   * project plus any project used by a workspace. Preserved so the instance
+   * can be re-constructed (e.g. by dock wrappers) without having to thread
+   * the full organization project list through again.
+   */
+  readonly projects: Project<false, false>[];
+
+  /**
+   * @param application - The studio application to create a list of workspaces for
+   * @param projects - The projects available in the organization. It's not enough to just pass
+   * the project that associates with the application because that is the project the app is deployed in relation to.
+   * The workspaces may have different projects completely.
+   */
+  constructor(
+    application: StudioUserApplication,
+    projects: Project<false, false>[],
+    options: {
+      isLocal?: boolean;
+      remoteApplication?: StudioApplication | null;
+    } = {},
+  ) {
+    super(application, "studio", options);
+
+    /**
+     * Derive workspaces from the application's most authoritative manifest.
+     * `this.manifest` already prefers the deployment manifest over the
+     * client manifest; the `Manifest` schema accepts either shape and
+     * rejects malformed ones (e.g. a v3 client manifest missing
+     * `studioVersion`). A parse failure logs a warning and falls through
+     * to the default-workspace path rather than crashing.
+     */
+    let workspaces: Workspace[] = [];
+    const manifest = this.manifest;
+    if (manifest) {
+      try {
+        workspaces = Manifest.parse(manifest).workspaces ?? [];
+      } catch (error) {
+        console.warn(
+          `Failed to parse manifest for application ${application.id}`,
+          error,
+        );
+      }
+    }
+
+    /**
+     * Filter all the workspaces that have a project the user does not have access to.
+     */
+    const workspacesWithProjectsMap = workspaces.reduce((acc, workspace) => {
+      const project = projects.find((p) => p.id === workspace.projectId);
+
+      if (project) {
+        acc.set(workspace, project);
+      } else {
+        console.warn(
+          `Project not found for application ${application.id} and workspace ${workspace.name}. This workspace has been omitted.`,
+        );
+      }
+
+      return acc;
+    }, new Map<Workspace, Project<false, false>>());
+
+    const project = projects.find((p) => p.id === application.projectId);
+
+    if (!project) {
+      throw new Error(`Project not found for application ${application.id}`);
+    }
+
+    if (workspacesWithProjectsMap.size === 0) {
+      /**
+       * If there are still no workspaces, we create a default workspace.
+       */
+      workspacesWithProjectsMap.set(
+        {
+          ...DEFAULT_WORKSPACE_DATA,
+          projectId: application.projectId,
+        } satisfies Workspace,
+        project,
+      );
+    }
+
+    this.workspaces = Object.freeze(
+      Array.from(workspacesWithProjectsMap.entries()).map(([workspace, p]) => {
+        /**
+         * A workspace is considered the default if the dashboard generated it OR because
+         * the properties match that of the default workspace generated by the studio.
+         * Which is why these values will match because dashboard generates an identical
+         * workspace to the default studio one.
+         */
+        const isDefaultWorkspace =
+          workspace.name === DEFAULT_WORKSPACE_DATA.name &&
+          workspace.basePath === DEFAULT_WORKSPACE_DATA.basePath &&
+          workspace.title === DEFAULT_WORKSPACE_DATA.title;
+
+        return this.createWorkspace(workspace, p, isDefaultWorkspace);
+      }),
+    );
+
+    this.project = project;
+
+    // Collect only the projects actually referenced by this studio — the
+    // application's own project plus any project used by a workspace.
+    const usedProjects = new Set<Project<false, false>>([project]);
+    for (const workspace of this.workspaces) {
+      usedProjects.add(workspace.project);
+    }
+    this.projects = Array.from(usedProjects);
+  }
+
+  /**
+   * Factory hook called for each workspace during construction. Subclasses
+   * override this to substitute a `StudioWorkspace` subclass (e.g. a UI-aware
+   * variant in a downstream package) without re-implementing the constructor's
+   * workspace-derivation logic.
+   */
+  protected createWorkspace(
+    workspace: Workspace,
+    project: Project<false, false>,
+    isDefaultWorkspace: boolean,
+  ): StudioWorkspace {
+    return new StudioWorkspace(this, workspace, project, isDefaultWorkspace);
+  }
+
+  get href() {
+    return this.isLocal
+      ? `/local/${this.id}`
+      : `/studio/${this.application.id}`;
+  }
+
+  get title() {
+    // Get the title from the user application, this has the highest precedence
+    const title = this.get("title");
+    if (title) {
+      return title;
+    }
+
+    // If there are multiple workspaces and the studio is internal, use the project display name
+    if (this.workspaces.length > 1 && this.get("urlType") === "internal") {
+      return this.project.displayName;
+    }
+
+    // Otherwise use the title of the first workspace
+    return this.workspaces[0].title;
+  }
+
+  get subtitle() {
+    return new URL(this.url).hostname;
+  }
+
+  get<TKey extends keyof StudioUserApplication>(
+    attr: TKey,
+  ): StudioUserApplication[TKey] {
+    if (!(attr in this.application)) {
+      throw new Error(
+        `Attribute ${attr.toString()} does not exist on studio ${this.application.id}`,
+      );
+    }
+
+    return this.application[attr];
+  }
+
+  /**
+   * Resolves the studio's most authoritative manifest. The lookup order is:
+   *
+   * 1. `activeDeployment.manifest` — deployment manifests are the new
+   *    primitive within Sanity and are preferred whenever available.
+   * 2. `manifestData.value` — fallback to support older studios that
+   *    haven't produced a deployment manifest yet.
+   * 3. `application.manifest` — last-resort legacy field.
+   *
+   * Returns `null` when no manifest is available. The return shape is a
+   * union because the deployment and client manifests are not
+   * interchangeable — consumers that depend on client-only fields (e.g.
+   * `studioVersion`, workspace `schema`) must narrow or read the raw
+   * field they need.
+   */
+  get manifest(): ClientManifestType | ServerManifestType | null {
+    return (
+      this.application.activeDeployment?.manifest ??
+      this.application.manifestData?.value ??
+      this.application.manifest ??
+      null
+    );
+  }
+
+  get hasManifest(): boolean {
+    const manifest = this.manifest;
+    if (!manifest) return false;
+
+    // `manifest` is a union: server manifests encode `version` as an optional
+    // string, client manifests as a required number. The typeof check doubles
+    // as a discriminator — if it's not a number, we're looking at a server
+    // manifest whose presence alone is authoritative.
+    return typeof manifest.version !== "number" || manifest.version >= 2;
+  }
+
+  get hasSchema(): boolean {
+    // A deployment manifest tracks a schema descriptor for every workspace,
+    // so its presence is sufficient to short-circuit.
+    if (this.application.activeDeployment?.manifest) return true;
+
+    // Otherwise inspect the client manifest. We cannot look at
+    // `this.workspaces` because it won't contain workspaces the user does
+    // not have access to. The application has a schema even if the user
+    // can't access any of the workspaces, otherwise it would be displayed
+    // as not having a manifest in the setup guide and therefore considered
+    // partially compatible.
+    const clientManifest =
+      this.application.manifestData?.value ?? this.application.manifest;
+    const workspaces = clientManifest?.workspaces ?? [];
+
+    if (workspaces.length === 0) return false;
+    return workspaces.every((w) => Boolean(w.schema));
+  }
+
+  private resolveVersion() {
+    // const growthbook = getGrowthbook()
+
+    let version: string | undefined;
+
+    if (this.get("urlType") === "internal") {
+      version = this.get("activeDeployment")?.version;
+    } else {
+      const clientManifest =
+        this.get("manifestData")?.value ?? this.get("manifest");
+      // The property 'studioVersion' exists only on external studios,
+      // starting from manifest.version 3
+      version =
+        clientManifest && "studioVersion" in clientManifest
+          ? clientManifest.studioVersion
+          : undefined;
+    }
+
+    /**
+     * Self-hosted studios are often not publicly accessible, which means that
+     * Brett often times cannot fetch the manifest to read the version. In this case
+     * we try to read the version from the deployment manifest or 'live-manifest', if it exists, to do
+     * everything we can to determine the version.
+     *
+     * Since the data of the live-maninfest can not be trusted, we also must validate
+     * that the version is a valid semver version before returning it. It always represents
+     * the last known version from when the studio was connected to Sanity's infrastructure,
+     * which might not be the version this studio is currently running (e.g. because the version
+     * has been downgraded).
+     */
+    const deploymentManifest = this.get("activeDeployment")?.manifest;
+    // const liveManifest = growthbook.isOn('dashboard-use-live-manifest')
+    //   ? this.get('config')?.['live-manifest']?.value
+    //   : null
+
+    const serverManifest = deploymentManifest; /*?? liveManifest*/
+    const bundleVersion = serverManifest?.bundleVersion;
+
+    if (bundleVersion && valid(coerce(bundleVersion))) {
+      if (!version || (version && gt(bundleVersion, version))) {
+        version = bundleVersion;
+      }
+    }
+
+    if (!version || !valid(coerce(version))) {
+      return null;
+    }
+
+    return coerce(version);
+  }
+
+  get version() {
+    const version = this.resolveVersion();
+    return version ? version.toString() : null;
+  }
+
+  get compatibilityStatus(): CompatibilityStatus {
+    return StudioApplication.resolveCompatibilityStatus(this);
+  }
+
+  /**
+   * Used to calculate the compatibility status of a given studio application.
+   * Optionally if you've resolved the version elsewhere provide that value to
+   * get the new compatibility status without mutating the application.
+   */
+  static resolveCompatibilityStatus(
+    application: StudioApplication,
+    version: string | null = application.version,
+  ): CompatibilityStatus {
+    if (
+      version === null ||
+      lt(version, StudioApplication.MinimumStudioVersion)
+    ) {
+      return StudioApplication.CompatibilityStatuses.UNKNOWN;
+    }
+
+    if (
+      !application.hasSchema ||
+      !application.hasManifest ||
+      StudioApplication.resolveIssues(application, version).length > 0
+    ) {
+      return StudioApplication.CompatibilityStatuses.PARTIALLY_COMPATIBLE;
+    }
+
+    return StudioApplication.CompatibilityStatuses.FULLY_COMPATIBLE;
+  }
+
+  get isAutoRedirecting(): boolean {
+    return StudioApplication.resolveIsAutoRedirecting(this);
+  }
+
+  /**
+   * Mirrors the `isRedirectable` function from Saison defined in
+   * https://github.com/sanity-io/saison/blob/83556405d23e07f6d3a71c76249c67e33fe1101f/src/utils/applications.ts
+   *
+   * Returns whether a studio application is auto-redirecting, meaning it can only be accessed in the context of
+   * Dashboard.
+   */
+  static resolveIsAutoRedirecting(
+    application: StudioApplication,
+    versionArg = application.version,
+  ) {
+    let version: string | SemVer | null = versionArg;
+
+    if (application.get("urlType") === "external" || !version) {
+      return false;
+    }
+
+    if (!application.get("activeDeployment")?.isAutoUpdating) {
+      // If the studio is not auto-updating, we need to check if the version supports
+      // workspace switcher (3.92.0+) otherwise it would not be redirected.
+      return gt(version, "3.92.0");
+    }
+
+    const autoUpdatingVersion = application.get("autoUpdatingVersion");
+
+    if (autoUpdatingVersion) {
+      if (["next", "stable", "latest"].includes(autoUpdatingVersion)) {
+        return true;
+      }
+
+      const autoUpdatingVersionPinnedVersion = coerce(autoUpdatingVersion);
+
+      if (autoUpdatingVersionPinnedVersion) {
+        version = autoUpdatingVersionPinnedVersion;
+      }
+    }
+
+    return gt(version, StudioApplication.MinimumStudioVersion);
+  }
+
+  /**
+   * Returns a list of issues that prevent the studio from functioning properly in the Dashboard.
+   * This static value depends on the version of the studio that comes from the `activeDeployment` property.
+   * As such, if the studio is auto-updating, this list will be incorrect & instead you should use
+   * the static method `resolveIssues` to get the correct issues by passing the resolved version.
+   */
+  get issues(): StudioIssues {
+    return StudioApplication.resolveIssues(this);
+  }
+
+  static resolveIssues(
+    application: StudioApplication,
+    version: string | null = application.version,
+  ): StudioIssues {
+    const issues: StudioIssues = StudioApplication.Features.filter(
+      (feature) => {
+        return !application.isFeatureSupported(feature.id, version);
+      },
+    );
+
+    if (!application.hasManifest) {
+      issues.push({
+        id: StudioApplication.StudioIssues.ISSUE_MANIFEST,
+      });
+    }
+
+    return issues;
+  }
+
+  protected isFeatureSupported(
+    feature: StudioDashboardIssue,
+    version = this.version,
+  ) {
+    const featureVersion = StudioApplication.Features.find(
+      (_) => _.id === feature,
+    )?.version;
+
+    if (!featureVersion || !version) {
+      return false;
+    }
+
+    return gte(version, featureVersion);
+  }
+
+  toProtocolResource(): never {
+    throw new Error(
+      "Studio application resources cannot be converted to protocol resources",
+    );
+  }
+
+  static CompatibilityStatuses = {
+    UNKNOWN: "unknown",
+    PARTIALLY_COMPATIBLE: "partially-compatible",
+    FULLY_COMPATIBLE: "fully-compatible",
+  } as const;
+
+  static StudioIssues = {
+    ISSUE_ACTIVITY: "ACTIVITY",
+    ISSUE_AGENT: "AGENT",
+    ISSUE_FAVORITES: "FAVORITES",
+    ISSUE_URL_SYNCING: "URL_SYNCING",
+    ISSUE_UI_ADJUSTMENT: "UI_ADJUSTMENT",
+    ISSUE_CONTENT_MAPPING: "CONTENT_MAPPING",
+    ISSUE_LOGIN: "LOGIN",
+    ISSUE_MANIFEST: "MANIFEST",
+  } as const;
+
+  static Features = [
+    {
+      id: StudioApplication.StudioIssues.ISSUE_AGENT,
+      version: "5.1.0",
+    },
+    {
+      id: StudioApplication.StudioIssues.ISSUE_FAVORITES,
+      version: "3.88.1",
+    },
+    {
+      id: StudioApplication.StudioIssues.ISSUE_ACTIVITY,
+      version: "3.88.1",
+    },
+    {
+      id: StudioApplication.StudioIssues.ISSUE_URL_SYNCING,
+      version: "3.75.0",
+    },
+    {
+      id: StudioApplication.StudioIssues.ISSUE_UI_ADJUSTMENT,
+      version: "3.78.1",
+    },
+    {
+      id: StudioApplication.StudioIssues.ISSUE_CONTENT_MAPPING,
+      version: "3.68.0",
+    },
+    {
+      id: StudioApplication.StudioIssues.ISSUE_LOGIN,
+      version: "2.28.0",
+    },
+  ] satisfies StudioIssues;
+
+  static MinimumStudioVersion = "2.28.0" as const;
+
+  static MinimumStudioVersionWithNoIssues = rsort(
+    StudioApplication.Features.map((feature) => feature.version),
+  ).at(0);
+}
+
+type CompatibilityStatus =
+  (typeof StudioApplication.CompatibilityStatuses)[keyof typeof StudioApplication.CompatibilityStatuses];
+
+type StudioDashboardIssue =
+  (typeof StudioApplication.StudioIssues)[keyof typeof StudioApplication.StudioIssues];
+
+type StudioIssues = Array<{
+  id: StudioDashboardIssue;
+  version?: string;
+}>;

package/src/core/user-applications/studios/workspace.ts

@@ -0,0 +1,156 @@
+import type { StudioResource as ProtocolStudioResource } from "@sanity/message-protocol";
+
+import { AbstractApplication } from "../../applications/application";
+import type { Project } from "../../projects";
+import { joinUrlPaths, normalizePath } from "../../shared/urls";
+import type { UserApplicationId } from "../user-application";
+import type { Workspace } from "./schemas";
+import type { StudioApplication } from "./studio";
+
+/**
+ * @public
+ */
+export class StudioWorkspace extends AbstractApplication<
+  "workspace",
+  ProtocolStudioResource
+> {
+  /**
+   * Workspaces always belong to a studio application.
+   * They do not exist on their own & therefore can access
+   * information about the studio they're in via this property.
+   */
+  private readonly studioApplication: StudioApplication;
+  private readonly workspace: Workspace;
+  readonly project: Project<false, false>;
+  private readonly isDefaultWorkspace: boolean;
+
+  constructor(
+    studioApplication: StudioApplication,
+    workspace: Workspace,
+    project: Project<false, false>,
+    isDefaultWorkspace: boolean,
+  ) {
+    super("workspace");
+
+    this.studioApplication = studioApplication;
+    this.workspace = workspace;
+    this.project = project;
+    this.isDefaultWorkspace = isDefaultWorkspace;
+  }
+
+  /**
+   * The studio application that this workspace belongs to.
+   */
+  get studio() {
+    return this.studioApplication;
+  }
+
+  get id() {
+    return StudioWorkspace.makeId(this.studio.id, this.workspace.name);
+  }
+
+  get href() {
+    return joinUrlPaths(this.studio.href, this.workspace.name);
+  }
+
+  get title() {
+    /**
+     * If there's no manifest we will have created a single workspace for the application.
+     * In this circumstance we won't have a meaningful title, so instead we use the hostname of the appHost.
+     */
+    if (this.isDefaultWorkspace) {
+      return this.project.displayName;
+    }
+
+    return this.workspace.title;
+  }
+
+  get subtitle() {
+    if (this.isDefaultWorkspace) {
+      const isValidAppHost = URL.canParse(this.studio.get("appHost"));
+      const url = isValidAppHost
+        ? new URL(this.studio.get("appHost"))
+        : this.studio.url;
+
+      return url.hostname;
+    }
+
+    return this.get("subtitle");
+  }
+
+  get<TKey extends Exclude<keyof Workspace, "id" | "icon" | "title">>(
+    attr: TKey,
+  ): Workspace[TKey] {
+    return this.workspace[attr];
+  }
+
+  get isFederated() {
+    return this.studio.isFederated;
+  }
+
+  /**
+   * With comlink, studio-applications were not considered applications at all, only workspaces. This is partially why
+   * we create default workspaces when the application has no manifest or the manifest has no workspaces.
+   *
+   * Thereby, to create it we depend on a lot of information from the parent application even if it's duplicated across
+   * different workspaces.
+   */
+  toProtocolResource(): ProtocolStudioResource {
+    return {
+      ...this.workspace,
+      type: "studio",
+      userApplicationId: this.studio.id,
+      // The protocol still types `size`/`isAutoUpdating` as non-nullable,
+      // but the user-applications API reports both as nullable.
+      activeDeployment: this.studio.get(
+        "activeDeployment",
+      ) as ProtocolStudioResource["activeDeployment"],
+      autoUpdatingVersion: this.studio.get("autoUpdatingVersion"),
+      dashboardStatus: this.studio.get("dashboardStatus"),
+      url: this.studio.url.toString(),
+      href: this.href,
+      id: this.id,
+      hasManifest: true,
+      hasSchema: Boolean("schema" in this.workspace && this.workspace.schema),
+      // The protocol resource requires the client-shaped manifest (workspaces
+      // with `schema`). Read those sources directly rather than the unified
+      // `manifest` getter, which may return a `ServerManifest` for studios
+      // with a deployment manifest.
+      manifest: (this.studio.get("manifestData")?.value ??
+        this.studio.get("manifest") ??
+        null) as ProtocolStudioResource["manifest"],
+      updatedAt: this.studio.get("updatedAt"),
+      version: this.studio.get("activeDeployment")?.version,
+      urlType: this.studio.get("urlType"),
+      config: this.studio.get("config"),
+    } satisfies ProtocolStudioResource;
+  }
+
+  /**
+   * @returns the URL to the workspace of a studio application.
+   */
+  get url(): URL {
+    const studioUrl = new URL(this.studio.url);
+    const normalizedUrlPath = normalizePath(studioUrl.pathname);
+
+    let finalBasePath = normalizePath(this.get("basePath"));
+
+    // the appHost may already contain the basepath for externally hosted studios
+    // or embedded studios, so we deduplicate the segments
+    if (finalBasePath.startsWith(normalizedUrlPath)) {
+      finalBasePath = finalBasePath.slice(normalizedUrlPath.length);
+    }
+
+    studioUrl.pathname = joinUrlPaths(normalizedUrlPath, finalBasePath);
+
+    return studioUrl;
+  }
+
+  static makeId(applicationId: UserApplicationId, workspaceName: string) {
+    return `${applicationId}-${workspaceName}`;
+  }
+
+  static splitId(id: string): [string, string] {
+    return id.split(new RegExp(/-(.*)/)).slice(0, 2) as [string, string];
+  }
+}