@growthub/cli 0.3.54 → 0.3.55

package/assets/worker-kits/growthub-twenty-crm-v1/runtime-assumptions.md

@@ -0,0 +1,150 @@
+# Runtime Assumptions — Twenty CRM v1
+
+This document defines the runtime boundary for this kit.
+
+---
+
+## OVERVIEW
+
+This kit targets a self-contained local working directory used by an agent operating against one of four execution surfaces:
+
+| Mode | When to use | Assumption |
+|---|---|---|
+| `local-fork` | local checkout of Twenty via Docker Compose | repo files can be inspected before planning |
+| `self-hosted` | Twenty deployed on the team's own infrastructure | API is live and accessible via token |
+| `cloud` | Twenty Cloud workspace at app.twenty.com | API is live, no repo inspection required |
+| `agent-only` | no live Twenty instance | produce planning artifacts only, label as assumption-based |
+
+Default planning mode is `agent-only` when no deployment info is provided. Escalate to `local-fork` if a checkout path is confirmed.
+
+---
+
+## TWENTY CRM FROZEN ASSUMPTIONS
+
+Frozen upstream assumptions for this kit (based on Twenty v0.35+, MIT, TypeScript/React/NestJS):
+
+- Standard objects are: `Person`, `Company`, `Opportunity`, `Note`, `Task`, `Workspace Member`
+- Custom objects are supported via `Settings > Objects` (UI) and the metadata API
+- GraphQL is the primary query and mutation surface
+- REST API exists at `/api/objects/<object-name>` for CRUD operations
+- App tokens are generated in `Settings > API > Tokens` and must be sent as `Bearer` in the `Authorization` header
+- The workflow engine supports trigger types: `on_create`, `on_update`, `on_field_change`, `on_delete`, `on_schedule`, `on_webhook`
+- Outbound webhook actions are a supported workflow action type
+- The CLI (`@twenty-crm/cli`) exposes `twenty` commands for workspace management
+- Docker Compose is the canonical local development stack (PostgreSQL + Redis + server + frontend)
+- The default local development port for the Twenty server is `3000` and for the frontend is `3001`
+- The GraphQL endpoint is at `<TWENTY_API_URL>/graphql` (authenticated via Bearer token)
+- The metadata API is at `<TWENTY_API_URL>/metadata` (authenticated via Bearer token)
+
+If the local fork or live deployment differs, those actual values win.
+
+---
+
+## DEPLOYMENT MODE DETAILS
+
+### Local fork
+
+Expected operator flow:
+1. clone via `bash setup/clone-fork.sh`
+2. Docker Compose starts PostgreSQL, Redis, server, and frontend
+3. navigate to `http://localhost:3001` to configure workspace
+4. generate an API token in Settings
+5. set `TWENTY_API_TOKEN` and `TWENTY_API_URL=http://localhost:3000` in `.env`
+6. run `node setup/verify-env.mjs` to confirm connectivity
+7. proceed with data model inspection and implementation
+
+### Self-hosted
+
+Expected operator flow:
+1. confirm deployment URL and auth mechanism
+2. generate API token from the hosted workspace
+3. set `TWENTY_API_TOKEN` and `TWENTY_API_URL` to the deployed endpoint
+4. verify with `node setup/verify-env.mjs`
+5. proceed — no local fork inspection required
+
+### Cloud
+
+Expected operator flow:
+1. log in to Twenty Cloud at [app.twenty.com](https://app.twenty.com)
+2. go to Settings > API > Tokens and generate a token
+3. set `TWENTY_API_TOKEN` and `TWENTY_API_URL=https://api.twenty.com` in `.env`
+4. verify with `node setup/verify-env.mjs`
+5. proceed — no local fork inspection required
+
+### Agent-only
+
+- produce all planning artifacts using the frozen assumptions in this document
+- label every output with `mode: agent-only` at the top
+- note that implementation requires a live Twenty instance before any data or automation work can execute
+
+---
+
+## API AUTHENTICATION
+
+Twenty uses Bearer token authentication for all API access.
+
+```
+Authorization: Bearer <TWENTY_API_TOKEN>
+Content-Type: application/json
+```
+
+For the metadata API, the same token is used:
+
+```
+Authorization: Bearer <TWENTY_API_TOKEN>
+```
+
+Tokens are workspace-scoped. One token per workspace. Generate new tokens if the workspace membership changes.
+
+---
+
+## GRAPHQL ENDPOINT
+
+```
+POST <TWENTY_API_URL>/graphql
+Authorization: Bearer <TWENTY_API_TOKEN>
+Content-Type: application/json
+```
+
+Example:
+
+```bash
+curl -X POST https://api.twenty.com/graphql \
+  -H "Authorization: Bearer $TWENTY_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "{ people { edges { node { id name { firstName lastName } } } } }"}'
+```
+
+---
+
+## METADATA API ENDPOINT
+
+The metadata API is used to create and manage custom objects and fields.
+
+```
+POST <TWENTY_API_URL>/metadata
+Authorization: Bearer <TWENTY_API_TOKEN>
+Content-Type: application/json
+```
+
+---
+
+## DATA VOLUME ASSUMPTIONS
+
+- Small team (1–10 users): up to 10,000 Person records, 2,000 Company records
+- Mid-market (10–100 users): up to 100,000 Person records, 20,000 Company records
+- Enterprise (100+ users): requires infrastructure review before recommending Twenty without dedicated devops
+
+For enrichment pipelines above 50,000 records, recommend batched imports over direct CSV upload.
+
+---
+
+## OUTPUT WRITING ASSUMPTION
+
+All deliverables are written as Markdown in:
+
+```text
+output/<client-slug>/<project-slug>/
+```
+
+The kit does not require its own npm install or custom CLI to be operational. API connectivity requires only `node` for `setup/verify-env.mjs`.

package/assets/worker-kits/growthub-twenty-crm-v1/setup/check-deps.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# check-deps.sh — Verify local dependencies required for Twenty CRM local-fork and self-hosted workflows.
+# Run before your first local-fork session.
+set -e
+
+PASS=0
+FAIL=0
+
+check() {
+  local name="$1"
+  local cmd="$2"
+  local install_hint="$3"
+  if command -v "$cmd" >/dev/null 2>&1; then
+    echo "OK   $name ($(command -v "$cmd"))"
+    PASS=$((PASS + 1))
+  else
+    echo "MISSING  $name — $install_hint"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+check_docker_running() {
+  if docker info >/dev/null 2>&1; then
+    echo "OK   Docker daemon (running)"
+    PASS=$((PASS + 1))
+  else
+    echo "MISSING  Docker daemon — start Docker Desktop or the Docker service"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "=== Growthub Twenty CRM — Dependency Check ==="
+echo ""
+check "git"    "git"    "https://git-scm.com/downloads"
+check "node"   "node"   "https://nodejs.org (v18+ required)"
+check "npm"    "npm"    "Comes with Node.js"
+check "docker" "docker" "https://docs.docker.com/get-docker/"
+echo ""
+
+if command -v docker >/dev/null 2>&1; then
+  check_docker_running
+fi
+
+echo ""
+echo "Passed: $PASS  |  Missing: $FAIL"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo ""
+  echo "Install missing tools before running local-fork workflows."
+  echo "Agent-only mode does not require Docker or a local fork."
+  exit 1
+fi
+
+echo ""
+echo "All dependencies present."
+echo "You are ready for local-fork execution. Run: bash setup/clone-fork.sh"

package/assets/worker-kits/growthub-twenty-crm-v1/setup/clone-fork.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# clone-fork.sh — Clone the Twenty CRM repo and boot the local development environment
+# Usage: bash setup/clone-fork.sh
+# Requires: git, node, npm, docker, docker-compose
+set -e
+
+FORK_DIR="${TWENTY_FORK_PATH:-$HOME/twenty}"
+REPO_URL="https://github.com/twentyhq/twenty"
+
+echo "=== Growthub Twenty CRM Studio — Fork Setup ==="
+echo ""
+
+# Dependency checks
+for cmd in git node npm docker; do
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "ERROR: $cmd is required but not found."
+    echo "Install it before running this script."
+    exit 1
+  fi
+done
+
+if ! docker info >/dev/null 2>&1; then
+  echo "ERROR: Docker daemon is not running."
+  echo "Start Docker Desktop or the Docker service before running this script."
+  exit 1
+fi
+
+if [ -d "$FORK_DIR" ]; then
+  echo "Fork already exists at $FORK_DIR — skipping clone."
+  echo "To re-clone, remove the directory first: rm -rf $FORK_DIR"
+else
+  echo "Cloning Twenty CRM → $FORK_DIR"
+  git clone "$REPO_URL" "$FORK_DIR"
+  echo "Clone complete."
+fi
+
+cd "$FORK_DIR"
+
+echo ""
+echo "Copying environment config..."
+if [ ! -f ".env" ]; then
+  if [ -f ".env.example" ]; then
+    cp .env.example .env
+    echo "Copied .env.example → .env"
+    echo "Review .env and set any required values before starting."
+  else
+    echo "WARNING: .env.example not found — you may need to configure .env manually."
+  fi
+else
+  echo ".env already exists — skipping copy."
+fi
+
+echo ""
+echo "Starting Twenty via Docker Compose..."
+echo "This pulls images for PostgreSQL, Redis, the Twenty server, and frontend."
+echo "First run may take several minutes."
+echo ""
+
+if command -v docker-compose >/dev/null 2>&1; then
+  docker-compose up -d
+else
+  docker compose up -d
+fi
+
+echo ""
+echo "=== Twenty CRM is starting ==="
+echo ""
+echo "Frontend will be available at: http://localhost:3001"
+echo "Server API will be available at: http://localhost:3000"
+echo ""
+echo "Next steps:"
+echo "  1. Open http://localhost:3001 and create your workspace."
+echo "  2. Go to Settings > API > Tokens and generate an API token."
+echo "  3. Set TWENTY_API_TOKEN and TWENTY_API_URL=http://localhost:3000 in your kit .env file."
+echo "  4. Run: node setup/verify-env.mjs"
+echo ""
+echo "To stop Twenty: docker-compose down (or docker compose down)"

package/assets/worker-kits/growthub-twenty-crm-v1/setup/verify-env.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// verify-env.mjs — Validate Twenty CRM credentials and API connectivity.
+// Usage: node setup/verify-env.mjs
+// Exit 0 = credentials are valid and API is reachable. Exit 1 = missing, invalid, or unreachable.
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const envPath = resolve(process.cwd(), ".env");
+
+function parseEnvFile(filePath) {
+  const vars = {};
+  const lines = readFileSync(filePath, "utf8").split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = trimmed.slice(0, eqIndex).trim();
+    const value = trimmed.slice(eqIndex + 1).trim();
+    vars[key] = value;
+  }
+  return vars;
+}
+
+async function main() {
+  if (!existsSync(envPath)) {
+    console.error("ERROR: .env file not found.");
+    console.error("Run: cp .env.example .env  then set your TWENTY_API_TOKEN and TWENTY_API_URL.");
+    process.exit(1);
+  }
+
+  const env = parseEnvFile(envPath);
+  const apiToken = env["TWENTY_API_TOKEN"];
+  const apiUrl = env["TWENTY_API_URL"] ?? "https://api.twenty.com";
+
+  if (!apiToken || apiToken === "your_twenty_api_token_here" || apiToken.trim() === "") {
+    console.error("ERROR: TWENTY_API_TOKEN is not set in .env.");
+    console.error("Generate a token in your Twenty workspace: Settings > API > Tokens");
+    process.exit(1);
+  }
+
+  console.log(`Verifying token against ${apiUrl} ...`);
+
+  const graphqlQuery = JSON.stringify({
+    query: "{ currentWorkspace { id displayName } }",
+  });
+
+  let res;
+  try {
+    res = await fetch(`${apiUrl}/graphql`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        "Content-Type": "application/json",
+      },
+      body: graphqlQuery,
+    });
+  } catch (err) {
+    console.error(`ERROR: Could not reach ${apiUrl}.`);
+    console.error(err.message);
+    console.error("");
+    console.error("If using local-fork mode, ensure Twenty is running via Docker Compose.");
+    console.error("Run: bash setup/clone-fork.sh");
+    process.exit(1);
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    console.error(`ERROR: API token rejected (HTTP ${res.status}).`);
+    console.error("Check your TWENTY_API_TOKEN in .env — generate a new one at Settings > API > Tokens.");
+    process.exit(1);
+  }
+
+  if (!res.ok) {
+    console.error(`ERROR: Unexpected response from Twenty API (HTTP ${res.status}).`);
+    process.exit(1);
+  }
+
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    console.error("ERROR: Could not parse API response as JSON.");
+    process.exit(1);
+  }
+
+  if (body.errors && body.errors.length > 0) {
+    console.error("ERROR: GraphQL error from Twenty API:");
+    for (const err of body.errors) {
+      console.error(` - ${err.message}`);
+    }
+    process.exit(1);
+  }
+
+  const workspace = body?.data?.currentWorkspace;
+  if (workspace) {
+    console.log(`OK: Connected to workspace "${workspace.displayName}" (id: ${workspace.id})`);
+  } else {
+    console.log("OK: TWENTY_API_TOKEN is valid and the API is reachable.");
+  }
+
+  process.exit(0);
+}
+
+main();