@growthub/cli 0.7.9 → 0.8.1

package/assets/worker-kits/growthub-agency-portal-starter-v1/QUICKSTART.md

@@ -0,0 +1,98 @@
+# Agency Portal Starter Kit — Quickstart
+
+This kit is a governed Growthub workspace first. It contains two runtime surfaces:
+
+- `studio/` — local-first Vite operator shell.
+- `apps/agency-portal/` — Vercel-ready agency portal app.
+
+## 0. Discover, export, and register the fork
+
+From Growthub Local:
+
+```bash
+growthub discover
+growthub kit list --family studio
+growthub kit download growthub-agency-portal-starter-v1 --out ./agency-portal-workspace --yes
+growthub kit fork register ./agency-portal-workspace
+growthub kit fork status <fork-id>
+```
+
+Natural-language prompt for an agent after export:
+
+```text
+Read SKILL.md, skills.md, QUICKSTART.md, docs/adapter-contracts.md, and workers/agency-portal-operator/CLAUDE.md. Set up the local Vite shell, validate the Next/Vercel app, configure either Growthub bridge integrations or BYO API key integration metadata, then produce a deployment handoff for Vercel + GitHub.
+```
+
+The exported directory is the governed environment. Do not move `apps/agency-portal/` out of the workspace root; the fork primitives live beside it.
+
+## 1. Verify the governed workspace
+
+```bash
+bash setup/check-deps.sh
+node setup/verify-env.mjs
+```
+
+Set adapter env in `.env` or your shell. Defaults are documented in `.env.example`.
+
+## 2. Run the local Growthub shell
+
+```bash
+cd studio
+npm install
+npm run dev
+```
+
+This validates local-first Vite support without requiring Vercel, database setup, Windsor, or third-party API credentials.
+
+## 3. Run the Vercel app locally
+
+```bash
+cd apps/agency-portal
+npm install
+npm run dev
+```
+
+Open `/settings/integrations` to validate the dedicated integrations page. It renders:
+
+- Data pipeline objects: Windsor AI, Google Sheets blended data, Google Analytics, Shopify, Meta Facebook/Instagram.
+- MCP connection integrations: Asana, Slack, GoHighLevel, Google Drive, Notion.
+
+## 4. Choose integration authority
+
+Use the first-party Growthub bridge when the user already has connections in the hosted GH app:
+
+```text
+AGENCY_PORTAL_INTEGRATION_ADAPTER=growthub-bridge
+GROWTHUB_BRIDGE_BASE_URL=<growthub-gh-app-url>
+GROWTHUB_BRIDGE_INTEGRATIONS_PATH=/api/mcp/accounts
+GROWTHUB_BRIDGE_ACCESS_TOKEN=<growthub-issued-bridge-token>
+GROWTHUB_BRIDGE_USER_ID=<growthub-auth-user-id>
+```
+
+Use BYO API key setup only when the workspace owner wants explicit local/provider setup:
+
+```text
+AGENCY_PORTAL_INTEGRATION_ADAPTER=byo-api-key
+WINDSOR_API_KEY=<set locally or in Vercel>
+AGENCY_PORTAL_BYO_CONNECTIONS_JSON=[{"id":"slack","provider":"slack","status":"connected","secretEnvName":"SLACK_BOT_TOKEN"}]
+```
+
+Both paths normalize into the same integration object shape. The bridge path is lower friction because Growthub GH app owns user auth, provider tokens, account IDs, scopes, and MCP verification.
+
+## 5. Deploy to Vercel
+
+Use `apps/agency-portal` as the Vercel project root. Configure adapter env according to `docs/adapter-contracts.md`.
+
+Production deployment checklist:
+
+```bash
+cd apps/agency-portal
+npm install
+npm run build
+```
+
+Then connect the GitHub repo to Vercel with root directory `apps/agency-portal`. Reuse the Growthub GH app connection bridge for user-owned integrations where available.
+
+## 6. Governed operation
+
+Read `SKILL.md`, `skills.md`, and `workers/agency-portal-operator/CLAUDE.md` before material changes. Inside a registered fork, record material changes to `.growthub-fork/project.md` and `.growthub-fork/trace.jsonl`.

package/assets/worker-kits/growthub-agency-portal-starter-v1/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: growthub-agency-portal-starter-v1
+description: First-party governed workspace starter for agency portals. Use when creating a composable agency operations portal that must run locally through the Growthub Vite workspace shell and deploy cleanly to Vercel with thin persistence/auth/payment adapters for Postgres, Qstash KV, or provider-managed backends.
+triggers:
+  - agency portal starter
+  - agency operations portal
+  - composable worker kit
+  - vercel agency portal
+  - multi database portal
+  - fork growthub-agency-portal-starter-v1
+progressiveDisclosure: true
+sessionMemory:
+  path: .growthub-fork/project.md
+selfEval:
+  criteria:
+    - Governed workspace primitives remain present and declared in kit.json frozenAssetPaths.
+    - Local-first Vite operator shell under studio/ remains runnable independently from Vercel deployment.
+    - Vercel app under apps/agency-portal/ depends on adapter contracts, not provider-specific kit identity.
+    - Persistence remains configurable through AGENCY_PORTAL_DATA_ADAPTER with Postgres, Qstash KV, and provider-managed options documented.
+    - Integration settings remain configurable through AGENCY_PORTAL_INTEGRATION_ADAPTER with Growthub bridge authority and static local catalog options documented.
+    - Windsor AI and Google Sheets blended data remain first-class data pipeline objects.
+    - GH app integration primitives are represented as catalog metadata plus normalized user connection state; the starter consumes bridge output and does not query hosted databases directly.
+    - Auth and payment surfaces remain thin adapter contracts selected by environment variables.
+    - .growthub-fork/project.md and .growthub-fork/trace.jsonl receive records for material changes inside a governed fork.
+  maxRetries: 3
+  traceTo: .growthub-fork/trace.jsonl
+helpers: []
+subSkills: []
+mcpTools: []
+---
+
+# Agency Portal Starter — Governed Workspace
+
+This kit is built from the custom workspace starter primitive. It preserves the Growthub local-first workspace shape and adds an adapter-first agency portal app.
+
+## Boundaries
+
+- `studio/` — Vite + React local operator shell for Growthub Local.
+- `apps/agency-portal/` — Vercel-ready serverless app payload.
+- `lib/adapters/*` inside the app — thin persistence/auth/payment/integration contracts.
+- `apps/agency-portal/app/api/settings/integrations/route.js` — normalized Settings lanes for data sources and workspace integrations.
+- `apps/agency-portal/app/settings/integrations/page.jsx` — dedicated integrations UI modeled after the GH app integration page primitive.
+- `.growthub-fork/` in exported forks — identity, policy, session memory, trace, and optional authority.
+
+## Integration primitives
+
+Use the GH app mental model:
+
+1. Catalog metadata describes what can be connected.
+2. User connection state describes what is active for the signed-in user.
+3. Provider tokens remain in hosted authority or explicit env vars, never in source.
+4. The portal renders a single integrations page with separate object lanes.
+
+Data pipeline objects:
+
+- Windsor AI
+- Google Sheets blended data
+- Google Analytics
+- Shopify
+- Meta Facebook/Instagram
+
+MCP connection integrations:
+
+- Asana
+- Slack
+- GoHighLevel
+- Google Drive
+- Notion
+
+## Read order
+
+1. `.growthub-fork/project.md`
+2. `SKILL.md`
+3. `skills.md`
+4. `docs/governed-workspace-primitives.md`
+5. `docs/adapter-contracts.md`
+6. `docs/vercel-serverless-deployment.md`
+7. `workers/agency-portal-operator/CLAUDE.md`
+
+## Execution verbs
+
+- `growthub kit download growthub-agency-portal-starter-v1 --out <path>`
+- `growthub kit fork register <path>`
+- `growthub kit fork status <fork-id>`
+- `growthub skills validate --root <path>`
+- `bash setup/check-deps.sh`
+- `node setup/verify-env.mjs`
+- `cd studio && npm run dev`
+- `cd apps/agency-portal && npm run dev`

package/assets/worker-kits/growthub-agency-portal-starter-v1/apps/agency-portal/.env.example

@@ -0,0 +1,25 @@
+# ── Supabase ──────────────────────────────────────────────────────────────────
+# Get these from: https://supabase.com/dashboard → your project → Settings → API
+NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
+
+# Service role key — used only in server-side API routes (keep secret, never commit)
+# Get from: Settings → API → service_role key
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
+
+# ── Windsor AI (optional — only needed for the automated report engine) ────────
+# Get from: https://windsor.ai → Settings → API Key
+WINDSOR_API_KEY=your-windsor-api-key-here
+
+# ── Cron / Automation (optional) ─────────────────────────────────────────────
+# A random secret you generate — used to authenticate the /api/reports/generate endpoint
+# Generate one: openssl rand -hex 32
+CRON_SECRET=your-random-secret-here
+
+# The Supabase user ID of the portal owner (used by the cron report job)
+# Find it in: Supabase Dashboard → Authentication → Users
+PORTAL_USER_ID=your-supabase-user-uuid-here
+
+# ── Agency settings ───────────────────────────────────────────────────────────
+# Monthly revenue target shown on the dashboard (in your local currency)
+NEXT_PUBLIC_REVENUE_TARGET=10000

package/assets/worker-kits/growthub-agency-portal-starter-v1/apps/agency-portal/README.md

@@ -0,0 +1,36 @@
+# Agency Portal App
+
+This app is the Vercel/serverless runtime payload for `growthub-agency-portal-starter-v1`.
+
+It intentionally depends on adapter contracts:
+
+- `AGENCY_PORTAL_DATA_ADAPTER`
+- `AGENCY_PORTAL_AUTH_ADAPTER`
+- `AGENCY_PORTAL_PAYMENT_ADAPTER`
+- `AGENCY_PORTAL_INTEGRATION_ADAPTER`
+- `GROWTHUB_BRIDGE_BASE_URL`
+- `GROWTHUB_BRIDGE_INTEGRATIONS_PATH`
+- `GROWTHUB_BRIDGE_ACCESS_TOKEN`
+- `GROWTHUB_BRIDGE_USER_ID`
+- `AGENCY_PORTAL_BYO_CONNECTIONS_JSON`
+
+The Growthub local-first operator shell remains at `../../studio`.
+
+Settings exposes two integration lanes:
+
+- Data sources: Windsor AI, Google Sheets blended data, Google Analytics, Shopify, Meta Facebook/Instagram.
+- Workspace integrations: Asana, Slack, GoHighLevel, Google Drive, Notion.
+
+Use `AGENCY_PORTAL_INTEGRATION_ADAPTER=growthub-bridge` when the deployed app should read connection state from the Growthub GH app MCP bridge. The reusable primitive is `lib/adapters/integrations/growthub-connection-normalizer.js`; it accepts SDK/profile-style `integrations[]` payloads and GH app MCP `accounts[]` payloads, then emits the same normalized object shape used by `byo-api-key`. Keep provider tokens in the hosted authority layer or named env vars; this app consumes normalized connection metadata only.
+
+## Run
+
+```bash
+npm install
+npm run dev
+npm run build
+```
+
+## Deploy
+
+Use this directory as the Vercel project root.

package/assets/worker-kits/growthub-agency-portal-starter-v1/apps/agency-portal/app/api/settings/integrations/route.js

@@ -0,0 +1,13 @@
+import { NextResponse } from "next/server";
+import { describeIntegrationAdapter, listAgencyPortalIntegrations } from "@/lib/adapters/integrations";
+import { groupIntegrationsByLane } from "@/lib/domain/integrations";
+async function GET() {
+  const integrations = await listAgencyPortalIntegrations();
+  return NextResponse.json({
+    adapter: describeIntegrationAdapter(),
+    ...groupIntegrationsByLane(integrations)
+  });
+}
+export {
+  GET
+};

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

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+import { describeAuthAdapter } from "@/lib/adapters/auth";
+import { readAdapterConfig } from "@/lib/adapters/env";
+import { describeIntegrationAdapter, listAgencyPortalIntegrations } from "@/lib/adapters/integrations";
+import { describePaymentAdapter } from "@/lib/adapters/payments";
+import { describePersistenceAdapter } from "@/lib/adapters/persistence";
+import { groupIntegrationsByLane } from "@/lib/domain/integrations";
+import { portalCapabilities } from "@/lib/domain/portal";
+async function GET() {
+  const integrations = await listAgencyPortalIntegrations();
+  return NextResponse.json({
+    config: readAdapterConfig(),
+    adapters: {
+      persistence: describePersistenceAdapter(),
+      auth: describeAuthAdapter(),
+      payments: describePaymentAdapter(),
+      integrations: describeIntegrationAdapter()
+    },
+    capabilities: portalCapabilities,
+    settings: {
+      integrations: groupIntegrationsByLane(integrations)
+    }
+  });
+}
+export {
+  GET
+};

package/assets/worker-kits/growthub-agency-portal-starter-v1/apps/agency-portal/app/globals.css

@@ -0,0 +1,237 @@
+:root {
+  color-scheme: dark;
+  --bg: #080b12;
+  --sidebar: #0d1118;
+  --panel: #111827;
+  --panel-soft: #0d1420;
+  --ink: #f7fafc;
+  --muted: #93a3b8;
+  --line: #223047;
+  --accent: #38bdf8;
+  --accent-soft: rgba(56, 189, 248, 0.12);
+  --good: #22c55e;
+  --warn: #f59e0b;
+}
+
+* { box-sizing: border-box; }
+html { scroll-behavior: smooth; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--ink);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+a { color: inherit; }
+code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.9em; }
+
+.shell {
+  min-height: 100vh;
+  display: grid;
+  grid-template-columns: 232px minmax(0, 1fr);
+  background: radial-gradient(circle at top right, rgba(56, 189, 248, 0.12), transparent 360px), var(--bg);
+}
+.sidebar {
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  gap: 22px;
+  background: rgba(13, 17, 24, 0.96);
+  border-right: 1px solid var(--line);
+  padding: 22px 16px;
+}
+.brand { display: flex; align-items: center; gap: 10px; font-weight: 800; }
+.brand-mark {
+  width: 34px;
+  height: 34px;
+  display: grid;
+  place-items: center;
+  border-radius: 8px;
+  background: var(--accent);
+  color: #06111d;
+  font-size: 13px;
+  font-weight: 900;
+}
+.nav { display: grid; gap: 5px; }
+.nav a {
+  color: #c6d1e1;
+  text-decoration: none;
+  padding: 9px 10px;
+  border-radius: 7px;
+  font-size: 14px;
+}
+.nav a.active, .nav a:hover { background: #172133; color: white; }
+.sidebar-footer {
+  margin-top: auto;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--muted);
+  font-size: 13px;
+}
+.status-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 999px;
+  background: var(--good);
+  box-shadow: 0 0 0 4px rgba(34, 197, 94, 0.12);
+}
+.main {
+  width: min(100%, 1180px);
+  padding: 30px;
+}
+.utility-bar {
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+  align-items: center;
+  margin-bottom: 20px;
+  padding: 12px 14px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: rgba(17, 24, 39, 0.82);
+}
+.utility-bar strong { display: block; font-size: 14px; }
+.utility-bar span, .page-heading p, .panel-copy, .card p, .setup-card p, .results-panel p {
+  color: var(--muted);
+  line-height: 1.5;
+}
+.utility-actions { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
+.utility-actions a, .pill, .badge {
+  display: inline-flex;
+  align-items: center;
+  min-height: 28px;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  padding: 5px 10px;
+  background: #0c1320;
+  color: #c9d7e8;
+  text-decoration: none;
+  font-size: 12px;
+}
+.page-heading { position: relative; margin-bottom: 22px; }
+.page-heading h1 {
+  margin: 4px 0 8px;
+  font-size: clamp(32px, 5vw, 58px);
+  line-height: 0.98;
+  letter-spacing: 0;
+}
+.page-heading p { max-width: 780px; margin: 0 0 12px; }
+.eyebrow { color: var(--accent); font-size: 12px; font-weight: 800; text-transform: uppercase; letter-spacing: 0.12em; }
+.hero-grid {
+  display: grid;
+  grid-template-columns: 1.2fr 0.9fr 0.9fr;
+  gap: 14px;
+  margin-bottom: 16px;
+}
+.hero-card, .card, .setup-card, .integration-section, .integration-toolbar, .results-panel {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: rgba(17, 24, 39, 0.9);
+}
+.hero-card { min-height: 188px; padding: 18px; }
+.hero-card.primary { background: linear-gradient(135deg, rgba(56, 189, 248, 0.18), rgba(17, 24, 39, 0.95)); }
+.hero-card.wide { min-height: 210px; }
+.hero-card span, .card span, .setup-card span { color: var(--accent); font-size: 12px; font-weight: 800; text-transform: uppercase; }
+.hero-card strong { display: block; margin-top: 10px; font-size: 34px; line-height: 1; }
+.hero-card p { margin: 12px 0 0; color: var(--muted); line-height: 1.5; }
+.card-label { color: var(--accent) !important; font-size: 12px; font-weight: 800; text-transform: uppercase; }
+.muted { color: var(--muted) !important; }
+.progress { height: 8px; margin: 18px 0 2px; overflow: hidden; border-radius: 999px; background: #0a101b; border: 1px solid var(--line); }
+.progress span { display: block; height: 100%; background: var(--accent); }
+.ops-strip, .setup-grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 12px;
+  margin-bottom: 18px;
+}
+.setup-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.ops-strip article, .setup-card { padding: 14px; border: 1px solid var(--line); border-radius: 8px; background: rgba(13, 20, 32, 0.88); }
+.ops-strip strong, .setup-card strong { display: block; margin: 7px 0; font-size: 14px; }
+.ops-strip p, .setup-card p { margin: 0 0 10px; font-size: 13px; }
+.setup-card code { color: #d7e8ff; word-break: break-word; }
+.grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 14px; }
+.compact-grid .card { min-height: 124px; }
+.card { min-height: 138px; padding: 16px; }
+.card h3 { margin: 7px 0 8px; font-size: 15px; }
+.metric { font-size: 26px; font-weight: 800; margin-top: 12px; }
+.adapter { margin-top: 18px; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 12px; }
+.adapter .card { min-height: auto; }
+.results-panel { margin-top: 18px; padding: 18px; display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
+.results-panel h2 { margin: 0 0 8px; }
+.results-metrics { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 10px; }
+.results-metrics span { display: block; color: var(--muted); font-size: 12px; }
+.quick-actions {
+  position: fixed;
+  right: 20px;
+  bottom: 20px;
+  display: grid;
+  gap: 8px;
+  width: 190px;
+}
+.quick-actions button {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 10px 12px;
+  background: #0d1420;
+  color: var(--ink);
+  text-align: left;
+  font: inherit;
+}
+.integration-board { display: grid; gap: 14px; }
+.integration-toolbar { display: flex; justify-content: space-between; align-items: center; gap: 16px; padding: 14px 16px; }
+.integration-toolbar p { margin: 4px 0 0; color: var(--muted); font-size: 14px; }
+.section-heading { display: flex; justify-content: space-between; gap: 14px; align-items: flex-start; margin-bottom: 12px; }
+.integration-section { padding: 16px; }
+.integration-section h2 { margin: 0 0 8px; font-size: 18px; }
+.integration-list { display: grid; gap: 10px; }
+.integration-card { border: 1px solid var(--line); border-radius: 8px; padding: 14px; background: #0d1420; }
+.integration-card-top { display: grid; grid-template-columns: 38px minmax(0, 1fr) auto; gap: 12px; align-items: start; }
+.provider-mark {
+  width: 34px;
+  height: 34px;
+  display: grid;
+  place-items: center;
+  border: 1px solid var(--line);
+  border-radius: 7px;
+  background: #101a2b;
+  font-weight: 800;
+  color: var(--accent);
+}
+.integration-card strong { display: block; font-size: 14px; }
+.integration-card p { margin: 4px 0 0; color: var(--muted); font-size: 13px; line-height: 1.4; }
+.status {
+  white-space: nowrap;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  padding: 4px 8px;
+  font-size: 12px;
+  color: var(--muted);
+}
+.status.connected { color: var(--good); border-color: rgba(34, 197, 94, 0.45); background: rgba(34, 197, 94, 0.1); }
+.status.needs-connection { color: var(--warn); border-color: rgba(245, 158, 11, 0.5); background: rgba(245, 158, 11, 0.1); }
+.integration-card-meta { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 12px; }
+.integration-card-meta span {
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  padding: 3px 7px;
+  color: var(--muted);
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+}
+
+@media (max-width: 1020px) {
+  .shell { grid-template-columns: 1fr; }
+  .sidebar { position: static; height: auto; }
+  .hero-grid, .grid, .adapter, .ops-strip, .setup-grid, .results-panel, .results-metrics { grid-template-columns: 1fr; }
+  .quick-actions { position: static; width: auto; margin: 20px 30px; }
+}
+
+@media (max-width: 720px) {
+  .main { padding: 20px; }
+  .utility-bar, .integration-toolbar, .section-heading { display: block; }
+  .utility-actions { margin-top: 10px; }
+  .integration-card-top { grid-template-columns: 34px minmax(0, 1fr); }
+  .integration-card-top .status { grid-column: 2; width: fit-content; }
+}

package/assets/worker-kits/growthub-agency-portal-starter-v1/apps/agency-portal/app/layout.jsx

@@ -0,0 +1,14 @@
+import "./globals.css";
+const metadata = {
+  title: "Agency Portal",
+  description: "Composable agency operations portal with thin infrastructure adapters."
+};
+function RootLayout({ children }) {
+  return <html lang="en">
+      <body>{children}</body>
+    </html>;
+}
+export {
+  RootLayout as default,
+  metadata
+};