@growthub/cli 0.3.54 → 0.3.55

package/assets/worker-kits/growthub-twenty-crm-v1/docs/twenty-fork-integration.md

@@ -0,0 +1,213 @@
+# Twenty Fork Integration — Developer Notes
+
+**Kit:** `growthub-twenty-crm-v1`  
+**Repo:** `github.com/twentyhq/twenty`  
+**Stack:** TypeScript / React / NestJS / PostgreSQL / Redis
+
+---
+
+## OVERVIEW
+
+Twenty is a fully open-source CRM built to replace Salesforce and Apollo-style tools for teams that want control over their data and growth stack. It ships with a REST and GraphQL API, a workflow engine, custom object support, and a CLI. This document defines how this kit targets the Twenty fork for local development and self-hosted deployments.
+
+---
+
+## REPOSITORY STRUCTURE (KEY PATHS)
+
+```text
+twenty/
+├── packages/
+│   ├── twenty-server/          # NestJS API server
+│   │   ├── src/
+│   │   │   ├── modules/        # CRM domain modules (Person, Company, Opportunity, etc.)
+│   │   │   ├── metadata/       # Custom object and field metadata API
+│   │   │   ├── api/            # REST and GraphQL endpoint handlers
+│   │   │   └── workflow/       # Workflow engine (triggers, actions)
+│   ├── twenty-front/           # React frontend (Vite)
+│   │   ├── src/
+│   │   │   ├── modules/        # UI modules per CRM object
+│   │   │   └── pages/          # Page definitions
+│   └── twenty-cli/             # CLI package (@twenty-crm/cli)
+│       └── src/                # CLI commands (workspace management, etc.)
+├── docker-compose.yml          # Local development stack
+├── .env.example                # Server environment template
+└── README.md
+```
+
+---
+
+## STANDARD OBJECT MODULES
+
+Each standard CRM object lives in `packages/twenty-server/src/modules/<object>/`:
+
+| Object module | Key files |
+|---|---|
+| `person` | `person.entity.ts`, `person.repository.ts`, `person.resolver.ts` |
+| `company` | `company.entity.ts`, `company.repository.ts`, `company.resolver.ts` |
+| `opportunity` | `opportunity.entity.ts`, `opportunity.resolver.ts` |
+| `note` | `note.entity.ts`, `note.resolver.ts` |
+| `task` | `task.entity.ts`, `task.resolver.ts` |
+
+**Inspecting standard object fields:** Read the entity file (e.g. `person.entity.ts`) to confirm which fields are available, their types, and which are required.
+
+---
+
+## METADATA API (CUSTOM OBJECTS)
+
+Custom objects and fields are managed via the metadata API at `/metadata`.
+
+### Creating a custom object
+
+```graphql
+POST <TWENTY_API_URL>/metadata
+Authorization: Bearer <token>
+
+mutation CreateObject {
+  createOneObject(input: {
+    labelSingular: "Partner Account"
+    labelPlural: "Partner Accounts"
+    nameSingular: "partnerAccount"
+    namePlural: "partnerAccounts"
+    icon: "IconBuilding"
+    description: "Tracks partner organizations separately from customers"
+  }) {
+    id
+    nameSingular
+    isActive
+  }
+}
+```
+
+### Adding a field to a custom object
+
+```graphql
+mutation CreateTextField {
+  createOneField(input: {
+    objectMetadataId: "<object-id>"
+    type: TEXT
+    name: "partnerTier"
+    label: "Partner Tier"
+    isNullable: true
+    defaultValue: null
+  }) {
+    id
+    name
+    type
+  }
+}
+```
+
+### Activating a custom object
+
+After creation, activate via the UI (Settings > Objects > toggle Active) or via API:
+
+```graphql
+mutation ActivateObject {
+  activateWorkspaceObject(input: { id: "<object-id>" }) {
+    id
+    isActive
+  }
+}
+```
+
+---
+
+## WORKFLOW ENGINE
+
+Twenty's workflow engine is in `packages/twenty-server/src/workflow/`.
+
+### Trigger types (frozen assumptions, verify in fork)
+
+| Trigger | Description |
+|---|---|
+| `RECORD_CREATED` | Fires when a record of the target object is created |
+| `RECORD_UPDATED` | Fires when a record is updated |
+| `MANUAL` | Manually triggered by a user |
+| `CRON` | Time-based schedule |
+
+### Action types (frozen assumptions, verify in fork)
+
+| Action | Description |
+|---|---|
+| `SEND_EMAIL` | Send an email |
+| `CREATE_RECORD` | Create a CRM record |
+| `UPDATE_RECORD` | Update a CRM record |
+| `DELETE_RECORD` | Delete a CRM record |
+| `CODE` | Execute a custom code action (TypeScript function) |
+| `FILTER` | Condition filter (branch logic) |
+| `SEND_HTTP_REQUEST` | Outbound HTTP POST (webhook action) |
+
+**Recommendation for custom automation logic:** Use the `CODE` action type for complex conditional logic that the standard action types do not support. The CODE action executes a TypeScript function in a sandboxed environment.
+
+---
+
+## LOCAL DEVELOPMENT STACK
+
+### Prerequisites
+
+- Docker and Docker Compose
+- Node.js 18+
+- Git
+
+### Boot sequence
+
+```bash
+git clone https://github.com/twentyhq/twenty ~/twenty
+cd ~/twenty
+cp .env.example .env
+docker-compose up -d
+```
+
+Services started:
+- `twenty-server` — NestJS API at `http://localhost:3000`
+- `twenty-front` — React frontend at `http://localhost:3001`
+- `postgres` — PostgreSQL at `localhost:5432`
+- `redis` — Redis at `localhost:6379`
+
+### Running migrations
+
+```bash
+npx nx run twenty-server:database:migrate
+```
+
+### Seeding the database
+
+```bash
+npx nx run twenty-server:database:seed
+```
+
+### Accessing the GraphQL playground
+
+Navigate to `http://localhost:3000/graphql` in the browser. The playground requires an active Bearer token.
+
+---
+
+## KNOWN FORK CONSIDERATIONS
+
+### Environment variables (`.env`)
+
+The Twenty server requires several environment variables. Key ones:
+
+| Variable | Purpose |
+|---|---|
+| `PG_DATABASE_URL` | PostgreSQL connection string |
+| `REDIS_URL` | Redis connection string |
+| `SERVER_URL` | Public API URL (used for webhooks) |
+| `FRONT_BASE_URL` | Frontend URL |
+| `SIGN_IN_PREFILLED` | Pre-fill sign-in for local dev |
+| `STORAGE_TYPE` | `local` (dev) or `s3` (production) |
+
+### First-time workspace setup
+
+After booting Docker Compose, navigate to `http://localhost:3001` and create your first workspace. The default seeded admin credentials (if seeded) are in the Twenty README.
+
+### CLI
+
+The Twenty CLI (`@twenty-crm/cli`) provides workspace management commands:
+
+```bash
+npx twenty workspace:create --name "My Workspace"
+npx twenty workspace:list
+```
+
+Run `npx twenty --help` for the full command surface.

package/assets/worker-kits/growthub-twenty-crm-v1/examples/crm-playbook-sample.md

@@ -0,0 +1,172 @@
+# CRM Playbook — Growthub (SAMPLE)
+
+**Date:** 2026-04-15  
+**Kit:** `growthub-twenty-crm-v1`  
+**Version:** v1
+
+> **Note:** This is a sample output. Adapt all procedures to the actual client context.
+
+---
+
+## ABOUT THIS PLAYBOOK
+
+This playbook is the operating manual for the Growthub Twenty CRM workspace. It defines roles, daily workflows, pipeline procedures, and data hygiene rules. All four team members with CRM access must read this before their first session.
+
+---
+
+## 1. TEAM ROLES AND PERMISSIONS
+
+| Role | Name | Access level | Responsibilities |
+|---|---|---|---|
+| CRM Admin | Antonio Romero | Full access | Object config, member management, integration maintenance, data hygiene |
+| Sales Rep | [Rep 1] | Create/edit own records | Lead creation, pipeline updates, notes |
+| Sales Rep | [Rep 2] | Create/edit own records | Lead creation, pipeline updates, notes |
+| CS Manager | [CS] | Read/edit post-close | Customer success tracking, renewal notes |
+
+**Onboarding new members:** CRM Admin creates the workspace member in Settings > Members, assigns the correct role, and shares this playbook.
+
+---
+
+## 2. DAILY WORKFLOW
+
+### Sales rep daily workflow (10–15 min)
+
+1. Log in to Twenty and open **Pipeline Board** view (pre-filtered: open opportunities, my records)
+2. Review new leads assigned to you in the LEAD stage — move any that are ICP-qualified to QUALIFIED
+3. For every call or email from today: add a Note on the Person record (what you discussed, next step, date)
+4. Check Tasks due today — complete each or reschedule with a Note explaining the delay
+5. End of day: every new contact from today's outreach must be in Twenty before logging off
+
+**Expected daily time investment:** 10–15 minutes
+
+### CRM Admin daily workflow (5–10 min)
+
+1. Check import error log if enrichment pipeline ran overnight
+2. Spot-check 3 records for data quality (no blank required fields, company linked, stage current)
+3. Check workflow logs (Settings > Workflows) for any automation failures
+
+---
+
+## 3. PIPELINE MANAGEMENT PROCEDURES
+
+### Creating a new Opportunity
+
+1. Navigate to Opportunities → click `+ New`
+2. Fill in: **Name** (e.g. "Acme Corp — Growthub Platform"), **Stage** (start at LEAD), **Amount**, **Close Date**
+3. Link **Point of Contact** (Person) and **Company**
+4. Set **Assignee** to yourself or the responsible rep
+5. Add a first Note: where did this lead come from, what is the hook?
+
+### Moving a stage
+
+1. Open the Opportunity → click the stage badge at the top
+2. Select the new stage
+3. Add a Note immediately explaining what happened and what the next step is
+4. If moving to **CLOSED_WON**: confirm Amount and Close Date are accurate before saving
+5. If moving to **CLOSED_LOST**: add a Note with the reason (e.g. "No budget Q2", "Chose competitor", "Ghosted after demo")
+
+**Pipeline stages and exit criteria:**
+
+| Stage | Exit criteria |
+|---|---|
+| LEAD | ICP fit confirmed + email opened or replied |
+| QUALIFIED | Discovery call complete, pain confirmed, budget range known |
+| DEMO | Product demo complete, specific use case validated |
+| PROPOSAL | Commercial terms sent or under negotiation |
+| CLOSED_WON | Contract signed, payment confirmed |
+| CLOSED_LOST | Explicitly lost or no response after 3 follow-ups past close date |
+
+### Weekly pipeline review (team — 30 min)
+
+**View:** Pipeline Board filtered to QUALIFIED + DEMO + PROPOSAL  
+**Sort:** Close Date ascending
+
+For each open opportunity in the top 10 by close date:
+- Is the stage accurate?
+- When was the last Note added? (if >7 days, flag as stale)
+- What is the next action and who owns it?
+- Is there a Task assigned for the next action?
+
+---
+
+## 4. ENRICHMENT CADENCE
+
+**Schedule:** Weekly on Monday at 6 AM (automated cron job)
+
+**What runs automatically:**
+- Apollo enrichment job pulls the latest saved search export and runs a merge import into Twenty
+- New Person records are created; existing records are updated with latest enrichment data
+
+**What to do if the enrichment job fails:**
+1. CRM Admin checks the error log file `enrichment-errors.csv` (stored in the enrichment job output)
+2. Review skipped records — most common reason is missing email
+3. Manually add missing contacts from Apollo if volume is small (< 20 records)
+4. Contact [developer] if the job fails to run at all (check cron logs)
+
+---
+
+## 5. REPORTING AND DASHBOARD INSTRUCTIONS
+
+### Pipeline health view (built in Twenty)
+
+**Filter:** Opportunities where stage IN [QUALIFIED, DEMO, PROPOSAL]  
+**Group by:** Stage  
+**Sort:** Close Date ascending
+
+**Reading the view:**
+- Count in each stage = pipeline coverage (healthy = more in LEAD/QUALIFIED than PROPOSAL)
+- Total amount in DEMO + PROPOSAL = near-term revenue signal
+- Opportunities with last Note > 14 days old = stale — review in weekly pipeline call
+
+### Weekly metrics to track (manual, 5 min)
+
+Count from Twenty each Friday:
+- New Opportunities created this week
+- Opportunities moved to CLOSED_WON this week
+- Opportunities moved to CLOSED_LOST this week + note the loss reasons
+- Opportunities moved to DEMO this week (pipeline velocity indicator)
+
+---
+
+## 6. ESCALATION AND HANDOFF PROTOCOLS
+
+### Record dispute (wrong data)
+
+1. Do **not** delete the record
+2. Add a Note: "Data quality issue — [describe problem]" and tag `@antonio`
+3. CRM Admin reviews and resolves within 2 business days
+
+### Integration failure
+
+1. Check Settings > Workflows for automation errors
+2. Check enrichment error log file
+3. If unresolved: email [developer contact] with the error message and timestamp
+4. CRM Admin documents the gap in a Note on the affected object if data is missing
+
+### Offboarding a team member
+
+1. CRM Admin reassigns all open Opportunities from the departing member to the remaining rep
+2. Reassigns all open Tasks
+3. Deactivates the workspace member (Settings > Members > Deactivate)
+4. Revokes any API tokens the member had access to
+
+---
+
+## 7. MAINTENANCE AND DATA HYGIENE CHECKLIST
+
+**Weekly (CRM Admin — 15 min):**
+- [ ] Review import error log — resolve skipped records
+- [ ] Check stale Opportunities (no update in 14 days) — flag for reps to update
+- [ ] Confirm all Closed Won / Closed Lost opportunities have a loss/win reason Note
+
+**Monthly (CRM Admin — 30 min):**
+- [ ] Search for duplicate Person records (same email) — merge duplicates
+- [ ] Search for Companies with no linked Persons — flag for review or archive
+- [ ] Review workflow logs for repeated failures — escalate to developer if pattern
+- [ ] Update this playbook if any procedures have changed
+
+**Quarterly (CRM Admin + head of sales — 60 min):**
+- [ ] Review pipeline stage definitions — do they still match how we sell?
+- [ ] Evaluate enrichment provider data quality — are enriched fields accurate?
+- [ ] Review custom field usage — archive any fields the team stopped using
+- [ ] Check if new automation opportunities exist based on team pain points

package/assets/worker-kits/growthub-twenty-crm-v1/examples/crm-setup-sample.md

@@ -0,0 +1,100 @@
+# CRM Setup Brief — Growthub (SAMPLE)
+
+**Date:** 2026-04-15  
+**Operator:** `twenty-crm-operator`  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `cloud`
+
+> **Note:** This is a sample output illustrating the quality and format expected from this kit. Adapt all values to the actual client context.
+
+---
+
+## 1. CLIENT CONTEXT AND CRM OBJECTIVE
+
+**Client:** Growthub  
+**Industry:** B2B SaaS / Growth Platform  
+**Company size:** 12 employees  
+**CRM objective:** Build a structured outbound sales pipeline with automated lead enrichment from Apollo, Stripe event capture, and Intercom conversation logging.
+
+**Why Twenty:**
+- Open-source, MIT license — no vendor lock-in risk for a growing platform company
+- TypeScript/React/NestJS stack matches Growthub's existing codebase — easier to self-host and extend
+- REST and GraphQL APIs make it straightforward to build custom enrichment pipelines
+- Custom object support handles the non-standard Growthub product-led-growth workflow
+
+---
+
+## 2. DEPLOYMENT MODE
+
+**Selected mode:** `cloud`  
+**API URL:** `https://api.twenty.com`  
+**Environment:** production
+
+**Prerequisites confirmed:**
+- [x] Twenty workspace created at app.twenty.com
+- [x] API token generated: `growthub-production` token (stored in `.env`)
+- [x] `node setup/verify-env.mjs` exits 0 — connected to workspace "Growthub" (id: abc123)
+
+---
+
+## 3. TEAM SIZE AND USER ROLES
+
+| Role | User | Permissions |
+|---|---|---|
+| CRM Admin | Antonio Romero | Full access |
+| Sales Rep | [Sales Rep 1] | Create/edit Opportunities and Persons |
+| Sales Rep | [Sales Rep 2] | Create/edit Opportunities and Persons |
+| CS Manager | [CS Manager] | Read/edit Opportunities post-close |
+
+**Total workspace members:** 4
+
+---
+
+## 4. DATA SOURCES AND VOLUME ESTIMATES
+
+| Source | Object type | Estimated volume | Import method |
+|---|---|---|---|
+| Apollo CSV export | Person + Company | ~1,200 contacts, ~400 companies | CSV import |
+| Stripe | Company + Note | ~50 new customers/month | Webhook (customer.created) |
+| Intercom | Note | ~150 conversations/month | Webhook (conversation.created) |
+
+---
+
+## 5. INTEGRATION SCOPE
+
+| Integration | Direction | Priority |
+|---|---|---|
+| Apollo | Inbound enrichment | High |
+| Stripe | Inbound webhook | High |
+| Intercom | Inbound webhook | Medium |
+| Slack | Outbound notification (Closed Won) | Low |
+
+---
+
+## 6. GO-LIVE TIMELINE AND MILESTONES
+
+| Milestone | Target date | Owner |
+|---|---|---|
+| Data model finalized | 2026-04-18 | Antonio (CRM Admin) |
+| Initial Apollo import complete | 2026-04-20 | Antonio |
+| Stripe webhook live | 2026-04-22 | Developer |
+| Intercom webhook live | 2026-04-25 | Developer |
+| Stage automations active | 2026-04-25 | Developer |
+| Team onboarded | 2026-04-28 | Antonio |
+
+---
+
+## 7. SUCCESS CRITERIA
+
+- [x] All 1,200 contacts imported and deduplicated against email
+- [x] Pipeline visible with 6 stages (Lead → Closed Won/Lost)
+- [x] 3 automations active (stage change → task creation, Closed Won → Slack notify, Intercom → Note)
+- [x] Stripe enrichment running on customer.created event
+- [x] All 4 team members onboarded and logging daily activity in the CRM
+
+---
+
+## OPEN QUESTIONS
+
+- [ ] Does the head of sales want round-robin assignment or territory-based routing?
+- [ ] Should Intercom conversations be logged as Notes on Person or as a custom Activity object?

package/assets/worker-kits/growthub-twenty-crm-v1/examples/lead-enrichment-sample.md

@@ -0,0 +1,117 @@
+# Lead Enrichment Pipeline — Growthub (SAMPLE)
+
+**Date:** 2026-04-15  
+**Kit:** `growthub-twenty-crm-v1`  
+**Mode:** `cloud`
+
+> **Note:** This is a sample output. Adapt all values to the actual client context.
+
+---
+
+## 1. ENRICHMENT PROVIDER(S)
+
+| Provider | Auth mechanism | Data tier | Primary use |
+|---|---|---|---|
+| Apollo | Bearer token | Person + Company | Outbound lead source |
+| Clay | API key | Person + Company | Enrichment waterfall (email verification + firmographic) |
+
+---
+
+## 2. SOURCE FIELDS PROVIDED
+
+### Apollo — Person fields
+
+| Provider field | Data type | Example value |
+|---|---|---|
+| `first_name` | string | `Jane` |
+| `last_name` | string | `Doe` |
+| `email` | string | `jane@acme.com` |
+| `title` | string | `Head of Growth` |
+| `seniority` | string | `director` |
+| `linkedin_url` | string | `https://linkedin.com/in/janedoe` |
+| `city` | string | `San Francisco` |
+| `organization.name` | string | `Acme Corp` |
+| `organization.website_url` | string | `https://acme.com` |
+| `organization.estimated_num_employees` | integer | `250` |
+
+---
+
+## 3. DEDUPLICATION STRATEGY
+
+**Person dedup key:** `emails.primaryEmail`  
+**Company dedup key:** `domain`  
+**Secondary person key (when email unavailable):** `linkedInLink.url`
+
+**Dedup behavior:**
+- Match found → **merge** (update existing record with enriched fields, preserve existing data)
+- No match found → **insert** (create new record)
+- If both email and LinkedIn are absent → **skip and log** for manual review
+
+---
+
+## 4. IMPORT MODE
+
+**Selected mode:** `merge-with-insert-fallback`
+
+**Rationale:** Growthub has existing contacts from previous manual spreadsheet work. Merging ensures enrichment data layers on top without creating duplicates.
+
+---
+
+## 5. IMPORT METHOD
+
+**Method:** CSV import via Twenty UI (first batch), then GraphQL mutation batch (ongoing enrichment)
+
+**Import sequence:**
+1. Export Apollo contact list as CSV with all available fields selected
+2. Clean CSV: lowercase all emails, strip `https://` and trailing slashes from domain field
+3. Import Company records first (Settings > Companies > Import)
+4. Import Person records second with company linking enabled
+5. Run post-import audit
+
+**Batch size recommendation:** 500 records per batch
+
+---
+
+## 6. FIELD MAPPING (SUMMARY)
+
+| Source field | → | Twenty object | Twenty field | Transformation |
+|---|---|---|---|---|
+| `email` | → | `Person` | `emails.primaryEmail` | lowercase, trim |
+| `first_name` | → | `Person` | `name.firstName` | none |
+| `last_name` | → | `Person` | `name.lastName` | none |
+| `title` | → | `Person` | `position` | none |
+| `linkedin_url` | → | `Person` | `linkedInLink.url` | none |
+| `city` | → | `Person` | `city` | none |
+| `organization.name` | → | `Company` | `name` | none |
+| `organization.website_url` | → | `Company` | `domain` | strip `https://` and trailing `/` |
+| `organization.estimated_num_employees` | → | `Company` | `employees` | integer cast |
+
+---
+
+## 7. POST-IMPORT VALIDATION
+
+| Check | Expected result | Actual result |
+|---|---|---|
+| Total Person records imported | ~1,200 | [fill after import] |
+| Total Company records imported | ~400 | [fill after import] |
+| Duplicate email check | 0 duplicates | [fill after import] |
+| Company linkage rate | ≥ 90% | [fill after import] |
+| Skipped records (no email) | < 5% | [fill after import] |
+
+---
+
+## 8. ERROR AND FAILURE HANDLING
+
+| Error type | Behavior | Resolution |
+|---|---|---|
+| Invalid email format | Skip record, log to `enrichment-errors.csv` | Manual review and clean |
+| Duplicate email (post-dedup) | Merge into existing record | Review merged record for accuracy |
+| Missing company domain | Create Company with name only; flag for manual domain entry | Review flagged companies weekly |
+| API rate limit hit | Pause 30 seconds, retry with smaller batch | Reduce to 250 records/batch |
+
+---
+
+## 9. UPDATE FREQUENCY
+
+**Enrichment cadence:** Weekly on Monday mornings  
+**Trigger:** Apollo saves a new export on Sundays; enrichment job runs at 6 AM Monday via cron