feat(fn-cli): add fn init subcommand using genomic Templatizer

Wave 6 of the portable-functions toolkit. Adds the user-facing way
to scaffold a new handler — bundled templates + minimal glue.

@constructive-io/fn-cli@0.1.0:
- New runtime dep on genomic@^5.3.11 (same engine pgpm init uses).
- Bundled templates at packages/fn-cli/templates/handler/:
  - node-graphql/ (.boilerplate.json, handler.json, handler.ts)
  - python/ (.boilerplate.json, handler.json, handler.py)
- New `fn init <name>` subcommand:
  - Positional name OR --name flag
  - --type=node-graphql|python (default: node-graphql)
  - --description=<d> (optional)
  - --force overwrites existing dir
  - --no-tty / CI=true detection (matches pgpm init's pattern)
  - Refuses to overwrite without --force; clean error
  - Honors functionsDir from fn.config.json
- Tarball includes templates/ via files: ["dist", "templates", "README.md"]
  so the bundled handler templates ship with the published package.
- Help text and README updated.

Tests: packages/fn-cli/__tests__/init.test.ts — 7 unit cases covering
node-graphql + python scaffolding, dir-exists guard, --force,
unknown-type rejection, missing-name error, and custom functionsDir
from fn.config.json. All pass.

Verified end-to-end against /tmp:
  $ fn init hello --no-tty                       → functions/hello/{handler.json,ts}
  $ fn init pyfn --type python --no-tty          → functions/pyfn/{handler.json,py}
  $ fn init hello --no-tty                       → refuses (exit 1)
  $ fn init hello --no-tty --force --description "second pass" → overwrites

Author: Anmol1696

packages/fn-cli/README.md

@@ -12,6 +12,7 @@ pnpm add @constructive-io/fn-runtime  # for handlers
 ## Commands
 
 ```bash
+fn init <name> [--type=node-graphql|python] [--description=<d>] [--force] [--no-tty]
 fn generate [--only=<name>] [--packages-only]
 fn build [--only=<name>]
 fn dev [--only=<name>]
@@ -22,4 +23,25 @@ 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.
+### `fn init`
+
+Scaffolds `functions/<name>/handler.{json,ts|py}` from a bundled template. Powered by [`genomic`](https://www.npmjs.com/package/genomic) — the same engine `pgpm init` uses — so prompt conventions and `--no-tty` flag-mapping match the rest of the Constructive ecosystem.
+
+```bash
+# Interactive (prompts for description)
+fn init send-welcome
+
+# Non-interactive
+fn init send-welcome --no-tty --description "User welcome email"
+
+# Python handler
+fn init pyfn --type python --no-tty
+
+# Custom functionsDir (read from fn.config.json)
+fn init my-fn --no-tty   # writes to <functionsDir>/my-fn/
+
+# Overwrite an existing dir
+fn init dup --no-tty --force
+```
+
+Bundled templates live at `templates/handler/{node-graphql,python}/` inside this package. After `fn init`, run `fn generate` to stamp out the workspace package, then `fn build` to compile.

packages/fn-cli/__tests__/init.test.ts

@@ -0,0 +1,106 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { run } from '../src/cli';
+
+describe('fn init', () => {
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'fn-init-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it('scaffolds a node-graphql handler from the bundled template', async () => {
+    const code = await run(['init', 'send-welcome', '--no-tty', '--root', tmpRoot]);
+    expect(code).toBe(0);
+    const handlerJson = path.join(tmpRoot, 'functions/send-welcome/handler.json');
+    const handlerTs = path.join(tmpRoot, 'functions/send-welcome/handler.ts');
+    expect(fs.existsSync(handlerJson)).toBe(true);
+    expect(fs.existsSync(handlerTs)).toBe(true);
+    const json = JSON.parse(fs.readFileSync(handlerJson, 'utf-8'));
+    expect(json.name).toBe('send-welcome');
+    expect(json.type).toBe('node-graphql');
+    expect(json.version).toBe('0.1.0');
+    const ts = fs.readFileSync(handlerTs, 'utf-8');
+    expect(ts).toContain("ctx.log.info('send-welcome invoked'");
+    expect(ts).toContain("import type { FunctionHandler } from '@constructive-io/fn-runtime'");
+  });
+
+  it('scaffolds a python handler when --type=python', async () => {
+    const code = await run([
+      'init',
+      'pyfn',
+      '--type',
+      'python',
+      '--no-tty',
+      '--root',
+      tmpRoot,
+    ]);
+    expect(code).toBe(0);
+    expect(fs.existsSync(path.join(tmpRoot, 'functions/pyfn/handler.py'))).toBe(true);
+    const json = JSON.parse(
+      fs.readFileSync(path.join(tmpRoot, 'functions/pyfn/handler.json'), 'utf-8')
+    );
+    expect(json.type).toBe('python');
+  });
+
+  it('refuses to overwrite without --force', async () => {
+    await run(['init', 'dup', '--no-tty', '--root', tmpRoot]);
+    const code = await run(['init', 'dup', '--no-tty', '--root', tmpRoot]);
+    expect(code).toBe(1);
+  });
+
+  it('overwrites with --force', async () => {
+    await run(['init', 'dup', '--no-tty', '--root', tmpRoot]);
+    const code = await run([
+      'init',
+      'dup',
+      '--no-tty',
+      '--force',
+      '--description',
+      'second',
+      '--root',
+      tmpRoot,
+    ]);
+    expect(code).toBe(0);
+    const json = JSON.parse(
+      fs.readFileSync(path.join(tmpRoot, 'functions/dup/handler.json'), 'utf-8')
+    );
+    expect(json.description).toBe('second');
+  });
+
+  it('rejects an unknown --type', async () => {
+    const code = await run([
+      'init',
+      'broken',
+      '--type',
+      'rust',
+      '--no-tty',
+      '--root',
+      tmpRoot,
+    ]);
+    expect(code).toBe(1);
+    expect(fs.existsSync(path.join(tmpRoot, 'functions/broken'))).toBe(false);
+  });
+
+  it('errors when no name is given', async () => {
+    const code = await run(['init', '--no-tty', '--root', tmpRoot]);
+    expect(code).toBe(1);
+  });
+
+  it('honors a custom functionsDir from fn.config.json', async () => {
+    fs.writeFileSync(
+      path.join(tmpRoot, 'fn.config.json'),
+      JSON.stringify({ functionsDir: 'src/handlers', outputDir: 'generated' })
+    );
+    const code = await run(['init', 'cfg', '--no-tty', '--root', tmpRoot]);
+    expect(code).toBe(0);
+    expect(
+      fs.existsSync(path.join(tmpRoot, 'src/handlers/cfg/handler.json'))
+    ).toBe(true);
+  });
+});

packages/fn-cli/jest.config.js

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

packages/fn-cli/package.json

@@ -11,23 +11,29 @@
   },
   "files": [
     "dist",
+    "templates",
     "README.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && chmod +x dist/bin/fn.js",
-    "clean": "rimraf dist"
+    "clean": "rimraf dist",
+    "test": "jest"
   },
   "dependencies": {
     "@constructive-io/fn-client": "workspace:^",
+    "genomic": "^5.3.11",
     "minimist": "^1.2.8"
   },
   "devDependencies": {
+    "@types/jest": "^29.5.14",
     "@types/minimist": "^1.2.5",
     "@types/node": "^22.10.4",
+    "jest": "^29.7.0",
     "rimraf": "^5.0.5",
+    "ts-jest": "^29.2.5",
     "typescript": "^5.1.6"
   }
 }

packages/fn-cli/src/cli.ts

@@ -4,6 +4,9 @@ import { commands, type CommandFn } from './commands';
 const HELP = `Usage: fn <command> [options]
 
 Commands:
+  init <name>  Scaffold a new function under functions/<name>/
+               Flags: --type=node-graphql|python (default: node-graphql)
+                      --description=<d>  --force  --no-tty
   generate     Generate workspace packages, k8s YAML, configmaps, skaffold.yaml
                Flags: --only=<name>  --packages-only
   build        Run \`pnpm -r build\` (optionally filtered)
@@ -21,8 +24,8 @@ Common flags:
 
 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'],
+    string: ['only', 'config', 'root', 'type', 'name', 'description'],
+    boolean: ['packages-only', 'help', 'version', 'no-tty', 'force'],
     alias: { h: 'help', v: 'version' },
   });
 

packages/fn-cli/src/commands.ts

@@ -1,4 +1,7 @@
+import * as fs from 'fs';
+import * as path from 'path';
 import { FnClient } from '@constructive-io/fn-client';
+import { Templatizer } from 'genomic';
 import type { ParsedArgs } from 'minimist';
 
 export type CommandFn = (args: ParsedArgs) => number | Promise<number>;
@@ -9,6 +12,23 @@ const buildClient = (args: ParsedArgs): FnClient =>
     config: typeof args.config === 'string' ? args.config : undefined,
   });
 
+/** Bundled handler templates ship next to the compiled commands. */
+const TEMPLATES_ROOT = path.resolve(__dirname, '..', 'templates', 'handler');
+
+const KNOWN_HANDLER_TYPES = ['node-graphql', 'python'] as const;
+type HandlerType = (typeof KNOWN_HANDLER_TYPES)[number];
+
+const isHandlerType = (s: string): s is HandlerType =>
+  (KNOWN_HANDLER_TYPES as readonly string[]).includes(s);
+
+const detectNoTty = (args: ParsedArgs): boolean =>
+  Boolean(
+    args['no-tty'] ||
+      args.noTty ||
+      args.tty === false ||
+      process.env.CI === 'true'
+  );
+
 const cmdGenerate: CommandFn = (args) => {
   const client = buildClient(args);
   const result = client.generate({
@@ -74,7 +94,72 @@ const cmdVerify: CommandFn = (args) => {
   return 2;
 };
 
+const cmdInit: CommandFn = async (args) => {
+  // Positional name first, then --name flag.
+  const positional = typeof args._[1] === 'string' ? args._[1] : undefined;
+  const name = positional ?? (typeof args.name === 'string' ? args.name : '');
+  if (!name) {
+    process.stderr.write(
+      'fn init: function name is required (positional or --name=<name>)\n'
+    );
+    return 1;
+  }
+
+  const type = typeof args.type === 'string' ? args.type : 'node-graphql';
+  if (!isHandlerType(type)) {
+    process.stderr.write(
+      `Unknown type "${type}". Available: ${KNOWN_HANDLER_TYPES.join(', ')}\n`
+    );
+    return 1;
+  }
+
+  const templateDir = path.join(TEMPLATES_ROOT, type);
+  if (!fs.existsSync(templateDir)) {
+    process.stderr.write(
+      `Bundled template missing at ${templateDir}. Reinstall @constructive-io/fn-cli.\n`
+    );
+    return 1;
+  }
+
+  const client = buildClient(args);
+  const functionsDir = client.config.functionsDir
+    ? path.resolve(client.rootDir, client.config.functionsDir)
+    : path.resolve(client.rootDir, 'functions');
+  const outDir = path.join(functionsDir, name);
+
+  if (fs.existsSync(outDir) && !args.force) {
+    process.stderr.write(
+      `${path.relative(client.rootDir, outDir) || outDir} already exists. Pass --force to overwrite.\n`
+    );
+    return 1;
+  }
+
+  // Genomic strips the ____ wrapping when matching argv keys, so plain
+  // names ('name', 'description', …) are the right shape. version defaults
+  // to 0.1.0 from the .boilerplate.json; users can edit handler.json after.
+  const argv: Record<string, string> = {
+    name,
+    version: '0.1.0',
+    description: typeof args.description === 'string' ? args.description : '',
+  };
+
+  const templatizer = new Templatizer();
+  await templatizer.process(templateDir, outDir, {
+    argv,
+    noTty: detectNoTty(args),
+  });
+
+  const written = fs
+    .readdirSync(outDir)
+    .map((f) => path.join(path.relative(client.rootDir, outDir) || outDir, f));
+  process.stdout.write(`Created ${name} (${type}):\n`);
+  for (const f of written) process.stdout.write(`  + ${f}\n`);
+  process.stdout.write('Next: run `fn generate` to stamp out workspace packages.\n');
+  return 0;
+};
+
 export const commands: Record<string, CommandFn> = {
+  init: cmdInit,
   generate: cmdGenerate,
   build: cmdBuild,
   dev: cmdDev,

packages/fn-cli/templates/handler/node-graphql/.boilerplate.json

@@ -0,0 +1,20 @@
+{
+  "type": "module",
+  "requiresWorkspace": false,
+  "questions": [
+    {
+      "name": "____name____",
+      "message": "Function name (used as directory and module identifier)",
+      "required": true
+    },
+    {
+      "name": "____version____",
+      "message": "Initial version",
+      "default": "0.1.0"
+    },
+    {
+      "name": "____description____",
+      "message": "Short description"
+    }
+  ]
+}

packages/fn-cli/templates/handler/node-graphql/handler.json

@@ -0,0 +1,6 @@
+{
+  "name": "____name____",
+  "version": "____version____",
+  "type": "node-graphql",
+  "description": "____description____"
+}

packages/fn-cli/templates/handler/node-graphql/handler.ts

@@ -0,0 +1,16 @@
+import type { FunctionHandler } from '@constructive-io/fn-runtime';
+
+interface Payload {
+  // TODO: shape your function input
+}
+
+interface Result {
+  ok: true;
+}
+
+const handler: FunctionHandler<Payload, Result> = async (params, ctx) => {
+  ctx.log.info('____name____ invoked', params);
+  return { ok: true };
+};
+
+export default handler;

packages/fn-cli/templates/handler/python/.boilerplate.json

@@ -0,0 +1,20 @@
+{
+  "type": "module",
+  "requiresWorkspace": false,
+  "questions": [
+    {
+      "name": "____name____",
+      "message": "Function name (used as directory and module identifier)",
+      "required": true
+    },
+    {
+      "name": "____version____",
+      "message": "Initial version",
+      "default": "0.1.0"
+    },
+    {
+      "name": "____description____",
+      "message": "Short description"
+    }
+  ]
+}