Merge pull request #13 from constructive-io/anmol/templates

feature: templates

Author: Anmol1696

.gitignore

@@ -137,3 +137,6 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+# Generated function workspace packages (created by scripts/generate.ts)
+generated/

AGENTS.md

@@ -2,95 +2,137 @@
 
 This guide helps AI agents quickly navigate the constructive-functions workspace.
 
-## Quick Start
+## Architecture
+
+See [docs/spec/function-templating.md](docs/spec/function-templating.md) for the full specification.
+
+Functions use a **template-based system**: developers write `handler.ts` + `handler.json` in `functions/`, and `scripts/generate.ts` copies template files from `templates/<type>/` into `generated/` with placeholder replacement and dependency merging.
 
-**Most important commands:**
-- `pnpm build` — Build all function packages (TypeScript → `dist/`)
-- `make docker-build` — Build Docker images for all functions
-- `make docker-build-simple-email` — Build just the simple-email image
-- `make docker-build-send-email-link` — Build just the send-email-link image
-- `cd k8s && make kustomize-local` — Deploy functions to a local Kubernetes cluster
+## Quick Start
 
-**Entry points:**
-- Function HTTP handlers: `functions/*/src/index.ts`
-- Docker entrypoints: `functions/*/Dockerfile` (`CMD ["node", "dist/index.js"]`)
-- K8s manifests: `k8s/base/functions/*` and `k8s/overlays/local/functions/*`
+```bash
+pnpm generate     # Generate generated/<name>/ from functions/*/handler.json
+pnpm install      # Install deps (preinstall runs generate.ts automatically)
+pnpm build        # Build all packages + functions
+```
 
 ## Monorepo Layout
 
-- `functions/*` — Function packages (`send-email-link`, `simple-email`)
-- `k8s/` — Kubernetes manifests, overlays, and setup scripts
-- `types/` — Custom type definitions for `@launchql/*` packages
+```
+functions/              # User-authored source (git tracked)
+  <name>/
+    handler.ts          # Business logic (default export)
+    handler.json        # Metadata + dependencies + template type
+    *.d.ts              # Optional type declarations
+
+templates/              # Template definitions (git tracked)
+  node-graphql/         # Default template type
+    package.json        # Base package.json with {{placeholders}}
+    tsconfig.json       # Static compiler config
+    index.ts            # Entry point template with {{name}}
+    Dockerfile          # Per-function production Docker build
+    k8s/
+      knative-service.yaml  # Base Knative Service manifest
+
+generated/              # Generated workspace packages (gitignored)
+  <name>/
+    package.json        # Merged from template + handler.json deps
+    tsconfig.json       # Copied from template (+ .d.ts includes)
+    index.ts            # Copied from template with {{name}} replaced
+    handler.ts          # Symlink -> functions/<name>/handler.ts
+    dist/               # Compiled output
+
+packages/
+  fn-app/               # Express app factory with job callbacks
+  fn-runtime/           # Runtime: createFunctionServer, GraphQL clients, context
+
+job/
+  server/               # Callback receiver
+  worker/               # Job dispatcher
+  service/              # Orchestrator (loads functions + worker + scheduler)
+
+scripts/
+  generate.ts           # Template-based generator (copies + merges + replaces)
+  docker-build.ts       # Per-function Docker image builder
+```
 
-## Function Architecture
+## Function Pattern
 
-**Image naming:**
+Each function exports a `FunctionHandler` that receives params and a context:
 
-All Docker images use the registry prefix `ghcr.io/constructive-io/constructive-functions/`:
+```typescript
+import type { FunctionHandler } from '@constructive-io/fn-runtime';
 
-- `ghcr.io/constructive-io/constructive-functions/simple-email:latest`
-- `ghcr.io/constructive-io/constructive-functions/send-email-link:latest`
+const handler: FunctionHandler = async (params, context) => {
+  const { client, meta, log, env, job } = context;
+  // client/meta: GraphQL clients (tenant-scoped, created per-request)
+  // log: structured logger
+  // env: process.env
+  // job: { jobId, workerId, databaseId }
+  return { complete: true };
+};
 
-The `REGISTRY` variable in the Makefile controls this prefix.
+export default handler;
+```
 
-Both functions follow the same pattern:
+## handler.json Schema
+
+```json
+{
+  "name": "send-email-link",
+  "version": "1.1.0",
+  "description": "Sends invite, password reset, and verification emails",
+  "type": "node-graphql",
+  "dependencies": {
+    "graphql-tag": "^2.12.6"
+  }
+}
+```
 
-1. **Source** (`src/index.ts`):
-   - Import `app` from `@constructive-io/knative-job-fn` (Express app)
-   - Define HTTP handler with `app.post('/', ...)`
-   - Export `app` and start server if `require.main === module`
-2. **Build** (`package.json` → `tsc`):
-   - TypeScript compiles to `dist/index.js`
-3. **Docker** (`Dockerfile`):
-   - Uses `node:22-alpine`
-   - Installs production deps via `pnpm`
-   - Copies `dist/` and runs `node dist/index.js`
+- `type` selects the template from `templates/<type>/` (default: `"node-graphql"`)
+- `dependencies` are merged into the template's base package.json
 
-## Common Workflows
+## Entry Points
 
-**Build all functions locally:**
+- Function handlers: `functions/*/handler.ts`
+- Generated entry points: `generated/*/index.ts` (compiled to `generated/*/dist/index.js`)
+- Job orchestrator: `job/service/src/index.ts`
+- Generator script: `scripts/generate.ts`
+- Docker builder: `scripts/docker-build.ts`
 
-```bash
-pnpm install
-pnpm build
-```
+## Common Workflows
 
-**Build Docker images:**
+**Add a new function:**
+1. Create `functions/<name>/handler.json` with name, version, type, dependencies
+2. Create `functions/<name>/handler.ts` with default export
+3. Run `pnpm generate && pnpm install && pnpm build`
+4. Add to function registry in `job/service/src/index.ts` if needed
 
+**Build Docker images:**
 ```bash
-make docker-build                    # Build all functions
-make docker-build-simple-email         # Build one function
-make docker-build-send-email-link
+make docker-build                    # build all function images
+make docker-build-send-email-link    # build single function image
 ```
 
-**Deploy to Kubernetes (local):**
-
+**Local development with Docker:**
 ```bash
-cd k8s
-make operators-knative-only   # Install Knative
-make kustomize-local          # Apply manifests
-make proxy-server            # Forward API to localhost:8080
+make dev          # docker compose up (postgres + job-service)
+make dev-down     # docker compose down
 ```
 
-**Run locally with Docker (manual):**
-
+**Regenerate after changing handler.json:**
 ```bash
-docker run -p 8080:8080 -e SIMPLE_EMAIL_DRY_RUN=true ghcr.io/constructive-io/constructive-functions/simple-email:latest
+pnpm generate     # Copies templates, merges deps, replaces placeholders
+pnpm install      # Picks up any new dependencies
+pnpm build        # Recompile
 ```
 
-## Type Definitions
-
-The `types/` directory contains manual type definitions for packages without built-in types:
-
-- `@launchql/mjml` — Styled-email generator (MJML-based email templates)
-- `@launchql/postmaster` — Mailgun email sender
-- `@launchql/styled-email` — Email template components
-
-These are referenced in `tsconfig.json` via `"typeRoots": ["./types", "./node_modules/@types"]`.
-
-## Tips
+## Key Details
 
-1. Build functions before building Docker images — `dist/` must exist
-2. Functions run on `PORT=8080` (Knative default)
-3. Email functions support dry-run mode via env vars (`SIMPLE_EMAIL_DRY_RUN`, `SEND_EMAIL_LINK_DRY_RUN`)
-4. K8s manifests reference Docker images; update image tags after pushing to registry
+- Functions run on `PORT=8080` (Knative default)
+- Email functions support dry-run via `SIMPLE_EMAIL_DRY_RUN` / `SEND_EMAIL_LINK_DRY_RUN`
+- `loadFunctionApp()` in job/service resolves modules by name (e.g. `@constructive-io/simple-email-fn`)
+- GraphQL clients require `GRAPHQL_URL` env var and `X-Database-Id` header
+- The `generated/` directory is entirely gitignored
+- Templates use `{{name}}`, `{{version}}`, `{{description}}` placeholders
+- Generator supports `--only=<name>` for single-function generation

Dockerfile.dev

@@ -0,0 +1,29 @@
+FROM node:22-alpine
+
+RUN npm install -g pnpm@10.12.2
+
+WORKDIR /usr/src/app
+
+# Copy config files, generate script, and templates
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig.json ./
+COPY scripts/ scripts/
+COPY templates/ templates/
+
+# Copy all package/job manifests for caching
+COPY packages/fn-app/package.json packages/fn-app/
+COPY packages/fn-runtime/package.json packages/fn-runtime/
+COPY job/server/package.json job/server/
+COPY job/worker/package.json job/worker/
+COPY job/service/package.json job/service/
+
+# Copy function handler.json manifests
+COPY functions/ functions/
+
+# Generate workspace packages + install deps
+RUN node --experimental-strip-types scripts/generate.ts && pnpm install --frozen-lockfile
+
+# Copy source and build
+COPY . .
+RUN pnpm generate && pnpm build
+
+ENV NODE_ENV=production

Makefile

@@ -1,6 +1,4 @@
-.PHONY: build clean lint docker-build docker-build-simple-email docker-build-send-email-link docker-push docker-push-simple-email docker-push-send-email-link
-
-REGISTRY := ghcr.io/constructive-io/constructive-functions
+.PHONY: build clean lint generate dev dev-build dev-down docker-build
 
 build:
 	pnpm run build
@@ -11,32 +9,21 @@ clean:
 lint:
 	pnpm run lint
 
+generate:
+	pnpm run generate
+
+dev-build:
+	docker compose build
+
+dev:
+	docker compose up
+
+dev-down:
+	docker compose down
+
 docker-build:
-	@echo "Building Docker images for functions..."
-	@for fn in functions/*; do \
-		if [ -f "$$fn/Dockerfile" ]; then \
-			echo "Building $$fn..."; \
-			docker build -t "$(REGISTRY)/$$(basename $$fn):latest" "$$fn"; \
-		fi \
-	done
-
-docker-build-simple-email:
-	docker build -t $(REGISTRY)/simple-email:latest functions/simple-email
-
-docker-build-send-email-link:
-	docker build -t $(REGISTRY)/send-email-link:latest functions/send-email-link
-
-docker-push:
-	@echo "Pushing Docker images to $(REGISTRY)..."
-	@for fn in functions/*; do \
-		if [ -f "$$fn/Dockerfile" ]; then \
-			echo "Pushing $$fn..."; \
-			docker push "$(REGISTRY)/$$(basename $$fn):latest"; \
-		fi \
-	done
-
-docker-push-simple-email:
-	docker push $(REGISTRY)/simple-email:latest
-
-docker-push-send-email-link:
-	docker push $(REGISTRY)/send-email-link:latest
+	pnpm run docker:build
+
+# Build a single function image: make docker-build-send-email-link
+docker-build-%:
+	node --experimental-strip-types scripts/docker-build.ts --only=$*

docker-compose.yml

@@ -0,0 +1,33 @@
+services:
+  postgres:
+    image: ghcr.io/launchql/pgvector-postgis:16.10
+    environment:
+      POSTGRES_DB: launchql
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+  job-service:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    command: node job/service/dist/run.js
+    environment:
+      PGHOST: postgres
+      PGUSER: postgres
+      PGPASSWORD: password
+      PGDATABASE: launchql
+      CONSTRUCTIVE_FUNCTIONS: all
+      CONSTRUCTIVE_JOBS_ENABLED: "true"
+    depends_on:
+      - postgres
+    ports:
+      - "8080:8080"
+      - "8081:8081"
+      - "8082:8082"
+
+volumes:
+  pgdata: