feat(fn-generator): port scripts/generate.ts into a typed library

Wave 2 of the portable-functions toolkit. Introduces the programmatic
generator that fn-client and fn-cli (next waves) will compose.

@constructive-io/fn-generator@0.1.0
- FnGenerator class with discover()/buildPackages()/buildManifest()/
  buildConfigMaps()/buildSkaffold()/apply()/generate() methods.
- Pure builder layer (returns Manifest[]) + a single apply() boundary
  that does idempotent file I/O via writeIfChanged() and ensureSymlink().
- Builders: per-function package files (templates + shared + handler
  symlinks), functions-manifest.json, per-function and aggregate
  functions-configmap.yaml, root skaffold.yaml.
- Honours --only and --packages-only modes (skip k8s/skaffold and
  per-function/aggregate configmaps respectively).
- Auto-assigns ports starting at 8081, validates 8080 is reserved
  for the job-service, detects port conflicts.

Verification: snapshot test runs FnGenerator against the brasilia
repo's own functions/+templates/ into a tmp dir and asserts byte-
identical output (file contents, symlink targets, skaffold.yaml) vs
scripts/generate.ts. All three assertions pass.

Also updates @constructive-io/fn-types FnRegistry to match the actual
on-disk format ({name, dir, port, type}) and adds optional moduleName
and url for the upcoming job-service rewrite (Wave 4).

scripts/generate.ts is unchanged in this PR — Wave 4 will collapse it
into a one-line shim that delegates to FnGenerator.

Author: Anmol1696

packages/fn-generator/README.md

@@ -0,0 +1,45 @@
+# @constructive-io/fn-generator
+
+Programmatic generator for the Constructive Functions toolkit. Given a `functions/<name>/handler.json` manifest and a set of templates, it produces:
+
+- A workspace package per function (Dockerfile, entry point, package.json with merged deps, tsconfig, k8s YAML).
+- Symlinks back to the source `handler.{ts,py}` and any auxiliary `.d.ts` / `.py` files.
+- A `functions-manifest.json` registry.
+- Per-function and aggregate `functions-configmap.yaml` (Knative job-service registry).
+- A root `skaffold.yaml` with one profile per function plus an aggregate `local-simple` profile.
+
+The library is **pure**: each builder returns a list of `Manifest` objects (`file` or `symlink`); `FnGenerator.apply()` is the only step that touches disk, and it does so idempotently (no rewrite if the on-disk content already matches).
+
+## Usage
+
+```ts
+import { FnGenerator } from '@constructive-io/fn-generator';
+
+const generator = new FnGenerator({
+  rootDir: process.cwd(),                       // default
+  functionsDir: 'functions',                    // default <root>/functions
+  outputDir: 'generated',                       // default <root>/generated
+  templatesDir: 'templates',                    // default <root>/templates
+  namespace: 'constructive-functions',          // default
+});
+
+// One-shot
+generator.generate();                           // all functions
+generator.generate({ only: 'simple-email' });   // single
+generator.generate({ packagesOnly: true });     // skip k8s/skaffold
+
+// Or assemble manifests yourself
+const fns = generator.discover();
+const manifests = [
+  ...generator.buildPackages(fns),
+  generator.buildManifest(fns),
+  ...generator.buildConfigMaps(fns),
+  generator.buildSkaffold(fns),
+];
+const result = generator.apply(manifests);
+console.log(result.filesWritten, result.symlinksCreated);
+```
+
+## Byte-identical output guarantee
+
+`FnGenerator` is a port of the legacy `scripts/generate.ts` and is verified by a snapshot regression test against that script's output. Any change that breaks byte-identicalness is a bug.

packages/fn-generator/__tests__/snapshot.test.ts

@@ -0,0 +1,91 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { FnGenerator } from '../src';
+
+/**
+ * Regression test: run FnGenerator against the brasilia repo's own
+ * `functions/` and `templates/`, output to a temp dir, and assert it
+ * is byte-identical to the brasilia repo's checked-in `generated/`
+ * (which is produced by the legacy `scripts/generate.ts`).
+ */
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const FUNCTIONS_DIR = path.join(ROOT, 'functions');
+const TEMPLATES_DIR = path.join(ROOT, 'templates');
+const BASELINE_GENERATED = path.join(ROOT, 'generated');
+const BASELINE_SKAFFOLD = path.join(ROOT, 'skaffold.yaml');
+
+const walk = (dir: string): { files: string[]; symlinks: string[] } => {
+  const files: string[] = [];
+  const symlinks: string[] = [];
+  const recurse = (current: string, base: string): void => {
+    const entries = fs.readdirSync(current);
+    for (const entry of entries) {
+      // Skip pnpm-installed dirs that aren't generator output.
+      if (entry === 'node_modules' || entry === 'dist') continue;
+      const full = path.join(current, entry);
+      const rel = base ? path.join(base, entry) : entry;
+      const stat = fs.lstatSync(full);
+      if (stat.isSymbolicLink()) {
+        symlinks.push(rel);
+      } else if (stat.isDirectory()) {
+        recurse(full, rel);
+      } else {
+        files.push(rel);
+      }
+    }
+  };
+  recurse(dir, '');
+  return { files, symlinks };
+};
+
+describe('FnGenerator snapshot vs scripts/generate.ts', () => {
+  let tmpDir: string;
+  let tmpRoot: string;
+
+  beforeAll(() => {
+    // The generator writes skaffold.yaml at the rootDir, so we mirror the
+    // brasilia layout into a tmp tree (functions/, templates/ symlinked to
+    // the real ones; outputDir in tmpDir; rootDir = tmpRoot).
+    tmpRoot = fs.mkdtempSync(path.join(require('os').tmpdir(), 'fn-gen-test-'));
+    tmpDir = path.join(tmpRoot, 'generated');
+
+    fs.symlinkSync(FUNCTIONS_DIR, path.join(tmpRoot, 'functions'));
+    fs.symlinkSync(TEMPLATES_DIR, path.join(tmpRoot, 'templates'));
+
+    const gen = new FnGenerator({ rootDir: tmpRoot });
+    gen.generate();
+  });
+
+  afterAll(() => {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it('produces the same files (byte-identical)', () => {
+    const baseline = walk(BASELINE_GENERATED);
+    const actual = walk(tmpDir);
+    expect([...actual.files].sort()).toEqual([...baseline.files].sort());
+    for (const rel of baseline.files) {
+      const a = fs.readFileSync(path.join(tmpDir, rel), 'utf-8');
+      const b = fs.readFileSync(path.join(BASELINE_GENERATED, rel), 'utf-8');
+      expect({ file: rel, content: a }).toEqual({ file: rel, content: b });
+    }
+  });
+
+  it('produces the same symlinks (same relative target)', () => {
+    const baseline = walk(BASELINE_GENERATED);
+    const actual = walk(tmpDir);
+    expect([...actual.symlinks].sort()).toEqual([...baseline.symlinks].sort());
+    for (const rel of baseline.symlinks) {
+      const a = fs.readlinkSync(path.join(tmpDir, rel));
+      const b = fs.readlinkSync(path.join(BASELINE_GENERATED, rel));
+      expect({ symlink: rel, target: a }).toEqual({ symlink: rel, target: b });
+    }
+  });
+
+  it('produces an identical skaffold.yaml', () => {
+    const a = fs.readFileSync(path.join(tmpRoot, 'skaffold.yaml'), 'utf-8');
+    const b = fs.readFileSync(BASELINE_SKAFFOLD, 'utf-8');
+    expect(a).toBe(b);
+  });
+});

packages/fn-generator/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  collectCoverageFrom: ['src/**/*.ts'],
+};

packages/fn-generator/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@constructive-io/fn-generator",
+  "version": "0.1.0",
+  "description": "Programmatic generator for Constructive Functions: walks handler.json manifests and stamps out Dockerfiles, k8s YAML, configmaps, and Skaffold profiles. Pure functions; file I/O at the boundary.",
+  "author": "Constructive <developers@constructive.io>",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf dist",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@constructive-io/fn-types": "workspace:^"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.4",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.1.6"
+  }
+}

packages/fn-generator/src/builders/configmap.ts

@@ -0,0 +1,40 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { renderTemplate } from '../placeholders';
+import type { FunctionInfo, Manifest } from '../types';
+
+/**
+ * Build a `functions-configmap.yaml` for either a single function (when
+ * `target` is supplied) or the aggregate of all functions.
+ *
+ *   - per-function output: `<outputDir>/<target.dir>/k8s/functions-configmap.yaml`
+ *   - aggregate output:    `<outputDir>/functions-configmap.yaml`
+ */
+export const buildConfigMap = (args: {
+  fns: FunctionInfo[];
+  target?: FunctionInfo;
+  outputDir: string;
+  templatesDir: string;
+  namespace: string;
+}): Manifest => {
+  const targetFns = args.target ? [args.target] : args.fns;
+  const gatewayMap: Record<string, string> = {};
+  for (const fn of targetFns) {
+    gatewayMap[fn.name] = `http://${fn.name}.${args.namespace}.svc.cluster.local`;
+  }
+
+  const template = fs.readFileSync(
+    path.join(args.templatesDir, 'k8s', 'functions-configmap.yaml'),
+    'utf-8'
+  );
+  const yaml = renderTemplate(template, {
+    jobs_supported: targetFns.map((fn) => fn.name).join(','),
+    gateway_map: JSON.stringify(gatewayMap),
+  });
+
+  const outPath = args.target
+    ? path.join(args.outputDir, args.target.dir, 'k8s', 'functions-configmap.yaml')
+    : path.join(args.outputDir, 'functions-configmap.yaml');
+
+  return { kind: 'file', path: outPath, content: yaml };
+};

packages/fn-generator/src/builders/manifest.ts

@@ -0,0 +1,25 @@
+import * as path from 'path';
+import type { FunctionInfo, Manifest } from '../types';
+
+/**
+ * Build the `generated/functions-manifest.json` manifest. Field order is
+ * fixed (`name`, `dir`, `port`, `type`) to keep output byte-identical.
+ */
+export const buildManifestJson = (
+  fns: FunctionInfo[],
+  outputDir: string
+): Manifest => {
+  const data = {
+    functions: fns.map((fn) => ({
+      name: fn.name,
+      dir: fn.dir,
+      port: fn.port,
+      type: fn.type,
+    })),
+  };
+  return {
+    kind: 'file',
+    path: path.join(outputDir, 'functions-manifest.json'),
+    content: JSON.stringify(data, null, 2) + '\n',
+  };
+};

packages/fn-generator/src/builders/package.ts

@@ -0,0 +1,72 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { walkTemplateFiles } from '../fs-utils';
+import { processTemplateFile } from '../placeholders';
+import type { FunctionInfo, Manifest } from '../types';
+
+/**
+ * Build all manifests for a single function:
+ *   - per-template files (placeholders applied, package.json/tsconfig.json processed)
+ *   - shared template files (same processing)
+ *   - symlinks for handler.{ts,py}, *.d.ts, and any other *.py
+ *
+ * `templateDir` is the resolved type-specific dir (`templates/node-graphql/` etc.).
+ */
+export const buildPackageManifests = (
+  fn: FunctionInfo,
+  args: {
+    fnDir: string;          // absolute: <functionsDir>/<dir>
+    genDir: string;         // absolute: <outputDir>/<dir>
+    templateDir: string;    // absolute: <templatesDir>/<type>
+    sharedDir?: string;     // absolute: <templatesDir>/shared (if present)
+  }
+): Manifest[] => {
+  const out: Manifest[] = [];
+
+  // 1. Per-template files
+  const templateFiles = walkTemplateFiles(args.templateDir);
+  for (const relPath of templateFiles) {
+    const templateFile = path.join(args.templateDir, relPath);
+    const outputFile = path.join(args.genDir, relPath);
+    const templateContent = fs.readFileSync(templateFile, 'utf-8');
+    const baseName = path.basename(relPath);
+    const processed = processTemplateFile(baseName, templateContent, fn.manifest, args.fnDir);
+    out.push({ kind: 'file', path: outputFile, content: processed });
+  }
+
+  // 2. Shared template files
+  if (args.sharedDir && fs.existsSync(args.sharedDir)) {
+    const sharedFiles = walkTemplateFiles(args.sharedDir);
+    for (const relPath of sharedFiles) {
+      const templateFile = path.join(args.sharedDir, relPath);
+      const outputFile = path.join(args.genDir, relPath);
+      const templateContent = fs.readFileSync(templateFile, 'utf-8');
+      const baseName = path.basename(relPath);
+      const processed = processTemplateFile(baseName, templateContent, fn.manifest, args.fnDir);
+      out.push({ kind: 'file', path: outputFile, content: processed });
+    }
+  }
+
+  // 3. Handler symlink (handler.ts wins; handler.py only if no handler.ts)
+  const handlerTs = path.join(args.fnDir, 'handler.ts');
+  const handlerPy = path.join(args.fnDir, 'handler.py');
+  if (fs.existsSync(handlerTs)) {
+    out.push({ kind: 'symlink', path: path.join(args.genDir, 'handler.ts'), target: handlerTs });
+  } else if (fs.existsSync(handlerPy)) {
+    out.push({ kind: 'symlink', path: path.join(args.genDir, 'handler.py'), target: handlerPy });
+  }
+
+  // 4. Auxiliary symlinks: all *.d.ts and *.py (except handler.py already linked above)
+  const files = fs.readdirSync(args.fnDir);
+  for (const file of files) {
+    if (file.endsWith('.d.ts') || (file.endsWith('.py') && file !== 'handler.py')) {
+      out.push({
+        kind: 'symlink',
+        path: path.join(args.genDir, file),
+        target: path.join(args.fnDir, file),
+      });
+    }
+  }
+
+  return out;
+};

packages/fn-generator/src/builders/skaffold.ts

@@ -0,0 +1,71 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { renderTemplate } from '../placeholders';
+import type { FunctionInfo, Manifest } from '../types';
+
+const PYTHON_ARTIFACTS = `        - image: constructive-functions-python
+          context: .
+          docker:
+            dockerfile: Dockerfile.python.dev
+          sync:
+            manual:
+              - src: 'functions/**/*.py'
+                dest: /usr/src/app
+              - src: 'generated/**/*.py'
+                dest: /usr/src/app`;
+
+/**
+ * Build the root `skaffold.yaml` from `templates/k8s/skaffold.yaml`,
+ * including per-function profiles, an aggregate raw-yaml list, port
+ * forwards, and the Python build artifact (only if any function is python).
+ */
+export const buildSkaffold = (args: {
+  fns: FunctionInfo[];
+  rootDir: string;
+  templatesDir: string;
+  namespace: string;
+}): Manifest => {
+  const k8s = path.join(args.templatesDir, 'k8s');
+  const nodeProfile = fs.readFileSync(path.join(k8s, 'skaffold-profile.yaml'), 'utf-8');
+  const pythonProfile = fs.readFileSync(path.join(k8s, 'skaffold-profile-python.yaml'), 'utf-8');
+  const main = fs.readFileSync(path.join(k8s, 'skaffold.yaml'), 'utf-8');
+
+  const perFnProfiles = args.fns
+    .map((fn) =>
+      renderTemplate(fn.type === 'python' ? pythonProfile : nodeProfile, {
+        name: fn.name,
+        dir: fn.dir,
+        port: String(fn.port),
+        namespace: args.namespace,
+      }).trimEnd()
+    )
+    .join('\n');
+
+  const allRawYaml = args.fns
+    .map((fn) => `        - generated/${fn.dir}/k8s/local-deployment.yaml`)
+    .join('\n');
+
+  const allPortForwards = args.fns
+    .map((fn) =>
+      [
+        '      - resourceType: service',
+        `        resourceName: ${fn.name}`,
+        `        namespace: ${args.namespace}`,
+        '        port: 80',
+        `        localPort: ${fn.port}`,
+      ].join('\n')
+    )
+    .join('\n');
+
+  const pythonArtifacts = args.fns.some((fn) => fn.type === 'python') ? PYTHON_ARTIFACTS : '';
+
+  const skaffold = renderTemplate(main, {
+    per_function_profiles: perFnProfiles,
+    all_raw_yaml: allRawYaml,
+    all_port_forwards: allPortForwards,
+    python_artifacts: pythonArtifacts,
+    namespace: args.namespace,
+  });
+
+  return { kind: 'file', path: path.join(args.rootDir, 'skaffold.yaml'), content: skaffold };
+};