@funcd-dev/shim 0.0.0-bootstrap.0

package/dist/blob.d.ts

@@ -0,0 +1,17 @@
+/** Options for a presigned URL: the HTTP method it grants (default GET) and its lifetime (a Go duration
+ * string, e.g. "15m"; the driver's default when omitted). A PUT/DELETE URL requires s3::write. */
+export interface SignOptions {
+    method?: 'GET' | 'PUT' | 'DELETE';
+    expiry?: string;
+}
+/** A function's binding-scoped blob storage (ADR-0127): get/put/delete a bound prefix's objects, list
+ * keys, or mint a presigned URL — the blob twin of KVClient. */
+export interface BlobClient {
+    get(binding: string, key: string): Promise<Uint8Array | null>;
+    put(binding: string, key: string, value: Uint8Array): Promise<void>;
+    del(binding: string, key: string): Promise<void>;
+    list(binding: string, prefix?: string): Promise<string[]>;
+    signedUrl(binding: string, key: string, opts?: SignOptions): Promise<string>;
+}
+/** Build the context.blob client. */
+export declare function makeBlob(): BlobClient;

package/dist/blob.js

@@ -0,0 +1,72 @@
+// context.blob — function-facing blob over the worker-node local API (HTTP-over-UDS, ADR-0127). Dials the
+// same per-sandbox socket as context.kv/context.invoke (FUNCD_INVOKE_SOCKET); the platform routes /blob/…
+// to the binding-gated, PDP-authorized Facade with the sandbox's function identity (bind-as-grant on
+// spec.blob). Reached only through the built-in shim — no @aws-sdk, no keypair. The blob twin of context.kv;
+// v1 is bytes-in-memory (streaming is a v2 follow-up).
+import http from 'node:http';
+function request(method, path, body) {
+    return new Promise((resolve, reject) => {
+        const socketPath = process.env.FUNCD_INVOKE_SOCKET;
+        if (!socketPath) {
+            reject(new Error('context.blob: worker-node local API socket unavailable (FUNCD_INVOKE_SOCKET unset)'));
+            return;
+        }
+        const headers = {};
+        if (body)
+            headers['content-length'] = body.byteLength;
+        const req = http.request({ socketPath, path, method, headers }, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => resolve({ status: res.statusCode ?? 0, body: Buffer.concat(chunks) }));
+        });
+        req.on('error', reject);
+        if (body)
+            req.end(body);
+        else
+            req.end();
+    });
+}
+const enc = encodeURIComponent;
+// key may be hierarchical ("a/b"); keep the "/" separators (the server's {key...} captures them), encode segments.
+const keyPath = (binding, key) => `/blob/${enc(binding)}/${key.split('/').map(enc).join('/')}`;
+const fail = (verb, r) => new Error(`context.blob.${verb} failed: ${r.status} ${r.body.toString('utf8')}`);
+const ok = (r) => r.status >= 200 && r.status < 300;
+/** Build the context.blob client. */
+export function makeBlob() {
+    return {
+        async get(binding, key) {
+            const r = await request('GET', keyPath(binding, key));
+            if (r.status === 404)
+                return null;
+            if (!ok(r))
+                throw fail('get', r);
+            return new Uint8Array(r.body);
+        },
+        async put(binding, key, value) {
+            const r = await request('PUT', keyPath(binding, key), Buffer.from(value));
+            if (!ok(r))
+                throw fail('put', r);
+        },
+        async del(binding, key) {
+            const r = await request('DELETE', keyPath(binding, key));
+            if (!ok(r))
+                throw fail('del', r);
+        },
+        async list(binding, prefix) {
+            const q = prefix ? `?prefix=${enc(prefix)}` : '';
+            const r = await request('GET', `/blob/${enc(binding)}${q}`);
+            if (!ok(r))
+                throw fail('list', r);
+            return JSON.parse(r.body.toString('utf8') || '[]');
+        },
+        async signedUrl(binding, key, opts) {
+            let path = `${keyPath(binding, key)}?sign=1&method=${enc(opts?.method ?? 'GET')}`;
+            if (opts?.expiry)
+                path += `&expiry=${enc(opts.expiry)}`;
+            const r = await request('GET', path);
+            if (!ok(r))
+                throw fail('signedUrl', r);
+            return r.body.toString('utf8');
+        },
+    };
+}

package/dist/build.d.ts

@@ -0,0 +1,9 @@
+import { type Schema } from 'ts-json-schema-generator';
+export interface ContractBuild {
+    /** an ESM module source defining the precompiled __funcdValidate* (null ⇒ no contract). */
+    validatorSource: string | null;
+    inputSchema: Schema | null;
+    outputSchema: Schema | null;
+}
+/** Compile the FuncInput/FuncOutput contract of the TS module at `tsPath`. */
+export declare function buildContract(tsPath: string): ContractBuild;

package/dist/build.js

@@ -0,0 +1,123 @@
+// funcd Node contract compiler (BUILD-TIME, ADR-0058/0060). The TS analog of funcd_build.py:
+// for an author module declaring `FuncInput`/`FuncOutput` types it generates the JSON Schema
+// (ts-json-schema-generator — closed records, no $ref) and compiles a precompiled validator
+// (AJV-standalone) baked into the bundle as `__funcdValidateInput`/`__funcdValidateOutput`
+// (`(data) => Error[]`, [] ⇒ valid) — exactly what shim.ts's resolveValidators reads.
+//
+// Runs on the push box; NOT bundled into shim.mjs. The TS interfaces vanish at compile (esbuild
+// erases types), so unlike Python there is no source-stripping — only the validator is injected.
+//
+// (ADR-0060 names typia; typia needs a TS *transformer* (ts-patch) that does not compose with the
+//  esbuild bundle. ts-json-schema-generator is the no-transformer equivalent — same "TS type ->
+//  JSON Schema", same MIT licence; the runtime validator is still AJV-standalone as the ADR says.)
+import Ajv from 'ajv';
+import standaloneCode from 'ajv/dist/standalone/index.js';
+import { createGenerator } from 'ts-json-schema-generator';
+/** Compile the FuncInput/FuncOutput contract of the TS module at `tsPath`. */
+export function buildContract(tsPath) {
+    const inputSchema = schemaFor(tsPath, 'FuncInput');
+    const outputSchema = schemaFor(tsPath, 'FuncOutput');
+    if (!inputSchema && !outputSchema) {
+        return { validatorSource: null, inputSchema: null, outputSchema: null };
+    }
+    // Register each schema under an $id, then standalone-code by id (the multi-export API takes
+    // schema ids, not compiled fns). standaloneCode emits `export const _funcdInput = …` — eval-free
+    // (compiled here, at build).
+    // strictSchema:false ⇒ AJV ignores the `discriminator` keyword we add for the gate (it validates
+    // a tagged union via `oneOf` alone; `discriminator` is metadata the Go profile gate requires).
+    const ajv = new Ajv({ code: { source: true, esm: true }, allErrors: true, strictSchema: false });
+    const refs = {};
+    if (inputSchema) {
+        ajv.addSchema({ ...stripMeta(inputSchema), $id: 'funcdInput' });
+        refs._funcdInput = 'funcdInput';
+    }
+    if (outputSchema) {
+        ajv.addSchema({ ...stripMeta(outputSchema), $id: 'funcdOutput' });
+        refs._funcdOutput = 'funcdOutput';
+    }
+    const base = standaloneCode(ajv, refs);
+    const wrap = (name, fn) => `export function ${name}(d) { return ${fn}(d) ? [] : (${fn}.errors ?? []); }\n`;
+    const validatorSource = base +
+        '\n' +
+        (inputSchema ? wrap('__funcdValidateInput', '_funcdInput') : '') +
+        (outputSchema ? wrap('__funcdValidateOutput', '_funcdOutput') : '');
+    return { validatorSource, inputSchema, outputSchema };
+}
+/** Generate the JSON Schema for `type` from `tsPath`, inlined (no $ref) + closed records — the
+ *  funcd profile shape; returns null when the type is not declared. */
+function schemaFor(tsPath, type) {
+    try {
+        const schema = createGenerator({
+            path: tsPath,
+            type,
+            additionalProperties: false, // closed records (the profile forbids open ones)
+            topRef: false, // inline the root type (no $ref to a definition)
+            expose: 'none', // inline nested types too (no $ref/$defs — the profile forbids $ref)
+            skipTypeCheck: true,
+        }).createSchema(type);
+        const stripped = stripMeta(schema);
+        discriminateUnions(stripped); // tagged `anyOf` → the profile's discriminated `oneOf`
+        return stripped;
+    }
+    catch {
+        return null; // the type is not declared in this module
+    }
+}
+/** Rewrite every tagged `anyOf` into the profile's discriminated `oneOf` + `discriminator`
+ *  (ADR-0058). ts-json-schema-generator emits a TS union as `anyOf`, but the gate accepts a union
+ *  only as a tagged `oneOf`; when the branches share a required, distinct-`const` property (the
+ *  discriminant) the two are equivalent, so convert in place (recursing all nested schemas). */
+function discriminateUnions(node) {
+    if (Array.isArray(node)) {
+        for (const child of node)
+            discriminateUnions(child);
+        return;
+    }
+    if (!node || typeof node !== 'object')
+        return;
+    const obj = node;
+    for (const value of Object.values(obj))
+        discriminateUnions(value);
+    if (Array.isArray(obj.anyOf)) {
+        const tag = discriminatorTag(obj.anyOf);
+        if (tag) {
+            obj.oneOf = obj.anyOf;
+            delete obj.anyOf;
+            obj.discriminator = { propertyName: tag };
+        }
+    }
+}
+/** The property that discriminates an `anyOf`'s branches: present + required + a single `const` in
+ *  every branch, with distinct const values. Returns null when the union isn't a clean tagged one. */
+function discriminatorTag(branches) {
+    const objs = branches.map((b) => (b && typeof b === 'object' ? b : null));
+    if (objs.some((b) => b === null))
+        return null;
+    const firstProps = objs[0]?.properties;
+    if (!firstProps)
+        return null;
+    for (const name of Object.keys(firstProps)) {
+        const consts = [];
+        const taggedByAll = objs.every((b) => {
+            const props = b?.properties;
+            const required = b?.required;
+            const field = props?.[name];
+            if (!props || !Array.isArray(required) || !required.includes(name) || !field || !('const' in field)) {
+                return false;
+            }
+            consts.push(JSON.stringify(field.const));
+            return true;
+        });
+        if (taggedByAll && new Set(consts).size === consts.length)
+            return name;
+    }
+    return null;
+}
+/** Drop JSON-Schema meta keys AJV/the gate don't need (the contract is the type shape). */
+function stripMeta(schema) {
+    const { $schema, $ref, definitions, ...rest } = schema;
+    void $schema;
+    void $ref;
+    void definitions;
+    return rest;
+}

package/dist/kv.d.ts

@@ -0,0 +1,15 @@
+/** A function's view of its namespace-scoped KV (ADR-0069): get/put/del a binding's key, or list keys. */
+export interface KVClient {
+    get(binding: string, key: string): Promise<Uint8Array | null>;
+    /** get() decoded as UTF-8 text — the common case (a missing key is null). Saves the caller a
+     * TextDecoder dance; put() already accepts a string. */
+    getText(binding: string, key: string): Promise<string | null>;
+    /** get() decoded as UTF-8 text then JSON-parsed (a missing key is null). The structured-value
+     * counterpart of getText; write with put(binding, key, JSON.stringify(value)). */
+    getJSON<T = unknown>(binding: string, key: string): Promise<T | null>;
+    put(binding: string, key: string, value: Uint8Array | string): Promise<void>;
+    del(binding: string, key: string): Promise<void>;
+    list(binding: string, prefix?: string): Promise<string[]>;
+}
+/** Build the context.kv client. */
+export declare function makeKV(): KVClient;

package/dist/kv.js

@@ -0,0 +1,78 @@
+// context.kv — function-facing KV over the worker-node local API (HTTP-over-UDS, ADR-0069). Dials the
+// same per-sandbox socket as context.invoke (FUNCD_INVOKE_SOCKET); the platform routes /kv/… to the
+// PDP-authorized Facade with the sandbox's namespace identity. Reached only through the built-in shim.
+import http from 'node:http';
+function request(method, path, body) {
+    return new Promise((resolve, reject) => {
+        const socketPath = process.env.FUNCD_INVOKE_SOCKET;
+        if (!socketPath) {
+            reject(new Error('context.kv: worker-node local API socket unavailable (FUNCD_INVOKE_SOCKET unset)'));
+            return;
+        }
+        const headers = {};
+        if (body)
+            headers['content-length'] = body.byteLength;
+        const req = http.request({ socketPath, path, method, headers }, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () => resolve({ status: res.statusCode ?? 0, body: Buffer.concat(chunks) }));
+        });
+        req.on('error', reject);
+        if (body)
+            req.end(body);
+        else
+            req.end();
+    });
+}
+const enc = encodeURIComponent;
+// key may be hierarchical ("a/b"); keep the "/" separators (the server's {key...} captures them), encode segments.
+const keyPath = (binding, key) => `/kv/${enc(binding)}/${key.split('/').map(enc).join('/')}`;
+const fail = (verb, r) => new Error(`context.kv.${verb} failed: ${r.status} ${r.body.toString('utf8')}`);
+const ok = (r) => r.status >= 200 && r.status < 300;
+/** Build the context.kv client. */
+export function makeKV() {
+    return {
+        async get(binding, key) {
+            const r = await request('GET', keyPath(binding, key));
+            if (r.status === 404)
+                return null;
+            if (!ok(r))
+                throw fail('get', r);
+            return new Uint8Array(r.body);
+        },
+        async getText(binding, key) {
+            const r = await request('GET', keyPath(binding, key));
+            if (r.status === 404)
+                return null;
+            if (!ok(r))
+                throw fail('get', r);
+            return r.body.toString('utf8');
+        },
+        async getJSON(binding, key) {
+            const r = await request('GET', keyPath(binding, key));
+            if (r.status === 404)
+                return null;
+            if (!ok(r))
+                throw fail('get', r);
+            return JSON.parse(r.body.toString('utf8'));
+        },
+        async put(binding, key, value) {
+            const buf = typeof value === 'string' ? Buffer.from(value, 'utf8') : Buffer.from(value);
+            const r = await request('PUT', keyPath(binding, key), buf);
+            if (!ok(r))
+                throw fail('put', r);
+        },
+        async del(binding, key) {
+            const r = await request('DELETE', keyPath(binding, key));
+            if (!ok(r))
+                throw fail('del', r);
+        },
+        async list(binding, prefix) {
+            const q = prefix ? `?prefix=${enc(prefix)}` : '';
+            const r = await request('GET', `/kv/${enc(binding)}${q}`);
+            if (!ok(r))
+                throw fail('list', r);
+            return JSON.parse(r.body.toString('utf8') || '[]');
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+import type { KVClient } from './kv.ts';
+import type { BlobClient } from './blob.ts';
+export type { KVClient } from './kv.ts';
+export type { BlobClient, SignOptions } from './blob.ts';
+/** A CloudEvent — the normalized trigger envelope (ADR-0023). */
+export interface CloudEvent<T = unknown> {
+    id: string;
+    source: string;
+    type: string;
+    specversion?: string;
+    time?: string;
+    datacontenttype?: string;
+    subject?: string;
+    data?: T;
+    /** Forward-compatible extension attributes. */
+    [key: string]: unknown;
+}
+/** The per-invocation context the shim passes to the handler. */
+export interface FunctionContext {
+    /** Structured log line → stdout (collected by the platform, ADR-0010). */
+    log(...args: unknown[]): void;
+    /** Synchronously invoke a linked function by its spec.links alias (ADR-0064). The input is
+     *  validated against the target's contract by the target's shim; its result is returned. Fails
+     *  closed (rejects) if the caller declares no such link. */
+    invoke<I = unknown, O = unknown>(alias: string, input: I): Promise<O>;
+    /** Namespace-scoped key-value storage (ADR-0069): get/put/del a binding's key, or list keys. */
+    kv: KVClient;
+    /** Binding-scoped blob storage (ADR-0127): get/put/del/list a bound prefix's objects, or mint a
+     *  presigned URL — the blob twin of kv. */
+    blob: BlobClient;
+}
+/** A function handler: receives the context + CloudEvent, returns a response (or nothing). */
+export type Handler<In = unknown, Out = unknown> = (context: FunctionContext, event: CloudEvent<In>) => Out | Promise<Out>;
+/** Json — the explicit "arbitrary JSON value" contract type (ADR-0058). Declare `FuncInput`/
+ *  `FuncOutput = Json`, or a field `payload: Json`, when the shape is genuinely unknown; the
+ *  generated contract is the empty schema `{}` (accepts any JSON). Typed as `unknown` so the
+ *  handler must narrow before use — deliberately NOT the unsafe `any`. */
+export type Json = unknown;
+/** A single error from a precompiled validator. Shape kept loose (AJV vs pydantic differ); the
+ *  shim only inspects the array length and echoes the errors as 422/500 details. */
+export type ValidationError = unknown;
+/** A precompiled, eval-free validator the push build inlines into the bundle from the author's
+ *  FuncInput/FuncOutput type (ADR-0058). Returns [] when `data` is valid. The shim runs it; it
+ *  never compiles a schema at runtime. */
+export type Validator = (data: unknown) => ValidationError[];

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@funcd-dev/shim",
+  "version": "0.0.0-bootstrap.0",
+  "type": "module",
+  "description": "Types and the contract build for writing funcd functions in TypeScript",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pyvvo/funcd-typescript.git",
+    "directory": "shim"
+  },
+  "homepage": "https://github.com/pyvvo/funcd-typescript#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "default": "./dist/build.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --experimental-strip-types test/*.test.ts",
+    "build": "yarn build:shim && yarn build:pool && yarn build:lib",
+    "build:shim": "esbuild src/shim.ts --bundle --platform=node --format=esm --target=node22 --outfile=shim.mjs --banner:js=\"// GENERATED from shim/src/shim.ts by 'yarn build' (esbuild). Do not edit by hand.\"",
+    "build:pool": "esbuild src/pool.ts --bundle --platform=node --format=esm --target=node22 --outfile=pool.mjs --banner:js=\"// GENERATED from shim/src/pool.ts by 'yarn build' (esbuild). Do not edit by hand.\"",
+    "build:lib": "tsc -p tsconfig.lib.json"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ts-json-schema-generator": "^2.9.0"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^2.0.5",
+    "@types/node": "^22.10.0",
+    "esbuild": "^0.28.1",
+    "hono": "^4.12.25",
+    "typescript": "^5.7.0"
+  }
+}