@skillsregistry/contracts 1.1.0 → 3.0.0

package/README.md

@@ -4,7 +4,7 @@ Zod schemas + TypeScript types for the SkillsRegistry public API and the
 local-node ↔ mothership contract.
 
 **License:** Apache-2.0. Consumed by both the open-source
-[skillsregistry-local](https://github.com/cogniumhq/skillsregistry-local)
+[SkillsRegistry local](https://github.com/cogniumhq/skillsregistry)
 node and the proprietary mothership. Both sides pin the exact same
 version so no field ever silently drifts.
 
@@ -17,6 +17,14 @@ version so no field ever silently drifts.
 | `@skillsregistry/contracts/responses` | HTTP response envelopes for public REST routes. Depends on `@hono/zod-openapi`. |
 | `@skillsregistry/contracts/upstream` | Local-node → mothership contract: trust scoring, budget, publish, delta sync, error taxonomy. Plain `zod` — no OpenAPI meta. |
 
+## Requirements
+
+Since **3.0.0** the schemas are **zod 4** instances and the OpenAPI modules
+use **`@hono/zod-openapi` 1.x** (which needs `hono` >= 4.10). Consumers must
+be on zod `^4.6.6` (the GHSA-mrhx-c7xc-m3w5 fix) and `@hono/zod-openapi`
+`^1.x`; mixing these schemas with zod 3 or `@hono/zod-openapi` 0.x does not
+type-check and breaks OpenAPI generation. Pin `2.x` to stay on zod 3.
+
 ## Install
 
 ```bash

package/dist/common.d.ts

@@ -1,5 +1,5 @@
 import { z } from '@hono/zod-openapi';
-export declare const SkillIdParam: z.ZodString;
+export declare const SkillIdParam: z.ZodGUID;
 export declare const SkillSlugParam: z.ZodString;
 export declare const VersionParam: z.ZodString;
 export declare const HoursQuery: z.ZodDefault<z.ZodOptional<z.ZodString>>;

package/dist/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAEtC,eAAO,MAAM,YAAY,aAGvB,CAAC;AAEH,eAAO,MAAM,cAAc,aAGzB,CAAC;AAEH,eAAO,MAAM,YAAY,aAGvB,CAAC;AAEH,eAAO,MAAM,UAAU,0CAI6C,CAAC;AAErE,eAAO,MAAM,UAAU,0CAI8C,CAAC;AAEtE,eAAO,MAAM,WAAW,0CAI4C,CAAC"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAEtC,eAAO,MAAM,YAAY,WAGvB,CAAC;AAEH,eAAO,MAAM,cAAc,aAGzB,CAAC;AAEH,eAAO,MAAM,YAAY,aAGvB,CAAC;AAEH,eAAO,MAAM,UAAU,0CAI6C,CAAC;AAErE,eAAO,MAAM,UAAU,0CAI8C,CAAC;AAEtE,eAAO,MAAM,WAAW,0CAI4C,CAAC"}

package/dist/common.js

@@ -2,7 +2,7 @@
 // Common OpenAPI Schemas — Shared parameters and query schemas
 // ══════════════════════════════════════════════════════════════════════════════
 import { z } from '@hono/zod-openapi';
-export const SkillIdParam = z.string().uuid().openapi({
+export const SkillIdParam = z.guid().openapi({
     param: { name: 'id', in: 'path' },
     example: '550e8400-e29b-41d4-a716-446655440000',
 });

package/dist/common.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.js","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,+DAA+D;AAC/D,iFAAiF;AAEjF,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAEtC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC;IACpD,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE;IACjC,OAAO,EAAE,sCAAsC;CAChD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC;IAC/C,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE;IACnC,OAAO,EAAE,sBAAsB;CAChC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC;IAC7C,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE;IACtC,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,OAAO,CAAC,IAAI,CAAC;KACb,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;AAErE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,OAAO,CAAC,KAAK,CAAC;KACd,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;AAEtE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,OAAO,CAAC,GAAG,CAAC;KACZ,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC"}
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,+DAA+D;AAC/D,iFAAiF;AAEjF,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAC;AAEtC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC;IAC3C,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE;IACjC,OAAO,EAAE,sCAAsC;CAChD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC;IAC/C,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE;IACnC,OAAO,EAAE,sBAAsB;CAChC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC;IAC7C,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE;IACtC,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,OAAO,CAAC,IAAI,CAAC;KACb,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;AAErE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,OAAO,CAAC,KAAK,CAAC;KACd,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;AAEtE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,OAAO,CAAC,GAAG,CAAC;KACZ,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC"}

package/dist/openapi.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=openapi.test.d.ts.map

package/dist/openapi.test.d.ts.map

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

package/dist/openapi.test.js

@@ -0,0 +1,71 @@
+// ══════════════════════════════════════════════════════════════════════════════
+// OpenAPI generation smoke — contracts schemas inside an OpenAPIHono app
+// ══════════════════════════════════════════════════════════════════════════════
+//
+// Guards the 3.0.0 move to zod 4 + @hono/zod-openapi 1.x: the `.openapi()`
+// metadata on `./common` and `./responses` must still produce named
+// components and typed params, and the plain-zod `./upstream` schemas must
+// still be usable as request bodies in a consumer's OpenAPI route (the
+// mothership wraps them that way).
+import { describe, it, expect } from 'vitest';
+import { OpenAPIHono, createRoute, z } from '@hono/zod-openapi';
+import { SkillIdParam, LimitQuery, SkillDetailSchema, ErrorResponseSchema, SearchRequestSchema, SearchResponseSchema, } from './index.js';
+describe('OpenAPI document generation', () => {
+    const doc = (() => {
+        const a = new OpenAPIHono();
+        a.openapi(createRoute({
+            method: 'get',
+            path: '/v1/skills/{id}',
+            request: {
+                params: z.object({ id: SkillIdParam }),
+                query: z.object({ limit: LimitQuery }),
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: SkillDetailSchema } },
+                    description: 'Skill detail',
+                },
+                404: {
+                    content: { 'application/json': { schema: ErrorResponseSchema } },
+                    description: 'Not found',
+                },
+            },
+        }), (c) => c.json({ error: 'not_found' }, 404));
+        a.openapi(createRoute({
+            method: 'post',
+            path: '/v1/search',
+            request: {
+                body: { content: { 'application/json': { schema: SearchRequestSchema } } },
+            },
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: SearchResponseSchema } },
+                    description: 'Search results',
+                },
+            },
+        }), (c) => c.json({}, 200));
+        return a.getOpenAPI31Document({
+            openapi: '3.1.0',
+            info: { title: 'contracts-smoke', version: '0.0.0' },
+        });
+    })();
+    it('registers named components from .openapi("Name")', () => {
+        const names = Object.keys(doc.components?.schemas ?? {});
+        expect(names).toEqual(expect.arrayContaining(['SkillDetail', 'ErrorResponse', 'SearchResponse']));
+    });
+    it('emits the path param and query param with their examples', () => {
+        const op = doc.paths?.['/v1/skills/{id}']?.get;
+        const params = (op?.parameters ?? []);
+        const id = params.find((p) => p.name === 'id');
+        expect(id?.in).toBe('path');
+        expect(id?.schema?.format).toBe('uuid');
+        const limit = params.find((p) => p.name === 'limit');
+        expect(limit?.in).toBe('query');
+    });
+    it('accepts a plain-zod upstream schema as a request body', () => {
+        const body = doc.paths?.['/v1/search']?.post?.requestBody;
+        const props = body?.content['application/json']?.schema.properties ?? {};
+        expect(Object.keys(props)).toEqual(expect.arrayContaining(['query', 'minTrust', 'allowVulnerable', 'limit']));
+    });
+});
+//# sourceMappingURL=openapi.test.js.map

package/dist/openapi.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.test.js","sourceRoot":"","sources":["../src/openapi.test.ts"],"names":[],"mappings":"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"}