feat(packages): extract fn-types; make fn-runtime/fn-app publishable

First wave of the portable-functions toolkit (Starship-style split).
Establishes a single source-of-truth types package that the rest of
the toolkit (fn-generator, fn-client, fn-cli — landing in later waves)
will depend on.

- New @constructive-io/fn-types@0.1.0 — runtime contract types
  (FunctionHandler, FunctionContext, ServerOptions), HandlerManifest,
  FnRegistry/FnRegistryEntry, FnConfig + defineConfig() helper for
  typed fn.config.ts files. No logic, no shell-out.
- @constructive-io/fn-runtime@1.2.0 — drops private:true; now depends
  on fn-types and re-exports the runtime types from there. Source files
  import from @constructive-io/fn-types instead of local ./types.ts
  (which is removed).
- @constructive-io/knative-job-fn@1.6.0 — drops private:true; ready to
  publish (rename to @constructive-io/fn-app deferred to a later wave
  to avoid churning internal imports).

Verified: pnpm generate && pnpm install && pnpm build passes for all
three existing functions (example, simple-email, send-email-link).

Author: Anmol1696

packages/fn-app/README.md

@@ -1 +1,20 @@
 # @constructive-io/knative-job-fn
+
+Express app factory for Knative-style job functions. Provides:
+
+- One POST `/` endpoint with JSON body parsing and request logging.
+- Per-request job context lifted from `X-Worker-Id`, `X-Job-Id`, `X-Database-Id`, `X-Callback-Url` headers.
+- An on-finish hook that POSTs `{status: "success" | "error"}` to the callback URL when set.
+- Centralized error middleware that emits an error callback and a 200 with `{message}` body (Knative requires 2xx for delivery acknowledgment).
+
+Most users should depend on `@constructive-io/fn-runtime`, which wraps this with a typed handler and GraphQL clients. Use this package directly only if you need raw Express middleware control.
+
+```ts
+import { createJobApp } from '@constructive-io/knative-job-fn';
+
+const app = createJobApp();
+app.post('/', (req, res) => {
+  res.json({ ok: true });
+});
+app.listen(8080);
+```

packages/fn-app/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@constructive-io/knative-job-fn",
-  "version": "1.5.2",
-  "description": "Express app factory for Knative job functions with callback handling",
+  "version": "1.6.0",
+  "description": "Express app factory for Knative job functions with callback handling.",
   "author": "Constructive <developers@constructive.io>",
-  "private": true,
+  "license": "SEE LICENSE IN LICENSE",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "makage build",
     "build:dev": "makage build --dev",

packages/fn-runtime/README.md

@@ -0,0 +1,36 @@
+# @constructive-io/fn-runtime
+
+Runtime contract for Constructive Functions: wraps a typed handler in an Express app with a built-in GraphQL client, structured logger, and Knative job-callback support.
+
+This is the package handler authors import directly. The `@constructive-io/fn-cli` toolchain stamps out function packages that depend on this runtime.
+
+## Usage
+
+```ts
+import { createFunctionServer } from '@constructive-io/fn-runtime';
+import type { FunctionHandler } from '@constructive-io/fn-types';
+
+type Payload = { to: string; subject: string };
+
+const handler: FunctionHandler<Payload, { ok: true }> = async (params, ctx) => {
+  ctx.log.info('processing', { to: params.to });
+  return { ok: true };
+};
+
+const app = createFunctionServer(handler, { name: 'my-function' });
+
+if (require.main === module) {
+  app.listen(Number(process.env.PORT || 8080));
+}
+
+export default app;
+```
+
+## What you get on `ctx`
+
+- `ctx.job` — `{ jobId, workerId, databaseId }` lifted from `X-*` request headers.
+- `ctx.client` / `ctx.meta` — GraphQL clients, configured via `GRAPHQL_URL` / `META_GRAPHQL_URL` env. Lazily created when `databaseId` is present; throw a helpful error if used without configuration.
+- `ctx.log` — structured logger (`@pgpmjs/logger`).
+- `ctx.env` — `process.env` reference for convenience.
+
+The HTTP contract (one POST `/`, callback-on-finish) and error handling come from `@constructive-io/knative-job-fn` underneath, so the function plays nicely with the Constructive job-service.

packages/fn-runtime/package.json

@@ -1,16 +1,24 @@
 {
   "name": "@constructive-io/fn-runtime",
-  "version": "1.1.0",
-  "description": "Runtime for Constructive functions — wraps handler in Express app with GraphQL client, logging, and job callback support",
+  "version": "1.2.0",
+  "description": "Runtime for Constructive functions — wraps a handler in an Express app with GraphQL client, logging, and job callback support.",
   "author": "Constructive <developers@constructive.io>",
-  "private": true,
+  "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"
   },
   "dependencies": {
+    "@constructive-io/fn-types": "workspace:^",
     "@constructive-io/knative-job-fn": "workspace:^",
     "@pgpmjs/logger": "^2.4.3",
     "graphql-request": "^7.1.2"

packages/fn-runtime/src/context.ts

@@ -1,6 +1,6 @@
 import { createLogger } from '@pgpmjs/logger';
+import type { FunctionContext } from '@constructive-io/fn-types';
 import { createClients } from './graphql';
-import type { FunctionContext } from './types';
 
 type RequestHeaders = {
   databaseId?: string;

packages/fn-runtime/src/index.ts

@@ -1,4 +1,9 @@
 export { createFunctionServer } from './server';
 export { createClients } from './graphql';
 export { buildContext } from './context';
-export type { FunctionHandler, FunctionContext, ServerOptions } from './types';
+export type {
+  FunctionHandler,
+  FunctionContext,
+  FunctionLogger,
+  ServerOptions
+} from '@constructive-io/fn-types';

packages/fn-runtime/src/server.ts

@@ -1,6 +1,6 @@
 import { createJobApp } from '@constructive-io/knative-job-fn';
+import type { FunctionHandler, ServerOptions } from '@constructive-io/fn-types';
 import { buildContext } from './context';
-import type { FunctionHandler, ServerOptions } from './types';
 
 export const createFunctionServer = (
   handler: FunctionHandler<any, any>,

packages/fn-types/README.md

@@ -0,0 +1,37 @@
+# @constructive-io/fn-types
+
+Source-of-truth TypeScript types for the Constructive Functions toolkit.
+
+This package has **no logic** — it's the contract every other `@constructive-io/fn-*` package depends on. Types are split into four areas:
+
+- **Runtime** — `FunctionHandler`, `FunctionContext`, `ServerOptions` (used by `@constructive-io/fn-runtime` and handler authors).
+- **Manifest** — `HandlerManifest` (the shape of `functions/<name>/handler.json`).
+- **Config** — `FnConfig`, `FnPreset`, `K8sOptions`, `DockerOptions`, plus a `defineConfig()` helper for `fn.config.ts` files.
+- **Registry** — `FnRegistry`, `FnRegistryEntry` (manifest format consumed by `@constructive-io/fn-job-service`).
+
+## Usage in `fn.config.ts`
+
+```ts
+import { defineConfig } from '@constructive-io/fn-types';
+
+export default defineConfig({
+  functionsDir: 'functions',
+  outputDir: 'generated',
+  preset: 'jobs-bundle',
+  registry: 'ghcr.io/my-org',
+  k8s: { target: 'knative' }
+});
+```
+
+## Usage in a handler
+
+```ts
+import type { FunctionHandler } from '@constructive-io/fn-types';
+
+const handler: FunctionHandler<{ to: string }, { ok: true }> = async (params, ctx) => {
+  ctx.log.info('sending', params);
+  return { ok: true };
+};
+
+export default handler;
+```

packages/fn-types/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@constructive-io/fn-types",
+  "version": "0.1.0",
+  "description": "Source-of-truth TypeScript types for the Constructive Functions toolkit: handler manifests, FnConfig, runtime context, registry.",
+  "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",
+    "lint": "eslint . --fix"
+  },
+  "dependencies": {
+    "graphql-request": "^7.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.4",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.1.6"
+  }
+}

packages/fn-types/src/config.ts

@@ -0,0 +1,53 @@
+export type FnPreset = 'functions-only' | 'jobs-bundle';
+
+export type K8sTarget = 'knative' | 'deployment';
+
+export interface K8sResourceQuantities {
+  cpu?: string;
+  memory?: string;
+}
+
+export interface K8sOptions {
+  target?: K8sTarget;
+  namespace?: string;
+  imagePullSecrets?: string[];
+  resources?: {
+    requests?: K8sResourceQuantities;
+    limits?: K8sResourceQuantities;
+  };
+  /** Knative-specific: containerConcurrency, timeoutSeconds, etc. */
+  knative?: {
+    containerConcurrency?: number;
+    timeoutSeconds?: number;
+    visibility?: 'cluster-local' | 'public';
+  };
+}
+
+export interface DockerOptions {
+  /** Image registry, e.g. 'ghcr.io/my-org'. */
+  registry?: string;
+  /** Base image override; defaults to template's choice. */
+  baseImage?: string;
+  /** Generate one Dockerfile per function (true) vs one shared image (false). */
+  perFunction?: boolean;
+}
+
+export interface FnConfig {
+  /** Directory containing per-function source: <dir>/<name>/handler.{json,ts,py}. Default: 'functions'. */
+  functionsDir?: string;
+  /** Output directory for generated artifacts. Default: 'generated'. */
+  outputDir?: string;
+  /** Bundle preset. Default: 'functions-only'. */
+  preset?: FnPreset;
+  /** Image registry default; per-function manifests can still override. */
+  registry?: string;
+  /** Default Kubernetes namespace for generated manifests. */
+  namespace?: string;
+  k8s?: K8sOptions;
+  docker?: DockerOptions;
+  /** Map of template type → module specifier resolved by the generator. */
+  templates?: Record<string, string>;
+}
+
+/** Identity helper for editor autocomplete in fn.config.ts files. */
+export const defineConfig = (config: FnConfig): FnConfig => config;