@growthub/cli 0.9.8 → 0.9.9

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

@@ -1,7 +1,12 @@
 {
   "id": "workspace-builder-default",
-  "name": "Workspace Builder",
-  "description": "Default no-code composition for the official Growthub Custom Workspace Starter. The interface starts as a configurable dashboard-builder shell and can be customized by editing this file or by future governed UI controls.",
+  "name": "Growthub Workspace",
+  "description": "Default no-code composition for the official Growthub Custom Workspace Starter. The interface starts as a governed dashboard workspace and can be customized by editing this file or by future governed UI controls.",
+  "branding": {
+    "name": "Growthub Workspace",
+    "logoUrl": "",
+    "accent": "#3f68ff"
+  },
   "capabilities": [
     "dashboards",
     "canvas",
@@ -47,7 +52,7 @@
   },
   "provenance": {
     "createdBy": "cli",
-    "mirrors": "growthub-agency-portal-starter-v1",
+    "mirrors": "growthub-custom-workspace-starter-v1",
     "note": "Shipped with growthub-custom-workspace-starter-v1; safe to edit inside a governed fork and validate through the starter export smoke path."
   }
 }

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

@@ -1,11 +1,11 @@
 function readAdapterConfig() {
   return {
     deployTarget: "vercel",
-    dataAdapter: readEnum("AGENCY_PORTAL_DATA_ADAPTER", ["postgres", "qstash-kv", "provider-managed"], "provider-managed"),
-    authAdapter: readEnum("AGENCY_PORTAL_AUTH_ADAPTER", ["oidc", "clerk", "authjs", "provider-managed"], "provider-managed"),
-    paymentAdapter: readEnum("AGENCY_PORTAL_PAYMENT_ADAPTER", ["none", "stripe", "polar"], "none"),
-    integrationAdapter: readEnum("AGENCY_PORTAL_INTEGRATION_ADAPTER", ["growthub-bridge", "byo-api-key", "static"], "static"),
-    reportingAdapter: process.env.AGENCY_PORTAL_REPORTING_ADAPTER || void 0,
+    dataAdapter: readEnum(["GROWTHUB_WORKSPACE_DATA_ADAPTER", "AGENCY_PORTAL_DATA_ADAPTER"], ["postgres", "qstash-kv", "provider-managed"], "provider-managed"),
+    authAdapter: readEnum(["GROWTHUB_WORKSPACE_AUTH_ADAPTER", "AGENCY_PORTAL_AUTH_ADAPTER"], ["oidc", "clerk", "authjs", "provider-managed"], "provider-managed"),
+    paymentAdapter: readEnum(["GROWTHUB_WORKSPACE_PAYMENT_ADAPTER", "AGENCY_PORTAL_PAYMENT_ADAPTER"], ["none", "stripe", "polar"], "none"),
+    integrationAdapter: readEnum(["GROWTHUB_WORKSPACE_INTEGRATION_ADAPTER", "AGENCY_PORTAL_INTEGRATION_ADAPTER"], ["growthub-bridge", "byo-api-key", "static"], "static"),
+    reportingAdapter: process.env.GROWTHUB_WORKSPACE_REPORTING_ADAPTER || process.env.AGENCY_PORTAL_REPORTING_ADAPTER || void 0,
     growthubBridge: {
       baseUrl: process.env.GROWTHUB_BRIDGE_BASE_URL || void 0,
       integrationsPath: process.env.GROWTHUB_BRIDGE_INTEGRATIONS_PATH || "/api/mcp/accounts",
@@ -17,8 +17,10 @@ function readAdapterConfig() {
     }
   };
 }
-function readEnum(key, allowed, fallback) {
-  const value = process.env[key];
+function readEnum(keys, allowed, fallback) {
+  const keyList = Array.isArray(keys) ? keys : [keys];
+  const key = keyList.find((candidate) => process.env[candidate]);
+  const value = key ? process.env[key] : undefined;
   if (!value) return fallback;
   if (allowed.includes(value)) return value;
   throw new Error(`${key} must be one of: ${allowed.join(", ")}`);

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

@@ -1,6 +1,6 @@
 import { readAdapterConfig } from "@/lib/adapters/env";
 import {
-  agencyPortalIntegrationCatalog
+  governedWorkspaceIntegrationCatalog
 } from "@/lib/domain/integrations";
 import {
   normalizeGrowthubBridgePayload
@@ -19,7 +19,7 @@ function describeIntegrationAdapter() {
     return {
       id: "byo-api-key",
       label: "Bring your own API key",
-      requiredEnv: ["AGENCY_PORTAL_BYO_CONNECTIONS_JSON"],
+      requiredEnv: ["GROWTHUB_WORKSPACE_BYO_CONNECTIONS_JSON"],
       authority: "workspace-env"
     };
   }
@@ -30,16 +30,16 @@ function describeIntegrationAdapter() {
     authority: "local-catalog"
   };
 }
-async function listAgencyPortalIntegrations() {
+async function listGovernedWorkspaceIntegrations() {
   const config = readAdapterConfig();
   if (config.integrationAdapter !== "growthub-bridge") {
     if (config.integrationAdapter === "byo-api-key") {
       return mergeBringYourOwnRows(readBringYourOwnRows());
     }
-    return agencyPortalIntegrationCatalog;
+    return governedWorkspaceIntegrationCatalog;
   }
   if (!config.growthubBridge.baseUrl || !process.env.GROWTHUB_BRIDGE_ACCESS_TOKEN) {
-    return agencyPortalIntegrationCatalog;
+    return governedWorkspaceIntegrationCatalog;
   }
   const url = new URL(config.growthubBridge.integrationsPath, config.growthubBridge.baseUrl);
   const headers = {
@@ -54,7 +54,7 @@ async function listAgencyPortalIntegrations() {
     next: { revalidate: 30 }
   });
   if (!response.ok) {
-    return agencyPortalIntegrationCatalog;
+    return governedWorkspaceIntegrationCatalog;
   }
   const payload = await response.json();
   const merged = mergeBridgeRows(normalizeGrowthubBridgePayload(payload));
@@ -80,7 +80,7 @@ function applyApiKeyOverlays(integrations, config) {
   });
 }
 function readBringYourOwnRows() {
-  const raw = process.env.AGENCY_PORTAL_BYO_CONNECTIONS_JSON;
+  const raw = process.env.GROWTHUB_WORKSPACE_BYO_CONNECTIONS_JSON || process.env.AGENCY_PORTAL_BYO_CONNECTIONS_JSON;
   const rows = [];
   if (process.env.WINDSOR_API_KEY) {
     rows.push({
@@ -129,7 +129,7 @@ function mergeBringYourOwnRows(rows) {
 }
 function mergeBridgeRows(rows) {
   const seenProviders = /* @__PURE__ */ new Set();
-  const merged = agencyPortalIntegrationCatalog.map((catalogItem) => {
+  const merged = governedWorkspaceIntegrationCatalog.map((catalogItem) => {
     const row = rows.find((item) => {
       const provider = item.provider || item.id;
       return provider === catalogItem.provider || item.id === catalogItem.id;
@@ -160,7 +160,7 @@ function mergeBridgeRows(rows) {
     const provider = row.provider || row.id;
     if (!provider) return false;
     if (seenProviders.has(provider)) return false;
-    return !agencyPortalIntegrationCatalog.some((item) => item.provider === provider || item.id === row.id);
+    return !governedWorkspaceIntegrationCatalog.some((item) => item.provider === provider || item.id === row.id);
   });
   return [...merged, ...discoveredRows.map(toDiscoveredIntegration)];
 }
@@ -194,5 +194,5 @@ function toDiscoveredIntegration(row) {
 }
 export {
   describeIntegrationAdapter,
-  listAgencyPortalIntegrations
+  listGovernedWorkspaceIntegrations
 };

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

@@ -172,7 +172,7 @@ const workspaceIntegrations = [
     setupMode: "hosted-authority"
   }
 ];
-const agencyPortalIntegrationCatalog = [...dataSources, ...workspaceIntegrations];
+const governedWorkspaceIntegrationCatalog = [...dataSources, ...workspaceIntegrations];
 function groupIntegrationsByLane(integrations) {
   return {
     dataSources: integrations.filter((item) => item.lane === "data-source"),
@@ -180,6 +180,6 @@ function groupIntegrationsByLane(integrations) {
   };
 }
 export {
-  agencyPortalIntegrationCatalog,
+  governedWorkspaceIntegrationCatalog,
   groupIntegrationsByLane
 };

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

@@ -1,3 +1,22 @@
+/**
+ * Workspace persistence — thin adapter boundary.
+ *
+ * Modes (Workspace Builder Runtime V1 contract — `docs/WORKSPACE_BUILDER_RUNTIME_V1.md`):
+ *
+ *   - `filesystem`    Local Next.js dev or any runtime that opts in via
+ *                     `WORKSPACE_CONFIG_ALLOW_FS_WRITE=true`. Save writes
+ *                     `growthub.config.json` on disk.
+ *   - `read-only`     Vercel / Netlify-style runtimes where the bundle is
+ *                     immutable. `PATCH /api/workspace` returns 409 with the
+ *                     same `guidance` string the no-code Save UI surfaces.
+ *   - `database` (future) Reserved adapter slot. Not implemented in V1 — the
+ *                     return shape is stable so a hosted adapter can be wired
+ *                     without changing UI or API contracts.
+ *
+ * `describePersistenceMode()` is the single source of truth the GET payload,
+ * the no-code Settings/Readiness panel, and the PATCH 409 path all read.
+ */
+
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { readAdapterConfig } from "@/lib/adapters/env";
@@ -8,6 +27,15 @@ import {
   validateWorkspaceConfig
 } from "@/lib/workspace-schema";
 
+const PERSISTENCE_ADAPTERS = Object.freeze({
+  FILESYSTEM: "filesystem",
+  READ_ONLY: "read-only",
+  DATABASE: "database"
+});
+
+const READ_ONLY_GUIDANCE =
+  "Edit growthub.config.json locally, or set WORKSPACE_CONFIG_ALLOW_FS_WRITE=true on a writable runtime.";
+
 function resolveWorkspaceConfigPath() {
   return path.resolve(/*turbopackIgnore: true*/ process.cwd(), "growthub.config.json");
 }
@@ -18,23 +46,47 @@ async function readWorkspaceConfig() {
   return JSON.parse(raw);
 }
 
+/**
+ * `canSave` is a *logical* statement about adapter mode, not a *filesystem*
+ * guarantee. A `filesystem`-mode workspace whose `growthub.config.json` is
+ * actually read-only on disk (permission denied, RO mount) will still report
+ * `canSave: true`; the no-code Save UI surfaces the underlying fs error
+ * (workspace-builder.jsx#save → setConfigMessage) and PATCH returns 500 with
+ * the original error message. Read-only-mode 409 is the *contractual* not-save
+ * path and gets verbatim `guidance` instead.
+ */
 function describePersistenceMode() {
-  const target = process.env.AGENCY_PORTAL_DEPLOY_TARGET || "vercel";
+  const target = process.env.GROWTHUB_WORKSPACE_DEPLOY_TARGET || process.env.AGENCY_PORTAL_DEPLOY_TARGET || "vercel";
   const isReadOnlyDeploy = target === "vercel" || target === "netlify";
   const allowFsWrite = process.env.WORKSPACE_CONFIG_ALLOW_FS_WRITE === "true";
+  const baseFilesystem = (reason) => ({
+    mode: PERSISTENCE_ADAPTERS.FILESYSTEM,
+    adapter: PERSISTENCE_ADAPTERS.FILESYSTEM,
+    canSave: true,
+    saveLabel: "Save writes growthub.config.json on disk.",
+    reason,
+    nextAction: null,
+    guidance: null
+  });
   if (allowFsWrite) {
-    return { mode: "filesystem", reason: "WORKSPACE_CONFIG_ALLOW_FS_WRITE=true" };
+    return baseFilesystem("WORKSPACE_CONFIG_ALLOW_FS_WRITE=true");
   }
   if (process.env.NODE_ENV === "development") {
-    return { mode: "filesystem", reason: "Local Next.js development" };
+    return baseFilesystem("Local Next.js development");
   }
   if (isReadOnlyDeploy) {
+    const reason = `Deploy target ${target} treats the bundle as read-only. Set WORKSPACE_CONFIG_ALLOW_FS_WRITE=true on a writable runtime, or wire a hosted persistence adapter.`;
     return {
-      mode: "read-only",
-      reason: `Deploy target ${target} treats the bundle as read-only. Set WORKSPACE_CONFIG_ALLOW_FS_WRITE=true on a writable runtime, or wire a hosted persistence adapter.`
+      mode: PERSISTENCE_ADAPTERS.READ_ONLY,
+      adapter: PERSISTENCE_ADAPTERS.READ_ONLY,
+      canSave: false,
+      saveLabel: "Save is disabled in this runtime.",
+      reason,
+      nextAction: "Set WORKSPACE_CONFIG_ALLOW_FS_WRITE=true or connect a persistence adapter.",
+      guidance: READ_ONLY_GUIDANCE
     };
   }
-  return { mode: "filesystem", reason: "Local development" };
+  return baseFilesystem("Local development");
 }
 
 function applyPatch(currentConfig, patch) {
@@ -76,10 +128,11 @@ function applyPatch(currentConfig, patch) {
 async function writeWorkspaceConfig(patch) {
   const persistence = describePersistenceMode();
   const adapter = readAdapterConfig();
-  if (persistence.mode !== "filesystem") {
+  if (persistence.mode !== PERSISTENCE_ADAPTERS.FILESYSTEM || !persistence.canSave) {
     const error = new Error(persistence.reason);
     error.code = "WORKSPACE_PERSISTENCE_READ_ONLY";
     error.adapter = adapter.integrationAdapter;
+    error.guidance = persistence.guidance || READ_ONLY_GUIDANCE;
     throw error;
   }
   const current = await readWorkspaceConfig();
@@ -104,6 +157,8 @@ export {
   GRID_COLUMNS,
   GRID_ROWS,
   KNOWN_WIDGET_KINDS,
+  PERSISTENCE_ADAPTERS,
+  READ_ONLY_GUIDANCE,
   describePersistenceMode,
   readWorkspaceConfig,
   resolveWorkspaceConfigPath,

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

@@ -1,3 +1,41 @@
+/**
+ * Workspace Config Contract V1 — local source of truth.
+ *
+ * Authoritative reference: `docs/WORKSPACE_CONFIG_CONTRACT_V1.md`.
+ * Companion runtime doc: `docs/WORKSPACE_BUILDER_RUNTIME_V1.md`.
+ *
+ * This file owns the workspace config validator. The persisted file lives at
+ * `<workspace>/growthub.config.json`. The PATCH allowlist on `/api/workspace`
+ * is permanently restricted to:
+ *
+ *   - `dashboards`     dashboard rows (id, name, status, tabs, activeTabId)
+ *   - `widgetTypes`    palette of allowed widget kinds (label/icon)
+ *   - `canvas`         active canvas: layout, single-tab `widgets[]`, or
+ *                      multi-tab `tabs[]` + `activeTabId`, plus `bindings`
+ *
+ * Other top-level fields (`id`, `name`, `description`, `capabilities`,
+ * `branding`, `pipelines`, `integrations`, `provenance`) are preserved
+ * round-trip but cannot be mutated through PATCH. The validator rejects
+ * unknown fields inside the three allowlisted sections.
+ *
+ * Canonical canvas shape (mutually exclusive — never both at once):
+ *
+ *   single-tab → `canvas.widgets[]`           (DO NOT also serialize tabs)
+ *   multi-tab  → `canvas.tabs[]` + `activeTabId` (DO NOT also serialize widgets)
+ *
+ * Import/export envelope: `{ version: 1, kind: "growthub-workspace-template",
+ * exportedAt, source, name, description, payload }`. Raw `{dashboards,
+ * widgetTypes, canvas}` payloads are also accepted for back-compat.
+ *
+ * Widget grid is a strict 12-column × 16-row fixed lattice with
+ * non-overlapping integer rectangles. Widget IDs are minted at clone time —
+ * template widgets intentionally omit `id`.
+ *
+ * Validation errors are surfaced as readable strings on the thrown error
+ * (`error.details: string[]`) so agents and the no-code Save UI can round-trip
+ * them without parsing a stack trace.
+ */
+
 const GRID_COLUMNS = 12;
 const GRID_ROWS = 16;
 const KNOWN_WIDGET_KINDS = ["chart", "view", "iframe", "rich-text"];

package/assets/worker-kits/growthub-custom-workspace-starter-v1/kit.json

@@ -73,9 +73,12 @@
     "apps/workspace/app/layout.jsx",
     "apps/workspace/app/page.jsx",
     "apps/workspace/app/globals.css",
+    "apps/workspace/app/workspace-builder.jsx",
     "apps/workspace/app/settings/integrations/page.jsx",
     "apps/workspace/app/api/workspace/route.js",
     "apps/workspace/app/api/settings/integrations/route.js",
+    "apps/workspace/lib/workspace-schema.js",
+    "apps/workspace/lib/workspace-config.js",
     "apps/workspace/lib/domain/portal.js",
     "apps/workspace/lib/domain/integrations.js",
     "apps/workspace/lib/adapters/env.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growthub/cli",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "Growthub Local is a control plane for forked worker kits. The CLI is the executor, the hosted app is the identity authority, the worker kit is the unit of portable agent infrastructure, and the fork is the operator's personal branch of that infrastructure — policy-governed, trace-backed, and self-healing.",
   "type": "module",
   "bin": {