@growthub/cli 0.3.54 → 0.3.56

package/assets/worker-kits/growthub-twenty-crm-v1/output-standards.md

@@ -0,0 +1,175 @@
+# Output Standards — Twenty CRM v1
+
+This document defines the output contract for every artifact produced by this kit.
+
+---
+
+## OUTPUT FOLDER STRUCTURE
+
+```text
+output/
+└── <client-slug>/
+    └── <project-slug>/
+        ├── <ClientSlug>_CRMSetupBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_DataModelDesign_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_LeadEnrichmentPipeline_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_PipelineAutomationBrief_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_WebhookIntegrationSpec_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_APIQueryPlan_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_CustomObjectDesign_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_ImportMapping_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_WorkspaceConfigChecklist_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_IntegrationHandoff_v<N>_<YYYYMMDD>.md
+        ├── <ClientSlug>_EnrichmentFieldMap_v<N>_<YYYYMMDD>.md
+        └── <ClientSlug>_CRMPlaybook_v<N>_<YYYYMMDD>.md
+```
+
+---
+
+## REQUIRED OUTPUT TYPES
+
+Every full CRM implementation package must include:
+- CRM setup brief
+- data model design
+- lead enrichment pipeline
+- pipeline automation brief
+- webhook integration spec
+- API query plan
+- workspace config checklist
+- integration handoff
+- CRM playbook
+
+Custom object design and import mapping are included when the scope requires them.
+
+---
+
+## REQUIRED SECTIONS
+
+### CRM setup brief
+1. Client context and CRM objective
+2. Deployment mode (cloud / self-hosted / local-fork)
+3. Team size and user roles
+4. Data sources and volume estimates
+5. Integration scope
+6. Go-live timeline and milestones
+7. Success criteria
+
+### Data model design
+1. Standard objects in use and configuration notes
+2. Custom objects (if any) with full field definitions
+3. Relationship map (which objects link to which)
+4. Field type table per object
+5. Display configuration (labels, icons, default views)
+6. Open questions / decisions required
+
+### Lead enrichment pipeline
+1. Enrichment provider(s) and auth mechanism
+2. Source fields provided
+3. Target Twenty fields
+4. Deduplication strategy and match key
+5. Insert vs. merge behavior
+6. Update frequency
+7. Error and failure handling
+
+### Pipeline automation brief
+1. Pipeline name and purpose
+2. Trigger type and object
+3. Trigger conditions (field, value, timing)
+4. Action sequence
+5. Failure / timeout behavior
+6. Monitoring and alerting plan
+
+### Webhook integration spec
+1. Inbound vs. outbound classification
+2. Event name and trigger object
+3. Payload schema
+4. Target endpoint or source
+5. Auth mechanism
+6. Retry policy
+7. Test procedure
+
+### API query plan
+1. Query type (GraphQL / REST)
+2. Object(s) targeted
+3. Filter conditions
+4. Field selection
+5. Expected response structure
+6. Use case and consumer
+
+### Custom object design
+1. Object name and purpose
+2. Field table (name, type, required, options)
+3. Relationship definitions
+4. Creation method (UI vs. metadata API)
+5. Default view configuration
+6. Validation rules
+
+### Import mapping
+1. Source CRM / export format
+2. Column-by-column mapping table
+3. Transformation rules
+4. Deduplication key
+5. Import mode (insert / merge)
+6. Post-import validation steps
+
+### Workspace config checklist
+1. Settings to configure (auth, members, roles, branding)
+2. Integrations to enable
+3. Objects to activate or create
+4. Views and filters to configure
+5. Email and notification settings
+6. API token generation and distribution
+
+### Integration handoff
+1. System integration diagram
+2. Auth credentials required (types only — no values)
+3. Endpoint contracts
+4. Sequence diagram for data flow
+5. Environment checklist (dev / staging / prod)
+6. Rollback plan
+
+### Enrichment field map
+1. Provider name
+2. Provider field → Twenty field table with types and transformations
+3. Deduplication key
+4. Update frequency
+5. Notes and edge cases
+
+### CRM playbook
+1. Team roles and permissions
+2. Daily workflow (record creation, updates, activities)
+3. Pipeline management procedures
+4. Enrichment cadence
+5. Reporting and dashboard instructions
+6. Escalation and handoff protocols
+7. Maintenance and data hygiene checklist
+
+---
+
+## FILE NAMING RULES
+
+Pattern:
+
+```text
+<ClientSlug>_<OutputType>_v<N>_<YYYYMMDD>.md
+```
+
+Rules:
+- `ClientSlug` is PascalCase
+- never overwrite an existing version
+- keep one artifact per file
+- Markdown only
+
+---
+
+## QUALITY BAR
+
+An output is complete when:
+- no placeholder text remains
+- all object and field names match Twenty's naming conventions
+- deduplication keys are named in every enrichment or import artifact
+- every automation trigger-action pair has a documented failure path
+- webhook specs include full payload schemas
+- GraphQL queries are syntactically correct
+- the CRM playbook is written at a level a non-technical team member can execute
+- integration handoff provides enough detail for a developer to implement without asking follow-up questions

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();