initial setup for templatized functions

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,103 @@
 
 This guide helps AI agents quickly navigate the constructive-functions workspace.
 
-## Quick Start
-
-**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
-
-**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/*`
+## Architecture
 
-## Monorepo Layout
-
-- `functions/*` — Function packages (`send-email-link`, `simple-email`)
-- `k8s/` — Kubernetes manifests, overlays, and setup scripts
-- `types/` — Custom type definitions for `@launchql/*` packages
+See [docs/spec/function-templating.md](docs/spec/function-templating.md) for the full specification.
 
-## Function Architecture
+Functions use a **templating system**: developers write `handler.ts` + `handler.json` in `functions/`, and `scripts/generate.ts` produces workspace packages in `generated/` with all boilerplate.
 
-**Image naming:**
+## Quick Start
 
-All Docker images use the registry prefix `ghcr.io/constructive-io/constructive-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
+```
 
-- `ghcr.io/constructive-io/constructive-functions/simple-email:latest`
-- `ghcr.io/constructive-io/constructive-functions/send-email-link:latest`
+## Monorepo Layout
 
-The `REGISTRY` variable in the Makefile controls this prefix.
+```
+functions/              # User-authored source (git tracked)
+  <name>/
+    handler.ts          # Business logic (default export)
+    handler.json        # Metadata + dependencies
+    *.d.ts              # Optional type declarations
+
+generated/              # Generated workspace packages (gitignored)
+  <name>/
+    package.json        # Workspace package
+    tsconfig.json       # Compiler config
+    index.ts            # Entry point
+    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           # Generator script (runs via Node's native type stripping)
+
+k8s/                    # Kubernetes manifests and overlays
+```
 
-Both functions follow the same pattern:
+## Function Pattern
 
-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`
+Each function exports a `FunctionHandler` that receives params and a context:
 
-## Common Workflows
+```typescript
+import type { FunctionHandler } from '@constructive-io/fn-runtime';
 
-**Build all functions locally:**
+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 };
+};
 
-```bash
-pnpm install
-pnpm build
+export default handler;
 ```
 
-**Build Docker images:**
+## Entry Points
 
-```bash
-make docker-build                    # Build all functions
-make docker-build-simple-email         # Build one function
-make docker-build-send-email-link
-```
+- 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`
+
+## Common Workflows
 
-**Deploy to Kubernetes (local):**
+**Add a new function:**
+1. Create `functions/<name>/handler.json` with name, version, 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
 
+**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     # Regenerates package.json, tsconfig, index.ts, symlinks
+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

Dockerfile.dev

@@ -0,0 +1,28 @@
+FROM node:22-alpine
+
+RUN npm install -g pnpm@10.12.2
+
+WORKDIR /usr/src/app
+
+# Copy config files and generate script
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml tsconfig.json ./
+COPY scripts/ scripts/
+
+# 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
 
 build:
 	pnpm run build
@@ -11,32 +9,14 @@ clean:
 lint:
 	pnpm run lint
 
-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
+generate:
+	pnpm run generate
 
-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
+dev-build:
+	docker compose build
 
-docker-push-simple-email:
-	docker push $(REGISTRY)/simple-email:latest
+dev:
+	docker compose up
 
-docker-push-send-email-link:
-	docker push $(REGISTRY)/send-email-link:latest
+dev-down:
+	docker compose down

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: