@sanity/workbench-cli 1.1.0-beta.0

package/README.md

@@ -0,0 +1,10 @@
+# @sanity/workbench-cli
+
+Internal implementation detail of the [Sanity CLI](https://github.com/sanity-io/cli).
+It backs the CLI's **unstable** workbench support and is not meant to be installed
+or imported directly — its API can change or be removed without notice.
+
+Workbench is opt-in per project via `unstable_defineApp` in `sanity.cli.ts`; use it
+through the `sanity` CLI, not this package.
+
+Maintainers: see `ARCHITECTURE.md` (not published) for how this package fits together.

package/dist/_exports/build.d.ts

@@ -0,0 +1,129 @@
+import { CliConfig } from "@sanity/cli-core";
+import { PluginOption } from "vite";
+import { z } from "zod/mini";
+
+/**
+ * User-facing input for `unstable_defineApp`. Excludes the internal
+ * `applicationType` — that field is validated by the schema but is not part of
+ * the public surface (Sanity-owned apps set it via `@ts-expect-error`).
+ * @public
+ */
+declare type DefineAppInput = Omit<
+  z.output<typeof DefineAppInputSchema>,
+  "applicationType"
+>;
+
+/**
+ * Runtime-validation schema for `unstable_defineApp`. Validates the full shape
+ * including the internal `applicationType`; the user-facing `DefineAppInput`
+ * type below omits that field.
+ * @internal
+ */
+declare const DefineAppInputSchema: z.ZodMiniObject<
+  {
+    applicationType: z.ZodMiniOptional<
+      z.ZodMiniEnum<{
+        coreApp: "coreApp";
+        studio: "studio";
+        canvas: "canvas";
+        dashboard: "dashboard";
+        "media-library": "media-library";
+      }>
+    >;
+    entry: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    group: z.ZodMiniOptional<
+      z.ZodMiniEnum<{
+        "dock.system": "dock.system";
+        "dock.applications": "dock.applications";
+        "dock.user": "dock.user";
+      }>
+    >;
+    icon: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    name: z.ZodMiniString<string>;
+    organizationId: z.ZodMiniString<string>;
+    priority: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+    services: z.ZodMiniOptional<
+      z.ZodMiniArray<
+        z.ZodMiniDiscriminatedUnion<
+          [
+            z.ZodMiniObject<
+              {
+                name: z.ZodMiniString<string>;
+                src: z.ZodMiniString<string>;
+                type: z.ZodMiniLiteral<"worker">;
+              },
+              z.core.$strip
+            >,
+          ],
+          "type"
+        >
+      >
+    >;
+    title: z.ZodMiniString<string>;
+    views: z.ZodMiniOptional<
+      z.ZodMiniArray<
+        z.ZodMiniDiscriminatedUnion<
+          [
+            z.ZodMiniObject<
+              {
+                name: z.ZodMiniString<string>;
+                src: z.ZodMiniString<string>;
+                type: z.ZodMiniLiteral<"panel">;
+              },
+              z.core.$strip
+            >,
+          ],
+          "type"
+        >
+      >
+    >;
+  },
+  z.core.$strip
+>;
+
+/** @public */
+declare interface ResolvedWorkbenchApp {
+  /** Background worker services the app declares. */
+  readonly services: NonNullable<DefineAppInput["services"]>;
+  /** Dock panel views the app declares. */
+  readonly views: NonNullable<DefineAppInput["views"]>;
+  /** Resolved app kind — `studio` or one of the SDK app types. */
+  readonly applicationType?: string;
+  /** SDK app-view entrypoint, when declared. */
+  readonly entry?: string;
+}
+
+/**
+ * Resolve the workbench app for a CLI config, or `null` for a plain project.
+ * @public
+ */
+export declare function resolveWorkbenchApp(
+  cliConfig: CliConfig | null | undefined,
+): ResolvedWorkbenchApp | null;
+
+declare interface WorkbenchViteOptions {
+  /** Project root — read for the federation remote name, and the plugin workDir. */
+  cwd: string;
+  /**
+   * Build entry paths relative to the federation runtime dir. `relativeEntry` is
+   * the app's `entry` (null for a dock-only app with no app view);
+   * `relativeConfigLocation` is the studio's `sanity.config.*` (null when absent).
+   */
+  entries: {
+    relativeConfigLocation: string | null;
+    relativeEntry: string | null;
+  };
+  /** App (vs studio) build — selects the discriminated federation option shape. */
+  isApp?: boolean;
+  /** Declared background services. */
+  services?: DefineAppInput["services"];
+  /** Declared dock views. */
+  views?: DefineAppInput["views"];
+}
+
+/** Build the Vite plugins for a workbench app's module-federation remote. */
+export declare function workbenchVitePlugins(
+  options: WorkbenchViteOptions,
+): Promise<PluginOption>;
+
+export {};

package/dist/_exports/build.js

@@ -0,0 +1,9 @@
+// Node-only build entry: the module-federation Vite plugins that
+// `@sanity/cli-build`'s `getViteConfig` swaps in for a workbench app, plus the
+// resolver the build reads declared views/services from. The build needs no
+// deploy-time guards, so it takes the bare `resolveWorkbenchApp` — the guarded
+// view (`getWorkbench`) is the deploy entry's export.
+export { workbenchVitePlugins } from '../actions/build/vite/workbench-vite-plugins.js';
+export { resolveWorkbenchApp } from '../resolveWorkbenchApp.js';
+
+//# sourceMappingURL=build.js.map

package/dist/_exports/build.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/_exports/build.ts"],"sourcesContent":["// Node-only build entry: the module-federation Vite plugins that\n// `@sanity/cli-build`'s `getViteConfig` swaps in for a workbench app, plus the\n// resolver the build reads declared views/services from. The build needs no\n// deploy-time guards, so it takes the bare `resolveWorkbenchApp` — the guarded\n// view (`getWorkbench`) is the deploy entry's export.\n\nexport {workbenchVitePlugins} from '../actions/build/vite/workbench-vite-plugins.js'\nexport {resolveWorkbenchApp} from '../resolveWorkbenchApp.js'\n"],"names":["workbenchVitePlugins","resolveWorkbenchApp"],"mappings":"AAAA,iEAAiE;AACjE,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,sDAAsD;AAEtD,SAAQA,oBAAoB,QAAO,kDAAiD;AACpF,SAAQC,mBAAmB,QAAO,4BAA2B"}

package/dist/_exports/deploy.d.ts

@@ -0,0 +1,115 @@
+import { CliConfig } from "@sanity/cli-core";
+import { z } from "zod/mini";
+
+/**
+ * User-facing input for `unstable_defineApp`. Excludes the internal
+ * `applicationType` — that field is validated by the schema but is not part of
+ * the public surface (Sanity-owned apps set it via `@ts-expect-error`).
+ * @public
+ */
+declare type DefineAppInput = Omit<
+  z.output<typeof DefineAppInputSchema>,
+  "applicationType"
+>;
+
+/**
+ * Runtime-validation schema for `unstable_defineApp`. Validates the full shape
+ * including the internal `applicationType`; the user-facing `DefineAppInput`
+ * type below omits that field.
+ * @internal
+ */
+declare const DefineAppInputSchema: z.ZodMiniObject<
+  {
+    applicationType: z.ZodMiniOptional<
+      z.ZodMiniEnum<{
+        coreApp: "coreApp";
+        studio: "studio";
+        canvas: "canvas";
+        dashboard: "dashboard";
+        "media-library": "media-library";
+      }>
+    >;
+    entry: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    group: z.ZodMiniOptional<
+      z.ZodMiniEnum<{
+        "dock.system": "dock.system";
+        "dock.applications": "dock.applications";
+        "dock.user": "dock.user";
+      }>
+    >;
+    icon: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    name: z.ZodMiniString<string>;
+    organizationId: z.ZodMiniString<string>;
+    priority: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+    services: z.ZodMiniOptional<
+      z.ZodMiniArray<
+        z.ZodMiniDiscriminatedUnion<
+          [
+            z.ZodMiniObject<
+              {
+                name: z.ZodMiniString<string>;
+                src: z.ZodMiniString<string>;
+                type: z.ZodMiniLiteral<"worker">;
+              },
+              z.core.$strip
+            >,
+          ],
+          "type"
+        >
+      >
+    >;
+    title: z.ZodMiniString<string>;
+    views: z.ZodMiniOptional<
+      z.ZodMiniArray<
+        z.ZodMiniDiscriminatedUnion<
+          [
+            z.ZodMiniObject<
+              {
+                name: z.ZodMiniString<string>;
+                src: z.ZodMiniString<string>;
+                type: z.ZodMiniLiteral<"panel">;
+              },
+              z.core.$strip
+            >,
+          ],
+          "type"
+        >
+      >
+    >;
+  },
+  z.core.$strip
+>;
+
+declare interface DeployableWorkbenchApp extends ResolvedWorkbenchApp {
+  /**
+   * Throws when the app declares nothing the build can expose — no entry, view
+   * or service. A federated app with none would ship a remote with nothing to
+   * load, so deploy gates on this before any prompts or API calls.
+   */
+  assertDeployable(): void;
+  /**
+   * Throws unless `sourceDir` is a directory holding a federation build.
+   * Workbench builds emit a module-federation remote instead of a static SPA,
+   * so the usual `index.html` contract doesn't apply — `mf-manifest.json` is the
+   * marker that `sanity build` produced a federation build.
+   */
+  checkBuiltOutput(sourceDir: string): Promise<void>;
+}
+
+export declare function getWorkbench(
+  cliConfig: CliConfig | null | undefined,
+): DeployableWorkbenchApp | null;
+
+/** @public */
+declare interface ResolvedWorkbenchApp {
+  /** Background worker services the app declares. */
+  readonly services: NonNullable<DefineAppInput["services"]>;
+  /** Dock panel views the app declares. */
+  readonly views: NonNullable<DefineAppInput["views"]>;
+  /** Resolved app kind — `studio` or one of the SDK app types. */
+  readonly applicationType?: string;
+  /** SDK app-view entrypoint, when declared. */
+  readonly entry?: string;
+}
+
+export {};

package/dist/_exports/deploy.js

@@ -0,0 +1,6 @@
+// Node-only deploy entry: the workbench-app accessor with the deploy-time guards
+// (`assertDeployable`, `checkBuiltOutput`) the deploy command runs before
+// shipping. Built on the same shared resolver as the build accessor.
+export { getWorkbench } from '../actions/deploy/getWorkbench.js';
+
+//# sourceMappingURL=deploy.js.map

package/dist/_exports/deploy.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/_exports/deploy.ts"],"sourcesContent":["// Node-only deploy entry: the workbench-app accessor with the deploy-time guards\n// (`assertDeployable`, `checkBuiltOutput`) the deploy command runs before\n// shipping. Built on the same shared resolver as the build accessor.\nexport {getWorkbench} from '../actions/deploy/getWorkbench.js'\n"],"names":["getWorkbench"],"mappings":"AAAA,iFAAiF;AACjF,0EAA0E;AAC1E,qEAAqE;AACrE,SAAQA,YAAY,QAAO,oCAAmC"}

package/dist/_exports/dev.d.ts

@@ -0,0 +1,166 @@
+import { z } from "zod/mini";
+
+/**
+ * Attempt to acquire an exclusive lock for the workbench process.
+ * Uses `O_EXCL` (the `wx` flag) which is atomic at the OS level — only one
+ * process can create the file.
+ *
+ * The lock stores `{pid, host, port}` so other processes can find the
+ * running workbench. Call `updatePort` after the Vite server starts to
+ * write the actual port (Vite may pick a different one).
+ *
+ * @returns A {@link WorkbenchLock} if acquired, or `undefined` if another
+ *          live process already holds it.
+ */
+export declare function acquireWorkbenchLock(
+  info: {
+    host: string;
+    port: number;
+  },
+  retries?: number,
+): WorkbenchLock | undefined;
+
+/**
+ * Resolve a directory to its canonical (long) form before handing it to
+ * `fs.watch`.
+ *
+ * On Windows, `fs.watch` aborts with a libuv assertion
+ * (`!_wcsnicmp(filename, dir, dirlen)` in `fs-event.c`) when the watched path
+ * is an 8.3 short name — e.g. temp dirs under `RUNNER~1` — because the OS
+ * reports long-form filenames that fail libuv's prefix check.
+ * `realpathSync.native` expands short names to their long form so the
+ * prefixes match.
+ *
+ * Falls back to the original path when it can't be resolved (e.g. it doesn't
+ * exist yet), which is no worse than watching it directly.
+ */
+export declare function canonicalizeWatchDir(dir: string): string;
+
+/**
+ * A manifest describing a running dev server process (studio or app).
+ * Stored as `~/.sanity/dev-servers/<pid>.json`.
+ *
+ * The workbench singleton is tracked separately via the lock file — see
+ * `acquireWorkbenchLock` and `readWorkbenchLock` below.
+ */
+export declare type DevServerManifest = z.infer<typeof devServerManifestSchema>;
+
+declare const devServerManifestSchema: z.ZodMiniObject<
+  {
+    host: z.ZodMiniString<string>;
+    id: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    interfaces: z.ZodMiniOptional<
+      z.ZodMiniArray<
+        z.ZodMiniObject<
+          {
+            entry_point: z.ZodMiniString<string>;
+            interface_type: z.ZodMiniString<string>;
+            name: z.ZodMiniString<string>;
+          },
+          z.core.$strip
+        >
+      >
+    >;
+    manifest: z.ZodMiniOptional<
+      z.ZodMiniUnion<
+        readonly [
+          z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>,
+          z.ZodMiniObject<
+            {
+              group: z.ZodMiniOptional<z.ZodMiniString<string>>;
+              icon: z.ZodMiniOptional<z.ZodMiniString<string>>;
+              priority: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+              title: z.ZodMiniOptional<z.ZodMiniString<string>>;
+              version: z.ZodMiniString<string>;
+            },
+            z.core.$strip
+          >,
+        ]
+      >
+    >;
+    manifestUpdatedAt: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    pid: z.ZodMiniNumber<number>;
+    port: z.ZodMiniNumber<number>;
+    projectId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    startedAt: z.ZodMiniString<string>;
+    type: z.ZodMiniEnum<{
+      coreApp: "coreApp";
+      studio: "studio";
+    }>;
+    version: z.ZodMiniLiteral<1>;
+    workDir: z.ZodMiniString<string>;
+  },
+  z.core.$strip
+>;
+
+declare interface DevServerRegistration {
+  /** Remove the registry entry. */
+  release: () => void;
+  /**
+   * Rewrite the registry entry with partial updates merged in. Also bumps the
+   * file's mtime, which fires `watchRegistry` in any workbench process and
+   * triggers a rebroadcast to connected clients.
+   */
+  update: (
+    patch: Partial<Omit<DevServerManifest, "pid" | "startedAt" | "version">>,
+  ) => void;
+}
+
+/**
+ * Read all manifest files from the registry, prune stale entries (dead PIDs),
+ * and return the live ones.
+ */
+export declare function getRegisteredServers(): DevServerManifest[];
+
+/**
+ * Read the workbench lock file and return its contents if the holding
+ * process is still alive. Prunes stale locks from crashed processes.
+ */
+export declare function readWorkbenchLock():
+  | z.infer<typeof workbenchLockSchema>
+  | undefined;
+
+/**
+ * Write a manifest file for the current process and return a handle with a
+ * `release` function that removes it plus an `update` function for patching
+ * fields post-registration. Uses synchronous I/O so the file exists before
+ * any signal handler could fire.
+ */
+export declare function registerDevServer(
+  manifest: Omit<DevServerManifest, "pid" | "startedAt" | "version">,
+): DevServerRegistration;
+
+declare interface RegistryWatcher {
+  close(): void;
+}
+
+/**
+ * Watch the registry directory for changes and invoke the callback with the
+ * current list of live servers whenever a change is detected.
+ *
+ * Uses `fs.watch` with a debounce to coalesce rapid file changes (e.g. a
+ * server starting and writing its manifest triggers multiple FS events).
+ */
+export declare function watchRegistry(
+  callback: (servers: DevServerManifest[]) => void,
+): RegistryWatcher;
+
+declare interface WorkbenchLock {
+  /** Release the lock file. */
+  release: () => void;
+  /** Update the lock with the actual port after the server starts listening. */
+  updatePort: (port: number) => void;
+}
+
+declare const workbenchLockSchema: z.ZodMiniObject<
+  {
+    host: z.ZodMiniString<string>;
+    pid: z.ZodMiniNumber<number>;
+    port: z.ZodMiniNumber<number>;
+    startedAt: z.ZodMiniString<string>;
+    version: z.ZodMiniLiteral<1>;
+  },
+  z.core.$strip
+>;
+
+export {};

package/dist/_exports/dev.js

@@ -0,0 +1,10 @@
+// Node-only dev entry: the workbench dev-server registry the CLI's dev
+// orchestration drives. It tracks running studio/app dev servers (single
+// instance via a lock + PID-liveness), and the workbench host watches it to
+// render local panels/services without a deploy. The CLI owns the orchestration
+// (starting servers, extracting manifests); this package owns the registry it
+// registers into and watches.
+export { canonicalizeWatchDir } from '../actions/dev/canonicalizeWatchDir.js';
+export { acquireWorkbenchLock, getRegisteredServers, readWorkbenchLock, registerDevServer, watchRegistry } from '../actions/dev/registry.js';
+
+//# sourceMappingURL=dev.js.map

package/dist/_exports/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/_exports/dev.ts"],"sourcesContent":["// Node-only dev entry: the workbench dev-server registry the CLI's dev\n// orchestration drives. It tracks running studio/app dev servers (single\n// instance via a lock + PID-liveness), and the workbench host watches it to\n// render local panels/services without a deploy. The CLI owns the orchestration\n// (starting servers, extracting manifests); this package owns the registry it\n// registers into and watches.\nexport {canonicalizeWatchDir} from '../actions/dev/canonicalizeWatchDir.js'\nexport {\n  acquireWorkbenchLock,\n  type DevServerManifest,\n  getRegisteredServers,\n  readWorkbenchLock,\n  registerDevServer,\n  watchRegistry,\n} from '../actions/dev/registry.js'\n"],"names":["canonicalizeWatchDir","acquireWorkbenchLock","getRegisteredServers","readWorkbenchLock","registerDevServer","watchRegistry"],"mappings":"AAAA,uEAAuE;AACvE,yEAAyE;AACzE,4EAA4E;AAC5E,gFAAgF;AAChF,8EAA8E;AAC9E,8BAA8B;AAC9B,SAAQA,oBAAoB,QAAO,yCAAwC;AAC3E,SACEC,oBAAoB,EAEpBC,oBAAoB,EACpBC,iBAAiB,EACjBC,iBAAiB,EACjBC,aAAa,QACR,6BAA4B"}