feat(fn-client,fn-cli): programmatic API + thin CLI wrapper

Wave 3 of the portable-functions toolkit. Composes fn-generator into a
user-facing layer; closes the loop on the Starship-style split:
fn-types → fn-generator → fn-client → fn-cli.

@constructive-io/fn-client@0.1.0
- FnClient class wraps FnGenerator and adds:
  - JSON config loading (fn.config.json or .fnconfig.json) — .ts/.js
    loading deferred until we add an esbuild/jiti loader.
  - loadManifest() — reads generated/functions-manifest.json.
  - defaultProcessDefs() — derives DevProcessDef[] from the manifest.
  - build({ only? }) — runs `pnpm -r build` with optional filter.
  - dev({ only?, env?, jobService? }) — spawns Node child processes,
    returns a DevHandle with pids and a SIGTERM-based stop().
- Job-service is opt-in (jobs-bundle preset is wired by passing
  `dev({ jobService: ... })`); functions-only consumers omit it.
- Smoke tests cover discover/generate/manifest round-trip and
  defaultProcessDefs derivation.

@constructive-io/fn-cli@0.1.0
- bin/fn executable (chmod +x in build) using minimist for argparse.
- Subcommands: generate (--only, --packages-only), build, dev,
  manifest, verify, help.
- Each command is ~10 lines: parse → FnClient method → format output.
- Verified end-to-end against the brasilia repo:
    fn generate    ⇒ idempotent (0 file changes on rerun)
    fn manifest    ⇒ prints functions-manifest.json
    fn verify      ⇒ "OK: 4 function(s) in sync."

The brasilia scripts/generate.ts, scripts/dev.ts, scripts/docker-build.ts
remain in place; Wave 4 will collapse them into one-line shims.

Author: Anmol1696

packages/fn-cli/README.md

@@ -0,0 +1,25 @@
+# @constructive-io/fn-cli
+
+Thin command-line wrapper around `@constructive-io/fn-client`. Exposes the `fn` executable.
+
+## Install
+
+```bash
+pnpm add -D @constructive-io/fn-cli
+pnpm add @constructive-io/fn-runtime  # for handlers
+```
+
+## Commands
+
+```bash
+fn generate [--only=<name>] [--packages-only]
+fn build [--only=<name>]
+fn dev [--only=<name>]
+fn manifest
+fn verify
+fn help
+```
+
+Common flags: `--root=<dir>`, `--config=<file>`.
+
+This wave (Wave 3) ships `generate`, `build`, `dev`, `manifest`, and `verify`. `init`, `dockerfile`, and `k8s` (standalone manifest emission) land in Waves 4–5.

packages/fn-cli/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@constructive-io/fn-cli",
+  "version": "0.1.0",
+  "description": "Thin command-line wrapper for the Constructive Functions toolkit. Exposes the `fn` executable.",
+  "author": "Constructive <developers@constructive.io>",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "fn": "dist/bin/fn.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/bin/fn.js",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@constructive-io/fn-client": "workspace:^",
+    "minimist": "^1.2.8"
+  },
+  "devDependencies": {
+    "@types/minimist": "^1.2.5",
+    "@types/node": "^22.10.4",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.1.6"
+  }
+}

packages/fn-cli/src/bin/fn.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { run } from '../cli';
+
+run().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`fn: ${err?.message ?? err}\n`);
+    process.exit(1);
+  }
+);

packages/fn-cli/src/cli.ts

@@ -0,0 +1,49 @@
+import minimist from 'minimist';
+import { commands, type CommandFn } from './commands';
+
+const HELP = `Usage: fn <command> [options]
+
+Commands:
+  generate     Generate workspace packages, k8s YAML, configmaps, skaffold.yaml
+               Flags: --only=<name>  --packages-only
+  build        Run \`pnpm -r build\` (optionally filtered)
+               Flags: --only=<name>
+  dev          Start functions as local Node processes
+               Flags: --only=<name>
+  manifest     Print the on-disk functions-manifest.json
+  verify       Sanity-check generated/ vs functions/ (no writes)
+  help         Print this message
+
+Common flags:
+  --root=<dir>   Repo root (default: cwd)
+  --config=<f>   Path to fn.config.json (default: <root>/fn.config.json)
+`;
+
+export const run = async (argv: string[] = process.argv.slice(2)): Promise<number> => {
+  const parsed = minimist(argv, {
+    string: ['only', 'config', 'root'],
+    boolean: ['packages-only', 'help', 'version'],
+    alias: { h: 'help', v: 'version' },
+  });
+
+  const [name] = parsed._;
+
+  if (parsed.help || name === 'help' || (!name && argv.length === 0)) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  if (parsed.version) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const pkg = require('../package.json');
+    process.stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+
+  const cmd: CommandFn | undefined = commands[name];
+  if (!cmd) {
+    process.stderr.write(`Unknown command: ${name}\n\n${HELP}`);
+    return 1;
+  }
+  return cmd(parsed);
+};

packages/fn-cli/src/commands.ts

@@ -0,0 +1,83 @@
+import { FnClient } from '@constructive-io/fn-client';
+import type { ParsedArgs } from 'minimist';
+
+export type CommandFn = (args: ParsedArgs) => number | Promise<number>;
+
+const buildClient = (args: ParsedArgs): FnClient =>
+  new FnClient({
+    rootDir: typeof args.root === 'string' ? args.root : undefined,
+    config: typeof args.config === 'string' ? args.config : undefined,
+  });
+
+const cmdGenerate: CommandFn = (args) => {
+  const client = buildClient(args);
+  const result = client.generate({
+    only: typeof args.only === 'string' ? args.only : undefined,
+    packagesOnly: Boolean(args['packages-only']),
+  });
+  process.stdout.write(
+    `Generated ${result.functions.length} function(s); wrote ${result.filesWritten.length} file(s), ${result.symlinksCreated.length} symlink(s).\n`
+  );
+  for (const f of result.filesWritten) process.stdout.write(`  + ${f}\n`);
+  for (const s of result.symlinksCreated) process.stdout.write(`  ~ ${s}\n`);
+  return 0;
+};
+
+const cmdBuild: CommandFn = async (args) => {
+  const client = buildClient(args);
+  await client.build({ only: typeof args.only === 'string' ? args.only : undefined });
+  return 0;
+};
+
+const cmdDev: CommandFn = (args) => {
+  const client = buildClient(args);
+  const handle = client.dev({ only: typeof args.only === 'string' ? args.only : undefined });
+  const stop = (): void => {
+    handle.stop().finally(() => process.exit(0));
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+  process.stdout.write(`Started: ${Object.keys(handle.pids).join(', ')}\n`);
+  // Hold the event loop until a signal arrives.
+  return new Promise<number>(() => {});
+};
+
+const cmdManifest: CommandFn = (args) => {
+  const client = buildClient(args);
+  const m = client.loadManifest();
+  if (!m) {
+    process.stderr.write('functions-manifest.json not found. Run `fn generate` first.\n');
+    return 1;
+  }
+  process.stdout.write(JSON.stringify(m, null, 2) + '\n');
+  return 0;
+};
+
+const cmdVerify: CommandFn = (args) => {
+  const client = buildClient(args);
+  const fns = client.discover();
+  const manifest = client.loadManifest();
+  if (!manifest) {
+    process.stderr.write('functions-manifest.json not found. Run `fn generate` first.\n');
+    return 1;
+  }
+  const expected = new Set(fns.map((f) => f.name));
+  const actual = new Set(manifest.functions.map((f) => f.name));
+  const missing = [...expected].filter((n) => !actual.has(n));
+  const extra = [...actual].filter((n) => !expected.has(n));
+  if (missing.length === 0 && extra.length === 0) {
+    process.stdout.write(`OK: ${fns.length} function(s) in sync.\n`);
+    return 0;
+  }
+  if (missing.length) process.stderr.write(`Missing in manifest: ${missing.join(', ')}\n`);
+  if (extra.length) process.stderr.write(`Stale in manifest: ${extra.join(', ')}\n`);
+  return 2;
+};
+
+export const commands: Record<string, CommandFn> = {
+  generate: cmdGenerate,
+  build: cmdBuild,
+  dev: cmdDev,
+  manifest: cmdManifest,
+  verify: cmdVerify,
+};

packages/fn-cli/src/index.ts

@@ -0,0 +1,2 @@
+export { run } from './cli';
+export { commands } from './commands';

packages/fn-cli/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}

packages/fn-client/README.md

@@ -0,0 +1,39 @@
+# @constructive-io/fn-client
+
+Programmatic client for the Constructive Functions toolkit. Composes `@constructive-io/fn-generator` with config loading, manifest readers, and child-process orchestration so a host repo (or a thin CLI) can drive the whole pipeline from one object.
+
+## Usage
+
+```ts
+import { FnClient } from '@constructive-io/fn-client';
+
+const client = new FnClient({
+  rootDir: process.cwd(),         // default
+  config: { functionsDir: 'functions', outputDir: 'generated' },
+});
+
+// 1. Generate workspace packages, k8s manifests, configmaps, skaffold.yaml.
+client.generate();
+
+// 2. Build the generated packages (runs `pnpm -r build`).
+await client.build();
+
+// 3. Start functions as local Node processes; stop them when done.
+const dev = client.dev({
+  env: { GRAPHQL_URL: 'http://localhost:3002/graphql' },
+});
+
+await new Promise((r) => process.once('SIGINT', r));
+await dev.stop();
+```
+
+## Surface
+
+- `discover(only?)` — list discovered functions with resolved port/type.
+- `generate(opts?)` — run the full generator pipeline (delegates to `FnGenerator`).
+- `loadManifest()` — read the on-disk `functions-manifest.json`.
+- `defaultProcessDefs()` — derive `DevProcessDef[]` from the manifest (one per function, pointing at `<outputDir>/<dir>/dist/index.js`).
+- `build(opts?)` — `pnpm -r build`, optionally filtered.
+- `dev(opts?)` — spawn process defs as `node` children, return a `DevHandle` with `pids` and `stop()`.
+
+The job-service is optional: pass `dev({ jobService: { name, script, port, env } })` to start it alongside the functions; omit to run functions only.

packages/fn-client/__tests__/client.test.ts

@@ -0,0 +1,51 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { FnClient } from '../src';
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+
+describe('FnClient', () => {
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'fn-client-test-'));
+    fs.symlinkSync(path.join(ROOT, 'functions'), path.join(tmpRoot, 'functions'));
+    fs.symlinkSync(path.join(ROOT, 'templates'), path.join(tmpRoot, 'templates'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it('discovers functions in fs.readdirSync order', () => {
+    const client = new FnClient({ rootDir: tmpRoot });
+    const fns = client.discover();
+    const names = fns.map((f) => f.name);
+    expect(names).toContain('simple-email');
+    expect(names).toContain('send-email-link');
+    expect(fns.every((f) => f.port > 0 && f.port !== 8080)).toBe(true);
+  });
+
+  it('generate() writes a manifest that loadManifest() can read', () => {
+    const client = new FnClient({ rootDir: tmpRoot });
+    const result = client.generate();
+    expect(result.functions.length).toBeGreaterThan(0);
+    const m = client.loadManifest();
+    expect(m).not.toBeNull();
+    expect(m!.functions.map((f) => f.name).sort()).toEqual(
+      result.functions.map((f) => f.name).sort()
+    );
+  });
+
+  it('defaultProcessDefs() builds one entry per function pointing at dist/index.js', () => {
+    const client = new FnClient({ rootDir: tmpRoot });
+    client.generate();
+    const defs = client.defaultProcessDefs();
+    expect(defs.length).toBe(client.discover().length);
+    for (const def of defs) {
+      expect(def.script).toMatch(/dist\/index\.js$/);
+      expect(typeof def.port).toBe('number');
+    }
+  });
+});

packages/fn-client/jest.config.js

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