Local development

Prerequisites

• Node.js 24+ (the repo's .tool-versions pins it)
• Python 3.12+ (for packages/color-edit)
• Firebase CLI 15.7.0 (ASDF_FIREBASE_VERSION=15.7.0 firebase --version)
• gcloud authenticated against cpl-gen-ai-marketing (for ADC-based Vertex / Firestore / GCS access)

Install

npm install

Backend

# Genkit dev UI with hot reload (recommended)
npx nx dev server

# Plain Express server on :8080
npm start

In dev mode (NODE_ENV=development and USE_CLOUD_TASKS unset), pipeline-core/cloud-tasks.ts short-circuits the Cloud Tasks API and does direct fetch POSTs to localhost stage handlers. No Cloud Tasks queue or OIDC handshake required.

Frontend

npx nx dev frontend

Vite dev server on :5173 with a proxy to backend :8080 (see packages/frontend/vite.config.ts for the route map).

MCP server

npx nx serve mcp-server   # Express on :8080

For local OAuth flow without Google credentials, set MCP_ALLOW_INSECURE_OIDC=1. This is only respected when NODE_ENV !== 'production'; production rejects insecure-mode hard.

Documentation site

npx nx dev docs

Docusaurus dev server on :3000, hot reload on .md saves.

Build it locally:

npx nx build docs
npx nx serve docs   # serves the built dist/ on :3000

Tests

# Everything (lint + test + type-check across all packages)
npx nx run-many -t build lint test type-check --parallel=1

# Single package
npx nx test pipeline-core
npx nx test mcp-server
npx nx test color-edit

Tests for pipeline-core, mcp-server, server use the Firestore emulator (each on its own port to avoid collisions: 8085 / 8086 / 8087). nx.json sets parallel=false on the test target for this reason.

Useful environment overrides

Variable	Default	When
FIRESTORE_DB_ID	(default)	Talk to a non-default Firestore database
GCS_BUCKET_NAME	cpl-gen-ai-marketing-images	Use a personal sandbox bucket
USE_CLOUD_TASKS	unset	Force real Cloud Tasks even in dev
MCP_ALLOW_INSECURE_OIDC	0	Skip Google ID token signature verification