@growthub/cli 0.9.13 → 0.9.14

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/README.md

@@ -27,6 +27,33 @@ Use `GROWTHUB_WORKSPACE_INTEGRATION_ADAPTER=growthub-bridge` when the deployed a
 
 For first boot, the bundled app also supports a hybrid path: keep `GROWTHUB_WORKSPACE_INTEGRATION_ADAPTER=growthub-bridge` and set `WINDSOR_API_KEY` locally. That overlays connected state for Windsor AI and Google Sheets blended data without moving the rest of the workspace off the hosted bridge authority path.
 
+## Data sources and API registry
+
+Use the Data Model page to configure API-backed Data Sources and reusable API Registry records. Credentials stay in workspace settings or server env; Data Model records store only non-secret references such as `authRef`.
+
+See [`docs/data-sources-api-registry.md`](./docs/data-sources-api-registry.md) for the setup guide, test flow, widget source eligibility rules, and the LeadShark example.
+
+## Integration resolvers
+
+Drop one `.js` file per integration into `lib/adapters/integrations/resolvers/`. Each file registers a provider-agnostic resolver that the workspace routes (`test-source`, `refresh-sources`) dispatch to. The bridge confirms which integrations are connected — resolvers call the provider API directly using env-var tokens.
+
+```bash
+# List registered resolvers (JSON)
+curl -s http://localhost:3000/api/workspace/resolvers
+
+# Test a resolver before saving to data model (JSON)
+curl -s -X POST http://localhost:3000/api/workspace/test-source \
+  -H "Content-Type: application/json" \
+  -d '{"integrationId":"google-analytics","binding":{"entityType":"ga4.traffic","sourceStorage":"workspace-source-records","sourceId":"ga4-traffic"}}'
+
+# Register a resolver-backed data model object (persists to growthub.config.json)
+curl -s -X PATCH http://localhost:3000/api/workspace \
+  -H "Content-Type: application/json" \
+  -d '{"dataModel":{"objects":[...]}}'
+```
+
+See [`lib/adapters/integrations/resolvers/README.md`](./lib/adapters/integrations/resolvers/README.md) for the full resolver shape, all CLI commands with JSON response contracts, and the complete data model → source dropdown → refresh flow.
+
 ## Run
 
 ```bash

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/integration-entities/route.js

@@ -16,8 +16,10 @@
  *   400 { error: string }
  */
 import { NextResponse } from "next/server";
-import { listEntityMetadataForIntegration } from "@/lib/adapters/integrations";
+import { listEntityMetadataForIntegration, listGovernedWorkspaceIntegrations } from "@/lib/adapters/integrations";
 import { readAdapterConfig } from "@/lib/adapters/env";
+import { loadAllResolvers } from "@/lib/adapters/integrations/resolver-loader";
+import { getSourceResolver } from "@/lib/adapters/integrations/source-resolver-registry";
 
 async function GET(request) {
   const { searchParams } = new URL(request.url);
@@ -30,21 +32,51 @@ async function GET(request) {
     );
   }
 
+  const id = integrationId.trim();
   const config = readAdapterConfig();
   const isBridgeMode =
     config.integrationAdapter === "growthub-bridge" &&
     config.growthubBridge?.baseUrl &&
     !!process.env.GROWTHUB_BRIDGE_ACCESS_TOKEN;
 
-  const entities = await listEntityMetadataForIntegration(integrationId.trim());
+  // 1. Try the Bridge / catalog path first
+  let entities = await listEntityMetadataForIntegration(id);
+  let source = entities.length ? "bridge" : "none";
 
-	  return NextResponse.json({
-	    integrationId: integrationId.trim(),
-	    entities,
-	    source: entities.length ? "resolver" : "none",
-	    requiresObjectResolver: entities.length === 0,
-	    authority: isBridgeMode ? "growthub-bridge" : "local"
-	  });
+  // 2. If Bridge returned nothing, fall back to resolver registry listEntities()
+  if (!entities.length) {
+    try {
+      await loadAllResolvers();
+      const resolver = getSourceResolver(id);
+      if (resolver && typeof resolver.listEntities === "function") {
+        const allConnections = await listGovernedWorkspaceIntegrations().catch(() => []);
+        const connection = allConnections.find((c) => c.provider === id || c.id === id) || null;
+        const raw = await resolver.listEntities(config, connection);
+        if (Array.isArray(raw) && raw.length) {
+          entities = raw.map((item) => ({
+            id: String(item.id || item.entityId || item.propertyId || item.accountId || ""),
+            label: String(item.label || item.name || item.displayName || item.id || ""),
+            secondaryLabel: item.secondaryLabel || item.domain || item.accountId || undefined,
+            entityType: item.entityType || item.type || undefined,
+            provider: id,
+            status: item.status || undefined,
+            metadata: item.metadata || undefined
+          })).filter((e) => e.id);
+          source = "resolver";
+        }
+      }
+    } catch {
+      // resolver not available or threw — leave entities empty
+    }
+  }
+
+  return NextResponse.json({
+    integrationId: id,
+    entities,
+    source,
+    requiresObjectResolver: entities.length === 0,
+    authority: isBridgeMode ? "growthub-bridge" : "local"
+  });
 }
 
 export { GET };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/list-entities/route.js

@@ -0,0 +1,67 @@
+/**
+ * GET /api/workspace/list-entities?integrationId=<id>
+ *
+ * Calls the registered resolver's `listEntities()` function and returns a
+ * normalized entity list. Fully composable — no provider-specific logic here.
+ * The resolver file is the only place that knows what an "entity" means for its
+ * integration.
+ *
+ * Response (success):
+ *   { entities: { id: string, label: string, meta?: object }[], hasListEntities: true }
+ *
+ * Response (resolver has no listEntities):
+ *   { entities: [], hasListEntities: false }
+ *
+ * Response (resolver not found):
+ *   { error: "no-resolver", integrationId } — 404
+ */
+
+import { NextResponse } from "next/server";
+import { loadAllResolvers } from "@/lib/adapters/integrations/resolver-loader";
+import { getSourceResolver } from "@/lib/adapters/integrations/source-resolver-registry";
+
+async function GET(request) {
+  const { searchParams } = new URL(request.url);
+  const integrationId = searchParams.get("integrationId");
+
+  if (!integrationId) {
+    return NextResponse.json(
+      { error: "integrationId query param required" },
+      { status: 400 }
+    );
+  }
+
+  await loadAllResolvers();
+  const resolver = getSourceResolver(integrationId);
+
+  if (!resolver) {
+    return NextResponse.json(
+      { error: "no-resolver", integrationId },
+      { status: 404 }
+    );
+  }
+
+  if (typeof resolver.listEntities !== "function") {
+    return NextResponse.json({ entities: [], hasListEntities: false });
+  }
+
+  try {
+    const entities = await resolver.listEntities({}, {});
+    return NextResponse.json({
+      entities: Array.isArray(entities) ? entities : [],
+      hasListEntities: true,
+    });
+  } catch (err) {
+    return NextResponse.json(
+      {
+        error: err.message || "Failed to list entities",
+        reason: "list-error",
+        entities: [],
+        hasListEntities: true,
+      },
+      { status: 500 }
+    );
+  }
+}
+
+export { GET };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/refresh-source/route.js

@@ -0,0 +1,124 @@
+/**
+ * POST /api/workspace/refresh-source
+ *
+ * Calls the registered resolver's `fetchRecords()` with the supplied binding,
+ * then persists the resulting rows into the specified data model object.
+ *
+ * Fully composable — the route has no knowledge of any specific provider.
+ * All provider logic lives in the resolver file.
+ *
+ * Request body:
+ *   {
+ *     integrationId: string,       // matches resolver.integrationId
+ *     binding:       object,       // forwarded verbatim to resolver.fetchRecords
+ *     objectId:      string | null // data model object to persist rows into
+ *   }
+ *
+ * Response (success):
+ *   {
+ *     ok:        true,
+ *     rowCount:  number,
+ *     columns:   string[],
+ *     objectId:  string | null,
+ *     persisted: boolean,       // true when rows were written to growthub.config.json
+ *     dataModel: object | null  // full updated dataModel (for local state sync)
+ *   }
+ *
+ * Response (failure):
+ *   { ok: false, reason: string, error: string }
+ */
+
+import { NextResponse } from "next/server";
+import { loadAllResolvers } from "@/lib/adapters/integrations/resolver-loader";
+import { getSourceResolver } from "@/lib/adapters/integrations/source-resolver-registry";
+import { readWorkspaceConfig, writeWorkspaceConfig, describePersistenceMode } from "@/lib/workspace-config";
+
+async function POST(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ ok: false, reason: "invalid-json" }, { status: 400 });
+  }
+
+  const { integrationId, binding, objectId } = body || {};
+
+  if (!integrationId) {
+    return NextResponse.json({ ok: false, reason: "integrationId required" }, { status: 400 });
+  }
+
+  await loadAllResolvers();
+  const resolver = getSourceResolver(integrationId);
+
+  if (!resolver) {
+    return NextResponse.json(
+      { ok: false, reason: "no-resolver", integrationId },
+      { status: 404 }
+    );
+  }
+
+  let rows;
+  try {
+    rows = await resolver.fetchRecords({}, {}, binding || {});
+    if (!Array.isArray(rows)) rows = [];
+  } catch (err) {
+    return NextResponse.json(
+      { ok: false, reason: "fetch-error", error: err.message || "Resolver threw" },
+      { status: 500 }
+    );
+  }
+
+  const columns = rows.length > 0
+    ? Object.keys(rows[0])
+    : (Array.isArray(binding?.columns) ? binding.columns : []);
+
+  // Persist rows to the data model object when objectId is provided and FS writes are allowed
+  const persistence = describePersistenceMode();
+  let persisted = false;
+  let dataModel = null;
+
+  if (objectId && persistence.canSave) {
+    try {
+      const current = await readWorkspaceConfig();
+      const wc = current.workspaceConfig || current;
+      const existingObjects = Array.isArray(wc.dataModel?.objects) ? wc.dataModel.objects : [];
+
+      const updatedObjects = existingObjects.map((obj) => {
+        if (obj.id !== objectId) return obj;
+        return {
+          ...obj,
+          columns: columns.length ? columns : obj.columns,
+          rows,
+          refreshedAt: new Date().toISOString(),
+        };
+      });
+
+      // If objectId wasn't found in the list, nothing to update but don't error
+      dataModel = { ...(wc.dataModel || {}), objects: updatedObjects };
+
+      await writeWorkspaceConfig({ dataModel });
+      persisted = true;
+    } catch (err) {
+      return NextResponse.json({
+        ok: true,
+        rowCount: rows.length,
+        columns,
+        objectId: objectId || null,
+        persisted: false,
+        persistError: err.message,
+        dataModel: null,
+      });
+    }
+  }
+
+  return NextResponse.json({
+    ok: true,
+    rowCount: rows.length,
+    columns,
+    objectId: objectId || null,
+    persisted,
+    dataModel,
+  });
+}
+
+export { POST };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/refresh-sources/route.js

@@ -0,0 +1,127 @@
+/**
+ * POST /api/workspace/refresh-sources
+ *
+ * Thin dispatcher for live-backed data sources. Zero provider-specific logic
+ * lives here. Each integration ships its own resolver file under
+ * `lib/adapters/integrations/resolvers/<id>.js` and registers itself via
+ * `registerSourceResolver()` from source-resolver-registry.js.
+ *
+ * This route never imports any provider directly. It reads the registry and
+ * dispatches to whatever resolvers the operator has registered. An upstream
+ * kit with no resolver files registered still works — it just skips sources
+ * that have no resolver and returns them in the `skipped` array.
+ *
+ * Request body:
+ *   { sourceIds: string[] }   — IDs of dataModel.objects to refresh
+ *
+ * Response shape:
+ *   200 { refreshed: SourceRefreshResult[], skipped: string[] }
+ *   400 { error: string }
+ *   500 { error: string }
+ *
+ * SourceRefreshResult:
+ *   { sourceId: string, integrationId: string, recordCount: number, fetchedAt: string }
+ *
+ * Authority contract (GOVERNED_WORKSPACE_TOPOLOGY_V1):
+ *   - Browser sends only non-secret sourceIds. No tokens, no provider auth.
+ *   - Server reads env credentials via readAdapterConfig().
+ *   - Normalized records are persisted via writeWorkspaceSourceRecords().
+ *   - Raw provider payloads are never forwarded to the client.
+ *   - The Growthub bridge owns provider auth — this route never holds tokens.
+ */
+
+import { NextResponse } from "next/server";
+import { readAdapterConfig } from "@/lib/adapters/env";
+import { listGovernedWorkspaceIntegrations } from "@/lib/adapters/integrations";
+import { readWorkspaceConfig, writeWorkspaceSourceRecords } from "@/lib/workspace-config";
+import { loadAllResolvers } from "@/lib/adapters/integrations/resolver-loader";
+import { getSourceResolver } from "@/lib/adapters/integrations/source-resolver-registry";
+
+async function POST(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: "invalid JSON body" }, { status: 400 });
+  }
+
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return NextResponse.json({ error: "body must be a plain object" }, { status: 400 });
+  }
+
+  const { sourceIds } = body;
+  if (!Array.isArray(sourceIds) || sourceIds.length === 0) {
+    return NextResponse.json({ error: "sourceIds must be a non-empty array" }, { status: 400 });
+  }
+
+  const invalidIds = sourceIds.filter((id) => typeof id !== "string" || !id.trim());
+  if (invalidIds.length) {
+    return NextResponse.json({ error: "every sourceId must be a non-empty string" }, { status: 400 });
+  }
+
+  let workspaceConfig;
+  try {
+    workspaceConfig = await readWorkspaceConfig();
+  } catch (err) {
+    return NextResponse.json({ error: `failed to read workspace config: ${err.message}` }, { status: 500 });
+  }
+
+  await loadAllResolvers();
+
+  const adapterConfig = readAdapterConfig();
+  const dataObjects = Array.isArray(workspaceConfig?.dataModel?.objects) ? workspaceConfig.dataModel.objects : [];
+
+  // Resolve bridge connections once for this batch so every resolver
+  // receives the full live connection object (connectionId, authPath, metadata).
+  let bridgeIntegrations = [];
+  try {
+    bridgeIntegrations = await listGovernedWorkspaceIntegrations();
+  } catch {
+    // Non-fatal — resolvers fall back to env-only auth
+  }
+
+  const refreshed = [];
+  const skipped = [];
+
+  for (const sourceId of sourceIds) {
+    const obj = dataObjects.find((o) => o.id === sourceId);
+    if (!obj) {
+      skipped.push(sourceId);
+      continue;
+    }
+
+    const binding = obj.binding;
+    if (!binding || binding.sourceStorage !== "workspace-source-records") {
+      skipped.push(sourceId);
+      continue;
+    }
+
+    const integrationId = binding.integrationId;
+    if (!integrationId) {
+      skipped.push(sourceId);
+      continue;
+    }
+
+    const resolver = getSourceResolver(integrationId);
+    if (!resolver) {
+      skipped.push(sourceId);
+      continue;
+    }
+
+    try {
+      const connection = bridgeIntegrations.find(
+        (i) => i.provider === integrationId || i.id === integrationId
+      ) || null;
+      const records = await resolver.fetchRecords(adapterConfig, connection, binding);
+      const fetchedAt = new Date().toISOString();
+      await writeWorkspaceSourceRecords(sourceId, records, { integrationId, fetchedAt });
+      refreshed.push({ sourceId, integrationId, recordCount: records.length, fetchedAt });
+    } catch {
+      skipped.push(sourceId);
+    }
+  }
+
+  return NextResponse.json({ refreshed, skipped });
+}
+
+export { POST };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/register-resolver/route.js

@@ -0,0 +1,119 @@
+/**
+ * POST /api/workspace/register-resolver
+ *
+ * Accepts a `.js` resolver file upload and saves it to
+ * `lib/adapters/integrations/resolvers/<filename>.js`.
+ *
+ * Only available in filesystem mode (local development with
+ * WORKSPACE_CONFIG_ALLOW_FS_WRITE=true or NODE_ENV=development).
+ * In read-only runtimes this returns 409 with guidance.
+ *
+ * The uploaded file must:
+ *   - be a valid UTF-8 text JavaScript module
+ *   - call registerSourceResolver() at module level
+ *   - have a .js extension
+ *
+ * After upload, call POST /api/workspace/test-source to verify the resolver
+ * registers correctly and fetchRecords returns well-formed records.
+ *
+ * Request: multipart/form-data
+ *   file     — the .js resolver file
+ *   filename — optional override for the saved filename (slug.js)
+ *
+ * Response:
+ *   201 { saved: true, filename, path }
+ *   400 { error }
+ *   409 { error, guidance }
+ *   500 { error }
+ */
+
+import { NextResponse } from "next/server";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { describePersistenceMode } from "@/lib/workspace-config";
+
+const MAX_RESOLVER_SIZE = 256 * 1024; // 256 KB — resolvers should be small
+
+function slugify(name) {
+  return name
+    .toLowerCase()
+    .replace(/\.js$/, "")
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 64) || "resolver";
+}
+
+async function POST(request) {
+  const persistence = describePersistenceMode();
+  if (!persistence.canSave) {
+    return NextResponse.json({
+      error: "resolver upload requires a writable filesystem runtime",
+      guidance: persistence.guidance || "Set WORKSPACE_CONFIG_ALLOW_FS_WRITE=true or use local Next.js development mode."
+    }, { status: 409 });
+  }
+
+  let formData;
+  try {
+    formData = await request.formData();
+  } catch {
+    return NextResponse.json({ error: "expected multipart/form-data with a file field" }, { status: 400 });
+  }
+
+  const file = formData.get("file");
+  const filenameOverride = formData.get("filename");
+
+  if (!file || typeof file.text !== "function") {
+    return NextResponse.json({ error: "file field is required" }, { status: 400 });
+  }
+
+  const originalName = typeof file.name === "string" ? file.name : "resolver.js";
+  if (!originalName.endsWith(".js")) {
+    return NextResponse.json({ error: "resolver file must have a .js extension" }, { status: 400 });
+  }
+
+  if (file.size > MAX_RESOLVER_SIZE) {
+    return NextResponse.json({ error: `resolver file must be smaller than ${MAX_RESOLVER_SIZE / 1024} KB` }, { status: 400 });
+  }
+
+  let text;
+  try {
+    text = await file.text();
+  } catch {
+    return NextResponse.json({ error: "could not read uploaded file" }, { status: 400 });
+  }
+
+  if (!text.includes("registerSourceResolver")) {
+    return NextResponse.json({
+      error: "resolver file must call registerSourceResolver() — see lib/adapters/integrations/resolvers/README.md for the required shape"
+    }, { status: 400 });
+  }
+
+  const rawName = typeof filenameOverride === "string" && filenameOverride.trim()
+    ? filenameOverride.trim()
+    : originalName;
+  const filename = `${slugify(rawName)}.js`;
+
+  const resolversDir = path.resolve(/*turbopackIgnore: true*/ process.cwd(), "lib/adapters/integrations/resolvers");
+  const outPath = path.join(resolversDir, filename);
+
+  if (path.dirname(outPath) !== resolversDir) {
+    return NextResponse.json({ error: "invalid filename — path traversal not allowed" }, { status: 400 });
+  }
+
+  try {
+    await fs.mkdir(resolversDir, { recursive: true });
+    await fs.writeFile(outPath, text, "utf8");
+  } catch (err) {
+    return NextResponse.json({ error: `failed to write resolver file: ${err.message}` }, { status: 500 });
+  }
+
+  return NextResponse.json({
+    saved: true,
+    filename,
+    path: `lib/adapters/integrations/resolvers/${filename}`,
+    hint: "Run POST /api/workspace/test-source with integrationId to verify the resolver registers and fetchRecords works."
+  }, { status: 201 });
+}
+
+export { POST };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/resolvers/route.js

@@ -0,0 +1,41 @@
+/**
+ * GET /api/workspace/resolvers
+ *
+ * Lists resolver files present in lib/adapters/integrations/resolvers/ and
+ * returns provider-agnostic metadata for each registered resolver.
+ * Used by the generic resolver management panel and ResolverControlPanel in the
+ * widget inspector. No provider names appear in the response shape.
+ *
+ * Response:
+ *   {
+ *     files:         string[],
+ *     registeredIds: string[],
+ *     resolvers: {
+ *       integrationId:   string,
+ *       entityTypes:     string[],
+ *       hasListEntities: boolean,
+ *       configSchema:    SchemaField[] | null
+ *     }[],
+ *     canUpload: boolean
+ *   }
+ */
+
+import { NextResponse } from "next/server";
+import { loadAllResolvers, listResolverFiles } from "@/lib/adapters/integrations/resolver-loader";
+import { describeRegisteredResolvers } from "@/lib/adapters/integrations/source-resolver-registry";
+import { describePersistenceMode } from "@/lib/workspace-config";
+
+async function GET() {
+  await loadAllResolvers();
+  const files = await listResolverFiles();
+  const resolvers = describeRegisteredResolvers();
+  const persistence = describePersistenceMode();
+  return NextResponse.json({
+    files,
+    registeredIds: resolvers.map((r) => r.integrationId),
+    resolvers,
+    canUpload: persistence.canSave
+  });
+}
+
+export { GET };