@growthub/cli 0.13.8 → 0.14.0

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/codex-sites-workspace-adapter.js

@@ -0,0 +1,156 @@
+const CODEX_SITES_OBJECT_ID = "workspace-codex-sites";
+const CODEX_SITES_COLUMNS = [
+  "Name",
+  "app",
+  "client",
+  "url",
+  "status",
+  "accessMode",
+  "dashboardId",
+  "lastRecordedAt",
+  "notes"
+];
+const CODEX_SITES_SOURCE_ID = "codex-sites";
+
+function isCodexSiteUrl(value) {
+  return /^https?:\/\//i.test(String(value || "").trim());
+}
+
+function defaultAppSource(apps) {
+  const first = Array.isArray(apps) ? apps.find((app) => app?.source) : null;
+  return first?.source || "apps/workspace";
+}
+
+function createCodexSitesObject(apps = []) {
+  return {
+    id: CODEX_SITES_OBJECT_ID,
+    label: "Codex Sites",
+    source: "Workspace Apps",
+    sourceId: CODEX_SITES_OBJECT_ID,
+    objectType: "custom",
+    icon: "Rocket",
+    columns: CODEX_SITES_COLUMNS,
+    rows: [],
+    binding: {
+      mode: "manual",
+      source: "Settings / Apps",
+      sourceType: "workspace-data-model",
+      sourceAuthority: "workspace-config",
+      objectId: CODEX_SITES_OBJECT_ID,
+      sourceId: CODEX_SITES_SOURCE_ID,
+      entityType: "codex-site",
+      app: defaultAppSource(apps)
+    },
+    fieldSettings: {
+      hidden: [],
+      order: CODEX_SITES_COLUMNS,
+      views: [
+        {
+          id: "codex-sites-live",
+          name: "Live",
+          favorite: true,
+          order: CODEX_SITES_COLUMNS,
+          filter: { op: "and", clauses: [{ fieldId: "status", operator: "eq", value: "live" }] }
+        },
+        {
+          id: "codex-sites-review",
+          name: "Draft & Review",
+          order: CODEX_SITES_COLUMNS,
+          filter: { op: "or", clauses: [
+            { fieldId: "status", operator: "eq", value: "draft" },
+            { fieldId: "status", operator: "eq", value: "review" }
+          ] }
+        }
+      ],
+      activeViewId: "codex-sites-live",
+      types: {
+        Name: "text",
+        app: "text",
+        client: "text",
+        url: "url",
+        status: "select",
+        accessMode: "select",
+        dashboardId: "text",
+        lastRecordedAt: "date",
+        notes: "text"
+      }
+    }
+  };
+}
+
+function normalizeCodexSiteRecord(record = {}) {
+  const url = String(record.url || record.liveUrl || record.current_live_url || "").trim();
+  return {
+    id: String(record.id || record.projectId || record.project_id || record.slug || url).trim(),
+    Name: String(record.Name || record.name || record.title || record.slug || "Codex Site").trim(),
+    app: String(record.app || record.source || "apps/workspace").trim(),
+    client: String(record.client || record.workspace || "Workspace").trim(),
+    url,
+    status: String(record.status || (url ? "live" : "draft")).trim(),
+    accessMode: String(record.accessMode || record.access_mode || "workspace").trim(),
+    dashboardId: String(record.dashboardId || record.dashboard_id || record.slug || record.id || "").trim(),
+    lastRecordedAt: String(record.lastRecordedAt || record.updated_at || record.created_at || "").trim(),
+    notes: String(record.notes || record.description || "").trim()
+  };
+}
+
+function codexSiteRecordToRow(record = {}) {
+  const site = normalizeCodexSiteRecord(record);
+  return {
+    Name: site.Name,
+    app: site.app,
+    client: site.client,
+    url: site.url,
+    status: site.status,
+    accessMode: site.accessMode,
+    dashboardId: site.dashboardId,
+    lastRecordedAt: site.lastRecordedAt || new Date().toISOString(),
+    notes: site.notes
+  };
+}
+
+function recordsFromSourceEntry(entry) {
+  if (Array.isArray(entry)) return entry;
+  if (Array.isArray(entry?.records)) return entry.records;
+  if (Array.isArray(entry?.sites)) return entry.sites;
+  if (Array.isArray(entry?.items)) return entry.items;
+  return [];
+}
+
+function listAvailableCodexSites(workspaceConfig = {}, workspaceSourceRecords = {}) {
+  const sidecarRecords = [
+    ...recordsFromSourceEntry(workspaceSourceRecords?.[CODEX_SITES_SOURCE_ID]),
+    ...recordsFromSourceEntry(workspaceSourceRecords?.[CODEX_SITES_OBJECT_ID])
+  ];
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  const object = objects.find((item) => item?.id === CODEX_SITES_OBJECT_ID);
+  const rowRecords = Array.isArray(object?.rows) ? object.rows : [];
+  const byUrl = new Map();
+  [...sidecarRecords, ...rowRecords].forEach((record) => {
+    const site = normalizeCodexSiteRecord(record);
+    if (!isCodexSiteUrl(site.url)) return;
+    byUrl.set(site.url, site);
+  });
+  return Array.from(byUrl.values());
+}
+
+function ensureCodexSitesDataModel(dataModel, apps = []) {
+  const objects = Array.isArray(dataModel?.objects) ? dataModel.objects : [];
+  if (objects.some((object) => object?.id === CODEX_SITES_OBJECT_ID)) return dataModel || {};
+  return {
+    ...(dataModel || {}),
+    objects: [...objects, createCodexSitesObject(apps)]
+  };
+}
+
+export {
+  CODEX_SITES_COLUMNS,
+  CODEX_SITES_OBJECT_ID,
+  CODEX_SITES_SOURCE_ID,
+  codexSiteRecordToRow,
+  createCodexSitesObject,
+  ensureCodexSitesDataModel,
+  isCodexSiteUrl,
+  listAvailableCodexSites,
+  normalizeCodexSiteRecord
+};

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/creation-error-recovery.js

@@ -0,0 +1,103 @@
+/**
+ * Creation Error Recovery V1 — turns raw failure signals from the creation
+ * lane (test / create / refresh / resolver / read-only runtime) into a
+ * structured, machine-readable recovery the cockpit can render as an exact next
+ * action instead of a generic error string.
+ *
+ * Pure + deterministic. Input is already-safe (callers redact secrets before
+ * passing detail). Output:
+ *   { errorKind, retryable, requiredAction, suggestedRoute, safeDetail }
+ */
+
+function clean(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+const RECOVERY = {
+  missing_auth_ref: {
+    requiredAction: "Set an authRef on this API Registry row, then save the secret in Settings.",
+    suggestedRoute: "/settings",
+    retryable: false,
+  },
+  env_not_configured: {
+    requiredAction: "Save the secret for this authRef in Settings → APIs & Webhooks (writes .env.local), then reopen.",
+    suggestedRoute: "/settings",
+    retryable: true,
+  },
+  api_test_failed: {
+    requiredAction: "Check the baseUrl, endpoint, method, and auth header, then Test again.",
+    suggestedRoute: "",
+    retryable: true,
+  },
+  not_live_backed: {
+    requiredAction: "Recreate the Data Source from the API Registry row so it is live-backed (sourceStorage + integrationId).",
+    suggestedRoute: "/data-model",
+    retryable: false,
+  },
+  missing_resolver: {
+    requiredAction: "Add a resolver for this integration so refresh can shape the response into rows.",
+    suggestedRoute: "/api/workspace/resolver-templates",
+    retryable: true,
+  },
+  missing_integration_id: {
+    requiredAction: "Set the Data Source object's integrationId to match the API Registry integrationId.",
+    suggestedRoute: "/data-model",
+    retryable: false,
+  },
+  source_refresh_failed: {
+    requiredAction: "Re-run Test on the API, confirm the resolver returns rows, then Refresh again.",
+    suggestedRoute: "",
+    retryable: true,
+  },
+  read_only_runtime: {
+    requiredAction: "Set WORKSPACE_CONFIG_ALLOW_FS_WRITE=true on a writable runtime (or edit growthub.config.json locally) to persist this.",
+    suggestedRoute: "",
+    retryable: false,
+  },
+  unknown: {
+    requiredAction: "Retry; if it persists, inspect the response in the row's lastResponse.",
+    suggestedRoute: "",
+    retryable: true,
+  },
+};
+
+/**
+ * Classify a failure from a creation-lane action.
+ *
+ * @param {object} input
+ * @param {string} input.phase      "test" | "create" | "refresh" | "resolver"
+ * @param {number} [input.httpStatus]
+ * @param {string} [input.reason]   route-supplied reason (e.g. "missing-resolver")
+ * @param {string} [input.detail]   already-safe human message
+ * @param {boolean} [input.readOnly] true when persistence is read-only (409)
+ */
+function classifyCreationError(input = {}) {
+  const phase = clean(input.phase);
+  const reason = clean(input.reason).toLowerCase().replace(/-/g, "_");
+  const httpStatus = Number(input.httpStatus) || 0;
+  const detail = clean(input.detail);
+
+  let errorKind = "unknown";
+  if (input.readOnly || httpStatus === 409) {
+    errorKind = "read_only_runtime";
+  } else if (reason && RECOVERY[reason]) {
+    errorKind = reason; // route reasons like missing_resolver / not_live_backed
+  } else if (reason === "not_live_backed") {
+    errorKind = "not_live_backed";
+  } else if (phase === "test") {
+    errorKind = "api_test_failed";
+  } else if (phase === "refresh") {
+    errorKind = "source_refresh_failed";
+  }
+
+  const recovery = RECOVERY[errorKind] || RECOVERY.unknown;
+  return {
+    errorKind,
+    retryable: recovery.retryable,
+    requiredAction: recovery.requiredAction,
+    suggestedRoute: recovery.suggestedRoute,
+    safeDetail: detail || errorKind.replace(/_/g, " "),
+  };
+}
+
+export { classifyCreationError };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/env-status.js

@@ -0,0 +1,100 @@
+/**
+ * Env Status V1 — the honest, secret-safe "which referenced env keys actually
+ * resolve right now" signal.
+ *
+ * The creation cockpit (api-registry drawer) cannot read process.env in the
+ * browser, so auth readiness must come from a server signal. This module is the
+ * pure core of `GET /api/workspace/env-status`: given the governed config and
+ * the runtime environment it returns the set of *referenced* auth/env ref slugs
+ * whose candidate keys resolve to a value — slugs only, never a value.
+ *
+ * Pure + env-injectable so it is deterministically testable.
+ */
+
+import { describePostgresAdapter } from "./adapters/persistence/postgres.js";
+import { describeQstashKvAdapter } from "./adapters/persistence/qstash-kv.js";
+import { describeProviderManagedAdapter } from "./adapters/persistence/provider-managed.js";
+
+function clean(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+/** Canonical UPPER_SNAKE candidate expansion for a logical ref. */
+function envKeyCandidates(ref) {
+  const token = clean(ref).replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toUpperCase();
+  if (!token) return [];
+  return Array.from(new Set([token, `${token}_API_KEY`, `${token}_TOKEN`]));
+}
+
+/**
+ * Collect every auth/env ref slug referenced by the governed config:
+ *   - api-registry rows: authRef
+ *   - data-source rows:  authRef
+ *   - sandbox-environment rows: envRefs (comma-separated)
+ * Returns the original ref strings (deduped), preserving the operator's casing
+ * so the cockpit can match them against a registry row's authRef.
+ */
+function collectReferencedRefs(workspaceConfig) {
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  const refs = new Set();
+  for (const object of objects) {
+    const rows = Array.isArray(object?.rows) ? object.rows : [];
+    if (object?.objectType === "api-registry" || object?.objectType === "data-source") {
+      for (const row of rows) {
+        const ref = clean(row?.authRef);
+        if (ref) refs.add(ref);
+      }
+    }
+    if (object?.objectType === "sandbox-environment") {
+      for (const row of rows) {
+        for (const part of clean(row?.envRefs).split(",")) {
+          const ref = clean(part);
+          if (ref) refs.add(ref);
+        }
+      }
+    }
+  }
+  return Array.from(refs);
+}
+
+/**
+ * Return the referenced refs whose candidate keys resolve in `env`.
+ * `env` is injectable (defaults to process.env). Never returns a value.
+ */
+function computeConfiguredEnvRefs(workspaceConfig, env = process.env) {
+  const source = env && typeof env === "object" ? env : {};
+  const resolves = (ref) => envKeyCandidates(ref).some((key) => Boolean(source[key]));
+  return collectReferencedRefs(workspaceConfig).filter(resolves);
+}
+
+/**
+ * Persistence/serverless adapter env-readiness — single-sourced from the real
+ * thin-adapter descriptors (postgres / qstash-kv / provider-managed). These are
+ * the durable-runtime layers a serverless workflow needs; the cockpit surfaces
+ * exactly which are env-ready so "make this workflow persistent + scheduled"
+ * has an honest, actionable signal. Slugs/booleans only — never a value.
+ */
+function listPersistenceAdapterReadiness(env = process.env) {
+  const source = env && typeof env === "object" ? env : {};
+  const descriptors = [describePostgresAdapter(), describeQstashKvAdapter(), describeProviderManagedAdapter()];
+  return descriptors.map((d) => {
+    const requiredEnv = Array.isArray(d.requiredEnv) ? d.requiredEnv : [];
+    const missingEnv = requiredEnv.filter((k) => !source[k]);
+    return {
+      id: d.id,
+      label: d.label,
+      mode: d.mode,
+      requiredEnv,
+      // provider-managed needs no env (the deploy provider owns persistence).
+      configured: requiredEnv.length === 0 ? true : missingEnv.length === 0,
+      missingEnv,
+    };
+  });
+}
+
+export {
+  envKeyCandidates,
+  collectReferencedRefs,
+  computeConfiguredEnvRefs,
+  listPersistenceAdapterReadiness,
+};

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/orchestration-graph.js

@@ -364,6 +364,67 @@ function buildSandboxRowFromApiRegistry(workspaceConfig, registryRow, options =
   };
 }
 
+/**
+ * Find existing data-source rows that already resolve through a given API
+ * Registry integration (by `registryId`). Mirrors findSandboxRowsForRegistry so
+ * the drawer can refuse to create a duplicate Data Source for the same API.
+ */
+function findDataSourceRowsForRegistry(workspaceConfig, integrationId) {
+  const id = String(integrationId || "").trim();
+  if (!id) return [];
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  const rows = [];
+  for (const object of objects) {
+    if (object?.objectType !== "data-source") continue;
+    for (const row of Array.isArray(object.rows) ? object.rows : []) {
+      if (String(row?.registryId || "").trim() === id) rows.push(row);
+    }
+  }
+  return rows;
+}
+
+/**
+ * Build a governed Data Source row from a tested API Registry row. The Data
+ * Source references the registry entry by `registryId` (the existing
+ * resolver-binding relation) and keeps auth as an `authRef` slug only — the
+ * secret never lands on the row. Shape matches the OBJECT_TYPE_PRESETS
+ * "data-source" columns so it slots straight into the data-source table.
+ */
+function buildDataSourceRowFromApiRegistry(workspaceConfig, registryRow, options = {}) {
+  const integrationId = String(registryRow?.integrationId || "").trim();
+  const baseName = String(options.name || registryRow?.Name || integrationId || "Data Source").trim();
+  const name = baseName.endsWith(" Source") ? baseName : `${baseName} Source`;
+  const entityType = String(
+    options.entityType || registryRow?.entityTypes || "records"
+  ).split(",")[0].trim() || "records";
+  const sourceId = String(
+    options.sourceId || slugifyName(`${integrationId || baseName}-${entityType}`) || slugifyName(baseName)
+  ).trim();
+  const sourceStorage = String(options.sourceStorage || "workspace-source-records").trim();
+  return {
+    Name: name,
+    slug: options.slug || slugifyName(name) || slugifyName(integrationId),
+    objectType: "data-source",
+    registryId: integrationId,
+    endpoint: String(registryRow?.endpoint || "").trim(),
+    authRef: String(options.authRef || registryRow?.authRef || integrationId).trim(),
+    baseUrl: String(registryRow?.baseUrl || "").trim(),
+    method: String(registryRow?.method || "GET").trim().toUpperCase(),
+    status: "draft",
+    lastTested: "",
+    lastResponse: "",
+    entityType,
+    sourceId,
+    sourceStorage,
+    resolverTemplateId: String(options.resolverTemplateId || registryRow?.resolverTemplateId || "").trim(),
+    description: String(
+      options.description
+        || registryRow?.description
+        || `Data Source for ${integrationId || baseName} — resolves ${entityType} through the API Registry resolver. authRef ${String(options.authRef || registryRow?.authRef || integrationId).trim()} only; secrets resolve server-side.`
+    ).trim()
+  };
+}
+
 function extractNodeByType(graph, type) {
   const parsed = parseOrchestrationGraph(graph) || graph;
   if (!parsed?.nodes) return null;
@@ -918,6 +979,8 @@ export {
   getNextCanonicalNodeId,
   addCanonicalNodeToGraph,
   buildSandboxRowFromApiRegistry,
+  buildDataSourceRowFromApiRegistry,
+  findDataSourceRowsForRegistry,
   extractApiRegistryCallNode,
   extractInputNode,
   extractTransformConfig,

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/sandbox-serverless-flow.js

@@ -0,0 +1,215 @@
+/**
+ * Sandbox Serverless Flow V1 — the governed persistence + scheduling journey for
+ * one sandbox-environment workflow row, expressed in the EXACT same step shape
+ * as the API Registry creation cockpit (lib/api-registry-creation-flow.js) so it
+ * renders through the same cockpit interface and mental model.
+ *
+ * It connects the dots that already exist:
+ *   - runLocality local|serverless toggle (sandbox row)
+ *   - execution adapter (sandbox-adapter-registry)
+ *   - schedulerRegistryId reference field → an API Registry row that delegates
+ *     the serverless run (sandbox-run's registry-delegation mode)
+ *   - the scheduler row's authRef → resolved via env-status configuredEnvRefs
+ *   - durable persistence via the real thin adapters (postgres / qstash-kv /
+ *     provider-managed) surfaced by env-status persistenceAdapters
+ *
+ * Pure + deterministic; never reads process.env, never throws. Secret-safe
+ * (slugs/ids/booleans only).
+ */
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function clean(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+/** Exact env keys a ref resolves through (runtime/.env.local), surfaced so the
+ *  config loop is concrete — same model as the NANGO_SECRET_KEY activation step. */
+function envCandidates(ref) {
+  const token = clean(ref).replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toUpperCase();
+  if (!token) return [];
+  return Array.from(new Set([token, `${token}_API_KEY`, `${token}_TOKEN`]));
+}
+
+const SCHEDULER_OK_STATUSES = new Set(["connected", "approved", "ok", "success", "live", "tested"]);
+const STATE_KIND = "growthub-sandbox-serverless-state-v1";
+
+function findApiRegistryRow(workspaceConfig, integrationId) {
+  const id = clean(integrationId);
+  if (!id) return null;
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  for (const object of objects) {
+    if (object?.objectType !== "api-registry") continue;
+    const match = (object.rows || []).find((r) => clean(r?.integrationId) === id);
+    if (match) return match;
+  }
+  return null;
+}
+
+/**
+ * Derive the serverless/scheduling/persistence journey for a sandbox row.
+ *
+ * @param {object} input
+ * @param {object} input.sandboxRow          the row being edited (drawer draft)
+ * @param {object} [input.workspaceConfig]   for scheduler row lookup
+ * @param {string[]} [input.configuredEnvRefs] auth/env slugs that resolve (env-status)
+ * @param {object[]} [input.persistenceAdapters] [{id,label,mode,configured,missingEnv}]
+ */
+function deriveSandboxServerlessState(input = {}) {
+  const row = isPlainObject(input.sandboxRow) ? input.sandboxRow : {};
+  const workspaceConfig = isPlainObject(input.workspaceConfig) ? input.workspaceConfig : {};
+  const configuredRefs = new Set((Array.isArray(input.configuredEnvRefs) ? input.configuredEnvRefs : []).map((s) => clean(s).toUpperCase()));
+  const adapters = Array.isArray(input.persistenceAdapters) ? input.persistenceAdapters : [];
+  // When the cockpit is rendered above the drawer's own editable fields
+  // (locality toggle, adapter picker, scheduler reference dropdown), those steps
+  // show status only — the inline field is the editor (no duplicate button).
+  const inlineEditing = input.inlineEditing === true;
+  const inline = (action) => (inlineEditing ? null : action);
+
+  const locality = clean(row.runLocality).toLowerCase() === "serverless" ? "serverless" : "local";
+  const isServerless = locality === "serverless";
+  const adapterId = clean(row.adapter);
+  const adapterChosen = Boolean(adapterId);
+
+  const schedulerId = clean(row.schedulerRegistryId);
+  const schedulerRow = isServerless ? findApiRegistryRow(workspaceConfig, schedulerId) : null;
+  const schedulerLinked = isServerless ? Boolean(schedulerId) : true;
+  const schedulerHealthy = Boolean(schedulerRow) && SCHEDULER_OK_STATUSES.has(clean(schedulerRow.status).toLowerCase());
+  const schedulerAuthRef = clean(schedulerRow?.authRef).toUpperCase();
+  const schedulerAuthConfigured = !schedulerAuthRef || configuredRefs.has(schedulerAuthRef);
+
+  // Durable persistence: any real adapter that is env-ready. provider-managed is
+  // always "ready" (the deploy provider owns persistence). qstash-kv/postgres
+  // require their env keys — surfaced honestly with the missing keys.
+  const durableAdapters = adapters.filter((a) => a && a.configured);
+  const durableReady = durableAdapters.length > 0;
+  const envBackedAdapter = durableAdapters.find((a) => Array.isArray(a.requiredEnv) && a.requiredEnv.length > 0) || durableAdapters[0] || null;
+
+  const steps = [];
+
+  steps.push({
+    id: "locality",
+    label: "Choose run locality",
+    status: isServerless ? "complete" : "active",
+    description: isServerless
+      ? "Serverless — runs are delegated to a scheduler and persist across redeploy."
+      : "Local — runs execute in-process on this machine.",
+    action: inline({ id: "toggle-locality", label: isServerless ? "Switch to local" : "Switch to serverless" }),
+  });
+
+  steps.push({
+    id: "adapter",
+    label: "Pick an execution adapter",
+    status: adapterChosen ? "complete" : "active",
+    description: adapterChosen
+      ? `Adapter "${adapterId}".`
+      : "Select the execution adapter for this workflow.",
+    action: adapterChosen ? null : inline({ id: "edit-adapter", label: "Choose adapter" }),
+  });
+
+  if (isServerless) {
+    steps.push({
+      id: "scheduler",
+      label: "Link a scheduler",
+      status: schedulerLinked ? (schedulerHealthy ? "complete" : "pending") : "active",
+      description: !schedulerLinked
+        ? "Set schedulerRegistryId to an API Registry row that delegates the serverless run."
+        : schedulerHealthy
+          ? `Scheduler "${schedulerId}" is connected.`
+          : `Scheduler "${schedulerId}" is linked but not connected yet — test that API Registry row.`,
+      hint: schedulerLinked && !schedulerRow ? "The referenced API Registry row was not found." : undefined,
+      action: inline({ id: "link-scheduler", label: schedulerLinked ? "Review scheduler" : "Link scheduler" }),
+    });
+
+    steps.push({
+      id: "scheduler-auth",
+      label: "Scheduler auth resolves",
+      status: !schedulerAuthRef
+        ? "complete"
+        : schedulerAuthConfigured
+          ? "complete"
+          : (schedulerLinked ? "pending" : "blocked"),
+      description: !schedulerAuthRef
+        ? "The scheduler needs no secret."
+        : schedulerAuthConfigured
+          ? `Scheduler secret ${schedulerAuthRef} resolves in this runtime.`
+          : `Set one of ${envCandidates(schedulerAuthRef).join(" / ")} in .env.local (or your hosted runtime), then reopen.`,
+      action: schedulerAuthRef && !schedulerAuthConfigured ? { id: "open-settings", label: "Manage in Settings", href: "/settings/apis-webhooks" } : null,
+    });
+
+    steps.push({
+      id: "persistence",
+      label: "Enable durable persistence",
+      status: durableReady ? "complete" : "active",
+      description: durableReady
+        ? `Durable store ready (${(envBackedAdapter || durableAdapters[0]).label}).`
+        : "Set a durable store's env keys in .env.local (or your hosted runtime) so serverless runs survive redeploy.",
+      // Fully surface every thin adapter + its exact env keys + readiness, so no
+      // adapter is assumed server-side without being shown to the operator.
+      hint: durableReady
+        ? undefined
+        : adapters.length
+          ? adapters.map((a) => `${a.label}: ${(a.requiredEnv || []).length ? a.requiredEnv.join(", ") : "no env"}${a.configured ? " ✓" : ""}`).join(" · ")
+          : "No persistence adapter signal yet — open env-status.",
+      action: durableReady ? null : { id: "open-settings", label: "Manage in Settings", href: "/settings" },
+    });
+  }
+
+  steps.push({
+    id: "run",
+    label: isServerless ? "Run on the scheduler" : "Run locally",
+    status: "optional",
+    description: isServerless
+      ? "Once the scheduler, auth, and store are ready, run delegates to the serverless scheduler."
+      : "Run this workflow in-process.",
+    action: inline({ id: "run-sandbox", label: "Run" }),
+  });
+
+  for (const s of steps) { if (!s.hint) delete s.hint; }
+
+  const required = steps.filter((s) => s.status !== "optional");
+  const completedCount = required.filter((s) => s.status === "complete").length;
+  const totalCount = required.length;
+  const complete = completedCount >= totalCount;
+  const nextStep = steps.find((s) => s.status === "active")
+    || steps.find((s) => s.status === "pending")
+    || steps.find((s) => s.status === "blocked")
+    || null;
+
+  // Milestone score tied to evidence.
+  let score = isServerless ? 10 : 40;
+  if (adapterChosen) score = Math.max(score, isServerless ? 25 : 70);
+  if (isServerless && schedulerLinked) score = Math.max(score, 45);
+  if (isServerless && schedulerHealthy) score = Math.max(score, 60);
+  if (isServerless && schedulerAuthConfigured && schedulerLinked) score = Math.max(score, 75);
+  if (isServerless && durableReady) score = Math.max(score, 90);
+  if (complete) score = 100;
+
+  return {
+    kind: STATE_KIND,
+    version: 1,
+    locality,
+    isServerless,
+    adapterChosen,
+    schedulerLinked,
+    schedulerHealthy,
+    schedulerAuthConfigured,
+    durableReady,
+    completedCount,
+    totalCount,
+    complete,
+    score,
+    nextStepId: nextStep ? nextStep.id : null,
+    nextAction: nextStep && nextStep.action ? { stepId: nextStep.id, ...nextStep.action } : null,
+    headline: !isServerless
+      ? "This workflow runs locally."
+      : complete
+        ? "This workflow is scheduled and durable."
+        : "Make this workflow persistent and scheduled.",
+    steps,
+  };
+}
+
+export { STATE_KIND, deriveSandboxServerlessState };