@growthub/cli 0.13.5 → 0.13.7

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

@@ -10,6 +10,25 @@ This kit is the canonical v1 starter primitive. Run `growthub starter init --nam
 
 After that, every customization you make stays yours — the Self-Healing Fork Sync Agent will propose upstream additions non-destructively, honouring your policy.
 
+## Official workspace paths
+
+Workspace 1 stays the blank governed workspace:
+
+```bash
+growthub starter init --name "My Workspace" --out ./my-workspace
+```
+
+Workspace 2 is the opinionated project-management template path. It builds on the same app and adapter surface, but seeds API Registry, Data Source, Sandbox Environment workflow, and dashboard placeholders for project task deltas. It stores no provider secrets, OAuth connection ids, or provider task data.
+
+```bash
+growthub starter init \
+  --name "Project Management Workspace" \
+  --out ./project-management-workspace \
+  --seed-config project-management
+```
+
+After export, set `NANGO_SECRET_KEY` in the workspace runtime, complete provider OAuth, then fill `providerConfigKey`, `connectionIds`, and project identifiers in the Data Model before running the workflow.
+
 ## Run the bundled Vite UI shell
 
 ```bash

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/.env.example

@@ -10,6 +10,14 @@ GROWTHUB_WORKSPACE_PAYMENT_ADAPTER=none
 # - static: local starter catalog only
 GROWTHUB_WORKSPACE_INTEGRATION_ADAPTER=growthub-bridge
 
+# Nango thin adapter — row-scoped, not a workspace-wide adapter.
+# Set NANGO_SECRET_KEY when any api-registry row has connectorKind: "nango".
+# Cloud mode reaches Nango Cloud; self-hosted requires NANGO_HOST_URL.
+NANGO_MODE=cloud
+NANGO_HOST_URL=
+NANGO_ENVIRONMENT=dev
+NANGO_SECRET_KEY=
+
 # Hosted bridge authority
 GROWTHUB_BRIDGE_BASE_URL=https://www.growthub.ai
 GROWTHUB_BRIDGE_INTEGRATIONS_PATH=/api/mcp/accounts

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

@@ -13,6 +13,10 @@ It intentionally depends on adapter contracts:
 - `GROWTHUB_BRIDGE_ACCESS_TOKEN`
 - `GROWTHUB_BRIDGE_USER_ID`
 - `GROWTHUB_WORKSPACE_BYO_CONNECTIONS_JSON`
+- `NANGO_SECRET_KEY` (required when any api-registry row uses `connectorKind: "nango"`)
+- `NANGO_HOST_URL` (self-hosted Nango only)
+- `NANGO_ENVIRONMENT` (default `dev`)
+- `NANGO_MODE` (`cloud` | `self-hosted`, default `cloud`)
 
 The Growthub local-first operator shell remains at `../../studio`.
 

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/integrations/nango/action/execute/route.js

@@ -0,0 +1,60 @@
+/**
+ * POST /api/workspace/integrations/nango/action/execute
+ *
+ * Executes a declared Nango action function against the connection
+ * identified by `providerConfigKey` + `connectionId`. Used by workspace
+ * agents as a tool-call surface.
+ *
+ * Request body:
+ *   {
+ *     providerConfigKey: string,
+ *     connectionId: string,
+ *     action: string,              // action function name from nango.yaml
+ *     input?: object | array       // arguments to the action
+ *   }
+ *
+ * Response — success: 200 { ok: true, action, providerConfigKey, connectionId, result, environment }
+ * Response — validation failure: 400 { ok: false, error, details }
+ * Response — Nango not configured: 503 { ok: false, error, code }
+ * Response — upstream failure: 502 { ok: false, error }
+ */
+
+import { NextResponse } from "next/server";
+import { executeAction, validateActionExecuteRequest } from "@/lib/adapters/integrations/nango";
+
+async function POST(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ ok: false, error: "invalid JSON body" }, { status: 400 });
+  }
+
+  let validated;
+  try {
+    validated = validateActionExecuteRequest(body);
+  } catch (error) {
+    return NextResponse.json(
+      { ok: false, error: error.message, details: error.details || null },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const result = await executeAction(validated);
+    return NextResponse.json({ ok: true, ...result });
+  } catch (error) {
+    if (error.code === "NANGO_NOT_CONFIGURED" || error.code === "NANGO_SDK_UNAVAILABLE" || error.code === "NANGO_SDK_SHAPE") {
+      return NextResponse.json(
+        { ok: false, error: error.message, code: error.code },
+        { status: 503 }
+      );
+    }
+    return NextResponse.json(
+      { ok: false, error: error?.message || "nango action execution failed" },
+      { status: 502 }
+    );
+  }
+}
+
+export { POST };

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

@@ -0,0 +1,50 @@
+/**
+ * GET /api/workspace/integrations/nango/actions
+ *
+ * Lists the actions declared in `nango.yaml` for a given provider config key
+ * (or, when no key is provided, returns the full discoverable set). The
+ * response shape is MCP-compatible: each action exposes a name and (when
+ * provided by Nango) an input/output schema.
+ *
+ * Query parameters (optional):
+ *   - providerConfigKey  filter to actions for a single provider
+ *
+ * Response shape:
+ *   { ok: true, providerConfigKey, probedShape, actions: Array, hint: string|null }
+ */
+
+import { NextResponse } from "next/server";
+import { listActions, validateActionsListInput } from "@/lib/adapters/integrations/nango";
+
+async function GET(request) {
+  const url = new URL(request.url);
+  const raw = {
+    providerConfigKey: url.searchParams.get("providerConfigKey") || undefined
+  };
+  let input;
+  try {
+    input = validateActionsListInput(raw);
+  } catch (error) {
+    return NextResponse.json(
+      { ok: false, error: error.message, details: error.details || null },
+      { status: 400 }
+    );
+  }
+  try {
+    const result = await listActions(input);
+    return NextResponse.json({ ok: true, ...result });
+  } catch (error) {
+    if (error.code === "NANGO_NOT_CONFIGURED" || error.code === "NANGO_SDK_UNAVAILABLE") {
+      return NextResponse.json(
+        { ok: false, error: error.message, code: error.code },
+        { status: 503 }
+      );
+    }
+    return NextResponse.json(
+      { ok: false, error: error?.message || "nango actions list failed" },
+      { status: 502 }
+    );
+  }
+}
+
+export { GET };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/integrations/nango/connect-session/route.js

@@ -0,0 +1,68 @@
+/**
+ * POST /api/workspace/integrations/nango/connect-session
+ *
+ * Creates a Nango Connect Session for the given providerConfigKey and
+ * returns a short-lived connect_link the browser opens to start OAuth.
+ * The Nango Connect UI mints tokens directly against Nango — the workspace
+ * never sees the resulting OAuth credentials. The token returned here is a
+ * Connect Session token (handoff only), not a provider credential.
+ *
+ * Lifecycle: Nango creates the connectionId AFTER the user completes OAuth
+ * and delivers it through the auth webhook. A normal Connect Session
+ * therefore does NOT need a connectionId as input — only the explicit
+ * Reconnect path (`reconnect: true`) operates on an existing connectionId.
+ *
+ * Request body:
+ *   {
+ *     providerConfigKey: string,         // required, alphanumeric (+ _.-) <= 64 chars
+ *     reconnect?: boolean,                // true → use the SDK's reconnect-session path
+ *     connectionId?: string,              // REQUIRED when reconnect=true; ignored for a normal Create Connect Session
+ *     endUser?: { id?: string, email?: string },
+ *     tags?: Record<string, string>      // echoed back in the Nango auth webhook so the workspace can map the eventual connectionId to the originating row
+ *   }
+ *
+ * Response — success: 200 { ok: true, providerConfigKey, environment, mode, token, connectLink, sdkMethod, tagsEchoed }
+ * Response — validation failure: 400 { ok: false, error, details }
+ * Response — Nango not configured / SDK missing: 503 { ok: false, error, code }
+ * Response — upstream failure: 502 { ok: false, error }
+ */
+
+import { NextResponse } from "next/server";
+import { createConnectSession, validateConnectSessionRequest } from "@/lib/adapters/integrations/nango";
+
+async function POST(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ ok: false, error: "invalid JSON body" }, { status: 400 });
+  }
+
+  let validated;
+  try {
+    validated = validateConnectSessionRequest(body);
+  } catch (error) {
+    return NextResponse.json(
+      { ok: false, error: error.message, details: error.details || null },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const result = await createConnectSession(validated);
+    return NextResponse.json({ ok: true, ...result });
+  } catch (error) {
+    if (error.code === "NANGO_NOT_CONFIGURED" || error.code === "NANGO_SDK_UNAVAILABLE" || error.code === "NANGO_SDK_SHAPE") {
+      return NextResponse.json(
+        { ok: false, error: error.message, code: error.code },
+        { status: 503 }
+      );
+    }
+    return NextResponse.json(
+      { ok: false, error: error?.message || "nango connect session failed" },
+      { status: 502 }
+    );
+  }
+}
+
+export { POST };

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/api/workspace/integrations/nango/connection-status/route.js

@@ -0,0 +1,56 @@
+/**
+ * POST /api/workspace/integrations/nango/connection-status
+ *
+ * Returns the safe (non-credential) status summary for a specific Nango
+ * connection. Used by the NangoConnectionPanel sidecar to verify a
+ * per-row connection without exposing OAuth tokens to the browser.
+ *
+ * Request body:
+ *   { providerConfigKey: string, connectionId: string }
+ *
+ * Response — connected: 200 { ok: true, status: "connected", providerConfigKey, connectionId, environment, connection: { ...safe fields... } }
+ * Response — not yet connected: 200 { ok: true, status: "not-connected", providerConfigKey, connectionId, environment, reason }
+ * Response — validation failure: 400 { ok: false, error, details }
+ * Response — Nango not configured: 503 { ok: false, error, code }
+ * Response — upstream failure: 502 { ok: false, error }
+ */
+
+import { NextResponse } from "next/server";
+import { getConnectionSummary, validateConnectionSummaryRequest } from "@/lib/adapters/integrations/nango";
+
+async function POST(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ ok: false, error: "invalid JSON body" }, { status: 400 });
+  }
+
+  let validated;
+  try {
+    validated = validateConnectionSummaryRequest(body);
+  } catch (error) {
+    return NextResponse.json(
+      { ok: false, error: error.message, details: error.details || null },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const result = await getConnectionSummary(validated);
+    return NextResponse.json({ ok: true, ...result });
+  } catch (error) {
+    if (error.code === "NANGO_NOT_CONFIGURED" || error.code === "NANGO_SDK_UNAVAILABLE" || error.code === "NANGO_SDK_SHAPE") {
+      return NextResponse.json(
+        { ok: false, error: error.message, code: error.code },
+        { status: 503 }
+      );
+    }
+    return NextResponse.json(
+      { ok: false, error: error?.message || "nango connection status failed" },
+      { status: 502 }
+    );
+  }
+}
+
+export { POST };

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

@@ -0,0 +1,67 @@
+/**
+ * POST /api/workspace/integrations/nango/proxy
+ *
+ * Proxies an API request through Nango using the connection identified by
+ * `providerConfigKey` + `connectionId`. The Nango SDK injects credentials
+ * server-side; the browser never holds the upstream provider's auth.
+ *
+ * Request body:
+ *   {
+ *     providerConfigKey: string,   // Nango integration config key
+ *     connectionId: string,         // Nango connection id
+ *     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+ *     endpoint: string,             // path or absolute URL
+ *     headers?: object,             // forbidden: Authorization, X-API-Key, etc.
+ *     params?: object,
+ *     data?: any,
+ *     retries?: number,             // 0..10
+ *     timeoutMs?: number            // 0..60000
+ *   }
+ *
+ * Response — success:
+ *   { ok: true, status: number, data: any, environment: string }
+ *
+ * Response — validation failure: 400 { ok: false, error, details }
+ * Response — Nango not configured: 503 { ok: false, error, code }
+ * Response — upstream failure: 502 { ok: false, error }
+ */
+
+import { NextResponse } from "next/server";
+import { proxyRequest, validateProxyRequest } from "@/lib/adapters/integrations/nango";
+
+async function POST(request) {
+  let body;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ ok: false, error: "invalid JSON body" }, { status: 400 });
+  }
+
+  let validated;
+  try {
+    validated = validateProxyRequest(body);
+  } catch (error) {
+    return NextResponse.json(
+      { ok: false, error: error.message, details: error.details || null },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const result = await proxyRequest(validated);
+    return NextResponse.json({ ok: true, ...result });
+  } catch (error) {
+    if (error.code === "NANGO_NOT_CONFIGURED" || error.code === "NANGO_SDK_UNAVAILABLE" || error.code === "NANGO_SDK_SHAPE") {
+      return NextResponse.json(
+        { ok: false, error: error.message, code: error.code },
+        { status: 503 }
+      );
+    }
+    return NextResponse.json(
+      { ok: false, error: error?.message || "nango proxy failed" },
+      { status: 502 }
+    );
+  }
+}
+
+export { POST };

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

@@ -0,0 +1,50 @@
+/**
+ * GET /api/workspace/integrations/nango/status
+ *
+ * Returns Nango connection health for the no-code Integrations panel.
+ *
+ * Query parameters (all optional):
+ *   - providerConfigKey  probe a specific provider connection
+ *   - connectionId       probe a specific connection (paired with providerConfigKey)
+ *   - mode               override mode for the probe ("cloud" | "self-hosted")
+ *   - hostUrl            override host URL for self-hosted probes
+ *
+ * Response shape:
+ *   { status: "connected" | "disconnected" | "unconfigured", ... }
+ *
+ * Authority contract: never returns the Nango secret key. Never echoes
+ * credential-shaped fields from upstream SDK responses.
+ */
+
+import { NextResponse } from "next/server";
+import { getStatus, validateConnectionStatusRequest } from "@/lib/adapters/integrations/nango";
+
+async function GET(request) {
+  const url = new URL(request.url);
+  const raw = {
+    providerConfigKey: url.searchParams.get("providerConfigKey") || undefined,
+    connectionId: url.searchParams.get("connectionId") || undefined,
+    mode: url.searchParams.get("mode") || undefined,
+    hostUrl: url.searchParams.get("hostUrl") || undefined
+  };
+  let input;
+  try {
+    input = validateConnectionStatusRequest(raw);
+  } catch (error) {
+    return NextResponse.json(
+      { error: error.message, details: error.details || null },
+      { status: 400 }
+    );
+  }
+  try {
+    const result = await getStatus(input);
+    return NextResponse.json(result);
+  } catch (error) {
+    return NextResponse.json(
+      { error: error?.message || "nango status probe failed" },
+      { status: 500 }
+    );
+  }
+}
+
+export { GET };

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

@@ -152,6 +152,7 @@ async function GET(request) {
       runs: metadataStore.runs,
       outputArtifacts: metadataStore.outputArtifacts,
       workerKits: metadataStore.workerKits,
+      provenance: metadataStore.provenance,
       pipelineHealth: metadataStore.pipelineHealth
     },
     graph: {

package/assets/worker-kits/growthub-custom-workspace-starter-v1/apps/workspace/app/components/WorkspaceActivationPanel.jsx

@@ -0,0 +1,172 @@
+"use client";
+
+/**
+ * WorkspaceActivationPanel — customer activation checklist.
+ *
+ * Renders the derived activation state from
+ * `lib/workspace-activation.js` as a goal-first checklist with deep links
+ * into the existing surfaces. The panel is read-only; every step routes
+ * through routes the workspace already owns.
+ *
+ * Props:
+ *   workspaceConfig         — parsed growthub.config.json (governed)
+ *   workspaceSourceRecords  — parsed growthub.source-records.json (sidecar)
+ *   metadataGraph           — optional metadata graph envelope
+ *   onOpenHelper            — optional helper-thread CTA handler
+ *   compact                 — render the rail-friendly compact variant
+ *
+ * Invariants:
+ *   - No fetch. No mutation. No secret reading.
+ *   - Reads only safe data (booleans, status strings, deep-link routes).
+ *   - Falls back to a sensible default state if config is missing.
+ */
+
+import Link from "next/link";
+import {
+  ArrowRight,
+  Check,
+  CircleDot,
+  HelpCircle,
+  Lock,
+  Sparkles,
+} from "lucide-react";
+import { deriveWorkspaceActivationState } from "@/lib/workspace-activation";
+
+function StatusIcon({ status }) {
+  if (status === "complete") return <Check size={14} aria-hidden="true" />;
+  if (status === "blocked") return <Lock size={14} aria-hidden="true" />;
+  if (status === "optional") return <Sparkles size={14} aria-hidden="true" />;
+  return <CircleDot size={14} aria-hidden="true" />;
+}
+
+function StatusLabel({ status }) {
+  if (status === "complete") return "Done";
+  if (status === "blocked") return "Blocked";
+  if (status === "optional") return "Optional";
+  return "Next";
+}
+
+export function WorkspaceActivationPanel({
+  workspaceConfig,
+  workspaceSourceRecords,
+  metadataGraph,
+  onOpenHelper,
+  compact = false,
+}) {
+  const state = deriveWorkspaceActivationState({
+    workspaceConfig,
+    workspaceSourceRecords,
+    metadataGraph,
+  });
+
+  const stepsToRender = compact
+    ? state.steps.filter((step) => step.status !== "optional")
+    : state.steps;
+
+  return (
+    <section
+      className={
+        "workspace-activation-panel"
+        + (compact ? " is-compact" : "")
+        + (state.complete ? " is-complete" : "")
+      }
+      aria-label="Workspace activation"
+      data-template={state.template}
+    >
+      <header className="workspace-activation-head">
+        <div className="workspace-activation-head-text">
+          <p className="workspace-activation-eyebrow">{state.templateName}</p>
+          <h2 className="workspace-activation-headline">{state.headline}</h2>
+          {state.subheadline ? (
+            <p className="workspace-activation-subheadline">{state.subheadline}</p>
+          ) : null}
+        </div>
+        <div
+          className="workspace-activation-progress"
+          aria-label={`${state.completedCount} of ${state.totalCount} setup steps complete`}
+        >
+          <span className="workspace-activation-progress-value">
+            {state.completedCount}/{state.totalCount}
+          </span>
+          <span className="workspace-activation-progress-bar" aria-hidden="true">
+            <span
+              className="workspace-activation-progress-fill"
+              style={{
+                width: state.totalCount > 0
+                  ? `${Math.min(100, Math.round((state.completedCount / state.totalCount) * 100))}%`
+                  : "0%",
+              }}
+            />
+          </span>
+        </div>
+      </header>
+
+      <ol className="workspace-activation-steps" role="list">
+        {stepsToRender.map((step) => {
+          const isNext = state.nextStepId === step.id;
+          return (
+            <li
+              key={step.id}
+              className={
+                "workspace-activation-step"
+                + ` is-${step.status}`
+                + (isNext ? " is-next" : "")
+              }
+            >
+              <span className="workspace-activation-step-status" aria-hidden="true">
+                <StatusIcon status={step.status} />
+              </span>
+              <div className="workspace-activation-step-body">
+                <div className="workspace-activation-step-titlebar">
+                  <h3 className="workspace-activation-step-title">{step.label}</h3>
+                  <span className={`workspace-activation-step-badge is-${step.status}`}>
+                    <StatusLabel status={step.status} />
+                  </span>
+                </div>
+                <p className="workspace-activation-step-description">{step.description}</p>
+                {step.hint ? (
+                  <p className="workspace-activation-step-hint">
+                    <HelpCircle size={12} aria-hidden="true" />
+                    <span>{step.hint}</span>
+                  </p>
+                ) : null}
+                {step.href ? (
+                  <Link
+                    href={step.href}
+                    className={
+                      "workspace-activation-step-cta"
+                      + (isNext ? " is-primary" : "")
+                    }
+                  >
+                    <span>{step.cta || (step.status === "complete" ? "Review" : "Open")}</span>
+                    <ArrowRight size={12} aria-hidden="true" />
+                  </Link>
+                ) : null}
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+
+      {onOpenHelper ? (
+        <div className="workspace-activation-helper-cta">
+          <button
+            type="button"
+            className="workspace-activation-helper-btn"
+            onClick={() => onOpenHelper({
+              template: state.template,
+              nextStepId: state.nextStepId,
+            })}
+          >
+            <Sparkles size={13} aria-hidden="true" />
+            <span>
+              {state.complete
+                ? "Ask helper to customize this workspace"
+                : `Ask helper to finish ${state.templateName}`}
+            </span>
+          </button>
+        </div>
+      ) : null}
+    </section>
+  );
+}