@sanity/workbench-cli 1.1.0-beta.0

package/dist/actions/dev/registry.js

@@ -0,0 +1,279 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, watch, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { coreAppManifestSchema, getSanityDataDir, studioManifestSchema, subdebug } from '@sanity/cli-core';
+import { z } from 'zod/mini';
+import { canonicalizeWatchDir } from './canonicalizeWatchDir.js';
+import { getProcessStartTime, isOurProcess } from './processLiveness.js';
+const devDebug = subdebug('dev');
+/** Bump when the manifest/lock shape changes in a breaking way. */ const REGISTRY_VERSION = 1;
+/**
+ * The current process's start time as reported by the OS, for the `startedAt`
+ * that `isOurProcess` checks on re-read. Falls back to now when the OS time is
+ * unavailable — `new Date()` alone records the write time, which drifts from
+ * process start by enough to look stale and get pruned right after writing.
+ */ function ownStartedAt() {
+    return (getProcessStartTime(process.pid) ?? new Date()).toISOString();
+}
+const devServerManifestSchema = z.object({
+    host: z.string(),
+    id: z.optional(z.string()),
+    /**
+   * Interfaces the app exposes, mapped from the declared `views` (dock panels,
+   * `interface_type: "panel"`) and `services` (background workers,
+   * `interface_type: "worker"`). A service is just an interface, so both live
+   * in this one list. Carried separately from the manifest — interfaces live in
+   * the application service, not the manifest — so the workbench can render
+   * local panels and run local workers without a deploy. `entry_point` is the
+   * declared `src`. Lenient by design; the workbench is the authority on the
+   * interface shape.
+   */ interfaces: z.optional(z.array(z.object({
+        entry_point: z.string(),
+        interface_type: z.string(),
+        name: z.string()
+    }))),
+    /**
+   * Inlined manifest — either a {@link StudioManifest} or {@link CoreAppManifest},
+   * validated against the shared cli-core schemas. The registry stores and
+   * rebroadcasts it; the CLI is what extracts and writes it.
+   */ manifest: z.optional(z.union([
+        studioManifestSchema,
+        coreAppManifestSchema
+    ])),
+    /**
+   * ISO timestamp of the most recent successful manifest extraction. Bumped
+   * on every regeneration so re-writing this registry entry triggers the
+   * workbench `watchRegistry` watcher and forces a rebroadcast to clients.
+   */ manifestUpdatedAt: z.optional(z.string()),
+    pid: z.number(),
+    port: z.number(),
+    projectId: z.optional(z.string()),
+    startedAt: z.string(),
+    type: z.enum([
+        'coreApp',
+        'studio'
+    ]),
+    version: z.literal(REGISTRY_VERSION),
+    workDir: z.string()
+});
+/**
+ * Path to the dev server registry directory. Lives under the shared Sanity
+ * config directory to stay consistent with other CLI paths.
+ */ function getRegistryDir() {
+    return join(getSanityDataDir(), 'dev-servers');
+}
+/**
+ * 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 function registerDevServer(manifest) {
+    const registryDir = getRegistryDir();
+    mkdirSync(registryDir, {
+        recursive: true
+    });
+    let current = {
+        ...manifest,
+        pid: process.pid,
+        startedAt: ownStartedAt(),
+        version: REGISTRY_VERSION
+    };
+    const filePath = join(registryDir, `${process.pid}.json`);
+    writeFileSync(filePath, JSON.stringify(current, null, 2));
+    // Guard against late updates from background tasks (e.g. the initial
+    // manifest extraction) landing after `release()` has deleted the file —
+    // without this, the update would re-create the registry entry and leak.
+    let released = false;
+    return {
+        release () {
+            released = true;
+            try {
+                unlinkSync(filePath);
+            } catch  {
+            // ENOENT is fine — already cleaned up
+            }
+        },
+        update (patch) {
+            if (released) return;
+            current = {
+                ...current,
+                ...patch
+            };
+            writeFileSync(filePath, JSON.stringify(current, null, 2));
+        }
+    };
+}
+/**
+ * Read all manifest files from the registry, prune stale entries (dead PIDs),
+ * and return the live ones.
+ */ export function getRegisteredServers() {
+    const registryDir = getRegistryDir();
+    if (!existsSync(registryDir)) {
+        return [];
+    }
+    const files = readdirSync(registryDir).filter((f)=>f.endsWith('.json'));
+    const servers = [];
+    for (const file of files){
+        const filePath = join(registryDir, file);
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(filePath, 'utf8'));
+        } catch  {
+            continue;
+        }
+        const { data, success } = devServerManifestSchema.safeParse(raw);
+        if (!success) continue;
+        if (isOurProcess(data.pid, data.startedAt)) {
+            servers.push(data);
+        } else {
+            try {
+                unlinkSync(filePath);
+            } catch  {
+            // Ignore — another process may have already cleaned it up
+            }
+        }
+    }
+    return servers;
+}
+/**
+ * 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 function watchRegistry(callback) {
+    const registryDir = getRegistryDir();
+    mkdirSync(registryDir, {
+        recursive: true
+    });
+    // Canonicalize to the real long path so `fs.watch` doesn't abort on Windows
+    // short-path dirs. See `canonicalizeWatchDir`.
+    const watchDir = canonicalizeWatchDir(registryDir);
+    let debounceTimer;
+    const notify = ()=>{
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(()=>{
+            callback(getRegisteredServers());
+        }, 50);
+    };
+    const watcher = watch(watchDir, notify);
+    return {
+        close () {
+            clearTimeout(debounceTimer);
+            watcher.close();
+        }
+    };
+}
+// The workbench singleton lock — "one workbench per machine". Lives in the same
+// registry dir and shares the liveness/prune model: a stale lock left by a
+// crashed process is pruned on read so the next acquire isn't blocked forever.
+const workbenchLockSchema = z.object({
+    host: z.string(),
+    pid: z.number(),
+    port: z.number(),
+    startedAt: z.string(),
+    version: z.literal(REGISTRY_VERSION)
+});
+/**
+ * Read the workbench lock file and return its contents if the holding
+ * process is still alive. Prunes stale locks from crashed processes.
+ */ export function readWorkbenchLock() {
+    const lockPath = join(getRegistryDir(), 'workbench.lock');
+    let contents;
+    try {
+        contents = readFileSync(lockPath, 'utf8');
+    } catch  {
+        // File doesn't exist — nothing to prune, nothing to return
+        return undefined;
+    }
+    // Past this point the file exists. Anything that isn't a live, valid lock
+    // (unparsable JSON, schema mismatch, dead/reused PID) is stale and must be
+    // pruned — otherwise the next `acquireWorkbenchLock` call is blocked by
+    // EEXIST forever and `sanity dev` silently no-ops the workbench server.
+    const data = parseLockContents(contents);
+    devDebug('Read workbench lock: %o', data);
+    if (data && isOurProcess(data.pid, data.startedAt)) {
+        devDebug('Workbench process is alive at pid %d on port %d', data.pid, data.port);
+        return data;
+    }
+    pruneWorkbenchLock(lockPath);
+    return undefined;
+}
+function parseLockContents(contents) {
+    try {
+        const { data, success } = workbenchLockSchema.safeParse(JSON.parse(contents));
+        return success ? data : undefined;
+    } catch  {
+        return undefined;
+    }
+}
+function pruneWorkbenchLock(lockPath) {
+    try {
+        devDebug('Removing stale workbench lock');
+        unlinkSync(lockPath);
+        devDebug('Stale workbench lock removed');
+    } catch  {
+    // Another process may have already cleaned it up
+    }
+}
+/**
+ * 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 function acquireWorkbenchLock(info, retries = 1) {
+    const registryDir = getRegistryDir();
+    mkdirSync(registryDir, {
+        recursive: true
+    });
+    const lockPath = join(registryDir, 'workbench.lock');
+    const startedAt = ownStartedAt();
+    const lockData = {
+        host: info.host,
+        pid: process.pid,
+        port: info.port,
+        startedAt,
+        version: REGISTRY_VERSION
+    };
+    devDebug('Acquiring workbench lock at %s', lockPath);
+    try {
+        writeFileSync(lockPath, JSON.stringify(lockData), {
+            flag: 'wx'
+        });
+        devDebug('Workbench lock acquired');
+        return {
+            release () {
+                try {
+                    unlinkSync(lockPath);
+                } catch  {
+                // Already cleaned up
+                }
+            },
+            updatePort (port) {
+                writeFileSync(lockPath, JSON.stringify({
+                    ...lockData,
+                    port
+                }));
+            }
+        };
+    } catch (err) {
+        devDebug('Failed to acquire workbench lock: %s', err instanceof Error ? err.message : String(err));
+        if (!isNodeError(err) || err.code !== 'EEXIST') return undefined;
+        // Lock exists — check if the holder is still alive
+        const existing = readWorkbenchLock();
+        if (existing) return undefined;
+        // Stale lock was pruned by readWorkbenchLock — retry (with guard against infinite recursion)
+        if (retries <= 0) return undefined;
+        return acquireWorkbenchLock(info, retries - 1);
+    }
+}
+function isNodeError(err) {
+    return err instanceof Error && 'code' in err;
+}
+
+//# sourceMappingURL=registry.js.map

package/dist/actions/dev/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/actions/dev/registry.ts"],"sourcesContent":["import {\n  existsSync,\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  unlinkSync,\n  watch,\n  writeFileSync,\n} from 'node:fs'\nimport {join} from 'node:path'\n\nimport {\n  coreAppManifestSchema,\n  getSanityDataDir,\n  studioManifestSchema,\n  subdebug,\n} from '@sanity/cli-core'\nimport {z} from 'zod/mini'\n\nimport {canonicalizeWatchDir} from './canonicalizeWatchDir.js'\nimport {getProcessStartTime, isOurProcess} from './processLiveness.js'\n\nconst devDebug = subdebug('dev')\n\n/** Bump when the manifest/lock shape changes in a breaking way. */\nconst REGISTRY_VERSION = 1\n\n/**\n * The current process's start time as reported by the OS, for the `startedAt`\n * that `isOurProcess` checks on re-read. Falls back to now when the OS time is\n * unavailable — `new Date()` alone records the write time, which drifts from\n * process start by enough to look stale and get pruned right after writing.\n */\nfunction ownStartedAt(): string {\n  return (getProcessStartTime(process.pid) ?? new Date()).toISOString()\n}\n\nconst devServerManifestSchema = z.object({\n  host: z.string(),\n  id: z.optional(z.string()),\n  /**\n   * Interfaces the app exposes, mapped from the declared `views` (dock panels,\n   * `interface_type: \"panel\"`) and `services` (background workers,\n   * `interface_type: \"worker\"`). A service is just an interface, so both live\n   * in this one list. Carried separately from the manifest — interfaces live in\n   * the application service, not the manifest — so the workbench can render\n   * local panels and run local workers without a deploy. `entry_point` is the\n   * declared `src`. Lenient by design; the workbench is the authority on the\n   * interface shape.\n   */\n  interfaces: z.optional(\n    z.array(z.object({entry_point: z.string(), interface_type: z.string(), name: z.string()})),\n  ),\n  /**\n   * Inlined manifest — either a {@link StudioManifest} or {@link CoreAppManifest},\n   * validated against the shared cli-core schemas. The registry stores and\n   * rebroadcasts it; the CLI is what extracts and writes it.\n   */\n  manifest: z.optional(z.union([studioManifestSchema, coreAppManifestSchema])),\n  /**\n   * ISO timestamp of the most recent successful manifest extraction. Bumped\n   * on every regeneration so re-writing this registry entry triggers the\n   * workbench `watchRegistry` watcher and forces a rebroadcast to clients.\n   */\n  manifestUpdatedAt: z.optional(z.string()),\n  pid: z.number(),\n  port: z.number(),\n  projectId: z.optional(z.string()),\n  startedAt: z.string(),\n  type: z.enum(['coreApp', 'studio']),\n  version: z.literal(REGISTRY_VERSION),\n  workDir: z.string(),\n})\n/**\n * A manifest describing a running dev server process (studio or app).\n * Stored as `~/.sanity/dev-servers/<pid>.json`.\n *\n * The workbench singleton is tracked separately via the lock file — see\n * `acquireWorkbenchLock` and `readWorkbenchLock` below.\n */\nexport type DevServerManifest = z.infer<typeof devServerManifestSchema>\n\n/**\n * Path to the dev server registry directory. Lives under the shared Sanity\n * config directory to stay consistent with other CLI paths.\n */\nfunction getRegistryDir(): string {\n  return join(getSanityDataDir(), 'dev-servers')\n}\n\ninterface DevServerRegistration {\n  /** Remove the registry entry. */\n  release: () => void\n  /**\n   * Rewrite the registry entry with partial updates merged in. Also bumps the\n   * file's mtime, which fires `watchRegistry` in any workbench process and\n   * triggers a rebroadcast to connected clients.\n   */\n  update: (patch: Partial<Omit<DevServerManifest, 'pid' | 'startedAt' | 'version'>>) => void\n}\n\n/**\n * Write a manifest file for the current process and return a handle with a\n * `release` function that removes it plus an `update` function for patching\n * fields post-registration. Uses synchronous I/O so the file exists before\n * any signal handler could fire.\n */\nexport function registerDevServer(\n  manifest: Omit<DevServerManifest, 'pid' | 'startedAt' | 'version'>,\n): DevServerRegistration {\n  const registryDir = getRegistryDir()\n  mkdirSync(registryDir, {recursive: true})\n\n  let current: DevServerManifest = {\n    ...manifest,\n    pid: process.pid,\n    startedAt: ownStartedAt(),\n    version: REGISTRY_VERSION,\n  }\n\n  const filePath = join(registryDir, `${process.pid}.json`)\n  writeFileSync(filePath, JSON.stringify(current, null, 2))\n\n  // Guard against late updates from background tasks (e.g. the initial\n  // manifest extraction) landing after `release()` has deleted the file —\n  // without this, the update would re-create the registry entry and leak.\n  let released = false\n\n  return {\n    release() {\n      released = true\n      try {\n        unlinkSync(filePath)\n      } catch {\n        // ENOENT is fine — already cleaned up\n      }\n    },\n    update(patch) {\n      if (released) return\n      current = {...current, ...patch}\n      writeFileSync(filePath, JSON.stringify(current, null, 2))\n    },\n  }\n}\n\n/**\n * Read all manifest files from the registry, prune stale entries (dead PIDs),\n * and return the live ones.\n */\nexport function getRegisteredServers(): DevServerManifest[] {\n  const registryDir = getRegistryDir()\n\n  if (!existsSync(registryDir)) {\n    return []\n  }\n\n  const files = readdirSync(registryDir).filter((f) => f.endsWith('.json'))\n  const servers: DevServerManifest[] = []\n\n  for (const file of files) {\n    const filePath = join(registryDir, file)\n    let raw: unknown\n    try {\n      raw = JSON.parse(readFileSync(filePath, 'utf8'))\n    } catch {\n      continue\n    }\n\n    const {data, success} = devServerManifestSchema.safeParse(raw)\n    if (!success) continue\n\n    if (isOurProcess(data.pid, data.startedAt)) {\n      servers.push(data)\n    } else {\n      try {\n        unlinkSync(filePath)\n      } catch {\n        // Ignore — another process may have already cleaned it up\n      }\n    }\n  }\n\n  return servers\n}\n\ninterface RegistryWatcher {\n  close(): void\n}\n\n/**\n * Watch the registry directory for changes and invoke the callback with the\n * current list of live servers whenever a change is detected.\n *\n * Uses `fs.watch` with a debounce to coalesce rapid file changes (e.g. a\n * server starting and writing its manifest triggers multiple FS events).\n */\nexport function watchRegistry(callback: (servers: DevServerManifest[]) => void): RegistryWatcher {\n  const registryDir = getRegistryDir()\n  mkdirSync(registryDir, {recursive: true})\n\n  // Canonicalize to the real long path so `fs.watch` doesn't abort on Windows\n  // short-path dirs. See `canonicalizeWatchDir`.\n  const watchDir = canonicalizeWatchDir(registryDir)\n\n  let debounceTimer: ReturnType<typeof setTimeout> | undefined\n\n  const notify = () => {\n    clearTimeout(debounceTimer)\n    debounceTimer = setTimeout(() => {\n      callback(getRegisteredServers())\n    }, 50)\n  }\n\n  const watcher = watch(watchDir, notify)\n\n  return {\n    close() {\n      clearTimeout(debounceTimer)\n      watcher.close()\n    },\n  }\n}\n\n// The workbench singleton lock — \"one workbench per machine\". Lives in the same\n// registry dir and shares the liveness/prune model: a stale lock left by a\n// crashed process is pruned on read so the next acquire isn't blocked forever.\n\nconst workbenchLockSchema = z.object({\n  host: z.string(),\n  pid: z.number(),\n  port: z.number(),\n  startedAt: z.string(),\n  version: z.literal(REGISTRY_VERSION),\n})\n\n/**\n * Read the workbench lock file and return its contents if the holding\n * process is still alive. Prunes stale locks from crashed processes.\n */\nexport function readWorkbenchLock(): z.infer<typeof workbenchLockSchema> | undefined {\n  const lockPath = join(getRegistryDir(), 'workbench.lock')\n\n  let contents: string\n  try {\n    contents = readFileSync(lockPath, 'utf8')\n  } catch {\n    // File doesn't exist — nothing to prune, nothing to return\n    return undefined\n  }\n\n  // Past this point the file exists. Anything that isn't a live, valid lock\n  // (unparsable JSON, schema mismatch, dead/reused PID) is stale and must be\n  // pruned — otherwise the next `acquireWorkbenchLock` call is blocked by\n  // EEXIST forever and `sanity dev` silently no-ops the workbench server.\n  const data = parseLockContents(contents)\n  devDebug('Read workbench lock: %o', data)\n  if (data && isOurProcess(data.pid, data.startedAt)) {\n    devDebug('Workbench process is alive at pid %d on port %d', data.pid, data.port)\n    return data\n  }\n\n  pruneWorkbenchLock(lockPath)\n  return undefined\n}\n\nfunction parseLockContents(contents: string): z.infer<typeof workbenchLockSchema> | undefined {\n  try {\n    const {data, success} = workbenchLockSchema.safeParse(JSON.parse(contents))\n    return success ? data : undefined\n  } catch {\n    return undefined\n  }\n}\n\nfunction pruneWorkbenchLock(lockPath: string): void {\n  try {\n    devDebug('Removing stale workbench lock')\n    unlinkSync(lockPath)\n    devDebug('Stale workbench lock removed')\n  } catch {\n    // Another process may have already cleaned it up\n  }\n}\n\ninterface WorkbenchLock {\n  /** Release the lock file. */\n  release: () => void\n  /** Update the lock with the actual port after the server starts listening. */\n  updatePort: (port: number) => void\n}\n\n/**\n * Attempt to acquire an exclusive lock for the workbench process.\n * Uses `O_EXCL` (the `wx` flag) which is atomic at the OS level — only one\n * process can create the file.\n *\n * The lock stores `{pid, host, port}` so other processes can find the\n * running workbench. Call `updatePort` after the Vite server starts to\n * write the actual port (Vite may pick a different one).\n *\n * @returns A {@link WorkbenchLock} if acquired, or `undefined` if another\n *          live process already holds it.\n */\nexport function acquireWorkbenchLock(\n  info: {host: string; port: number},\n  retries = 1,\n): WorkbenchLock | undefined {\n  const registryDir = getRegistryDir()\n  mkdirSync(registryDir, {recursive: true})\n\n  const lockPath = join(registryDir, 'workbench.lock')\n  const startedAt = ownStartedAt()\n  const lockData = {\n    host: info.host,\n    pid: process.pid,\n    port: info.port,\n    startedAt,\n    version: REGISTRY_VERSION,\n  }\n\n  devDebug('Acquiring workbench lock at %s', lockPath)\n\n  try {\n    writeFileSync(lockPath, JSON.stringify(lockData), {flag: 'wx'})\n    devDebug('Workbench lock acquired')\n    return {\n      release() {\n        try {\n          unlinkSync(lockPath)\n        } catch {\n          // Already cleaned up\n        }\n      },\n      updatePort(port: number) {\n        writeFileSync(lockPath, JSON.stringify({...lockData, port}))\n      },\n    }\n  } catch (err: unknown) {\n    devDebug(\n      'Failed to acquire workbench lock: %s',\n      err instanceof Error ? err.message : String(err),\n    )\n    if (!isNodeError(err) || err.code !== 'EEXIST') return undefined\n\n    // Lock exists — check if the holder is still alive\n    const existing = readWorkbenchLock()\n    if (existing) return undefined\n\n    // Stale lock was pruned by readWorkbenchLock — retry (with guard against infinite recursion)\n    if (retries <= 0) return undefined\n    return acquireWorkbenchLock(info, retries - 1)\n  }\n}\n\nfunction isNodeError(err: unknown): err is NodeJS.ErrnoException {\n  return err instanceof Error && 'code' in err\n}\n"],"names":["existsSync","mkdirSync","readdirSync","readFileSync","unlinkSync","watch","writeFileSync","join","coreAppManifestSchema","getSanityDataDir","studioManifestSchema","subdebug","z","canonicalizeWatchDir","getProcessStartTime","isOurProcess","devDebug","REGISTRY_VERSION","ownStartedAt","process","pid","Date","toISOString","devServerManifestSchema","object","host","string","id","optional","interfaces","array","entry_point","interface_type","name","manifest","union","manifestUpdatedAt","number","port","projectId","startedAt","type","enum","version","literal","workDir","getRegistryDir","registerDevServer","registryDir","recursive","current","filePath","JSON","stringify","released","release","update","patch","getRegisteredServers","files","filter","f","endsWith","servers","file","raw","parse","data","success","safeParse","push","watchRegistry","callback","watchDir","debounceTimer","notify","clearTimeout","setTimeout","watcher","close","workbenchLockSchema","readWorkbenchLock","lockPath","contents","undefined","parseLockContents","pruneWorkbenchLock","acquireWorkbenchLock","info","retries","lockData","flag","updatePort","err","Error","message","String","isNodeError","code","existing"],"mappings":"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"}

package/dist/actions/init/cliConfig.js

@@ -0,0 +1,45 @@
+// `sanity.cli.ts` templates for workbench (`unstable_defineApp`) projects,
+// consumed by the CLI's `init` scaffolding. The branded `unstable_defineApp`
+// result is the sole workbench (module-federation) opt-in, so its config shape
+// is workbench's to own; the CLI keeps the non-workbench templates and the
+// `%placeholder%` substitution. `%name%`/`%title%`/etc. are filled in by the
+// CLI's template processor.
+/** App scaffold — `entry` auto-declares the navigable app view. */ export const workbenchAppConfigTemplate = `
+import {defineCliConfig, unstable_defineApp} from 'sanity/cli'
+
+export default defineCliConfig({
+  app: unstable_defineApp({
+    name: '%name%',
+    title: '%title%',
+    organizationId: '%organizationId%',
+    entry: '%entry%',
+  }),
+})
+`;
+/**
+ * Studio scaffold — brands with name/title only, no `entry` (studio app views
+ * aren't implemented yet).
+ */ export const workbenchStudioConfigTemplate = `
+import {defineCliConfig, unstable_defineApp} from 'sanity/cli'
+
+export default defineCliConfig({
+  api: {
+    projectId: '%projectId%',
+    dataset: '%dataset%'
+  },
+  app: unstable_defineApp({
+    name: '%name%',
+    title: '%title%',
+    organizationId: '%organizationId%',
+  }),
+  deployment: {
+    /**
+     * Enable auto-updates for studios.
+     * Learn more at https://www.sanity.io/docs/studio/latest-version-of-sanity#k47faf43faf56
+     */
+    autoUpdates: __BOOL__autoUpdates__,
+  },
+})
+`;
+
+//# sourceMappingURL=cliConfig.js.map

package/dist/actions/init/cliConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/actions/init/cliConfig.ts"],"sourcesContent":["// `sanity.cli.ts` templates for workbench (`unstable_defineApp`) projects,\n// consumed by the CLI's `init` scaffolding. The branded `unstable_defineApp`\n// result is the sole workbench (module-federation) opt-in, so its config shape\n// is workbench's to own; the CLI keeps the non-workbench templates and the\n// `%placeholder%` substitution. `%name%`/`%title%`/etc. are filled in by the\n// CLI's template processor.\n\n/** App scaffold — `entry` auto-declares the navigable app view. */\nexport const workbenchAppConfigTemplate = `\nimport {defineCliConfig, unstable_defineApp} from 'sanity/cli'\n\nexport default defineCliConfig({\n  app: unstable_defineApp({\n    name: '%name%',\n    title: '%title%',\n    organizationId: '%organizationId%',\n    entry: '%entry%',\n  }),\n})\n`\n\n/**\n * Studio scaffold — brands with name/title only, no `entry` (studio app views\n * aren't implemented yet).\n */\nexport const workbenchStudioConfigTemplate = `\nimport {defineCliConfig, unstable_defineApp} from 'sanity/cli'\n\nexport default defineCliConfig({\n  api: {\n    projectId: '%projectId%',\n    dataset: '%dataset%'\n  },\n  app: unstable_defineApp({\n    name: '%name%',\n    title: '%title%',\n    organizationId: '%organizationId%',\n  }),\n  deployment: {\n    /**\n     * Enable auto-updates for studios.\n     * Learn more at https://www.sanity.io/docs/studio/latest-version-of-sanity#k47faf43faf56\n     */\n    autoUpdates: __BOOL__autoUpdates__,\n  },\n})\n`\n"],"names":["workbenchAppConfigTemplate","workbenchStudioConfigTemplate"],"mappings":"AAAA,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAC/E,2EAA2E;AAC3E,6EAA6E;AAC7E,4BAA4B;AAE5B,iEAAiE,GACjE,OAAO,MAAMA,6BAA6B,CAAC;;;;;;;;;;;AAW3C,CAAC,CAAA;AAED;;;CAGC,GACD,OAAO,MAAMC,gCAAgC,CAAC;;;;;;;;;;;;;;;;;;;;;AAqB9C,CAAC,CAAA"}

package/dist/contract.js

@@ -0,0 +1,66 @@
+import { z } from 'zod/mini';
+// The shared kernel of the module-federation extension contract: the supported
+// view/service types, the contract versions the helpers stamp, and the
+// declaration schemas an app author writes in `unstable_defineApp({views, services})`.
+//
+// Lives in `@sanity/workbench-cli` (alongside the vite plugin that consumes the
+// same contract) so there is a single source of truth. `zod/mini` is used
+// throughout workbench-cli to keep bundles small.
+/**
+ * Contract version stamped on every defined view — lets the host and the
+ * generated artifact evolve the contract without breaking deployed views.
+ * @internal
+ */ export const VIEW_CONTRACT_VERSION = 1;
+/**
+ * Contract version stamped on every defined service. Lets the workbench host
+ * and the generated worker artifact evolve the service contract without
+ * breaking already-deployed services; bumped only on a breaking change.
+ * @internal
+ */ export const SERVICE_CONTRACT_VERSION = 1;
+/**
+ * Component slots each interface type exposes, in render order — the source of
+ * truth for {@link InterfaceType} and for the build (the vite plugin expands a
+ * view into one render artifact per component). Add a type by registering it here.
+ * @internal
+ */ export const VIEW_COMPONENTS = {
+    panel: [
+        'title',
+        'panel'
+    ]
+};
+/**
+ * Fields every extension declaration shares — a view or a service. The shape is
+ * identical (`name` + `src`); `kind` only tailors the validation message. Each
+ * declaration adds its `type` discriminator on top.
+ */ function extensionDeclarationFields(kind) {
+    const pattern = /^[a-zA-Z0-9_-]+$/;
+    return {
+        name: z.string().check(z.regex(pattern, `${kind} \`name\` must match ${pattern}`)),
+        src: z.string()
+    };
+}
+/** What an author writes for a `panel` in `unstable_defineApp({views})`. */ const PanelViewSchema = z.object({
+    type: z.literal('panel'),
+    ...extensionDeclarationFields('View')
+});
+/**
+ * The `{type, name, src}` an app declares for a view, discriminated by `type`.
+ * Persisted to the application service on deploy; never part of the app manifest.
+ * @internal
+ */ export const InterfaceDeclarationSchema = z.discriminatedUnion('type', [
+    PanelViewSchema
+]);
+/** Declaration schema for a `worker` service — what a developer writes in `unstable_defineApp({services})`. */ const WorkerServiceSchema = z.object({
+    type: z.literal('worker'),
+    ...extensionDeclarationFields('Service')
+});
+/**
+ * A service declared on an app, discriminated by `type`. Metadata only; built
+ * into a worker artifact and persisted to the application service on deploy,
+ * never part of the app manifest.
+ * @internal
+ */ export const ServiceDeclarationSchema = z.discriminatedUnion('type', [
+    WorkerServiceSchema
+]);
+
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contract.ts"],"sourcesContent":["import {z} from 'zod/mini'\n\n// The shared kernel of the module-federation extension contract: the supported\n// view/service types, the contract versions the helpers stamp, and the\n// declaration schemas an app author writes in `unstable_defineApp({views, services})`.\n//\n// Lives in `@sanity/workbench-cli` (alongside the vite plugin that consumes the\n// same contract) so there is a single source of truth. `zod/mini` is used\n// throughout workbench-cli to keep bundles small.\n\n/**\n * Contract version stamped on every defined view — lets the host and the\n * generated artifact evolve the contract without breaking deployed views.\n * @internal\n */\nexport const VIEW_CONTRACT_VERSION = 1\n\n/**\n * Contract version stamped on every defined service. Lets the workbench host\n * and the generated worker artifact evolve the service contract without\n * breaking already-deployed services; bumped only on a breaking change.\n * @internal\n */\nexport const SERVICE_CONTRACT_VERSION = 1\n\n/**\n * A view component. The return is opaque so the runtime helpers carry no React\n * dependency — the generated artifact renders it with the app's own React.\n * @public\n */\nexport type ViewComponent<TProps> = (props: TProps) => unknown\n\n/**\n * Props every view component receives, whatever its type. Per-type props\n * compose from this, so a prop added here reaches every view.\n * @public\n */\nexport interface ViewComponentBaseProps<TView> {\n  view: TView\n}\n\n/**\n * Component slots each interface type exposes, in render order — the source of\n * truth for {@link InterfaceType} and for the build (the vite plugin expands a\n * view into one render artifact per component). Add a type by registering it here.\n * @internal\n */\nexport const VIEW_COMPONENTS = {\n  panel: ['title', 'panel'],\n} as const satisfies Record<string, readonly string[]>\n\n/**\n * Every supported interface type — the first argument to `unstable_defineView`.\n * @public\n */\nexport type InterfaceType = keyof typeof VIEW_COMPONENTS\n\n/**\n * Every supported service type — the first argument to `unstable_defineService`.\n * Add a service type by adding its declaration schema below and registering it\n * here.\n * @public\n */\nexport type ServiceType = 'worker'\n\n/**\n * Fields every extension declaration shares — a view or a service. The shape is\n * identical (`name` + `src`); `kind` only tailors the validation message. Each\n * declaration adds its `type` discriminator on top.\n */\nfunction extensionDeclarationFields(kind: 'Service' | 'View') {\n  const pattern = /^[a-zA-Z0-9_-]+$/\n  return {\n    name: z.string().check(z.regex(pattern, `${kind} \\`name\\` must match ${pattern}`)),\n    src: z.string(),\n  }\n}\n\n/** What an author writes for a `panel` in `unstable_defineApp({views})`. */\nconst PanelViewSchema = z.object({\n  type: z.literal('panel'),\n  ...extensionDeclarationFields('View'),\n})\n\n/**\n * The `{type, name, src}` an app declares for a view, discriminated by `type`.\n * Persisted to the application service on deploy; never part of the app manifest.\n * @internal\n */\nexport const InterfaceDeclarationSchema = z.discriminatedUnion('type', [PanelViewSchema])\n\n/** Declaration schema for a `worker` service — what a developer writes in `unstable_defineApp({services})`. */\nconst WorkerServiceSchema = z.object({\n  type: z.literal('worker'),\n  ...extensionDeclarationFields('Service'),\n})\n\n/**\n * A service declared on an app, discriminated by `type`. Metadata only; built\n * into a worker artifact and persisted to the application service on deploy,\n * never part of the app manifest.\n * @internal\n */\nexport const ServiceDeclarationSchema = z.discriminatedUnion('type', [WorkerServiceSchema])\n"],"names":["z","VIEW_CONTRACT_VERSION","SERVICE_CONTRACT_VERSION","VIEW_COMPONENTS","panel","extensionDeclarationFields","kind","pattern","name","string","check","regex","src","PanelViewSchema","object","type","literal","InterfaceDeclarationSchema","discriminatedUnion","WorkerServiceSchema","ServiceDeclarationSchema"],"mappings":"AAAA,SAAQA,CAAC,QAAO,WAAU;AAE1B,+EAA+E;AAC/E,uEAAuE;AACvE,uFAAuF;AACvF,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,kDAAkD;AAElD;;;;CAIC,GACD,OAAO,MAAMC,wBAAwB,EAAC;AAEtC;;;;;CAKC,GACD,OAAO,MAAMC,2BAA2B,EAAC;AAkBzC;;;;;CAKC,GACD,OAAO,MAAMC,kBAAkB;IAC7BC,OAAO;QAAC;QAAS;KAAQ;AAC3B,EAAsD;AAgBtD;;;;CAIC,GACD,SAASC,2BAA2BC,IAAwB;IAC1D,MAAMC,UAAU;IAChB,OAAO;QACLC,MAAMR,EAAES,MAAM,GAAGC,KAAK,CAACV,EAAEW,KAAK,CAACJ,SAAS,GAAGD,KAAK,qBAAqB,EAAEC,SAAS;QAChFK,KAAKZ,EAAES,MAAM;IACf;AACF;AAEA,0EAA0E,GAC1E,MAAMI,kBAAkBb,EAAEc,MAAM,CAAC;IAC/BC,MAAMf,EAAEgB,OAAO,CAAC;IAChB,GAAGX,2BAA2B,OAAO;AACvC;AAEA;;;;CAIC,GACD,OAAO,MAAMY,6BAA6BjB,EAAEkB,kBAAkB,CAAC,QAAQ;IAACL;CAAgB,EAAC;AAEzF,6GAA6G,GAC7G,MAAMM,sBAAsBnB,EAAEc,MAAM,CAAC;IACnCC,MAAMf,EAAEgB,OAAO,CAAC;IAChB,GAAGX,2BAA2B,UAAU;AAC1C;AAEA;;;;;CAKC,GACD,OAAO,MAAMe,2BAA2BpB,EAAEkB,kBAAkB,CAAC,QAAQ;IAACC;CAAoB,EAAC"}

package/dist/defineApp.js

@@ -0,0 +1,82 @@
+import { z } from 'zod/mini';
+import { InterfaceDeclarationSchema, ServiceDeclarationSchema } from './contract.js';
+/** Allowed characters for an app `name`. */ const APP_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Internal application discriminator. Sanity-owned singleton apps only;
+ * validated by the schema but excluded from the public `DefineAppInput` type.
+ */ const ApplicationType = z.enum([
+    'coreApp',
+    'studio',
+    'canvas',
+    'dashboard',
+    'media-library'
+]);
+/** Dock groups an app can place itself into. */ const DockGroupSchema = z.enum([
+    'dock.system',
+    'dock.applications',
+    'dock.user'
+]);
+/**
+ * Runtime-validation schema for `unstable_defineApp`. Validates the full shape
+ * including the internal `applicationType`; the user-facing `DefineAppInput`
+ * type below omits that field.
+ * @internal
+ */ export const DefineAppInputSchema = z.object({
+    /**
+     * Internal — Sanity-owned singleton apps only. Validated here but excluded
+     * from the public `DefineAppInput` type.
+     * @internal
+     */ applicationType: z.optional(ApplicationType),
+    /**
+     * App entrypoint module. Defaults to `./src/App.tsx` when omitted. The build
+     * derives the app's navigable `app` view from it. SDK apps only — setting it
+     * on a studio is rejected (studio app views are not yet implemented).
+     */ entry: z.optional(z.string()),
+    /** Dock group to render in. Defaults to `dock.applications` when omitted. */ group: z.optional(DockGroupSchema),
+    /** Optional icon override (path to an SVG). Wins over manifest/studio icon. */ icon: z.optional(z.string()),
+    /** Unique app identifier — must match `APP_NAME_PATTERN`. */ name: z.string().check(z.regex(APP_NAME_PATTERN, 'App `name` must match /^[a-zA-Z0-9_-]+$/')),
+    /** Organization that owns the app — the workbench runs and deploys against it. */ organizationId: z.string("App `organizationId` is required — pass the owning organization's ID to `unstable_defineApp`"),
+    /** Sort position within the group, ascending. Defaults to `100` when omitted. */ priority: z.optional(z.number()),
+    /**
+     * Background services the app runs (e.g. a `worker` emitting dock badges).
+     * Metadata only — built into worker artifacts and persisted to the
+     * application service on deploy, not into the app manifest. Service `name`s
+     * must be unique within the app.
+     */ services: z.optional(z.array(ServiceDeclarationSchema).check(z.refine((services)=>new Set(services.map((service)=>service.name)).size === services.length, 'Service `name` must be unique within an app'))),
+    /** User-facing app title. Wins over studio.config.ts title on merge. */ title: z.string(),
+    /**
+     * Views the app exposes (e.g. dock panels). Metadata only — built into
+     * render artifacts and persisted to the application service on deploy, not
+     * into the app manifest. View `name`s must be unique within the app.
+     */ views: z.optional(z.array(InterfaceDeclarationSchema).check(z.refine((views)=>new Set(views.map((view)=>view.name)).size === views.length, 'View `name` must be unique within an app')))
+}).check(// Studio app views are not implemented yet. A studio that declares `entry`
+// (the SDK app-view entrypoint) is rejected here rather than silently
+// generating one; studios keep navigating via their existing render path.
+z.refine((input)=>!(input.applicationType === 'studio' && input.entry !== undefined), {
+    error: 'App views for studios are not implemented yet',
+    path: [
+        'entry'
+    ]
+}));
+/**
+ * Nominal brand the CLI discriminates on to enable the workbench build/deploy
+ * codepath. Registered via `Symbol.for` so the marker survives module-realm
+ * boundaries — `@sanity/cli-core` re-derives the same global symbol with
+ * `Symbol.for` rather than importing it, so it stays internal to this module.
+ */ const WORKBENCH_APP = Symbol.for('sanity.workbench.defineApp');
+/**
+ * Declare a Sanity Workbench application. Identity at runtime — returns the same
+ * object reference, tagged with the workbench brand. Field validation (the
+ * `name` pattern etc.) runs at build time in the CLI via `DefineAppInputSchema`;
+ * this helper stays a thin, pure identity wrapper.
+ * @public
+ */ export function unstable_defineApp(input) {
+    return Object.defineProperty(input, WORKBENCH_APP, {
+        configurable: false,
+        enumerable: false,
+        value: true,
+        writable: false
+    });
+}
+
+//# sourceMappingURL=defineApp.js.map

package/dist/defineApp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/defineApp.ts"],"sourcesContent":["import {z} from 'zod/mini'\n\nimport {InterfaceDeclarationSchema, ServiceDeclarationSchema} from './contract.js'\n\n/** Allowed characters for an app `name`. */\nconst APP_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/\n\n/**\n * Internal application discriminator. Sanity-owned singleton apps only;\n * validated by the schema but excluded from the public `DefineAppInput` type.\n */\nconst ApplicationType = z.enum(['coreApp', 'studio', 'canvas', 'dashboard', 'media-library'])\n\n/** Dock groups an app can place itself into. */\nconst DockGroupSchema = z.enum(['dock.system', 'dock.applications', 'dock.user'])\n\n/**\n * Dock group identifier. The API does not block a user app from declaring a\n * reserved group (e.g. `dock.system`); priority conventions keep Sanity-owned\n * apps ahead.\n * @public\n */\nexport type DockGroup = z.output<typeof DockGroupSchema>\n\n/**\n * Runtime-validation schema for `unstable_defineApp`. Validates the full shape\n * including the internal `applicationType`; the user-facing `DefineAppInput`\n * type below omits that field.\n * @internal\n */\nexport const DefineAppInputSchema = z\n  .object({\n    /**\n     * Internal — Sanity-owned singleton apps only. Validated here but excluded\n     * from the public `DefineAppInput` type.\n     * @internal\n     */\n    applicationType: z.optional(ApplicationType),\n    /**\n     * App entrypoint module. Defaults to `./src/App.tsx` when omitted. The build\n     * derives the app's navigable `app` view from it. SDK apps only — setting it\n     * on a studio is rejected (studio app views are not yet implemented).\n     */\n    entry: z.optional(z.string()),\n    /** Dock group to render in. Defaults to `dock.applications` when omitted. */\n    group: z.optional(DockGroupSchema),\n    /** Optional icon override (path to an SVG). Wins over manifest/studio icon. */\n    icon: z.optional(z.string()),\n    /** Unique app identifier — must match `APP_NAME_PATTERN`. */\n    name: z.string().check(z.regex(APP_NAME_PATTERN, 'App `name` must match /^[a-zA-Z0-9_-]+$/')),\n    /** Organization that owns the app — the workbench runs and deploys against it. */\n    organizationId: z.string(\n      \"App `organizationId` is required — pass the owning organization's ID to `unstable_defineApp`\",\n    ),\n    /** Sort position within the group, ascending. Defaults to `100` when omitted. */\n    priority: z.optional(z.number()),\n    /**\n     * Background services the app runs (e.g. a `worker` emitting dock badges).\n     * Metadata only — built into worker artifacts and persisted to the\n     * application service on deploy, not into the app manifest. Service `name`s\n     * must be unique within the app.\n     */\n    services: z.optional(\n      z\n        .array(ServiceDeclarationSchema)\n        .check(\n          z.refine(\n            (services) => new Set(services.map((service) => service.name)).size === services.length,\n            'Service `name` must be unique within an app',\n          ),\n        ),\n    ),\n    /** User-facing app title. Wins over studio.config.ts title on merge. */\n    title: z.string(),\n    /**\n     * Views the app exposes (e.g. dock panels). Metadata only — built into\n     * render artifacts and persisted to the application service on deploy, not\n     * into the app manifest. View `name`s must be unique within the app.\n     */\n    views: z.optional(\n      z\n        .array(InterfaceDeclarationSchema)\n        .check(\n          z.refine(\n            (views) => new Set(views.map((view) => view.name)).size === views.length,\n            'View `name` must be unique within an app',\n          ),\n        ),\n    ),\n  })\n  .check(\n    // Studio app views are not implemented yet. A studio that declares `entry`\n    // (the SDK app-view entrypoint) is rejected here rather than silently\n    // generating one; studios keep navigating via their existing render path.\n    z.refine((input) => !(input.applicationType === 'studio' && input.entry !== undefined), {\n      error: 'App views for studios are not implemented yet',\n      path: ['entry'],\n    }),\n  )\n\n/**\n * User-facing input for `unstable_defineApp`. Excludes the internal\n * `applicationType` — that field is validated by the schema but is not part of\n * the public surface (Sanity-owned apps set it via `@ts-expect-error`).\n * @public\n */\nexport type DefineAppInput = Omit<z.output<typeof DefineAppInputSchema>, 'applicationType'>\n\n/**\n * Nominal brand the CLI discriminates on to enable the workbench build/deploy\n * codepath. Registered via `Symbol.for` so the marker survives module-realm\n * boundaries — `@sanity/cli-core` re-derives the same global symbol with\n * `Symbol.for` rather than importing it, so it stays internal to this module.\n */\nconst WORKBENCH_APP: unique symbol = Symbol.for('sanity.workbench.defineApp')\n\n/**\n * The branded result of `unstable_defineApp`. Carries the same fields as the\n * input plus the internal brand — users only ever see `DefineAppInput`.\n * @public\n */\nexport interface DefineAppResult extends DefineAppInput {\n  readonly [WORKBENCH_APP]: true\n}\n\n/**\n * Declare a Sanity Workbench application. Identity at runtime — returns the same\n * object reference, tagged with the workbench brand. Field validation (the\n * `name` pattern etc.) runs at build time in the CLI via `DefineAppInputSchema`;\n * this helper stays a thin, pure identity wrapper.\n * @public\n */\nexport function unstable_defineApp(input: DefineAppInput): DefineAppResult {\n  return Object.defineProperty(input, WORKBENCH_APP, {\n    configurable: false,\n    enumerable: false,\n    value: true,\n    writable: false,\n  }) as DefineAppResult\n}\n"],"names":["z","InterfaceDeclarationSchema","ServiceDeclarationSchema","APP_NAME_PATTERN","ApplicationType","enum","DockGroupSchema","DefineAppInputSchema","object","applicationType","optional","entry","string","group","icon","name","check","regex","organizationId","priority","number","services","array","refine","Set","map","service","size","length","title","views","view","input","undefined","error","path","WORKBENCH_APP","Symbol","for","unstable_defineApp","Object","defineProperty","configurable","enumerable","value","writable"],"mappings":"AAAA,SAAQA,CAAC,QAAO,WAAU;AAE1B,SAAQC,0BAA0B,EAAEC,wBAAwB,QAAO,gBAAe;AAElF,0CAA0C,GAC1C,MAAMC,mBAAmB;AAEzB;;;CAGC,GACD,MAAMC,kBAAkBJ,EAAEK,IAAI,CAAC;IAAC;IAAW;IAAU;IAAU;IAAa;CAAgB;AAE5F,8CAA8C,GAC9C,MAAMC,kBAAkBN,EAAEK,IAAI,CAAC;IAAC;IAAe;IAAqB;CAAY;AAUhF;;;;;CAKC,GACD,OAAO,MAAME,uBAAuBP,EACjCQ,MAAM,CAAC;IACN;;;;KAIC,GACDC,iBAAiBT,EAAEU,QAAQ,CAACN;IAC5B;;;;KAIC,GACDO,OAAOX,EAAEU,QAAQ,CAACV,EAAEY,MAAM;IAC1B,2EAA2E,GAC3EC,OAAOb,EAAEU,QAAQ,CAACJ;IAClB,6EAA6E,GAC7EQ,MAAMd,EAAEU,QAAQ,CAACV,EAAEY,MAAM;IACzB,2DAA2D,GAC3DG,MAAMf,EAAEY,MAAM,GAAGI,KAAK,CAAChB,EAAEiB,KAAK,CAACd,kBAAkB;IACjD,gFAAgF,GAChFe,gBAAgBlB,EAAEY,MAAM,CACtB;IAEF,+EAA+E,GAC/EO,UAAUnB,EAAEU,QAAQ,CAACV,EAAEoB,MAAM;IAC7B;;;;;KAKC,GACDC,UAAUrB,EAAEU,QAAQ,CAClBV,EACGsB,KAAK,CAACpB,0BACNc,KAAK,CACJhB,EAAEuB,MAAM,CACN,CAACF,WAAa,IAAIG,IAAIH,SAASI,GAAG,CAAC,CAACC,UAAYA,QAAQX,IAAI,GAAGY,IAAI,KAAKN,SAASO,MAAM,EACvF;IAIR,sEAAsE,GACtEC,OAAO7B,EAAEY,MAAM;IACf;;;;KAIC,GACDkB,OAAO9B,EAAEU,QAAQ,CACfV,EACGsB,KAAK,CAACrB,4BACNe,KAAK,CACJhB,EAAEuB,MAAM,CACN,CAACO,QAAU,IAAIN,IAAIM,MAAML,GAAG,CAAC,CAACM,OAASA,KAAKhB,IAAI,GAAGY,IAAI,KAAKG,MAAMF,MAAM,EACxE;AAIV,GACCZ,KAAK,CACJ,2EAA2E;AAC3E,sEAAsE;AACtE,0EAA0E;AAC1EhB,EAAEuB,MAAM,CAAC,CAACS,QAAU,CAAEA,CAAAA,MAAMvB,eAAe,KAAK,YAAYuB,MAAMrB,KAAK,KAAKsB,SAAQ,GAAI;IACtFC,OAAO;IACPC,MAAM;QAAC;KAAQ;AACjB,IACD;AAUH;;;;;CAKC,GACD,MAAMC,gBAA+BC,OAAOC,GAAG,CAAC;AAWhD;;;;;;CAMC,GACD,OAAO,SAASC,mBAAmBP,KAAqB;IACtD,OAAOQ,OAAOC,cAAc,CAACT,OAAOI,eAAe;QACjDM,cAAc;QACdC,YAAY;QACZC,OAAO;QACPC,UAAU;IACZ;AACF"}

package/dist/defineService.js

@@ -0,0 +1,19 @@
+import { SERVICE_CONTRACT_VERSION } from './contract.js';
+/**
+ * Define a Sanity Workbench background service. The first argument narrows the
+ * callback shape — `"worker"` runs the callback inside a Web Worker, where it
+ * can emit dock-badge updates and return a disposer.
+ *
+ * Identity at runtime: returns the callback tagged with its type and the contract
+ * version, for the CLI build to generate a worker artifact from. Used as the
+ * default export of a service's `src` file.
+ * @public
+ */ export function unstable_defineService(type, run) {
+    return {
+        run,
+        type,
+        version: SERVICE_CONTRACT_VERSION
+    };
+}
+
+//# sourceMappingURL=defineService.js.map

package/dist/defineService.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/defineService.ts"],"sourcesContent":["import {SERVICE_CONTRACT_VERSION, type ServiceType} from './contract.js'\n\n/**\n * The service's own declaration, surfaced to the callback.\n * @public\n */\nexport interface ServiceInfo {\n  readonly name: string\n  readonly type: string\n}\n\n/**\n * Context every service callback receives when its worker starts. Mirrors how a\n * view component receives its `view` — the service receives its own `service`.\n * @public\n */\nexport interface ServiceContext {\n  readonly service: ServiceInfo\n}\n\n/**\n * A service callback. Runs once inside the worker on start; returns an optional\n * disposer the host calls before terminating the worker.\n * @public\n */\nexport type ServiceCallback = (context: ServiceContext) => (() => void) | void\n\n/** The callback shape each service type defines, keyed by type. */\ninterface ServiceCallbacksByType {\n  worker: ServiceCallback\n}\n\n/**\n * The result of `unstable_defineService`: the author's callback, the service\n * type, and the internal contract version the worker artifact targets.\n * @public\n */\nexport interface DefinedService<TType extends ServiceType = ServiceType> {\n  readonly run: ServiceCallbacksByType[TType]\n  readonly type: TType\n  /** @internal */\n  readonly version: typeof SERVICE_CONTRACT_VERSION\n}\n\n/**\n * Define a Sanity Workbench background service. The first argument narrows the\n * callback shape — `\"worker\"` runs the callback inside a Web Worker, where it\n * can emit dock-badge updates and return a disposer.\n *\n * Identity at runtime: returns the callback tagged with its type and the contract\n * version, for the CLI build to generate a worker artifact from. Used as the\n * default export of a service's `src` file.\n * @public\n */\nexport function unstable_defineService<TType extends ServiceType>(\n  type: TType,\n  run: ServiceCallbacksByType[TType],\n): DefinedService<TType> {\n  return {run, type, version: SERVICE_CONTRACT_VERSION}\n}\n"],"names":["SERVICE_CONTRACT_VERSION","unstable_defineService","type","run","version"],"mappings":"AAAA,SAAQA,wBAAwB,QAAyB,gBAAe;AA4CxE;;;;;;;;;CASC,GACD,OAAO,SAASC,uBACdC,IAAW,EACXC,GAAkC;IAElC,OAAO;QAACA;QAAKD;QAAME,SAASJ;IAAwB;AACtD"}

package/dist/defineView.js

@@ -0,0 +1,19 @@
+import { VIEW_CONTRACT_VERSION } from './contract.js';
+/**
+ * Define a Sanity Workbench view. The first argument narrows the component shape
+ * and the props each component receives — `"panel"` yields a `{title, panel}`
+ * record whose components are typed with the panel props.
+ *
+ * Returns the component(s) tagged with their type and the contract version, for
+ * the CLI build to generate render artifacts from. Used as the default export of
+ * a view's `src` file.
+ * @public
+ */ export function unstable_defineView(type, components) {
+    return {
+        components,
+        type,
+        version: VIEW_CONTRACT_VERSION
+    };
+}
+
+//# sourceMappingURL=defineView.js.map

package/dist/defineView.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/defineView.ts"],"sourcesContent":["import {\n  type InterfaceType,\n  VIEW_CONTRACT_VERSION,\n  type ViewComponent,\n  type ViewComponentBaseProps,\n} from './contract.js'\n\n/**\n * Props a panel component receives: its interface record, minus the\n * service-assigned `id`/`deployment_id` a local dev server can't provide. Mirrors\n * the `panel` record the workbench host renders from (the wire format owned by\n * `@sanity/workbench`); drift is guarded by the stamped contract version.\n * @public\n */\nexport type PanelViewProps = ViewComponentBaseProps<{\n  entry_point: string\n  interface_type: 'panel'\n  name: string\n}>\n\n/**\n * The component slots a `panel` view exposes — each its own module-federation\n * island, typed with the panel props.\n * @public\n */\nexport interface PanelViewComponents {\n  panel: ViewComponent<PanelViewProps>\n  title: ViewComponent<PanelViewProps>\n}\n\n/**\n * A panel's view-component slot — the module-federation expose for one island.\n * @public\n */\nexport type PanelComponent = keyof PanelViewComponents\n\n/**\n * The components each interface type exposes, keyed by type.\n * @public\n */\nexport interface ViewComponentsByType {\n  panel: PanelViewComponents\n}\n\n/**\n * The result of `unstable_defineView`: the author's component(s), the view type,\n * and the internal contract version the build artifact targets.\n * @public\n */\nexport interface DefinedView<TType extends InterfaceType = InterfaceType> {\n  readonly components: ViewComponentsByType[TType]\n  readonly type: TType\n  /** @internal */\n  readonly version: typeof VIEW_CONTRACT_VERSION\n}\n\n/**\n * Define a Sanity Workbench view. The first argument narrows the component shape\n * and the props each component receives — `\"panel\"` yields a `{title, panel}`\n * record whose components are typed with the panel props.\n *\n * Returns the component(s) tagged with their type and the contract version, for\n * the CLI build to generate render artifacts from. Used as the default export of\n * a view's `src` file.\n * @public\n */\nexport function unstable_defineView<TType extends InterfaceType>(\n  type: TType,\n  components: ViewComponentsByType[TType],\n): DefinedView<TType> {\n  return {components, type, version: VIEW_CONTRACT_VERSION}\n}\n"],"names":["VIEW_CONTRACT_VERSION","unstable_defineView","type","components","version"],"mappings":"AAAA,SAEEA,qBAAqB,QAGhB,gBAAe;AAmDtB;;;;;;;;;CASC,GACD,OAAO,SAASC,oBACdC,IAAW,EACXC,UAAuC;IAEvC,OAAO;QAACA;QAAYD;QAAME,SAASJ;IAAqB;AAC1D"}

package/dist/resolveWorkbenchApp.js

@@ -0,0 +1,21 @@
+// Package-internal shared resolver: turn a CLI config's branded
+// `unstable_defineApp` app into its declared interfaces, or `null` for a plain
+// project. The build and deploy accessors (actions/build, actions/deploy) each
+// build their command-specific view on top of this one brand-check +
+// extraction, so the discrimination lives in exactly one place.
+import { isWorkbenchApp } from '@sanity/cli-core';
+/**
+ * Resolve the workbench app for a CLI config, or `null` for a plain project.
+ * @public
+ */ export function resolveWorkbenchApp(cliConfig) {
+    const app = cliConfig?.app;
+    if (!isWorkbenchApp(app)) return null;
+    return {
+        applicationType: app.applicationType,
+        entry: app.entry,
+        services: app.services ?? [],
+        views: app.views ?? []
+    };
+}
+
+//# sourceMappingURL=resolveWorkbenchApp.js.map

package/dist/resolveWorkbenchApp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resolveWorkbenchApp.ts"],"sourcesContent":["// Package-internal shared resolver: turn a CLI config's branded\n// `unstable_defineApp` app into its declared interfaces, or `null` for a plain\n// project. The build and deploy accessors (actions/build, actions/deploy) each\n// build their command-specific view on top of this one brand-check +\n// extraction, so the discrimination lives in exactly one place.\n\nimport {type CliConfig, isWorkbenchApp} from '@sanity/cli-core'\n\nimport {type DefineAppInput} from './defineApp.js'\n\n/** @public */\nexport interface ResolvedWorkbenchApp {\n  /** Background worker services the app declares. */\n  readonly services: NonNullable<DefineAppInput['services']>\n  /** Dock panel views the app declares. */\n  readonly views: NonNullable<DefineAppInput['views']>\n\n  /** Resolved app kind — `studio` or one of the SDK app types. */\n  readonly applicationType?: string\n  /** SDK app-view entrypoint, when declared. */\n  readonly entry?: string\n}\n\n/**\n * Resolve the workbench app for a CLI config, or `null` for a plain project.\n * @public\n */\nexport function resolveWorkbenchApp(\n  cliConfig: CliConfig | null | undefined,\n): ResolvedWorkbenchApp | null {\n  const app = cliConfig?.app\n  if (!isWorkbenchApp(app)) return null\n  return {\n    applicationType: app.applicationType,\n    entry: app.entry,\n    services: app.services ?? [],\n    views: app.views ?? [],\n  }\n}\n"],"names":["isWorkbenchApp","resolveWorkbenchApp","cliConfig","app","applicationType","entry","services","views"],"mappings":"AAAA,gEAAgE;AAChE,+EAA+E;AAC/E,+EAA+E;AAC/E,qEAAqE;AACrE,gEAAgE;AAEhE,SAAwBA,cAAc,QAAO,mBAAkB;AAiB/D;;;CAGC,GACD,OAAO,SAASC,oBACdC,SAAuC;IAEvC,MAAMC,MAAMD,WAAWC;IACvB,IAAI,CAACH,eAAeG,MAAM,OAAO;IACjC,OAAO;QACLC,iBAAiBD,IAAIC,eAAe;QACpCC,OAAOF,IAAIE,KAAK;QAChBC,UAAUH,IAAIG,QAAQ,IAAI,EAAE;QAC5BC,OAAOJ,IAAII,KAAK,IAAI,EAAE;IACxB;AACF"}