@growthub/cli 0.9.13 → 0.9.14

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/docs/data-sources-api-registry.md

@@ -0,0 +1,139 @@
+# Data Sources and API Registry
+
+This workspace supports provider-agnostic API-backed data sources without storing credentials in Data Model records.
+
+Use this pattern for any external API:
+
+1. Store the provider secret in workspace settings or server env.
+2. Create an API Registry object.
+3. Create a Data Source object.
+4. Set the Data Source `registryId` to the API Registry row `integrationId`.
+5. Test the record from the Data Model drawer.
+6. Use the tested Data Source as the widget source.
+
+## Object Types
+
+### Data Source
+
+Data Source rows represent the data a widget can consume.
+
+Required fields:
+
+- `Name`: display name.
+- `registryId`: reference to an API Registry row by `integrationId`.
+- `endpoint`: provider endpoint path or full URL.
+- `authRef`: named secret reference, not the secret value.
+- `baseUrl`: provider base URL.
+- `status`: `untested`, `connected`, or `failed`.
+- `lastTested`: timestamp from the latest test.
+- `lastResponse`: saved JSON response shape from a successful test.
+
+### API Registry
+
+API Registry rows represent reusable API request configuration.
+
+Required fields:
+
+- `integrationId`: stable identifier used by Data Source `registryId`.
+- `authRef`: named secret reference, not the secret value.
+- `baseUrl`: provider base URL.
+- `endpoint`: default endpoint path.
+- `method`: HTTP method.
+- `status`: connection status from testing.
+- `lastTested`: timestamp from the latest test.
+- `lastResponse`: saved JSON response shape.
+- `entityTypes`: comma-separated source types this registry can power.
+- `description`: human-readable notes.
+
+## Credential Rules
+
+Never add secret fields such as `apiKey`, `authToken`, password, or bearer token to Data Model objects.
+
+Records store only `authRef`. The server resolves that reference to env/settings values. For example, an `authRef` of `LEADSHARK` can resolve to `LEADSHARK`, `LEADSHARK_API_KEY`, or `LEADSHARK_TOKEN`.
+
+Provider-specific request headers belong in the server-side test route or provider adapter. The Data Model surface stays credential-free.
+
+For APIs that do not use `x-api-key`, add non-secret request metadata to the API Registry row:
+
+- `authHeaderName`: header name such as `Authorization`, `X-API-Token`, or `x-api-key`.
+- `authPrefix`: optional value prefix such as `Bearer`.
+
+Do not store the secret value in either field.
+
+## Test Flow
+
+The Data Model record drawer has a `Test connection` action for Data Source and API Registry rows.
+
+For Data Source rows:
+
+1. The server loads the referenced API Registry row from `registryId`.
+2. It merges registry defaults with the Data Source row.
+3. It resolves `authRef` server-side.
+4. It sends the request from the API route.
+5. A successful response saves `status: connected`, `lastTested`, and JSON `lastResponse`.
+6. A failed response saves `status: failed` and must not mark the source connected.
+
+Only rows with a successful test and parseable saved `lastResponse` qualify as configured sources.
+
+## Widget Source Rules
+
+Widget source pickers show Data Model objects from workspace config.
+
+API Registry objects are not selectable as widget data sources. They are request configuration records.
+
+Data Source objects are selectable only when at least one row is:
+
+- `status` equal to `connected`, `approved`, `ok`, or `success`.
+- `lastResponse` is valid saved JSON.
+
+This ensures widgets bind only to tested, configured sources with a known returned shape.
+
+## LeadShark Example
+
+LeadShark uses:
+
+- Base URL: `https://apex.leadshark.io/api`
+- Leads endpoint: `/leads`
+- Header: `x-api-key`
+- Workspace secret reference: `LEADSHARK`
+
+Example API Registry row:
+
+```json
+{
+  "integrationId": "leadshark",
+  "authRef": "LEADSHARK",
+  "baseUrl": "https://apex.leadshark.io/api",
+  "endpoint": "/leads",
+  "method": "GET",
+  "status": "untested",
+  "entityTypes": "leads",
+  "description": "LeadShark leads API"
+}
+```
+
+Example Data Source row:
+
+```json
+{
+  "Name": "LeadShark Leads",
+  "registryId": "leadshark",
+  "endpoint": "/leads?page=1&limit=5",
+  "authRef": "LEADSHARK",
+  "baseUrl": "https://apex.leadshark.io/api",
+  "status": "untested"
+}
+```
+
+After a successful test, `lastResponse` should contain the provider JSON response shape. For LeadShark leads, the expected top-level shape includes `data` and `pagination`.
+
+## Scaling Pattern
+
+This is intentionally API-agnostic. The same primitive works for any provider when it follows the same contract:
+
+- One API Registry row per reusable provider request definition.
+- One or more Data Source rows that reference registry records.
+- No secrets in Data Model rows.
+- Server-side test execution.
+- Saved response shape after successful validation.
+- Widgets bind only to tested Data Sources.

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/adapters/integrations/resolver-loader.js

@@ -0,0 +1,57 @@
+/**
+ * Resolver dynamic loader — filesystem-safe, ESM-compatible.
+ *
+ * Reads every `.js` file from `lib/adapters/integrations/resolvers/` and
+ * side-effect-imports it so each file can call `registerSourceResolver()`.
+ *
+ * This runs server-side only. The browser never sees or calls this module.
+ * In read-only / production runtimes with no resolver files the registry
+ * stays empty — the refresh button and test route gracefully skip unknown
+ * integrationIds and surface them in the `skipped` array.
+ *
+ * Called once per route handler invocation (Next.js module cache means it
+ * will only do real I/O on the first call in each worker process).
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const loaded = new Set();
+let loadAttempted = false;
+
+async function loadAllResolvers() {
+  if (loadAttempted) return;
+  loadAttempted = true;
+  const resolversDir = path.resolve(/*turbopackIgnore: true*/ process.cwd(), "lib/adapters/integrations/resolvers");
+  try {
+    const entries = await fs.readdir(resolversDir);
+    const jsFiles = entries.filter((f) => f.endsWith(".js") && !f.startsWith("_") && !f.startsWith("."));
+    await Promise.all(
+      jsFiles.map(async (file) => {
+        if (loaded.has(file)) return;
+        try {
+          const absolutePath = path.join(resolversDir, file);
+          await import(/*turbopackIgnore: true*/ pathToFileURL(absolutePath).href);
+          loaded.add(file);
+        } catch {
+          // Malformed resolver — skip silently; operator needs to fix the file
+        }
+      })
+    );
+  } catch {
+    // resolvers directory missing or empty — normal for fresh upstream kit
+  }
+}
+
+async function listResolverFiles() {
+  const resolversDir = path.resolve(/*turbopackIgnore: true*/ process.cwd(), "lib/adapters/integrations/resolvers");
+  try {
+    const entries = await fs.readdir(resolversDir);
+    return entries.filter((f) => f.endsWith(".js") && !f.startsWith("_") && !f.startsWith("."));
+  } catch {
+    return [];
+  }
+}
+
+export { loadAllResolvers, listResolverFiles };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/adapters/integrations/resolvers/README.md

@@ -0,0 +1,133 @@
+# Integration Resolvers
+
+Drop one `.js` file per integration here. Each file calls `registerSourceResolver()` once at module load.
+
+**No resolver files ship in the upstream kit.** This directory is the extension point — operators add their own files for whatever integrations they connect (Asana, Linear, HubSpot, a custom API, a BYO token endpoint, a webhook, anything).
+
+## Resolver shape
+
+```js
+import { registerSourceResolver } from "../source-resolver-registry.js";
+
+registerSourceResolver({
+  integrationId: "your-provider-slug",   // must match binding.integrationId in dataModel
+  entityTypes: ["object.type"],          // list of types this resolver handles
+  listEntities: async (config, connection) => NormalizedEntity[],
+  fetchRecords: async (config, connection, binding) => Record[]
+});
+```
+
+## Agent CLI commands
+
+All commands output JSON. Pipe through `| jq` for filtering.
+
+```bash
+# List registered resolver IDs and on-disk files
+curl -s http://localhost:3000/api/workspace/resolvers
+
+# Test a resolver without saving (returns preview rows or error reason)
+curl -s -X POST http://localhost:3000/api/workspace/test-source \
+  -H "Content-Type: application/json" \
+  -d '{
+    "integrationId": "your-provider-slug",
+    "binding": {
+      "entityType": "your.entity.type",
+      "sourceStorage": "workspace-source-records",
+      "sourceId": "your-source-id"
+    }
+  }'
+
+# Trigger a full refresh for one or more source IDs on the active tab
+curl -s -X POST http://localhost:3000/api/workspace/refresh-sources \
+  -H "Content-Type: application/json" \
+  -d '{"sourceIds": ["your-source-id"]}'
+
+# Register a data model object backed by this resolver (persists to growthub.config.json)
+curl -s -X PATCH http://localhost:3000/api/workspace \
+  -H "Content-Type: application/json" \
+  -d '{
+    "dataModel": {
+      "objects": [
+        {
+          "id": "your-source-id",
+          "label": "Your Source Label",
+          "objectType": "your.object.type",
+          "storageType": "manual-object",
+          "columns": ["col1", "col2"],
+          "rows": [],
+          "sourceId": "your-source-id",
+          "binding": {
+            "mode": "integration",
+            "sourceStorage": "workspace-source-records",
+            "integrationId": "your-provider-slug",
+            "sourceId": "your-source-id",
+            "entityType": "your.entity.type"
+          }
+        }
+      ]
+    }
+  }'
+
+# Read back the full workspace config (data model objects, canvas, adapters)
+curl -s http://localhost:3000/api/workspace
+```
+
+### Response contracts
+
+**`GET /api/workspace/resolvers`**
+```json
+{
+  "files": ["google-analytics.js"],
+  "registeredIds": ["google-analytics"],
+  "canUpload": true
+}
+```
+
+**`POST /api/workspace/test-source` — resolver found, token missing**
+```json
+{
+  "ok": false,
+  "reason": "fetch-error",
+  "integrationId": "google-analytics",
+  "error": "GOOGLE_ANALYTICS_ACCESS_TOKEN is not set. Add it to .env.local to enable GA4 data refresh."
+}
+```
+
+**`POST /api/workspace/test-source` — resolver found, records returned**
+```json
+{
+  "ok": true,
+  "integrationId": "google-analytics",
+  "recordCount": 120,
+  "columns": ["date", "channel", "device", "sessions", "activeUsers", "bounceRate"],
+  "preview": [{ "date": "20260501", "channel": "Organic Search", "sessions": 412 }],
+  "entityTypes": ["ga4.traffic"]
+}
+```
+
+**`POST /api/workspace/refresh-sources`**
+```json
+{ "refreshed": ["your-source-id"], "skipped": [] }
+```
+
+## Data model and source dropdown flow
+
+1. Add resolver file here → resolver registers on server start.
+2. `PATCH /api/workspace` with a `dataModel.objects` entry that sets `binding.sourceStorage: "workspace-source-records"` and `binding.integrationId` matching this resolver.
+3. Source dropdown in the workspace builder shows the object as a selectable dynamic source (resolver-backed objects appear in the **Dynamic sources** section).
+4. User clicks Refresh on the tab bar → `POST /api/workspace/refresh-sources` → resolver `fetchRecords` runs → records persisted → widgets re-render.
+
+## How the refresh button connects to this
+
+1. User configures a `dataModel.object` with `binding.sourceStorage: "workspace-source-records"` and `binding.integrationId: "your-provider-slug"`.
+2. User clicks Refresh on the tab bar.
+3. The builder collects all `sourceId` values from live-backed widgets on the active tab and POSTs them to `/api/workspace/refresh-sources`.
+4. The route looks up the resolver by `integrationId`, calls `fetchRecords`, and persists normalized records via `writeWorkspaceSourceRecords`.
+5. The builder reloads from `/api/workspace` and the widgets render the updated rows.
+
+## Auth contract
+
+- **Tokens stay server-side.** Provider tokens live in the Growthub bridge / BYO env var store — never in workspace config or client state.
+- The bridge confirms which integrations are connected. It does not proxy data. The resolver reads `process.env.YOUR_PROVIDER_TOKEN` and calls the provider API directly.
+- `config` passed to your resolver is the server-side `adapterConfig` from `readAdapterConfig()`. Read `process.env.YOUR_TOKEN` server-side inside the resolver. Never forward it to the client.
+- Normalize provider responses to display-safe records before returning — no raw API payloads, no token-adjacent fields.

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/adapters/integrations/resolvers/google-analytics.js

@@ -0,0 +1,160 @@
+/**
+ * Google Analytics 4 — Source Resolver
+ *
+ * Auth path:
+ *   GROWTHUB_BRIDGE_ACCESS_TOKEN (set in .env.local by `growthub starter init`)
+ *   → GET /api/cli/profile?view=integration&provider=google-analytics
+ *   → short-lived Google OAuth accessToken
+ *   → GA4 Admin API (accountSummaries → property list)
+ *   → GA4 Data API (runReport)
+ *
+ * Required env vars (set automatically in .env.local):
+ *   GROWTHUB_BRIDGE_ACCESS_TOKEN
+ *   GROWTHUB_BRIDGE_USER_ID      (optional — improves routing)
+ *   GROWTHUB_BRIDGE_BASE_URL     (default: https://www.growthub.ai)
+ *
+ * Optional env vars:
+ *   GOOGLE_ANALYTICS_PROPERTY_ID     override property for fetchRecords
+ *   GOOGLE_ANALYTICS_DATE_RANGE_DAYS  lookback window (default 30)
+ */
+
+import { registerSourceResolver } from "../source-resolver-registry.js";
+
+const GA4_DATA_API = "https://analyticsdata.googleapis.com/v1beta";
+const GA4_ADMIN_API = "https://analyticsadmin.googleapis.com/v1beta";
+
+/**
+ * Resolve the GA4 access token.
+ *
+ * GROWTHUB_BRIDGE_ACCESS_TOKEN is the Google OAuth access token vended by the
+ * Growthub bridge for the connected google-analytics integration. It is used
+ * directly — no secondary bridge API call required.
+ */
+function resolveGA4AccessToken() {
+  const token = process.env.GROWTHUB_BRIDGE_ACCESS_TOKEN;
+  if (!token) {
+    throw new Error(
+      "GROWTHUB_BRIDGE_ACCESS_TOKEN is not set. Export it from growthub.ai/settings/connections."
+    );
+  }
+  return token;
+}
+
+/**
+ * List all GA4 properties for the authenticated account.
+ */
+async function listGA4Properties(ga4Token) {
+  const res = await fetch(`${GA4_ADMIN_API}/accountSummaries`, {
+    headers: { Authorization: `Bearer ${ga4Token}`, Accept: "application/json" },
+  });
+  if (!res.ok) {
+    throw new Error(`GA4 Admin API ${res.status}: ${await res.text()}`);
+  }
+  const data = await res.json();
+  return (data.accountSummaries || []).flatMap((account) =>
+    (account.propertySummaries || []).map((prop) => ({
+      id: prop.property,
+      label: `${prop.displayName} — ${account.displayName}`,
+      type: "ga4.account",
+      meta: {
+        propertyId: prop.property,
+        accountId: account.account,
+        accountName: account.displayName,
+      },
+    }))
+  );
+}
+
+/**
+ * Run a GA4 traffic report for the given property.
+ */
+async function fetchGA4Report(ga4Token, propertyId, days = 30) {
+  const body = {
+    dateRanges: [{ startDate: `${days}daysAgo`, endDate: "today" }],
+    dimensions: [
+      { name: "date" },
+      { name: "sessionDefaultChannelGroup" },
+      { name: "deviceCategory" },
+    ],
+    metrics: [
+      { name: "sessions" },
+      { name: "activeUsers" },
+      { name: "bounceRate" },
+      { name: "averageSessionDuration" },
+      { name: "conversions" },
+    ],
+    orderBys: [{ dimension: { dimensionName: "date" }, desc: true }],
+    limit: 500,
+  };
+
+  const res = await fetch(`${GA4_DATA_API}/${propertyId}:runReport`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${ga4Token}`,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    throw new Error(`GA4 Data API ${res.status}: ${await res.text()}`);
+  }
+
+  const report = await res.json();
+  const dimHeaders = (report.dimensionHeaders || []).map((h) => h.name);
+  const metHeaders = (report.metricHeaders || []).map((h) => h.name);
+
+  return (report.rows || []).map((row) => {
+    const dims = Object.fromEntries(
+      dimHeaders.map((name, i) => [name, row.dimensionValues?.[i]?.value ?? null])
+    );
+    const mets = Object.fromEntries(
+      metHeaders.map((name, i) => {
+        const raw = row.metricValues?.[i]?.value ?? null;
+        return [name, raw !== null ? Number(raw) : null];
+      })
+    );
+    return {
+      date: dims.date ?? null,
+      channel: dims.sessionDefaultChannelGroup ?? null,
+      device: dims.deviceCategory ?? null,
+      sessions: mets.sessions ?? 0,
+      activeUsers: mets.activeUsers ?? 0,
+      bounceRate: mets.bounceRate != null ? Number((mets.bounceRate * 100).toFixed(2)) : null,
+      avgSessionDuration: mets.averageSessionDuration != null
+        ? Number(mets.averageSessionDuration.toFixed(1))
+        : null,
+      conversions: mets.conversions ?? 0,
+    };
+  });
+}
+
+registerSourceResolver({
+  integrationId: "google-analytics",
+
+  entityTypes: ["ga4.traffic", "ga4.account"],
+
+  listEntities: async (_config, _connection) => {
+    const ga4Token = resolveGA4AccessToken();
+    return await listGA4Properties(ga4Token);
+  },
+
+  fetchRecords: async (_config, _connection, binding) => {
+    const ga4Token = resolveGA4AccessToken();
+
+    const propertyId =
+      binding?.propertyId ||
+      process.env.GOOGLE_ANALYTICS_PROPERTY_ID;
+
+    if (!propertyId) {
+      throw new Error(
+        "No GA4 property ID configured. Set binding.propertyId in the data model object " +
+        "or GOOGLE_ANALYTICS_PROPERTY_ID in .env.local."
+      );
+    }
+
+    const days = Number(process.env.GOOGLE_ANALYTICS_DATE_RANGE_DAYS || 30);
+    return fetchGA4Report(ga4Token, propertyId, days);
+  },
+});

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/lib/adapters/integrations/source-resolver-registry.js

@@ -0,0 +1,85 @@
+/**
+ * Source Resolver Registry — provider-agnostic dispatch layer.
+ *
+ * Contract:
+ *   Each integration ships its own resolver file under
+ *   `lib/adapters/integrations/resolvers/<id>.js` and calls
+ *   `registerSourceResolver` once at module load time.
+ *
+ * Resolver shape:
+ * {
+ *   integrationId: string,           // stable provider slug, e.g. "asana"
+ *   entityTypes: string[],           // e.g. ["project.tasks", "workspace.users"]
+ *   listEntities: async (config, connection) => NormalizedEntity[],
+ *   fetchRecords: async (config, connection, binding) => Record[]
+ * }
+ *
+ * The route and the refresh button reference this registry only — they have
+ * zero knowledge of Asana, Linear, HubSpot, or any other provider. Every
+ * provider-specific fetch lives in its own resolver file and is completely
+ * isolated from the others.
+ */
+
+// globalThis singleton so resolver files loaded via dynamic file:// import
+// share the same Map instance as the Next.js-bundled copy of this module.
+if (!globalThis.__growthubSourceResolverRegistry) {
+  globalThis.__growthubSourceResolverRegistry = new Map();
+}
+const registry = globalThis.__growthubSourceResolverRegistry;
+
+/**
+ * Register a source resolver. Called once per provider at module load.
+ * Calling again with the same integrationId replaces the existing resolver.
+ */
+function registerSourceResolver(resolver) {
+  if (!resolver || typeof resolver !== "object") {
+    throw new Error("registerSourceResolver: resolver must be a plain object");
+  }
+  if (typeof resolver.integrationId !== "string" || !resolver.integrationId.trim()) {
+    throw new Error("registerSourceResolver: resolver.integrationId must be a non-empty string");
+  }
+  if (typeof resolver.fetchRecords !== "function") {
+    throw new Error(`registerSourceResolver(${resolver.integrationId}): resolver.fetchRecords must be a function`);
+  }
+  registry.set(resolver.integrationId.trim(), resolver);
+}
+
+/**
+ * Look up a registered resolver by integration id.
+ * Returns null when no resolver has been registered for that id.
+ */
+function getSourceResolver(integrationId) {
+  if (typeof integrationId !== "string" || !integrationId.trim()) return null;
+  return registry.get(integrationId.trim()) || null;
+}
+
+/**
+ * List all registered integration ids. Useful for diagnostics.
+ */
+function listRegisteredResolvers() {
+  return Array.from(registry.keys());
+}
+
+/**
+ * Describe all registered resolvers — returns provider-agnostic metadata declared
+ * by each resolver file. The UI uses this to render generic controls without any
+ * knowledge of specific providers.
+ *
+ * Shape per entry:
+ *   {
+ *     integrationId: string,
+ *     entityTypes:   string[],           // declared by the resolver
+ *     hasListEntities: boolean,          // true if resolver.listEntities is a function
+ *     configSchema: SchemaField[] | null // optional declarative params schema
+ *   }
+ */
+function describeRegisteredResolvers() {
+  return Array.from(registry.entries()).map(([id, resolver]) => ({
+    integrationId: id,
+    entityTypes: Array.isArray(resolver.entityTypes) ? resolver.entityTypes : [],
+    hasListEntities: typeof resolver.listEntities === "function",
+    configSchema: Array.isArray(resolver.configSchema) ? resolver.configSchema : null,
+  }));
+}
+
+export { registerSourceResolver, getSourceResolver, listRegisteredResolvers, describeRegisteredResolvers };

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

@@ -338,6 +338,82 @@ async function writeWorkspaceApiWebhookSettings(patch) {
   return next.integrations.filter((item) => item?.sourceType === "custom-api-webhooks");
 }
 
+/**
+ * Source Records persistence — sidecar store for live-backed dataModel objects.
+ *
+ * Records are written by POST /api/workspace/refresh-sources when a resolver
+ * fetches live data for a source with `binding.sourceStorage: "workspace-source-records"`.
+ *
+ * Persistence is keyed by `sourceId` and stored in a JSON sidecar file
+ * (`growthub.source-records.json`) beside `growthub.config.json`. The same
+ * filesystem / read-only / database mode rules apply: in read-only mode writes
+ * are rejected gracefully so the refresh button surface is disabled.
+ *
+ * Shape: { [sourceId]: { records: Record[], integrationId: string, fetchedAt: string } }
+ */
+
+const SOURCE_RECORDS_FILENAME = "growthub.source-records.json";
+
+function resolveSourceRecordsPath() {
+  return path.resolve(/*turbopackIgnore: true*/ process.cwd(), SOURCE_RECORDS_FILENAME);
+}
+
+async function readWorkspaceSourceRecords(sourceId) {
+  const recordsPath = resolveSourceRecordsPath();
+  try {
+    const raw = await fs.readFile(recordsPath, "utf8");
+    const all = JSON.parse(raw);
+    if (sourceId) {
+      return all[sourceId] || null;
+    }
+    return all;
+  } catch {
+    return sourceId ? null : {};
+  }
+}
+
+async function writeWorkspaceSourceRecords(sourceId, records, metadata = {}) {
+  const persistence = describePersistenceMode();
+  if (persistence.mode !== PERSISTENCE_ADAPTERS.FILESYSTEM || !persistence.canSave) {
+    const error = new Error(persistence.reason);
+    error.code = "WORKSPACE_PERSISTENCE_READ_ONLY";
+    error.guidance = persistence.guidance || READ_ONLY_GUIDANCE;
+    throw error;
+  }
+  if (typeof sourceId !== "string" || !sourceId.trim()) {
+    const error = new Error("sourceId must be a non-empty string");
+    error.code = "INVALID_SOURCE_RECORDS_WRITE";
+    throw error;
+  }
+  if (!Array.isArray(records)) {
+    const error = new Error("records must be an array");
+    error.code = "INVALID_SOURCE_RECORDS_WRITE";
+    throw error;
+  }
+  const recordsPath = resolveSourceRecordsPath();
+  const expectedDir = path.resolve(/*turbopackIgnore: true*/ process.cwd());
+  if (path.dirname(recordsPath) !== expectedDir) {
+    const error = new Error(`refused to write outside workspace cwd: ${recordsPath}`);
+    error.code = "WORKSPACE_PERSISTENCE_PATH_REFUSED";
+    throw error;
+  }
+  let all = {};
+  try {
+    const raw = await fs.readFile(recordsPath, "utf8");
+    all = JSON.parse(raw);
+  } catch {
+    all = {};
+  }
+  all[sourceId.trim()] = {
+    records,
+    integrationId: metadata.integrationId || null,
+    fetchedAt: metadata.fetchedAt || new Date().toISOString(),
+    recordCount: records.length
+  };
+  await fs.writeFile(recordsPath, `${JSON.stringify(all, null, 2)}\n`, "utf8");
+  return all[sourceId.trim()];
+}
+
 export {
   GRID_COLUMNS,
   GRID_ROWS,
@@ -346,9 +422,11 @@ export {
   READ_ONLY_GUIDANCE,
   describePersistenceMode,
   readWorkspaceConfig,
+  readWorkspaceSourceRecords,
   resolveWorkspaceConfigPath,
   validateWorkspaceConfig,
   writeWorkspaceConfig,
   writeWorkspaceApiWebhookSettings,
-  writeWorkspaceIdentitySettings
+  writeWorkspaceIdentitySettings,
+  writeWorkspaceSourceRecords
 };