@ts-pf/docs 0.1.0-beta.0

package/README.md

@@ -0,0 +1,90 @@
+# @ts-pf/docs
+
+Opt-in procedure catalog for a ts-pf **contract**. Walks procedures into JSON you can render, snapshot, project to OpenAPI with [`@ts-pf/openapi`](../openapi), or print a portable `Contract` `.d.ts` with [`@ts-pf/codegen`](../codegen).
+
+Agent skill: [`skills/ts-pf-docs/`](skills/ts-pf-docs/). Sync with `npx skills experimental_sync -y`.
+
+This package does **not** serve HTTP, embed Scalar/Swagger, or invent REST paths. The protocol stays POST JSON RPC.
+
+## Attach descriptions
+
+Descriptions live on existing `.meta()`. The helper is sugar so the key stays stable:
+
+```ts
+import { procedure, router } from '@ts-pf/contract'
+import { docs } from '@ts-pf/docs'
+import { z } from 'zod'
+
+export const contract = router({
+  planet: {
+    find: procedure
+      .meta(docs({ description: 'Find a planet by id' }))
+      .meta({ auth: true })
+      .input(z.object({ id: z.number() }))
+      .output(z.object({ id: z.number(), name: z.string() }))
+      .errors({ NOT_FOUND: { status: 404 } }),
+  },
+})
+```
+
+`docs.hidden: true` omits the procedure from `catalog()` unless you pass `filter: () => true`.
+
+## Generate a catalog
+
+```ts
+import { catalog } from '@ts-pf/docs'
+import { contract } from './contract'
+
+const spec = catalog(contract, { prefix: '/rpc' })
+// spec.procedures[0].key === 'planet/find'
+// spec.procedures[0].href === '/rpc/planet/find'
+// spec.protocol.method === 'POST'
+console.log(JSON.stringify(spec, null, 2))
+```
+
+JSON Schema conversion uses Standard JSON Schema (`~standard.jsonSchema`) then TypeBox. Register more with `registerJsonSchemaConverter` (same accept-first pattern as `registerSchemaAdapter`). Unconverted schemas become `{ kind: 'unavailable', reason }` — they do not fail the catalog. `stream()` is `{ kind: 'stream', item? }` (the iterable is not converted; the item schema is). Protocol `VALIDATION` includes its `data.issues` schema on `protocolErrors`.
+
+`walkContract(contract)` is public if you want a markdown/HTML renderer without going through `catalog()`.
+
+## Project the catalog
+
+The catalog is the portable spec (like `.proto` / `openapi.yaml`). Downstream packages print from it — they do not walk a live contract.
+
+OpenAPI 3.1 (polyglot, POST JSON RPC only):
+
+```ts
+import { openapi } from '@ts-pf/openapi'
+
+const spec = openapi(catalog(contract, { prefix: '/rpc' }), {
+  info: { title: 'Planet API', version: '1.0.0' },
+})
+```
+
+Typed `.d.ts` for a split-repo `createClient<Contract>`:
+
+```ts
+import { emit } from '@ts-pf/codegen'
+import { writeFileSync } from 'node:fs'
+
+writeFileSync('contract.d.ts', emit(catalog(contract, { prefix: '/rpc' })))
+```
+
+Serve the JSON in **userland**, outside the RPC prefix (`GET /rpc/...` is a procedure miss, not a spec):
+
+```ts
+if (url.pathname === '/catalog.json') {
+  return Response.json(catalog(contract, { prefix: '/rpc' }))
+}
+const result = await handler.handle(req, { prefix: '/rpc', context })
+```
+
+See [`@ts-pf/openapi`](../openapi) and [`@ts-pf/codegen`](../codegen).
+
+## Not in this package
+
+- OpenAPI / Swagger / Scalar (see [`@ts-pf/openapi`](../openapi))
+- Typed-client `.d.ts` codegen (see [`@ts-pf/codegen`](../codegen))
+- GET `/rpc/docs` or serving the catalog from `FetchHandler`
+- REST `method` / `path` / path params
+- Walking an implemented `app` (pass `contract`)
+- `.docs()` on the contract builder

package/dist/catalog.d.ts

@@ -0,0 +1,15 @@
+import type { ProcedureCatalog } from './types.js';
+export type CatalogOptions = {
+    prefix?: string;
+    schemas?: boolean;
+    filter?: (entry: {
+        path: string[];
+        procedure: {
+            readonly '~pf': {
+                meta: Record<string, unknown>;
+            };
+        };
+    }) => boolean;
+};
+export declare function catalog(contract: unknown, options?: CatalogOptions): ProcedureCatalog;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAKV,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAGnB,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE;QACf,IAAI,EAAE,MAAM,EAAE,CAAA;QACd,SAAS,EAAE;YAAE,QAAQ,CAAC,KAAK,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;aAAE,CAAA;SAAE,CAAA;KACjE,KAAK,OAAO,CAAA;CACd,CAAA;AA2CD,wBAAgB,OAAO,CACrB,QAAQ,EAAE,OAAO,EACjB,OAAO,GAAE,cAAmB,GAC3B,gBAAgB,CA+BlB"}

package/dist/catalog.js

@@ -0,0 +1,146 @@
+import { joinProcedurePath, PROTOCOL_HEADER } from '@ts-pf/http';
+import { PROTOCOL_VERSION, ProtocolErrorCode } from '@ts-pf/protocol';
+import { getDocs } from './docs.js';
+import { tryToJsonSchema } from './json-schema.js';
+import { walkContract } from './walk.js';
+// Must match packages/protocol/PROTOCOL.md (VALIDATION data.issues).
+const VALIDATION_DATA_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['issues'],
+    properties: {
+        issues: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['message', 'path'],
+                properties: {
+                    message: { type: 'string' },
+                    path: {
+                        type: 'array',
+                        items: { type: ['string', 'number'] },
+                    },
+                },
+            },
+        },
+    },
+};
+const PROTOCOL_ERRORS = [
+    { code: ProtocolErrorCode.BAD_REQUEST, status: 400 },
+    {
+        code: ProtocolErrorCode.VALIDATION,
+        status: 422,
+        data: { kind: 'json', jsonSchema: VALIDATION_DATA_SCHEMA },
+    },
+    { code: ProtocolErrorCode.NOT_FOUND, status: 404 },
+    { code: ProtocolErrorCode.INTERNAL, status: 500 },
+    { code: ProtocolErrorCode.METHOD_NOT_ALLOWED, status: 405 },
+    { code: ProtocolErrorCode.PAYLOAD_TOO_LARGE, status: 413 },
+];
+export function catalog(contract, options = {}) {
+    const schemas = options.schemas ?? true;
+    const filter = options.filter ??
+        ((entry) => getDocs(entry.procedure['~pf'].meta)?.hidden !== true);
+    const procedures = [];
+    for (const entry of walkContract(contract)) {
+        if (!filter(entry)) {
+            continue;
+        }
+        procedures.push(toProcedure(entry.path, entry.procedure, options.prefix, schemas));
+    }
+    const result = {
+        catalogVersion: 1,
+        protocol: {
+            name: 'ts-pf',
+            version: PROTOCOL_VERSION,
+            header: { name: PROTOCOL_HEADER, value: PROTOCOL_VERSION },
+            method: 'POST',
+        },
+        protocolErrors: PROTOCOL_ERRORS,
+        procedures,
+    };
+    if (options.prefix !== undefined) {
+        result.prefix = options.prefix;
+    }
+    return result;
+}
+function toProcedure(path, procedure, prefix, schemas) {
+    const def = procedure['~pf'];
+    const docs = getDocs(def.meta);
+    const proc = {
+        path,
+        key: path.join('/'),
+        meta: { ...def.meta },
+        errors: Object.entries(def.errors).map(([code, err]) => {
+            const item = { code };
+            if (err.status !== undefined) {
+                item.status = err.status;
+            }
+            if (err.message !== undefined) {
+                item.message = err.message;
+            }
+            if (schemas && err.data !== undefined) {
+                item.data = toCatalogSchema(err.data, 'output');
+            }
+            return item;
+        }),
+    };
+    if (prefix !== undefined) {
+        proc.href = joinProcedurePath(prefix, path);
+    }
+    if (docs !== undefined) {
+        proc.docs = docs;
+    }
+    if (schemas) {
+        if (def.input !== undefined) {
+            proc.input = toCatalogSchema(def.input, 'input');
+        }
+        if (def.output !== undefined) {
+            proc.output = toCatalogSchema(def.output, 'output');
+        }
+    }
+    return proc;
+}
+function isTsPfStream(schema) {
+    return (typeof schema === 'object' &&
+        schema !== null &&
+        '~standard' in schema &&
+        schema['~standard']?.vendor ===
+            'ts-pf');
+}
+function streamItem(schema) {
+    if (typeof schema !== 'object' ||
+        schema === null ||
+        !('~pfStream' in schema)) {
+        return undefined;
+    }
+    const brand = schema['~pfStream'];
+    if (typeof brand !== 'object' || brand === null || !('item' in brand)) {
+        return undefined;
+    }
+    return brand.item;
+}
+function toCatalogSchema(schema, io) {
+    if (isTsPfStream(schema)) {
+        const result = { kind: 'stream', vendor: 'ts-pf' };
+        const item = streamItem(schema);
+        if (item !== undefined) {
+            result.item = toCatalogSchema(item, io);
+        }
+        return result;
+    }
+    const converted = tryToJsonSchema(schema, { io });
+    if (converted.ok) {
+        const result = {
+            kind: 'json',
+            jsonSchema: converted.schema,
+        };
+        if (converted.vendor !== undefined) {
+            result.vendor = converted.vendor;
+        }
+        return result;
+    }
+    return { kind: 'unavailable', reason: converted.reason };
+}
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACrE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAQlD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAWxC,qEAAqE;AACrE,MAAM,sBAAsB,GAAe;IACzC,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,QAAQ,EAAE,CAAC,QAAQ,CAAC;IACpB,UAAU,EAAE;QACV,MAAM,EAAE;YACN,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,oBAAoB,EAAE,KAAK;gBAC3B,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;gBAC7B,UAAU,EAAE;oBACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBAC3B,IAAI,EAAE;wBACJ,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE;qBACtC;iBACF;aACF;SACF;KACF;CACF,CAAA;AAED,MAAM,eAAe,GAIhB;IACH,EAAE,IAAI,EAAE,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE;IACpD;QACE,IAAI,EAAE,iBAAiB,CAAC,UAAU;QAClC,MAAM,EAAE,GAAG;QACX,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,EAAE;KAC3D;IACD,EAAE,IAAI,EAAE,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE;IAClD,EAAE,IAAI,EAAE,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE;IACjD,EAAE,IAAI,EAAE,iBAAiB,CAAC,kBAAkB,EAAE,MAAM,EAAE,GAAG,EAAE;IAC3D,EAAE,IAAI,EAAE,iBAAiB,CAAC,iBAAiB,EAAE,MAAM,EAAE,GAAG,EAAE;CAC3D,CAAA;AAED,MAAM,UAAU,OAAO,CACrB,QAAiB,EACjB,UAA0B,EAAE;IAE5B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,CAAA;IACvC,MAAM,MAAM,GACV,OAAO,CAAC,MAAM;QACd,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,CAAA;IAEpE,MAAM,UAAU,GAAuB,EAAE,CAAA;IACzC,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACnB,SAAQ;QACV,CAAC;QACD,UAAU,CAAC,IAAI,CACb,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAClE,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAqB;QAC/B,cAAc,EAAE,CAAC;QACjB,QAAQ,EAAE;YACR,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,gBAAgB;YACzB,MAAM,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,gBAAgB,EAAE;YAC1D,MAAM,EAAE,MAAM;SACf;QACD,cAAc,EAAE,eAAe;QAC/B,UAAU;KACX,CAAA;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;IAChC,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,WAAW,CAClB,IAAc,EACd,SAUC,EACD,MAA0B,EAC1B,OAAgB;IAEhB,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC9B,MAAM,IAAI,GAAqB;QAC7B,IAAI;QACJ,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QACnB,IAAI,EAAE,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE;YACrD,MAAM,IAAI,GAAiB,EAAE,IAAI,EAAE,CAAA;YACnC,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC7B,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAA;YAC1B,CAAC;YACD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC9B,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAA;YAC5B,CAAC;YACD,IAAI,OAAO,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACtC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;YACjD,CAAC;YACD,OAAO,IAAI,CAAA;QACb,CAAC,CAAC;KACH,CAAA;IACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAC7C,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QAClD,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;QACrD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,YAAY,CAAC,MAAe;IACnC,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,WAAW,IAAI,MAAM;QACpB,MAAgD,CAAC,WAAW,CAAC,EAAE,MAAM;YACpE,OAAO,CACV,CAAA;AACH,CAAC;AAED,SAAS,UAAU,CAAC,MAAe;IACjC,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,CAAC,CAAC,WAAW,IAAI,MAAM,CAAC,EACxB,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,KAAK,GAAI,MAA+C,CAAC,WAAW,CAAC,CAAA;IAC3E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;QACtE,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAA;AACnB,CAAC;AAED,SAAS,eAAe,CACtB,MAAe,EACf,EAAsB;IAEtB,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,MAAM,MAAM,GAAkB,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;QACjE,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;QAC/B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QACzC,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;IACD,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;IACjD,IAAI,SAAS,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,MAAM,GAAkB;YAC5B,IAAI,EAAE,MAAM;YACZ,UAAU,EAAE,SAAS,CAAC,MAAM;SAC7B,CAAA;QACD,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACnC,MAAM,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAA;QAClC,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,CAAA;AAC1D,CAAC"}

package/dist/converters/standard.d.ts

@@ -0,0 +1,3 @@
+import type { JsonSchemaConverter } from '../json-schema.js';
+export declare const standardJsonSchemaConverter: JsonSchemaConverter;
+//# sourceMappingURL=standard.d.ts.map

package/dist/converters/standard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.d.ts","sourceRoot":"","sources":["../../src/converters/standard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAQ5D,eAAO,MAAM,2BAA2B,EAAE,mBAgCzC,CAAA"}

package/dist/converters/standard.js

@@ -0,0 +1,25 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export const standardJsonSchemaConverter = {
+    vendor: 'standard-json-schema',
+    accept(schema) {
+        if (!isRecord(schema) || !('~standard' in schema)) {
+            return false;
+        }
+        const standard = schema['~standard'];
+        if (!isRecord(standard) || !isRecord(standard.jsonSchema)) {
+            return false;
+        }
+        return (typeof standard.jsonSchema.input === 'function' &&
+            typeof standard.jsonSchema.output === 'function');
+    },
+    convert(schema, options) {
+        const standard = schema['~standard'];
+        const fn = options.io === 'input'
+            ? standard.jsonSchema.input
+            : standard.jsonSchema.output;
+        return fn({ target: options.target ?? 'draft-2020-12' });
+    },
+};
+//# sourceMappingURL=standard.js.map

package/dist/converters/standard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.js","sourceRoot":"","sources":["../../src/converters/standard.ts"],"names":[],"mappings":"AAEA,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAA;AACpD,CAAC;AAID,MAAM,CAAC,MAAM,2BAA2B,GAAwB;IAC9D,MAAM,EAAE,sBAAsB;IAC9B,MAAM,CAAC,MAAM;QACX,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,IAAI,MAAM,CAAC,EAAE,CAAC;YAClD,OAAO,KAAK,CAAA;QACd,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,CAAA;QACpC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1D,OAAO,KAAK,CAAA;QACd,CAAC;QACD,OAAO,CACL,OAAO,QAAQ,CAAC,UAAU,CAAC,KAAK,KAAK,UAAU;YAC/C,OAAO,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,UAAU,CACjD,CAAA;IACH,CAAC;IACD,OAAO,CAAC,MAAM,EAAE,OAAO;QACrB,MAAM,QAAQ,GACZ,MAQD,CAAC,WAAW,CAAC,CAAA;QACd,MAAM,EAAE,GACN,OAAO,CAAC,EAAE,KAAK,OAAO;YACpB,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK;YAC3B,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAA;QAChC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,eAAe,EAAE,CAAC,CAAA;IAC1D,CAAC;CACF,CAAA"}

package/dist/converters/typebox.d.ts

@@ -0,0 +1,3 @@
+import type { JsonSchemaConverter } from '../json-schema.js';
+export declare const typeboxJsonSchemaConverter: JsonSchemaConverter;
+//# sourceMappingURL=typebox.d.ts.map

package/dist/converters/typebox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typebox.d.ts","sourceRoot":"","sources":["../../src/converters/typebox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAE5D,eAAO,MAAM,0BAA0B,EAAE,mBAaxC,CAAA"}

package/dist/converters/typebox.js

@@ -0,0 +1,13 @@
+export const typeboxJsonSchemaConverter = {
+    vendor: 'typebox',
+    accept(schema) {
+        return (typeof schema === 'object' &&
+            schema !== null &&
+            '~kind' in schema &&
+            typeof schema['~kind'] === 'string');
+    },
+    convert(schema) {
+        return JSON.parse(JSON.stringify(schema));
+    },
+};
+//# sourceMappingURL=typebox.js.map

package/dist/converters/typebox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typebox.js","sourceRoot":"","sources":["../../src/converters/typebox.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,0BAA0B,GAAwB;IAC7D,MAAM,EAAE,SAAS;IACjB,MAAM,CAAC,MAAM;QACX,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;YAC1B,MAAM,KAAK,IAAI;YACf,OAAO,IAAI,MAAM;YACjB,OAAQ,MAA+B,CAAC,OAAO,CAAC,KAAK,QAAQ,CAC9D,CAAA;IACH,CAAC;IACD,OAAO,CAAC,MAAM;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAA4B,CAAA;IACtE,CAAC;CACF,CAAA"}

package/dist/docs.d.ts

@@ -0,0 +1,13 @@
+export declare const DOCS_KEY: "docs";
+export interface DocsMeta {
+    description?: string;
+    summary?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    hidden?: boolean;
+}
+export declare function docs(value: DocsMeta): {
+    [DOCS_KEY]: DocsMeta;
+};
+export declare function getDocs(meta: Record<string, unknown>): DocsMeta | undefined;
+//# sourceMappingURL=docs.d.ts.map

package/dist/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,QAAQ,EAAG,MAAe,CAAA;AAEvC,MAAM,WAAW,QAAQ;IACvB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG;IAAE,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAE,CAE9D;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,GAAG,SAAS,CAM3E"}

package/dist/docs.js

@@ -0,0 +1,12 @@
+export const DOCS_KEY = 'docs';
+export function docs(value) {
+    return { [DOCS_KEY]: value };
+}
+export function getDocs(meta) {
+    const value = meta[DOCS_KEY];
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+//# sourceMappingURL=docs.js.map

package/dist/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAe,CAAA;AAUvC,MAAM,UAAU,IAAI,CAAC,KAAe;IAClC,OAAO,EAAE,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAA;AAC9B,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAA6B;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,KAAiB,CAAA;AAC1B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { type CatalogOptions, catalog } from './catalog.js';
+export { DOCS_KEY, type DocsMeta, docs, getDocs } from './docs.js';
+export { type JsonSchemaConverter, type JsonSchemaConvertOptions, registerJsonSchemaConverter, toJsonSchema, tryToJsonSchema, } from './json-schema.js';
+export type { CatalogError, CatalogProcedure, CatalogSchema, JsonSchema, ProcedureCatalog, } from './types.js';
+export { type WalkEntry, walkContract } from './walk.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,QAAQ,EAAE,KAAK,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAClE,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,2BAA2B,EAC3B,YAAY,EACZ,eAAe,GAChB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,KAAK,SAAS,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { catalog } from './catalog.js';
+export { DOCS_KEY, docs, getDocs } from './docs.js';
+export { registerJsonSchemaConverter, toJsonSchema, tryToJsonSchema, } from './json-schema.js';
+export { walkContract } from './walk.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3D,OAAO,EAAE,QAAQ,EAAiB,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAClE,OAAO,EAGL,2BAA2B,EAC3B,YAAY,EACZ,eAAe,GAChB,MAAM,kBAAkB,CAAA;AAQzB,OAAO,EAAkB,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/json-schema.d.ts

@@ -0,0 +1,21 @@
+import type { JsonSchema } from './types.js';
+export type JsonSchemaConvertOptions = {
+    io: 'input' | 'output';
+    target?: 'draft-2020-12';
+};
+export interface JsonSchemaConverter {
+    vendor: string;
+    accept(schema: unknown): boolean;
+    convert(schema: unknown, options: JsonSchemaConvertOptions): JsonSchema;
+}
+export declare function registerJsonSchemaConverter(converter: JsonSchemaConverter): void;
+export declare function toJsonSchema(schema: unknown, options: JsonSchemaConvertOptions): JsonSchema;
+export declare function tryToJsonSchema(schema: unknown, options: JsonSchemaConvertOptions): {
+    ok: true;
+    schema: JsonSchema;
+    vendor: string;
+} | {
+    ok: false;
+    reason: string;
+};
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../src/json-schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,MAAM,MAAM,wBAAwB,GAAG;IACrC,EAAE,EAAE,OAAO,GAAG,QAAQ,CAAA;IACtB,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB,CAAA;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAA;IAChC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,GAAG,UAAU,CAAA;CACxE;AAQD,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,mBAAmB,GAC7B,IAAI,CAEN;AAED,wBAAgB,YAAY,CAC1B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,wBAAwB,GAChC,UAAU,CAkBZ;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,wBAAwB,GAE/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAqBhC"}

package/dist/json-schema.js

@@ -0,0 +1,50 @@
+import { standardJsonSchemaConverter } from './converters/standard.js';
+import { typeboxJsonSchemaConverter } from './converters/typebox.js';
+const customConverters = [];
+const builtinConverters = [
+    standardJsonSchemaConverter,
+    typeboxJsonSchemaConverter,
+];
+export function registerJsonSchemaConverter(converter) {
+    customConverters.unshift(converter);
+}
+export function toJsonSchema(schema, options) {
+    const resolved = {
+        io: options.io,
+        target: options.target ?? 'draft-2020-12',
+    };
+    for (const converter of customConverters) {
+        if (converter.accept(schema)) {
+            return converter.convert(schema, resolved);
+        }
+    }
+    for (const converter of builtinConverters) {
+        if (converter.accept(schema)) {
+            return converter.convert(schema, resolved);
+        }
+    }
+    throw new Error('No JSON Schema converter. Use a Standard JSON Schema library (Zod 4.2+, ArkType), TypeBox, or registerJsonSchemaConverter.');
+}
+export function tryToJsonSchema(schema, options) {
+    try {
+        const resolved = {
+            io: options.io,
+            target: options.target ?? 'draft-2020-12',
+        };
+        for (const converter of [...customConverters, ...builtinConverters]) {
+            if (converter.accept(schema)) {
+                return {
+                    ok: true,
+                    schema: converter.convert(schema, resolved),
+                    vendor: converter.vendor,
+                };
+            }
+        }
+        return { ok: false, reason: 'No JSON Schema converter matched' };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'JSON Schema conversion failed';
+        return { ok: false, reason: message };
+    }
+}
+//# sourceMappingURL=json-schema.js.map

package/dist/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","sourceRoot":"","sources":["../src/json-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAA;AACtE,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAA;AAcpE,MAAM,gBAAgB,GAA0B,EAAE,CAAA;AAClD,MAAM,iBAAiB,GAA0B;IAC/C,2BAA2B;IAC3B,0BAA0B;CAC3B,CAAA;AAED,MAAM,UAAU,2BAA2B,CACzC,SAA8B;IAE9B,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;AACrC,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,MAAe,EACf,OAAiC;IAEjC,MAAM,QAAQ,GAA6B;QACzC,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,eAAe;KAC1C,CAAA;IACD,KAAK,MAAM,SAAS,IAAI,gBAAgB,EAAE,CAAC;QACzC,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;QAC5C,CAAC;IACH,CAAC;IACD,KAAK,MAAM,SAAS,IAAI,iBAAiB,EAAE,CAAC;QAC1C,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;QAC5C,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CACb,4HAA4H,CAC7H,CAAA;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,MAAe,EACf,OAAiC;IAIjC,IAAI,CAAC;QACH,MAAM,QAAQ,GAA6B;YACzC,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,eAAe;SAC1C,CAAA;QACD,KAAK,MAAM,SAAS,IAAI,CAAC,GAAG,gBAAgB,EAAE,GAAG,iBAAiB,CAAC,EAAE,CAAC;YACpE,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7B,OAAO;oBACL,EAAE,EAAE,IAAI;oBACR,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC;oBAC3C,MAAM,EAAE,SAAS,CAAC,MAAM;iBACzB,CAAA;YACH,CAAC;QACH,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kCAAkC,EAAE,CAAA;IAClE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,+BAA+B,CAAA;QAC1E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IACvC,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+import type { DocsMeta } from './docs.js';
+export type JsonSchema = Record<string, unknown>;
+export type CatalogSchema = {
+    kind: 'json';
+    jsonSchema: JsonSchema;
+    vendor?: string;
+} | {
+    kind: 'stream';
+    vendor: 'ts-pf';
+    item?: CatalogSchema;
+} | {
+    kind: 'unavailable';
+    reason: string;
+    vendor?: string;
+};
+export type CatalogError = {
+    code: string;
+    status?: number;
+    message?: string;
+    data?: CatalogSchema;
+};
+export type CatalogProcedure = {
+    path: string[];
+    key: string;
+    href?: string;
+    docs?: DocsMeta;
+    meta: Record<string, unknown>;
+    input?: CatalogSchema;
+    output?: CatalogSchema;
+    errors: CatalogError[];
+};
+export type ProcedureCatalog = {
+    catalogVersion: 1;
+    protocol: {
+        name: 'ts-pf';
+        version: string;
+        header: {
+            name: string;
+            value: string;
+        };
+        method: 'POST';
+    };
+    prefix?: string;
+    protocolErrors: ReadonlyArray<{
+        code: string;
+        status: number;
+        data?: CatalogSchema;
+    }>;
+    procedures: CatalogProcedure[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAEzC,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEhD,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,aAAa,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAE5D,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,aAAa,CAAA;CACrB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,EAAE,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,cAAc,EAAE,CAAC,CAAA;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,OAAO,CAAA;QACb,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAA;QACvC,MAAM,EAAE,MAAM,CAAA;KACf,CAAA;IACD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,aAAa,CAAC;QAC5B,IAAI,EAAE,MAAM,CAAA;QACZ,MAAM,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,aAAa,CAAA;KACrB,CAAC,CAAA;IACF,UAAU,EAAE,gBAAgB,EAAE,CAAA;CAC/B,CAAA"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/walk.d.ts

@@ -0,0 +1,7 @@
+import { type ContractProcedure } from '@ts-pf/contract';
+export type WalkEntry = {
+    path: string[];
+    procedure: ContractProcedure;
+};
+export declare function walkContract(contract: unknown): WalkEntry[];
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAuB,MAAM,iBAAiB,CAAA;AAE7E,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,SAAS,EAAE,iBAAiB,CAAA;CAC7B,CAAA;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,EAAE,CAI3D"}

package/dist/walk.js

@@ -0,0 +1,23 @@
+import { isContractProcedure } from '@ts-pf/contract';
+export function walkContract(contract) {
+    const entries = [];
+    visit(contract, [], entries);
+    return entries;
+}
+function visit(node, path, entries) {
+    if (isContractProcedure(node)) {
+        entries.push({ path, procedure: node });
+        return;
+    }
+    if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+        const location = path.length > 0 ? path.join('.') : '<root>';
+        throw new Error(`Contract router leaf at "${location}" is not a procedure`);
+    }
+    for (const [key, child] of Object.entries(node)) {
+        if (key === '~pf') {
+            continue;
+        }
+        visit(child, [...path, key], entries);
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAO7E,MAAM,UAAU,YAAY,CAAC,QAAiB;IAC5C,MAAM,OAAO,GAAgB,EAAE,CAAA;IAC/B,KAAK,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,CAAC,CAAA;IAC5B,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,SAAS,KAAK,CAAC,IAAa,EAAE,IAAc,EAAE,OAAoB;IAChE,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACvC,OAAM;IACR,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;QAC5D,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,sBAAsB,CAAC,CAAA;IAC7E,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;YAClB,SAAQ;QACV,CAAC;QACD,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,CAAA;IACvC,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ts-pf/docs",
+  "version": "0.1.0-beta.0",
+  "description": "Opt-in procedure catalog from a contract (docs, catalog)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crobinson42/ts-pf.git",
+    "directory": "packages/docs"
+  },
+  "homepage": "https://github.com/crobinson42/ts-pf/tree/main/packages/docs#readme",
+  "bugs": {
+    "url": "https://github.com/crobinson42/ts-pf/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "biome check src tests"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.0.0",
+    "@ts-pf/contract": "0.1.0-beta.0",
+    "@ts-pf/http": "0.1.0-beta.0",
+    "@ts-pf/protocol": "0.1.0-beta.0"
+  },
+  "peerDependencies": {
+    "typebox": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ts-pf/stream": "0.1.0-beta.0",
+    "typebox": "^1.3.24",
+    "zod": "^4.0.0"
+  }
+}

package/skills/ts-pf-docs/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: ts-pf-docs
+description: Use when building a ts-pf procedure catalog with docs(), catalog(), walkContract, or registerJsonSchemaConverter. Triggers: @ts-pf/docs, catalog(), docs(), walkContract.
+---
+
+# @ts-pf/docs
+
+Opt-in procedure catalog from a **contract**. Does not serve HTTP.
+
+Install: `npm i @ts-pf/docs@beta`
+
+Link for agents: `npx skills experimental_sync -y`
+
+## Do
+
+```ts
+import { docs, catalog } from '@ts-pf/docs'
+
+procedure.meta(docs({ description: 'Find a planet by id' }))
+const spec = catalog(contract, { prefix: '/rpc' })
+```
+
+Serve JSON in userland, outside the RPC prefix:
+
+```ts
+if (url.pathname === '/catalog.json') {
+  return Response.json(catalog(contract, { prefix: '/rpc' }))
+}
+```
+
+`docs.hidden: true` omits the procedure unless `filter: () => true`. Unconverted schemas become `{ kind: 'unavailable' }` — they do not fail the catalog.
+
+## API
+
+- `docs`, `getDocs`, `catalog`, `walkContract`
+- `registerJsonSchemaConverter`, `toJsonSchema`
+
+## Pair with
+
+- OpenAPI: `ts-pf-openapi`
+- Split-repo `.d.ts`: `ts-pf-codegen`
+- Descriptions live on existing `.meta()` — not `.docs()` on the builder
+
+## Don't
+
+- `.docs()` on the contract builder.
+- Serve the catalog from `FetchHandler` (`GET /rpc/...` is a procedure miss).
+- Walk an implemented `app` — pass `contract`.
+- REST `method` / `path` / path params.