@growthub/cli 0.13.9 → 0.14.1

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/api-registry-creation-flow.js

@@ -0,0 +1,317 @@
+/**
+ * API Registry Creation Flow V1 — the governed creation spine for one API.
+ *
+ * Pure derivation that powers the creation cockpit inside the api-registry
+ * record drawer (DataModelShell). Given the live workspace config, the registry
+ * row being edited, the source-records sidecar, and the safe runtime signal, it
+ * resolves the full operator journey for THIS API as an ordered list of steps:
+ *
+ *   register → configure auth → test → (resolver) → sandbox tool → data source
+ *   → refresh records
+ *
+ * Each step carries a status (complete | active | pending | blocked | optional),
+ * a human description, and — when the operator can act — an `action` descriptor
+ * the drawer maps to an existing handler (test / create-data-source /
+ * create-sandbox-tool / open-data-source / refresh-source). The cockpit renders
+ * this verbatim, so the journey is one derivation, not UI guesswork.
+ *
+ * Invariants:
+ *   - Pure, deterministic, never throws on partial input. `runtime` /
+ *     `sourceRecords` are injected (no fetch, no process.env, no React).
+ *   - Auth "configured" is resolved ONLY from an explicit runtime signal
+ *     (`runtime.configuredEnvRefs`, slugs) — never from a secret value, never
+ *     guessed. Absent the signal the auth step stays pending with a verify hint.
+ *   - Secret-safe: the output contains slugs, ids, counts, and 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 an authRef resolves through — shown to the operator so the
+ *  "how do I configure this" loop is concrete (these are runtime/.env.local
+ *  keys, the same model the NANGO_SECRET_KEY activation step uses). */
+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`]));
+}
+
+function parseMaybeJson(value) {
+  if (isPlainObject(value)) return value;
+  const text = clean(value);
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A registry row is "registered" once it has an id and a reachable target. */
+function isRegistered(row) {
+  return Boolean(clean(row?.integrationId) && (clean(row?.baseUrl) || clean(row?.endpoint)));
+}
+
+/** Does this row's last test indicate success? Mirrors the drawer's testApiRecord. */
+function isTested(row) {
+  const status = clean(row?.status).toLowerCase();
+  if (["connected", "ok", "success", "live", "tested"].includes(status)) return true;
+  const resp = parseMaybeJson(row?.lastResponse);
+  if (resp && (resp.ok === true || resp.status === 200)) return true;
+  return false;
+}
+
+function findObjectsByType(workspaceConfig, objectType) {
+  const objects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+  return objects.filter((o) => isPlainObject(o) && o.objectType === objectType);
+}
+
+function sandboxRowsForIntegration(workspaceConfig, integrationId) {
+  const id = clean(integrationId);
+  if (!id) return [];
+  const rows = [];
+  for (const object of findObjectsByType(workspaceConfig, "sandbox-environment")) {
+    for (const row of Array.isArray(object.rows) ? object.rows : []) {
+      const envRefs = clean(row?.envRefs);
+      const schedulerId = clean(row?.schedulerRegistryId);
+      const cfg = parseMaybeJson(row?.orchestrationConfig);
+      const callsApi = Array.isArray(cfg?.nodes) && cfg.nodes.some(
+        (n) => n?.type === "api-registry-call"
+          && clean(n?.config?.registryId || n?.config?.integrationId) === id,
+      );
+      if (callsApi || schedulerId === id || envRefs.split(",").map(clean).includes(clean(row?.authRef))) {
+        rows.push(row);
+      }
+    }
+  }
+  return rows;
+}
+
+function dataSourceRowsForIntegration(workspaceConfig, integrationId) {
+  const id = clean(integrationId);
+  if (!id) return [];
+  const rows = [];
+  for (const object of findObjectsByType(workspaceConfig, "data-source")) {
+    for (const row of Array.isArray(object.rows) ? object.rows : []) {
+      if (clean(row?.registryId) === id) rows.push({ row, objectId: object.id });
+    }
+  }
+  return rows;
+}
+
+function sidecarHasRecords(sourceRecords, sourceId) {
+  const key = clean(sourceId);
+  if (!key || !isPlainObject(sourceRecords)) return false;
+  const sidecar = sourceRecords[key];
+  if (!isPlainObject(sidecar)) return false;
+  if (Number.isFinite(sidecar.recordCount) && sidecar.recordCount > 0) return true;
+  return Array.isArray(sidecar.records) && sidecar.records.length > 0;
+}
+
+const STEP_KIND = "growthub-api-registry-creation-state-v1";
+
+/**
+ * Derive the full creation state for one API Registry row.
+ *
+ * @param {object} input
+ * @param {object} input.workspaceConfig
+ * @param {object} input.registryRow       the row being edited (drawer draft)
+ * @param {object} [input.sourceRecords]   source-records sidecar
+ * @param {object} [input.runtime]         safe runtime signal (configuredEnvRefs[])
+ */
+function deriveApiRegistryCreationState(input = {}) {
+  const workspaceConfig = isPlainObject(input.workspaceConfig) ? input.workspaceConfig : {};
+  const row = isPlainObject(input.registryRow) ? input.registryRow : {};
+  const sourceRecords = isPlainObject(input.sourceRecords) ? input.sourceRecords : {};
+  const runtime = isPlainObject(input.runtime) ? input.runtime : {};
+
+  const integrationId = clean(row.integrationId);
+  const authRef = clean(row.authRef).toUpperCase();
+  const registered = isRegistered(row);
+  const tested = isTested(row);
+
+  const configuredRefs = new Set(
+    (Array.isArray(runtime.configuredEnvRefs) ? runtime.configuredEnvRefs : []).map((s) => clean(s).toUpperCase()),
+  );
+  const haveEnvSignal = Array.isArray(runtime.configuredEnvRefs);
+  const authNeeded = Boolean(authRef);
+  const authConfigured = !authNeeded || (haveEnvSignal && configuredRefs.has(authRef));
+
+  const sandboxRows = sandboxRowsForIntegration(workspaceConfig, integrationId);
+  const sandboxExists = sandboxRows.length > 0;
+  const sourceLinks = dataSourceRowsForIntegration(workspaceConfig, integrationId);
+  const sourceExists = sourceLinks.length > 0;
+  const linkedSourceId = sourceExists ? clean(sourceLinks[0].row?.sourceId) : "";
+  const linkedSourceObjectId = sourceExists ? clean(sourceLinks[0].objectId) : "";
+  // refresh-sources keys the sidecar by the data-source OBJECT id; older rows
+  // may have keyed by the row's sourceId. Check both so the step is honest.
+  const hasRecords = sourceLinks.some(
+    (link) => sidecarHasRecords(sourceRecords, clean(link.objectId))
+      || sidecarHasRecords(sourceRecords, clean(link.row?.sourceId)),
+  );
+
+  // resolverTemplateId other than the passthrough "custom-http" means a real
+  // shaping resolver is wired; "custom-http" / empty means raw passthrough.
+  const resolverTemplate = clean(row.resolverTemplateId);
+  const resolverWired = Boolean(resolverTemplate) && resolverTemplate !== "custom-http";
+
+  const steps = [];
+  const step = (s) => { steps.push(s); };
+
+  step({
+    id: "register",
+    label: "Register the API",
+    status: registered ? "complete" : "active",
+    description: registered
+      ? `Registered as "${integrationId}".`
+      : "Fill integrationId and a baseUrl or endpoint on this row.",
+    action: registered ? null : { id: "edit", label: "Edit fields" },
+  });
+
+  step({
+    id: "auth",
+    label: "Configure auth secret",
+    status: !authNeeded
+      ? (registered ? "complete" : "blocked")
+      : authConfigured
+        ? "complete"
+        : (registered ? "pending" : "blocked"),
+    description: !authNeeded
+      ? "This API needs no secret."
+      : authConfigured
+        ? `Secret for ${authRef} resolves in this runtime.`
+        : `Set one of ${envCandidates(authRef).join(" / ")} in .env.local (or your hosted runtime), then reopen. The workspace stores only the reference — the value never reaches the browser.`,
+    hint: authNeeded && !authConfigured
+      ? (haveEnvSignal
+        ? "Add the key to your runtime env; the cockpit re-checks resolution on reopen."
+        : "Runtime env signal unavailable — once the key is set and resolvable, this turns green.")
+      : undefined,
+    action: authNeeded && !authConfigured ? { id: "open-settings", label: "Manage in Settings", href: "/settings/apis-webhooks" } : null,
+  });
+
+  step({
+    id: "test",
+    label: "Test the API",
+    status: tested
+      ? "complete"
+      : (registered && authConfigured ? "active" : "blocked"),
+    description: tested
+      ? "Last test succeeded — lastResponse saved."
+      : "Run a server-side test; the secret stays server-side via authRef.",
+    action: !tested && registered && authConfigured ? { id: "test", label: "Test API" } : null,
+  });
+
+  step({
+    id: "resolver",
+    label: "Shape the response (resolver)",
+    status: resolverWired ? "complete" : (tested ? "optional" : "blocked"),
+    description: resolverWired
+      ? `Resolver "${resolverTemplate}" shapes the response into rows.`
+      : "Optional: add a resolver to normalize the response into governed rows. Raw passthrough works without one.",
+    action: tested && !resolverWired ? { id: "open-resolver", label: "Add resolver", href: "/api/workspace/resolver-templates" } : null,
+  });
+
+  step({
+    id: "data-source",
+    label: "Create a Data Source",
+    status: sourceExists
+      ? "complete"
+      : (tested ? "active" : "blocked"),
+    description: sourceExists
+      ? `Data Source linked (sourceId "${linkedSourceId}").`
+      : "Turn the tested API into a governed Data Source.",
+    action: !sourceExists && tested
+      ? { id: "create-data-source", label: "Create Data Source" }
+      : (sourceExists ? { id: "open-data-source", label: "Open Data Source", objectId: linkedSourceObjectId } : null),
+  });
+
+  step({
+    id: "refresh",
+    label: "Refresh source records",
+    status: hasRecords
+      ? "complete"
+      : (sourceExists ? "active" : "blocked"),
+    description: hasRecords
+      ? "The Data Source has hydrated records."
+      : "Pull live records into the workspace from the Data Source.",
+    action: sourceExists && !hasRecords
+      ? { id: "refresh-source", label: "Refresh source", sourceId: linkedSourceId, objectId: linkedSourceObjectId }
+      : null,
+  });
+
+  // Optional automation lane — a sandbox/workflow that calls this API.
+  step({
+    id: "sandbox-tool",
+    label: "Automate (sandbox tool)",
+    status: sandboxExists ? "complete" : (tested ? "optional" : "blocked"),
+    description: sandboxExists
+      ? "A sandbox tool calls this API."
+      : "Optional: wrap this API in a sandbox/workflow you can run or schedule.",
+    action: tested && !sandboxExists ? { id: "create-sandbox-tool", label: "Create sandbox tool" } : null,
+  });
+
+  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;
+  // The active step (or first pending/blocked) is the operator's next move.
+  const nextStep = steps.find((s) => s.status === "active")
+    || steps.find((s) => s.status === "pending")
+    || steps.find((s) => s.status === "blocked")
+    || null;
+
+  // Activation score — milestone-based, tied to real evidence (not a raw
+  // step-count progress bar). Each threshold corresponds to a concrete,
+  // derived state transition the operator can verify.
+  let score = 0;
+  if (registered) score = 20;
+  if (registered && authConfigured) score = Math.max(score, 35);
+  if (tested) score = Math.max(score, 50);
+  if (sourceExists) score = Math.max(score, 65);
+  if (hasRecords) score = Math.max(score, 80);
+  if (sandboxExists) score = Math.max(score, 90);
+  if (complete) score = 100;
+
+  return {
+    kind: STEP_KIND,
+    version: 1,
+    integrationId,
+    registered,
+    tested,
+    authNeeded,
+    authConfigured,
+    sandboxExists,
+    sourceExists,
+    hasRecords,
+    completedCount,
+    totalCount,
+    complete,
+    score,
+    nextStepId: nextStep ? nextStep.id : null,
+    nextAction: nextStep && nextStep.action ? { stepId: nextStep.id, ...nextStep.action } : null,
+    headline: !registered
+      ? "Register this API to begin."
+      : complete
+        ? "This API is live end-to-end."
+        : "Finish wiring this API into the workspace.",
+    steps,
+  };
+}
+
+export {
+  STEP_KIND,
+  isRegistered,
+  isTested,
+  sandboxRowsForIntegration,
+  dataSourceRowsForIntegration,
+  sidecarHasRecords,
+  deriveApiRegistryCreationState,
+};

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/api-response-profile.js

@@ -0,0 +1,207 @@
+/**
+ * API Response Profiler V1 — turns a tested API's `lastResponse` into a
+ * business-ready shape analysis, and recommends a resolver mode from it.
+ *
+ * This is the engine behind the cockpit's "Shape" lane: it is the difference
+ * between "API tested" and "API usable". Given the raw (already-fetched,
+ * server-side) response text, it finds the record array, infers field roles,
+ * proposes an entityType, and classifies what resolver work (if any) is needed
+ * to turn the response into governed rows.
+ *
+ * Pure + deterministic. No fetch, no secrets — it only inspects shape and a few
+ * sample values for type/role inference (and redaction is the caller's job for
+ * anything rendered). Never throws on malformed input.
+ */
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function clean(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function parseResponse(lastResponse) {
+  if (isPlainObject(lastResponse) || Array.isArray(lastResponse)) return lastResponse;
+  const text = clean(lastResponse);
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+const ARRAY_CANDIDATE_KEYS = ["data", "items", "results", "records", "rows", "list", "values", "entries", "edges", "nodes"];
+const PAGINATION_KEYS = ["next", "nextPage", "next_page", "cursor", "nextCursor", "next_cursor", "page", "offset", "hasMore", "has_more", "pageInfo", "_links", "paging"];
+
+/** Locate the most likely record array and its dotted path within the payload. */
+function findRecordArray(payload) {
+  if (Array.isArray(payload)) return { path: "", array: payload };
+  if (!isPlainObject(payload)) return { path: "", array: null };
+  // Prefer well-known container keys, then any top-level array, then one level deep.
+  for (const key of ARRAY_CANDIDATE_KEYS) {
+    if (Array.isArray(payload[key])) return { path: key, array: payload[key] };
+  }
+  for (const [key, value] of Object.entries(payload)) {
+    if (Array.isArray(value)) return { path: key, array: value };
+  }
+  for (const [key, value] of Object.entries(payload)) {
+    if (isPlainObject(value)) {
+      for (const inner of ARRAY_CANDIDATE_KEYS) {
+        if (Array.isArray(value[inner])) return { path: `${key}.${inner}`, array: value[inner] };
+      }
+      for (const [ik, iv] of Object.entries(value)) {
+        if (Array.isArray(iv)) return { path: `${key}.${ik}`, array: iv };
+      }
+    }
+  }
+  return { path: "", array: null };
+}
+
+function inferType(value) {
+  if (value === null || value === undefined) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "object") return "object";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "number") return "number";
+  const s = String(value);
+  if (/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2})?/.test(s)) return "datetime";
+  if (/^-?\d+(\.\d+)?$/.test(s)) return "number";
+  if (/^(true|false)$/i.test(s)) return "boolean";
+  return "text";
+}
+
+function detectRole(name, type) {
+  const n = clean(name).toLowerCase();
+  if (n === "id" || n.endsWith("_id") || n.endsWith("id") && n.length <= 6) return "id";
+  if (n === "id" || n === "uuid" || n === "gid" || n === "key") return "id";
+  if (n.includes("email")) return "email";
+  if (n === "name" || n.endsWith("name") || n === "title" || n === "label") return "name";
+  if (n.includes("company") || n.includes("organization") || n.includes("org")) return "company";
+  if (type === "datetime" || n.includes("date") || n.includes("_at") || n.includes("time") || n.includes("created") || n.includes("updated")) return "timestamp";
+  if (n.includes("status") || n.includes("state") || n.includes("stage")) return "status";
+  return "";
+}
+
+/** Profile a sample record into typed/roled fields. */
+function profileRecord(record) {
+  if (!isPlainObject(record)) return [];
+  return Object.entries(record).map(([name, value]) => {
+    const type = inferType(value);
+    const sample = type === "object" || type === "array" ? `[${type}]` : clean(value).slice(0, 60);
+    return { name, type, role: detectRole(name, type), sample };
+  });
+}
+
+const PROFILE_KIND = "growthub-api-response-profile-v1";
+
+/**
+ * Profile a tested API response.
+ * Returns a typed profile; `usable` is true when a record array was found.
+ */
+function profileApiResponse(lastResponse) {
+  const empty = {
+    kind: PROFILE_KIND,
+    parsed: false,
+    usable: false,
+    topLevelKeys: [],
+    arrayPath: "",
+    recordCount: 0,
+    fields: [],
+    candidates: { id: "", name: "", email: "", company: "", timestamp: "" },
+    suggestedEntityType: "records",
+    hasPagination: false,
+  };
+  const payload = parseResponse(lastResponse);
+  if (payload === null) return empty;
+
+  const topLevelKeys = isPlainObject(payload) ? Object.keys(payload) : [];
+  const hasPagination = isPlainObject(payload)
+    && PAGINATION_KEYS.some((k) => Object.prototype.hasOwnProperty.call(payload, k) && payload[k] != null && payload[k] !== false);
+
+  const { path, array } = findRecordArray(payload);
+  if (!Array.isArray(array) || array.length === 0) {
+    // No record array — a single object response is still profileable as one row.
+    if (isPlainObject(payload)) {
+      const fields = profileRecord(payload);
+      return {
+        ...empty,
+        parsed: true,
+        usable: fields.length > 0,
+        topLevelKeys,
+        arrayPath: "",
+        recordCount: isPlainObject(payload) ? 1 : 0,
+        fields,
+        candidates: pickCandidates(fields),
+        suggestedEntityType: "record",
+        hasPagination,
+      };
+    }
+    return { ...empty, parsed: true, topLevelKeys, hasPagination };
+  }
+
+  const sample = array.find(isPlainObject) || null;
+  const fields = profileRecord(sample);
+  const suggestedEntityType = path ? clean(path).split(".").pop() : "records";
+  return {
+    kind: PROFILE_KIND,
+    parsed: true,
+    usable: fields.length > 0,
+    topLevelKeys,
+    arrayPath: path,
+    recordCount: array.length,
+    fields,
+    candidates: pickCandidates(fields),
+    suggestedEntityType: suggestedEntityType || "records",
+    hasPagination,
+  };
+}
+
+function pickCandidates(fields) {
+  const byRole = (role) => (fields.find((f) => f.role === role)?.name) || "";
+  return {
+    id: byRole("id"),
+    name: byRole("name"),
+    email: byRole("email"),
+    company: byRole("company"),
+    timestamp: byRole("timestamp"),
+  };
+}
+
+const RESOLVER_RECOMMENDATION_KIND = "growthub-resolver-recommendation-v1";
+
+/**
+ * Recommend a resolver mode from a response profile.
+ *   none      — top-level array, clean records: raw passthrough works.
+ *   template  — records under a known container (data/items/...): simple extraction.
+ *   custom    — nested/non-standard path or single-object: a resolver is recommended.
+ *   required  — pagination detected or no record array: a resolver is required to
+ *               produce complete, governed rows.
+ */
+function recommendResolver(profile) {
+  const p = isPlainObject(profile) ? profile : {};
+  if (!p.parsed) {
+    return { kind: RESOLVER_RECOMMENDATION_KIND, mode: "required", level: "required", rootPath: "", reason: "Response could not be parsed as JSON — a resolver must normalize it into rows." };
+  }
+  if (p.hasPagination) {
+    return { kind: RESOLVER_RECOMMENDATION_KIND, mode: "custom", level: "required", rootPath: p.arrayPath || "", reason: "Pagination detected — a resolver is required to fetch and concatenate all pages." };
+  }
+  if (!p.usable || p.recordCount === 0) {
+    return { kind: RESOLVER_RECOMMENDATION_KIND, mode: "custom", level: "required", rootPath: "", reason: "No record array found — a resolver is required to extract rows from this response." };
+  }
+  if (!p.arrayPath) {
+    return { kind: RESOLVER_RECOMMENDATION_KIND, mode: "none", level: "optional", rootPath: "", reason: "Top-level array of records — raw passthrough works; a resolver is optional." };
+  }
+  if (p.arrayPath.includes(".")) {
+    return { kind: RESOLVER_RECOMMENDATION_KIND, mode: "custom", level: "recommended", rootPath: p.arrayPath, reason: `Records are nested at "${p.arrayPath}" — a resolver is recommended to normalize them.` };
+  }
+  return { kind: RESOLVER_RECOMMENDATION_KIND, mode: "template", level: "recommended", rootPath: p.arrayPath, reason: `Records under "${p.arrayPath}" — a template resolver can extract them at that path.` };
+}
+
+export {
+  PROFILE_KIND,
+  RESOLVER_RECOMMENDATION_KIND,
+  profileApiResponse,
+  recommendResolver,
+};

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 };