Merge pull request #6 from pipedrive/AINATIVEM-45

AINATIVEM-45 App Extensions Frontend Scaffold — React iframe UI (optional)

Author: dmitriyeff

CLAUDE.md

@@ -17,6 +17,12 @@ npm test            # Vitest suite
 npm run generate        # generate test project in apps/test-app/ (gitignored)
 ```
 
+Run a single test file:
+
+```bash
+npx vitest run src/generators/node/app.test.ts
+```
+
 ## Architecture
 
 The tool is **CLI-first**, with an **AI plugin layer** built on top:
@@ -29,46 +35,59 @@ The tool is **CLI-first**, with an **AI plugin layer** built on top:
 The CLI asks for:
 - Backend: Node.js/Express, Node.js/Fastify, or PHP/Laravel
 - Database: Postgres, MySQL, or SQLite
-- App Extensions frontend: React, Vanilla JS, or none
+- App Extensions frontend: multi-select of `custom-panel` and/or `custom-modal` (or neither)
 - Webhooks: Yes/No
 
+`GeneratorOptions.appExtensions` is `AppExtensionType[]` where `AppExtensionType = 'custom-panel' | 'custom-modal'`. Check membership with `.includes('custom-panel')`, not boolean equality.
+
 ### Generator flow
 
 ```
 cli.ts (collects prompts)
   → prompts/ (projectName, database, appExtensions, webhooks)
-    → nodeGenerator (orchestrates 5 sub-generators)
+    → nodeGenerator (orchestrates sub-generators via NodeProjectBuilder)
       → oauth.ts, database.ts, app.ts
-      → webhooks.ts (conditional), appExtensions.ts (conditional)
+      → webhooks.ts (conditional)
+      → appExtensions.ts (conditional)
+          → appExtensions/panel.ts   — backend router + React snippet contributions
+          → appExtensions/modal.ts   — backend router + React snippet contributions
+          → appExtensions/frontend.ts — Vite + React frontend (index.html, App.tsx, etc.)
+          → appExtensions/sdk.ts     — usePipedriveSdk hook wrapper
+          → appExtensions/router.ts  — shared Express static-file router
       → serverEntry, packageJson, tsConfig, envExample, dockerCompose
 ```
 
-**There is no template directory.** Generators build file content as strings using `dedent()`, with conditional string interpolation for optional features (webhooks, app extension types). The `src/utils/writeFile.ts` utility writes files, creates parent directories, and auto-formats output with Prettier — generated code is formatted automatically without an explicit format step.
-
-`app.ts` is the main example of the conditional pattern: imports and router mounts are included only when the relevant features are enabled, and the result is written once.
+**There is no template directory.** Generators build file content as strings using `dedent()`, with conditional string interpolation for optional features. The `src/utils/writeFile.ts` utility writes files, creates parent directories, and auto-formats output with Prettier — generated code is formatted automatically without an explicit format step.
 
 ### Generated project structure
 
 ```
 <project-name>/
-  backend/
-    oauth/         # Authorization redirect, callback, token exchange, refresh, state validation
-    pipedrive-client/  # Official API client wrapper with preconfigured auth
-    database/      # Tenant/account mapping, tokens, scopes, installation status
-    webhooks/      # Optional webhook handlers
+  src/
+    app.ts              # Express app, mounts all routers
+    index.ts            # Server entry with DB retry loop
+    oauth/              # Authorization redirect, callback, token exchange, refresh
+    pipedrive-client/   # Official API client wrapper
+    database/           # Drizzle schema, migrations, db setup
+    webhooks/           # Optional webhook handlers
+    app-extensions/
+      panel/            # Express router serving built frontend (custom-panel)
+      modal/            # Express router serving built frontend (custom-modal)
   frontend/
-    app-extension-ui/  # Optional: React or Vanilla iframe UI with App Extensions SDK
+    app-extension-ui/   # Vite + React iframe UI (only when App Extensions selected)
   .env.example
   README.md
   docker-compose.yml
   marketplace-checklist.md
 ```
 
-## Adding features
+## App Extensions pattern
 
-- **New prompt**: add `src/prompts/<feature>.ts` + `.test.ts`, export from `cli.ts`
-- **New generator**: add `src/generators/node/<feature>.ts` + `.test.ts`, call from `nodeGenerator`
-- **Modify generated scaffold**: edit template strings in the corresponding generator file
+Each extension type (panel, modal) contributes a `ReactSnippetContribution` — an object with `{ sdkImports, handlers, buttons }` — that gets merged into the generated `App.tsx`. This lets panel.ts and modal.ts independently declare what SDK imports and JSX they need without knowing about each other.
+
+When App Extensions are enabled, `docker-compose up --watch` starts both the Express backend and the Vite dev server in containers with Compose Watch for live code sync. The Vite server must be exposed via a public HTTPS tunnel and configured in Developer Hub as the iframe URL.
+
+The backend serves the built frontend at `/extensions/panel` and `/extensions/modal` via Express static routing (using the shared `routerContent()` from `appExtensions/router.ts`). In production, `npm run build` builds both backend TypeScript and the Vite bundle.
 
 ## Builder Pattern
 
@@ -96,45 +115,35 @@ The scaffold generator uses `NodeProjectBuilder` + `BuildStep` (`src/generators/
 - Use `RouterMountBuilder` (`src/utils/templates.ts`) to accumulate `app.use()` calls conditionally
 - Use plain `dedent` for static content (YAML, JSON, `.env`, SQL)
 
-## MVP Scope
-
-The initial implementation targets:
-- **Runtime**: Node.js + TypeScript
-- **Backend**: Express or Fastify
-- **Database**: Postgres via Docker Compose
-- **Auth**: Full OAuth 2.0 install/callback/token-refresh flow
-- **API client**: Pipedrive Node.js client wrapper
-- **Frontend** (optional): React App Extensions UI
-- Outputs `.env.example` and a Marketplace readiness checklist
+## Adding features
 
-PHP and MySQL/SQLite backends come after MVP. The PHP generator exists but throws "not yet implemented". App Extensions frontend is prompted but not yet generated.
+- **New prompt**: add `src/prompts/<feature>.ts` + `.test.ts`, export from `cli.ts`
+- **New generator**: add `src/generators/node/<feature>.ts` + `.test.ts`, call from `nodeGenerator`
+- **New App Extension type**: add a file under `src/generators/node/appExtensions/` that exports an `async generate*` function and a `*ReactSnippets()` function returning `ReactSnippetContribution`, then wire it in `appExtensions.ts` and `frontend.ts`
+- **Modify generated scaffold**: edit template strings in the corresponding generator file
 
 ## Core Modules
 
 ### OAuth (`backend/oauth/`)
 Full OAuth 2.0: app registration guidance, authorization redirect, callback handling, token exchange, token refresh, state validation.
 
 ### Database (`backend/database/`)
-Uses **Drizzle ORM** (`drizzle-orm` + `drizzle-kit`) for schema definition and migrations. Drizzle is chosen because it supports Postgres, MySQL, and SQLite with the same TypeScript API — matching the three database options the CLI offers — and produces readable schema files with no codegen step.
+Uses **Drizzle ORM** (`drizzle-orm` + `drizzle-kit`) for schema definition and migrations. Supports Postgres, MySQL, and SQLite with the same TypeScript API.
 
 Structure:
 - `schema.ts` — Drizzle table definitions (tenants, oauth_tokens, installations)
 - `migrations/` — SQL migration files managed by `drizzle-kit`
-- `db.ts` — driver setup (selects `postgres-js`, `mysql2`, or `better-sqlite3` based on the chosen DB)
+- `db.ts` — driver setup (selects `postgres-js`, `mysql2`, or `better-sqlite3` based on chosen DB)
 
 ### Pipedrive API client (`backend/pipedrive-client/`)
 Wrapper around the official Pipedrive Node.js client with preconfigured authentication and helpers for common API calls.
 
 ### App Extensions frontend (`frontend/app-extension-ui/`)
-Only generated when the user opts in. Iframe-based UI using the App Extensions SDK, supporting: initialization, resizing, modals, notifications/snackbars, theme handling.
+Generated when the user selects `custom-panel` and/or `custom-modal`. Iframe-based React + Vite UI using the App Extensions SDK (`usePipedriveSdk` hook), with: SDK initialization, theme handling, resize, snackbar, confirmation dialog, signed token, and extension-type-specific actions (open modal from panel, close modal).
 
 ## Tests
 
-Vitest. Tests generate files into a `tmpdir()/cpa-app-test` directory, read them back to verify content, and clean up in `afterEach`. Run a single test file:
-
-```bash
-npx vitest run src/generators/node/app.test.ts
-```
+Vitest. Tests generate files into a `tmpdir()/cpa-app-test` directory, read them back to verify content, and clean up in `afterEach`.
 
 ## AI Plugin Commands (future layer)
 

README.md

@@ -26,27 +26,38 @@ The CLI will prompt for:
     pipedrive-client/         # Pipedrive API client wrapper
     webhooks/                 # Webhook handlers (if selected)
     app-extensions/           # App Extensions handlers (if selected)
+  frontend/
+    app-extension-ui/         # React + Vite iframe UI (if App Extensions selected)
   .env.example
-  docker-compose.yml          # Postgres or MySQL (if applicable)
+  docker-compose.yml          # Postgres, MySQL, and/or App Extensions UI (if applicable)
+  README.md
   package.json
   tsconfig.json
 ```
 
 The generated project uses **Express + TypeScript + Drizzle ORM** (ESM, Node.js).
 
+When App Extensions are selected, the generated project also includes a shared React iframe app for custom panels and custom modals. `docker-compose up --watch` starts the backend and Vite dev server in containers with Compose Watch. Local Developer Hub iframe URLs should point at an HTTPS tunnel to the Vite dev server, for example `https://<your-vite-tunnel>/extensions/panel` or `https://<your-vite-tunnel>/extensions/modal`. After `npm run build`, production iframe URLs can point at the backend-hosted `/extensions/panel` and `/extensions/modal` routes.
+
 ## Next steps after generation
 
 ```bash
 cd <project-name>
 cp .env.example .env
-docker-compose up -d   # if Postgres or MySQL was selected
+docker-compose up -d db   # if Postgres or MySQL was selected
 npm install
 npm run dev
 ```
 
+If App Extensions were selected, use Compose Watch instead of the local dev server:
+
+```bash
+docker-compose up --watch
+```
+
 Fill in `PIPEDRIVE_CLIENT_ID`, `PIPEDRIVE_CLIENT_SECRET`, and `DATABASE_URL` in `.env`.
 
 ## Requirements
 
 - Node.js 18+
-- Docker (if using Postgres or MySQL)
+- Docker (if using Postgres, MySQL, or App Extensions frontend development)

src/cli.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { pathToFileURL } from 'node:url';
+import { isCliEntrypoint, nextStepLines } from './cli.js';
+
+describe('nextStepLines', () => {
+	it('prints backend-only next steps for apps without App Extensions', () => {
+		expect(nextStepLines({ nameOrPath: 'test-app', database: 'sqlite', installDeps: false, hasAppExtensions: false }).join('\n')).toBe(`
+Next steps:
+  cd test-app
+  cp .env.example .env
+  npm install
+  npm run dev`);
+	});
+
+	it('prints the Compose Watch command when App Extensions are selected', () => {
+		expect(nextStepLines({ nameOrPath: 'test-app', database: 'postgres', installDeps: true, hasAppExtensions: true }).join('\n')).toBe(`
+Next steps:
+  cd test-app
+  cp .env.example .env
+  docker-compose up --watch`);
+	});
+});
+
+describe('isCliEntrypoint', () => {
+	it('treats npm bin symlinks as the CLI entrypoint', () => {
+		const realCliPath = '/package/dist/cli.js';
+		const binSymlinkPath = '/npm-cache/.bin/create-pipedrive-app';
+		const importMetaUrl = pathToFileURL(realCliPath).href;
+
+		expect(
+			isCliEntrypoint(importMetaUrl, binSymlinkPath, (path) => (path === binSymlinkPath ? realCliPath : path)),
+		).toBe(true);
+	});
+
+	it('does not treat unrelated files as the CLI entrypoint', () => {
+		const importMetaUrl = pathToFileURL('/package/dist/cli.js').href;
+
+		expect(isCliEntrypoint(importMetaUrl, '/other/tool.js', (path) => path)).toBe(false);
+	});
+});

src/cli.ts

@@ -1,11 +1,60 @@
 import * as clack from '@clack/prompts';
 import { spawn } from 'node:child_process';
+import { realpathSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { promptAppExtensions } from './prompts/appExtensions.js';
 import { promptDatabase } from './prompts/database.js';
 import { promptProjectName } from './prompts/projectName.js';
 import { promptWebhooks } from './prompts/webhooks.js';
 import { nodeGenerator } from './generators/node/index.js';
+import type { Database } from './generators/interface.js';
+
+interface NextStepOptions {
+	nameOrPath: string;
+	database: Database;
+	installDeps: boolean;
+	hasAppExtensions: boolean;
+}
+
+export function nextStepLines(options: NextStepOptions): string[] {
+	const needsDocker = options.database === 'postgres' || options.database === 'mysql';
+	const runWithCompose = options.hasAppExtensions;
+
+	const steps = [`cd ${options.nameOrPath}`, 'cp .env.example .env'];
+
+	if (runWithCompose) {
+		steps.push('docker-compose up --watch');
+	} else {
+		if (needsDocker) steps.push('docker-compose up -d db');
+		if (!options.installDeps) steps.push('npm install');
+		steps.push('npm run dev');
+	}
+
+	return ['', 'Next steps:', ...steps.map((s) => `  ${s}`)];
+}
+
+function printNextSteps(options: NextStepOptions): void {
+	for (const line of nextStepLines(options)) {
+		console.log(line);
+	}
+}
+
+type ResolvePath = (path: string) => string;
+
+export function isCliEntrypoint(
+	importMetaUrl: string,
+	argvPath: string | undefined,
+	resolvePath: ResolvePath = realpathSync,
+): boolean {
+	if (!argvPath) return false;
+
+	try {
+		return resolvePath(fileURLToPath(importMetaUrl)) === resolvePath(argvPath);
+	} catch {
+		return importMetaUrl === pathToFileURL(argvPath).href;
+	}
+}
 
 async function main(): Promise<void> {
 	clack.intro('create-pipedrive-app');
@@ -40,13 +89,14 @@ async function main(): Promise<void> {
 		spinner.stop(ok ? 'Dependencies installed' : 'npm install failed — run it manually');
 	}
 
-	const needsDocker = database === 'postgres' || database === 'mysql';
-	console.log('\nNext steps:');
-	console.log(`  cd ${nameOrPath}`);
-	console.log('  cp .env.example .env');
-	if (needsDocker) console.log('  docker-compose up -d');
-	if (!installDeps) console.log('  npm install');
-	console.log('  npm run dev');
+	printNextSteps({
+		nameOrPath,
+		database,
+		installDeps: Boolean(installDeps),
+		hasAppExtensions: appExtensions.length > 0,
+	});
 }
 
-main();
+if (isCliEntrypoint(import.meta.url, process.argv[1])) {
+	void main();
+}

src/generators/node/app.test.ts

@@ -58,6 +58,8 @@ describe('generateApp', () => {
 			appExtensions: ['custom-panel'],
 		});
 		expect(content).toContain("from './app-extensions/panel/index.js'");
+		expect(content).toContain("import { join } from 'node:path';");
+		expect(content).toContain("app.use('/extensions/assets', express.static(appExtensionAssetsPath));");
 		expect(content).toContain("app.use('/extensions/panel'");
 	});
 
@@ -80,5 +82,6 @@ describe('generateApp', () => {
 			appExtensions: [],
 		});
 		expect(content).not.toContain('./app-extensions');
+		expect(content).not.toContain('/extensions/assets');
 	});
 });

src/generators/node/app.ts

@@ -7,6 +7,7 @@ import { RouterMountBuilder } from '../../utils/templates.js';
 export async function generateApp(outputDir: string, options: GeneratorOptions): Promise<void> {
 	const hasPanel = options.appExtensions.includes('custom-panel');
 	const hasModal = options.appExtensions.includes('custom-modal');
+	const hasAppExtensions = hasPanel || hasModal;
 
 	const mounts = new RouterMountBuilder()
 		.add('/oauth', 'oauthRouter')
@@ -17,11 +18,17 @@ export async function generateApp(outputDir: string, options: GeneratorOptions):
 
 	const content = new SourceFileBuilder()
 		.importDefault('express', 'express')
+		.importIf(hasAppExtensions, 'node:path', ['join'])
 		.importDefault('./oauth/index.js', 'oauthRouter')
 		.importDefaultIf(options.webhooks, './webhooks/index.js', 'webhooksRouter')
 		.importDefaultIf(hasPanel, './app-extensions/panel/index.js', 'panelRouter')
 		.importDefaultIf(hasModal, './app-extensions/modal/index.js', 'modalRouter')
 		.addBlock('const app = express();')
+		.addBlockIf(
+			hasAppExtensions,
+			"const appExtensionAssetsPath = join(process.cwd(), 'frontend/app-extension-ui/dist/assets');",
+		)
+		.addBlockIf(hasAppExtensions, "app.use('/extensions/assets', express.static(appExtensionAssetsPath));")
 		.addBlock(mounts)
 		.exportDefault('app')
 		.build();