@jarenjs/contract 0.43.1

package/src/project/openapi.jslt.json

@@ -0,0 +1,149 @@
+{
+  "$jslt": "0.1",
+  "rules": [
+    {
+      "match": "$",
+      "body": {
+        "openapi": "3.1.0",
+        "info": "$.info",
+        "servers": { "$let": { "s": "$.servers[*]" }, "$where": { "$exists": "$s" }, "$return": "$.servers" },
+        "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+        "paths": {
+          "$from-entries": {
+            "$for": { "op": "$.operations[*]" },
+            "$groupby": { "path": "$op.path" },
+            "$orderby": "$path",
+            "$return": {
+              "key": "$path",
+              "value": {
+                "$from-entries": {
+                  "$for": { "o": "$op" },
+                  "$orderby": "$o.method",
+                  "$return": { "key": "$o.method", "value": { "$apply": ["$o", "operation"] } }
+                }
+              }
+            }
+          }
+        },
+        "components": {
+          "$let": {
+            "c": {
+              "schemas": { "$let": { "n": { "$entries": "$.schemas" } }, "$where": { "$exists": "$n" }, "$return": "$.schemas" },
+              "responses": {
+                "$let": { "n": { "$entries": "$.shared" } },
+                "$where": { "$exists": "$n" },
+                "$return": {
+                  "$from-entries": {
+                    "$for": { "s": "$n" },
+                    "$return": {
+                      "key": "$s.key",
+                      "value": {
+                        "description": "$s.value.description",
+                        "content": { "application/json": { "schema": { "$apply": ["$s.value", "wire"] } } }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "$where": { "$exists": { "$entries": "$c" } },
+          "$return": "$c"
+        }
+      }
+    },
+    {
+      "mode": "operation",
+      "body": {
+        "operationId": "$.id",
+        "summary": "$.summary",
+        "description": "$.description",
+        "tags": ["$.tag"],
+        "parameters": { "$let": { "p": "$.parameters[*]" }, "$where": { "$exists": "$p" }, "$return": "$.parameters" },
+        "requestBody": {
+          "$let": { "b": "$.body" },
+          "$where": { "$exists": "$b" },
+          "$return": {
+            "required": "$b.required",
+            "content": { "$map": [["$b.media", { "schema": "$b.schema" }]] }
+          }
+        },
+        "responses": {
+          "$from-entries": {
+            "$seq": [
+              {
+                "key": "$.success.status",
+                "value": {
+                  "description": "Success",
+                  "content": {
+                    "$let": { "sch": "$.success.schema" },
+                    "$where": { "$exists": "$sch" },
+                    "$return": { "$map": [["$.success.media", { "schema": "$sch" }]] }
+                  }
+                }
+              },
+              {
+                "$for": { "e": "$.errors[*]" },
+                "$groupby": { "status": "$e.status" },
+                "$orderby": "$status",
+                "$return": { "key": "$status", "value": { "$apply": [{ "status": "$status", "entries": ["$e"] }, "response"] } }
+              }
+            ]
+          }
+        },
+        "x-jaren-policy": "$.policy"
+      }
+    },
+    {
+      "mode": "response",
+      "body": {
+        "$let": {
+          "declared": { "$for": { "x": "$.entries[*]" }, "$where": "$x.declared", "$return": "$x" },
+          "shared": { "$for": { "x": "$.entries[*]" }, "$where": { "$not": "$x.declared" }, "$return": "$x" }
+        },
+        "$return": {
+          "$if": [
+            { "$exists": "$declared" },
+            {
+              "description": {
+                "$concat": [
+                  "Declared failure: ",
+                  { "$string-join": ["$declared.code", ", "] },
+                  { "$if": [
+                    { "$exists": "$shared" },
+                    { "$concat": [" (or the binding's ", { "$string-join": ["$shared.code", ", "] }, ")"] },
+                    ""
+                  ] }
+                ]
+              },
+              "content": {
+                "application/json": {
+                  "schema": { "$apply": [{ "codes": ["$.entries[*].code"], "details": ["$declared.schema"] }, "wire"] }
+                }
+              }
+            },
+            { "$map": [["$$ref", { "$concat": ["#/components/responses/", { "$head": "$shared.shared" }] }]] }
+          ]
+        }
+      }
+    },
+    {
+      "mode": "wire",
+      "body": {
+        "type": "object",
+        "required": ["code", "message", "requestId", "retryable"],
+        "properties": {
+          "code": { "type": "string", "enum": "$.codes" },
+          "message": { "type": "string" },
+          "requestId": { "type": "string", "description": "The server trace, equal to the x-jaren-trace response header." },
+          "details": {
+            "$let": { "d": "$.details[*]" },
+            "$where": { "$exists": "$d" },
+            "$return": { "$if": [{ "$eq": [{ "$count": "$d" }, 1] }, "$d", { "anyOf": ["$d"] }] }
+          },
+          "retryable": { "type": "boolean" }
+        }
+      }
+    }
+  ]
+}

package/src/project/tools.js

@@ -0,0 +1,139 @@
+//@ts-check
+/**
+ * @file `contractTools`: the public, invokable operations of a contract as
+ * tool definitions for `@jarenjs/ai`'s toolbox — `{ name, description,
+ * inputSchema, execute }`, a plain object the toolbox and a WebMCP host
+ * read, so this package never imports the ai package (the generated-
+ * document rule). `execute` calls the client's `invoke` and answers the
+ * outcome JSON, so a model sees the same `{ ok, value | error, meta }`
+ * an app does; the toolbox validates the arguments against `inputSchema`
+ * before `execute` runs, and `invoke` validates them again against the
+ * same schema (the contract's own validator) before anything is sent.
+ */
+
+import { isJsonObject } from '@jarenjs/core/object';
+
+import { ContractHostError } from '../errors.js';
+import { retainedOperations } from '../public.js';
+import { bundleSameDocument } from '../bundle.js';
+
+/**
+ * @typedef {import('../compile.js').Contract} Contract
+ * @typedef {import('../compile.js').CompiledOperation} CompiledOperation
+ */
+
+/**
+ * A tool definition as `@jarenjs/ai`'s `createToolbox().add` takes it —
+ * the same shape WebMCP's `registerTool` reads.
+ * @typedef {Object} ToolDefinition
+ * @property {string} name
+ * @property {string} description
+ * @property {any} inputSchema - the operation's input schema, self-contained
+ * @property {(args: any) => any} execute - `client.invoke(op, args)`, resolving the outcome
+ */
+
+/**
+ * A client as the tools read it — any binding's client. The members are
+ * `any` so a client whose `invoke` narrows its own context type (the http
+ * client's `InvokeContext`) still assigns.
+ * @typedef {{ invoke: (op: string, input: any, ctx?: any) => any }} ToolClient
+ */
+
+/**
+ * @typedef {Object} ContractToolsOptions
+ * @property {readonly string[]} [ops] - the operations to expose (default:
+ *   every public, non-opaque, non-subscribe operation); an opaque,
+ *   subscribe or unknown id is refused
+ * @property {(id: string) => string} [name] - the tool name of an
+ *   operation (default: the id with `.` → `_`); must satisfy OpenAI's
+ *   `^[a-zA-Z0-9_-]{1,64}$` and be distinct per operation
+ */
+
+/** OpenAI's function-name constraint, which WebMCP tool names satisfy too. */
+const TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+
+/**
+ * The default tool name of an operation: its id with `.` → `_` (`a.b` →
+ * `a_b`; injective, since an id carries no `_`).
+ * @param {string} id
+ * @returns {string}
+ */
+function defaultName(id) {
+  return id.replaceAll('.', '_');
+}
+
+/**
+ * The input schema of a tool: the operation's input with the `$defs` it
+ * reaches inlined (self-contained), or a closed empty object for an
+ * operation without input.
+ * @param {CompiledOperation} op
+ * @param {Contract} contract
+ * @returns {any}
+ */
+function toolInputSchema(op, contract) {
+  if (op.input === null) return { type: 'object', properties: {}, additionalProperties: false };
+  return bundleSameDocument(op.input.schema, contract.doc);
+}
+
+/**
+ * Tool definitions for the public, invokable operations of a contract.
+ * @param {Contract} contract
+ * @param {ToolClient} client - a client opened on the same contract (`openHttpClient`, or any binding's)
+ * @param {ContractToolsOptions} [options]
+ * @returns {ToolDefinition[]} in document order
+ * @throws {ContractHostError} `JC1008` — not a compiled contract, a client
+ *   without `invoke`, `ops` naming an unknown or opaque operation, a tool
+ *   name outside `^[a-zA-Z0-9_-]{1,64}$`, or two operations mapping to one name
+ * @example
+ * const toolbox = createToolbox();                    // @jarenjs/ai
+ * for (const tool of contractTools(contract, client)) toolbox.add(tool);
+ * await toolbox.execute('product_save', { id: 1, revision: 2, product: { … } }); // → an outcome
+ */
+export function contractTools(contract, client, options = {}) {
+  if (!isJsonObject(options)) throw new ContractHostError('JC1008', 'contractTools: options must be an object');
+  const ops = retainedOperations(contract, options.ops, 'contractTools');
+  if (client === null || typeof client !== 'object' || typeof client.invoke !== 'function') {
+    throw new ContractHostError('JC1008', 'contractTools: client must be a contract client (an object with invoke)');
+  }
+  const nameOf = options.name === undefined ? defaultName : options.name;
+  if (typeof nameOf !== 'function') throw new ContractHostError('JC1008', 'contractTools: options.name must be a function (id) => string');
+  /** @type {ToolDefinition[]} */
+  const tools = [];
+  /** @type {Map<string, string>} */
+  const taken = new Map();
+  for (let i = 0; i < ops.length; i++) {
+    const op = ops[i];
+    if (op.http.opaque) {
+      // an explicit ops entry named it; the default set never includes one
+      if (options.ops !== undefined) {
+        throw new ContractHostError('JC1008', `contractTools: '${op.id}' is an opaque operation (media ${op.http.media}) — a tool carries JSON; reach it through client.url`);
+      }
+      continue;
+    }
+    if (op.kind === 'subscribe') {
+      // a tool call is one invoke; a stream has no tool shape
+      if (options.ops !== undefined) {
+        throw new ContractHostError('JC1008', `contractTools: '${op.id}' is a subscribe operation — a tool carries one invoke, not a stream`);
+      }
+      continue;
+    }
+    const name = nameOf(op.id);
+    if (typeof name !== 'string' || !TOOL_NAME.test(name)) {
+      throw new ContractHostError('JC1008', `contractTools: the tool name of '${op.id}' must match ^[a-zA-Z0-9_-]{1,64}$ (got ${typeof name === 'string' ? `'${name}'` : typeof name})`);
+    }
+    const other = taken.get(name);
+    if (other !== undefined) {
+      throw new ContractHostError('JC1008', `contractTools: operations '${other}' and '${op.id}' both map to the tool name '${name}'`);
+    }
+    taken.set(name, op.id);
+    const id = op.id;
+    const hasInput = op.input !== null;
+    tools.push({
+      name,
+      description: op.doc !== null ? op.doc : `${op.kind} operation ${id} (${op.http.method} ${op.http.path})`,
+      inputSchema: toolInputSchema(op, contract),
+      execute: (args) => client.invoke(id, hasInput ? args : null),
+    });
+  }
+  return tools;
+}

package/src/project/typescript.js

@@ -0,0 +1,152 @@
+//@ts-check
+/**
+ * @file `toTypeScript`: a compiled contract as one `.d.ts` — every public
+ * operation's input, output and error-details types through
+ * `@jarenjs/emit`'s type model (`compileEmitModel` + `renderTypeScript`,
+ * the suite's one declaration renderer), then a typed operation map and
+ * the client/handler declarations through a JTLT stylesheet
+ * (`typescript.jtlt.json`, compiled once at module scope).
+ *
+ * One emit model covers the whole contract: a synthetic root whose
+ * `$defs` holds the operation types first (`<PascalOp>Input`,
+ * `<PascalOp>Output`, `<PascalOp><PascalCode>Details`) and the reachable
+ * contract `$defs` after them. Emit declares `$defs` first and in
+ * document order and names each after its key, so the operation types
+ * keep the names this module gives them (a contract `$defs` entry that
+ * spells the same name is the one emit suffixes); their `#/$defs/X`
+ * references resolve against the same root, so a `Product` referenced
+ * from three operations is declared once. The root's own declaration
+ * (`unknown`) is not rendered.
+ *
+ * `Meta`, `WireError`, `Outcome<T>`, `InvokeContext`, `Client`,
+ * `Failure`, `HandlerContext` and `Handlers` are fixed text in the
+ * stylesheet — the D6 shapes as every binding carries them
+ * (`OUTCOME_META_MEMBERS` / `OUTCOME_ERROR_MEMBERS` in the client module
+ * are the runtime twins; a test holds the text to them).
+ */
+
+import { isJsonObject, setObjectMember } from '@jarenjs/core/object';
+import { compileJtltStylesheet } from '@jarenjs/json/jtlt';
+import { createTypeTestCompiler } from '@jarenjs/validate/query';
+import { compileEmitModel } from '@jarenjs/emit/model';
+import { renderTypeScript } from '@jarenjs/emit/typescript';
+
+import { ContractHostError } from '../errors.js';
+import { publicProjection, retainedOperations } from '../public.js';
+import TYPESCRIPT_STYLESHEET from './typescript.jtlt.json' with { type: 'json' };
+
+/**
+ * @typedef {import('../compile.js').Contract} Contract
+ * @typedef {import('../compile.js').CompiledOperation} CompiledOperation
+ */
+
+/**
+ * @typedef {Object} TypeScriptOptions
+ * @property {boolean} [banner=true] - emit the do-not-edit header
+ */
+
+/** The stylesheet, compiled once. */
+const render = compileJtltStylesheet(TYPESCRIPT_STYLESHEET, { compileTypeTest: createTypeTestCompiler() });
+
+/**
+ * PascalCase an operation id or error code: `product.save` → `ProductSave`,
+ * `not-found` → `NotFound`. Both grammars are lowercase words joined by
+ * `.` or `-`, so the result is always an identifier.
+ * @param {string} word
+ * @returns {string}
+ */
+function pascal(word) {
+  const parts = word.split(/[.-]/);
+  let out = '';
+  for (let i = 0; i < parts.length; i++) {
+    const p = parts[i];
+    if (p.length === 0) continue;
+    out += p.charAt(0).toUpperCase() + p.slice(1);
+  }
+  return out;
+}
+
+/**
+ * The type model of a contract: the synthetic `$defs` root, the row per
+ * operation the stylesheet renders, and the rendered declarations.
+ * @param {Contract} contract
+ * @param {CompiledOperation[]} ops
+ * @param {string} source - what the model records as its source
+ * @returns {{ types: string, rows: Record<string, unknown>[], model: import('@jarenjs/emit/model').EmitModel }}
+ */
+export function contractTypeModel(contract, ops, source) {
+  const pub = /** @type {any} */ (publicProjection(contract, { ops: ops.map((o) => o.id) }));
+  const contractDefs = isJsonObject(pub.$defs) ? pub.$defs : {};
+  /** @type {Set<string>} */
+  const taken = new Set(Object.keys(contractDefs));
+  /** @param {string} base */
+  const unique = (base) => {
+    let name = base;
+    for (let n = 2; taken.has(name); n++) name = `${base}${n}`;
+    taken.add(name);
+    return name;
+  };
+  /** @type {Record<string, any>} */
+  const defs = {};
+  /** @type {Record<string, unknown>[]} */
+  const rows = [];
+  for (let i = 0; i < ops.length; i++) {
+    const op = ops[i];
+    const base = pascal(op.id);
+    let input = 'null';
+    if (op.input !== null) {
+      input = unique(`${base}Input`);
+      setObjectMember(defs, input, op.input.schema);
+    }
+    const output = unique(`${base}Output`);
+    setObjectMember(defs, output, op.output.schema);
+    const codes = Object.keys(op.errors);
+    /** @type {Record<string, string | null>} */
+    const details = {};
+    for (let j = 0; j < codes.length; j++) {
+      const decl = op.errors[codes[j]];
+      if (decl.schema === null) {
+        setObjectMember(details, codes[j], null);
+        continue;
+      }
+      const name = unique(`${base}${pascal(codes[j])}Details`);
+      setObjectMember(defs, name, decl.schema);
+      setObjectMember(details, codes[j], name);
+    }
+    rows.push({ id: op.id, kind: op.kind, input, output, errors: codes, details, opaque: op.http.opaque });
+  }
+  const names = Object.keys(contractDefs);
+  for (let i = 0; i < names.length; i++) setObjectMember(defs, names[i], contractDefs[names[i]]);
+  const model = compileEmitModel({ $defs: defs }, { name: 'Contract', source });
+  const declarations = model.declarations.filter((d) => d.name !== model.root);
+  const types = renderTypeScript({ ...model, declarations }, { banner: false });
+  return { types, rows, model: { ...model, declarations } };
+}
+
+/**
+ * Project a compiled contract to TypeScript declarations: the operation
+ * types, `Operations`, `UrlOperations`, `Meta`, `WireError`, `Outcome<T>`,
+ * `InvokeContext`, `Client`, `Failure`, `HandlerContext`, `Handlers`.
+ * @param {Contract} contract
+ * @param {TypeScriptOptions} [options]
+ * @returns {string} TypeScript source (`.d.ts`)
+ * @throws {ContractHostError} `JC1008` — not a compiled contract, or a malformed option
+ * @example
+ * writeFileSync('shop.d.ts', toTypeScript(contract));
+ * // import type { Client, Operations } from './shop.js';
+ */
+export function toTypeScript(contract, options = {}) {
+  if (!isJsonObject(options)) throw new ContractHostError('JC1008', 'toTypeScript: options must be an object');
+  const ops = retainedOperations(contract, undefined, 'toTypeScript');
+  const banner = options.banner === undefined ? true : options.banner;
+  if (typeof banner !== 'boolean') throw new ContractHostError('JC1008', 'toTypeScript: options.banner must be a boolean');
+  const source = contract.id === null ? 'a jaren-contract document' : `the jaren-contract '${contract.id}'`;
+  const { types, rows } = contractTypeModel(contract, ops, source);
+  return render({
+    // a newline in the id could end the line comment; the grammar forbids
+    // one, the replacement is the belt to that brace
+    banner: banner ? `// Generated by @jarenjs/contract from ${source.replace(/[\r\n\u2028\u2029]+/g, ' ')}.\n// Do not edit: regenerate instead.\n\n` : '',
+    types,
+    operations: rows,
+  });
+}

package/src/project/typescript.jtlt.json

@@ -0,0 +1,72 @@
+{
+  "$jtlt": "0.1",
+  "output": "text",
+  "rules": [
+    {
+      "match": "$",
+      "body": [
+        "$.banner",
+        "$.types",
+        "/** Every invokable public operation by id: its kind, input and output types, and the error codes it declares. */\n",
+        "export interface Operations {\n",
+        [{ "$apply": ["$.operations[?@.opaque == false]", "op"] }],
+        "}\n\n",
+        "/** Every public operation by id — opaque ones included — with its input type, for `Client.url`. */\n",
+        "export interface UrlOperations {\n",
+        [{ "$apply": ["$.operations[*]", "url"] }],
+        "}\n\n",
+        "/** The correlation members of every outcome: the caller's attempt id (never read from a response), the server's trace, the contract revision, the entity tag and whether the answer was a 304. A member a binding cannot carry is null (or false for notModified), never omitted. */\n",
+        "export type Meta = { op: string; attempt: unknown; trace: string | null; revision: string | null; etag: string | null; notModified: boolean };\n\n",
+        "/** The error member of a failed outcome: a declared code, a JC2xxx taxonomy code or a JC205x client code; status is null on a binding without statuses; details is null when none. */\n",
+        "export type WireError = { code: string; message: string; status: number | null; details: unknown; retryable: boolean };\n\n",
+        "/** What every invoke resolves to — JSON, never a thrown error: a value, or a failure tagged by kind (a declared or taxonomy error, a transport failure, a peer that broke the contract, a local abort). */\n",
+        "export type Outcome<T> = { ok: true; value: T; meta: Meta } | { ok: false; kind: 'failure' | 'network' | 'contract' | 'cancelled'; error: WireError; meta: Meta };\n\n",
+        "/** Per-call options of invoke. */\n",
+        "export interface InvokeContext { signal?: AbortSignal; attempt?: unknown; idempotencyKey?: string; headers?: Record<string, string>; ifNoneMatch?: string; ifMatch?: string }\n\n",
+        "/** A contract client over any binding, typed by this contract's operations. */\n",
+        "export interface Client {\n",
+        "  invoke<K extends keyof Operations>(op: K, input: Operations[K]['input'], ctx?: InvokeContext): Promise<Outcome<Operations[K]['output']>>;\n",
+        "  url<K extends keyof UrlOperations>(op: K, input: UrlOperations[K]): string;\n",
+        "  close(): void;\n",
+        "}\n\n",
+        "/** A declared failure a handler returns (ctx.fail): the declared code, the catalog parameters, the wire details and whether the caller may retry (null defers to the operation's retry policy). */\n",
+        "export type Failure = { code: string; params: Readonly<Record<string, unknown>>; details: unknown; retryable: boolean | null };\n\n",
+        "/** The per-request context a server binding hands a handler. */\n",
+        "export interface HandlerContext {\n",
+        "  op: unknown;\n",
+        "  trace: string;\n",
+        "  method: string;\n",
+        "  path: string;\n",
+        "  params: Readonly<Record<string, string>>;\n",
+        "  headers: Readonly<Record<string, string>>;\n",
+        "  body: string | Uint8Array | null;\n",
+        "  signal: AbortSignal | null;\n",
+        "  idempotency: Readonly<{ key: string; scope: string }> | null;\n",
+        "  fail(code: string, params?: Record<string, unknown>, details?: unknown, options?: { retryable?: boolean }): Failure;\n",
+        "  etag(tag: string, options?: { strong?: boolean }): void;\n",
+        "  status(status: number): void;\n",
+        "}\n\n",
+        "/** The typed handler table of a server binding: one handler per invokable operation, answering the output, a declared failure, or a promise of either. */\n",
+        "export type Handlers = { [K in keyof Operations]: (input: Operations[K]['input'], ctx: HandlerContext) => Operations[K]['output'] | Failure | Promise<Operations[K]['output'] | Failure> };\n"
+      ]
+    },
+    {
+      "mode": "op",
+      "body": [
+        "  '", "$.id", "': { kind: '", "$.kind", "'; input: ", "$.input", "; output: ", "$.output", "; errors: ",
+        {
+          "$if": [
+            { "$exists": "$.errors[*]" },
+            { "$string-join": [{ "$for": { "e": "$.errors[*]" }, "$return": { "$concat": ["'", "$e", "'"] } }, " | "] },
+            "never"
+          ]
+        },
+        " };\n"
+      ]
+    },
+    {
+      "mode": "url",
+      "body": ["  '", "$.id", "': ", "$.input", ";\n"]
+    }
+  ]
+}