@guren/server 2.12.0 → 2.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/{McpServiceProvider-D6D9nhgn.js → McpServiceProvider-BawsYjgN.js} +72 -0
- package/dist/agent/derive.d.ts +155 -0
- package/dist/agent/dispatch.d.ts +123 -0
- package/dist/agent/events.d.ts +80 -0
- package/dist/agent/redact.d.ts +55 -0
- package/dist/agent/scopes.d.ts +115 -0
- package/dist/auth/AuthManager.d.ts +64 -0
- package/dist/auth/RequestAuthContext.d.ts +3 -5
- package/dist/auth/TokenGuard.d.ts +61 -0
- package/dist/auth/api-token.d.ts +25 -5
- package/dist/auth/context.d.ts +24 -0
- package/dist/auth/index.d.ts +5 -2
- package/dist/auth/index.js +2 -2
- package/dist/auth/providers/UserProvider.d.ts +7 -0
- package/dist/auth/types.d.ts +6 -0
- package/dist/{auth-C7sVmYgc.js → auth-BSUc14CD.js} +313 -122
- package/dist/authorization/index.js +1 -1
- package/dist/authorization/middleware.d.ts +28 -1
- package/dist/{authorization-Dbcuc5ZK.js → authorization-CdfbCj8J.js} +119 -12
- package/dist/broadcasting/index.js +1 -1
- package/dist/{broadcasting-Dw-FhyjN.js → broadcasting-BxU-LIfF.js} +2 -45
- package/dist/context-DoD0c7J_.js +26 -0
- package/dist/http/middleware/auth.d.ts +2 -2
- package/dist/http/middleware/capabilities.d.ts +57 -0
- package/dist/http/middleware/csrf.d.ts +3 -0
- package/dist/http/request.d.ts +51 -2
- package/dist/index.d.ts +12 -3
- package/dist/index.js +1015 -84
- package/dist/internal/agent-preflight.d.ts +28 -0
- package/dist/internal/request.d.ts +19 -0
- package/dist/internal/request.js +2 -0
- package/dist/internal/route-path.d.ts +28 -0
- package/dist/internal/route-path.js +33 -0
- package/dist/internal/zod-compat.d.ts +201 -0
- package/dist/internal/zod-compat.js +193 -0
- package/dist/internal/zod-json-schema.d.ts +102 -0
- package/dist/internal/zod-json-schema.js +461 -0
- package/dist/mcp/create-mcp-server.d.ts +29 -0
- package/dist/mcp/index.js +1 -1
- package/dist/mvc/Controller.d.ts +46 -0
- package/dist/mvc/Router.d.ts +53 -0
- package/dist/request-CRVuIiQr.js +78 -0
- package/dist/runtime/index.js +5 -2
- package/dist/{vite-manifest-BKuV1kfv.js → vite-manifest-BGfWbPYp.js} +1 -1
- package/package.json +17 -1
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The wire protocol of an agent preflight (RFC 0016 §5.4), in a leaf module
|
|
3
|
+
* so the two halves can share it without depending on each other.
|
|
4
|
+
*
|
|
5
|
+
* `Router` mounts the seam that answers a preflight; `agent/dispatch` builds
|
|
6
|
+
* the request that asks for one and reads the answer back. Putting the names
|
|
7
|
+
* in either of those would make one import the other — today only
|
|
8
|
+
* `dispatch → Router` exists, and the day `Router` needs anything from
|
|
9
|
+
* `agent/` that becomes a cycle.
|
|
10
|
+
*
|
|
11
|
+
* Not exported from the package index: an external dispatcher asks for a
|
|
12
|
+
* preflight through `BuildToolRequestOptions.preflight`, and the header
|
|
13
|
+
* spelling is this seam's business, not published API.
|
|
14
|
+
*/
|
|
15
|
+
/** Request header asking the route for a verdict instead of an execution. */
|
|
16
|
+
export declare const AGENT_PREFLIGHT_HEADER = "X-Guren-Agent-Preflight";
|
|
17
|
+
/**
|
|
18
|
+
* Response header marking a body as a preflight verdict rather than the
|
|
19
|
+
* route's own output.
|
|
20
|
+
*
|
|
21
|
+
* Load-bearing in two places that would otherwise mistake one for the other:
|
|
22
|
+
* a route's `output` schema validation (which would reject the verdict and
|
|
23
|
+
* turn it into a 500) and the MCP response mapping (which would advertise the
|
|
24
|
+
* verdict as the tool's `structuredContent`, so an SDK client validates it
|
|
25
|
+
* against the tool's output schema and throws). Both are answering the same
|
|
26
|
+
* question — "is this the route's result?" — so both read the same marker.
|
|
27
|
+
*/
|
|
28
|
+
export declare const AGENT_PREFLIGHT_VERDICT_HEADER = "X-Guren-Agent-Preflight-Verdict";
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one request-body parsing rule: which content types are read, how a
|
|
3
|
+
* repeated form field collapses, and what an unreadable body falls back to.
|
|
4
|
+
*
|
|
5
|
+
* `@guren/testing`'s controller mock reads it through this subpath so a
|
|
6
|
+
* mocked controller and a real one cannot disagree about a body. The mock
|
|
7
|
+
* holds a `Request` rather than a Hono context, so it adapts — it wraps the
|
|
8
|
+
* request in a `HonoRequest` and calls straight into these — rather than
|
|
9
|
+
* reimplementing the decision. A second copy is how the two came to disagree
|
|
10
|
+
* on an uppercase media type, on a `;`-parameterized one, and on a repeated
|
|
11
|
+
* `field[]`.
|
|
12
|
+
*
|
|
13
|
+
* Internal by the rules in `contributing/api-stability.md` — reachable only
|
|
14
|
+
* through a deep import under `internal/`, never re-exported from an index.
|
|
15
|
+
* `parseRequestPayload` beside it *is* public and stays exported from the
|
|
16
|
+
* package root; this subpath exists for the two that are not.
|
|
17
|
+
*/
|
|
18
|
+
export { parseRequestBody, asRecord } from '../http/request.js';
|
|
19
|
+
export type { RequestBodyContext } from '../http/request.js';
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one Hono route-path lexing rule, shared by every surface that has to say
|
|
3
|
+
* what parameters a path declares: the router's own substitution and binding
|
|
4
|
+
* scanners, RFC 0016's agent tool input, and `@guren/openapi`'s path template
|
|
5
|
+
* and parameter list.
|
|
6
|
+
*
|
|
7
|
+
* Internal by the rules in `contributing/api-stability.md` — reachable only
|
|
8
|
+
* through a deep import under `internal/`, never re-exported from an index.
|
|
9
|
+
* It lives in `@guren/server` and is re-exported by
|
|
10
|
+
* `@guren/core/internal/route-path` for the same build-order reason the
|
|
11
|
+
* JSON Schema walker beside it does: core's index is
|
|
12
|
+
* `export * from '@guren/server'`, so a server module cannot import a core
|
|
13
|
+
* one.
|
|
14
|
+
*
|
|
15
|
+
* It exists because two lexers is how two surfaces come to describe one path
|
|
16
|
+
* differently. They did: `@guren/openapi` carried its own copy with the `*`
|
|
17
|
+
* outside the capture group, so `/files/:name*` yielded the parameter `name`
|
|
18
|
+
* there and `name*` — what Hono actually registers — everywhere else. What
|
|
19
|
+
* *does* legitimately differ is rendering, not lexing, and that difference now
|
|
20
|
+
* lives at the one call site that needs it (see `stripExplodeModifier`).
|
|
21
|
+
*/
|
|
22
|
+
export declare const PATH_PARAM_PATTERN: RegExp;
|
|
23
|
+
/**
|
|
24
|
+
* Param labels in path order, exactly as Hono registers them: constraints
|
|
25
|
+
* dropped, a trailing `*` kept (it is part of the name), a trailing `?`
|
|
26
|
+
* dropped (it is not).
|
|
27
|
+
*/
|
|
28
|
+
export declare function extractPathParamNames(path: string): string[];
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
//#region src/internal/route-path.ts
|
|
2
|
+
/**
|
|
3
|
+
* The one Hono route-path lexing rule, shared by every surface that has to say
|
|
4
|
+
* what parameters a path declares: the router's own substitution and binding
|
|
5
|
+
* scanners, RFC 0016's agent tool input, and `@guren/openapi`'s path template
|
|
6
|
+
* and parameter list.
|
|
7
|
+
*
|
|
8
|
+
* Internal by the rules in `contributing/api-stability.md` — reachable only
|
|
9
|
+
* through a deep import under `internal/`, never re-exported from an index.
|
|
10
|
+
* It lives in `@guren/server` and is re-exported by
|
|
11
|
+
* `@guren/core/internal/route-path` for the same build-order reason the
|
|
12
|
+
* JSON Schema walker beside it does: core's index is
|
|
13
|
+
* `export * from '@guren/server'`, so a server module cannot import a core
|
|
14
|
+
* one.
|
|
15
|
+
*
|
|
16
|
+
* It exists because two lexers is how two surfaces come to describe one path
|
|
17
|
+
* differently. They did: `@guren/openapi` carried its own copy with the `*`
|
|
18
|
+
* outside the capture group, so `/files/:name*` yielded the parameter `name`
|
|
19
|
+
* there and `name*` — what Hono actually registers — everywhere else. What
|
|
20
|
+
* *does* legitimately differ is rendering, not lexing, and that difference now
|
|
21
|
+
* lives at the one call site that needs it (see `stripExplodeModifier`).
|
|
22
|
+
*/
|
|
23
|
+
const PATH_PARAM_PATTERN = /(^|\/):([A-Za-z0-9_-]+\*?)(?:\{[^{}]*\{[^{}]*\}[^{}]*\}|\{[^{}]*\})?\??/gu;
|
|
24
|
+
/**
|
|
25
|
+
* Param labels in path order, exactly as Hono registers them: constraints
|
|
26
|
+
* dropped, a trailing `*` kept (it is part of the name), a trailing `?`
|
|
27
|
+
* dropped (it is not).
|
|
28
|
+
*/
|
|
29
|
+
function extractPathParamNames(path) {
|
|
30
|
+
return Array.from(path.matchAll(PATH_PARAM_PATTERN), (match) => match[2]);
|
|
31
|
+
}
|
|
32
|
+
//#endregion
|
|
33
|
+
export { PATH_PARAM_PATTERN, extractPathParamNames };
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Zod 4 schema-reading primitives shared by everything that has to read an
|
|
3
|
+
* application's schemas without parsing anything: the JSON Schema walker next
|
|
4
|
+
* door (`zod-json-schema.ts`, behind `@guren/openapi`, RFC 0016's agent tools,
|
|
5
|
+
* and `deriveAgentTools`), `@guren/cli`'s TypeScript-type renderer
|
|
6
|
+
* (`src/schema-type-extractor.ts`), and its route contract check
|
|
7
|
+
* (`src/route-contract-check.ts`).
|
|
8
|
+
*
|
|
9
|
+
* Internal by the rules in `contributing/api-stability.md`: reachable only
|
|
10
|
+
* through a deep import under `internal/`, never re-exported from
|
|
11
|
+
* `@guren/server`'s or `@guren/core`'s index. It sits in this package rather
|
|
12
|
+
* than `@guren/core` because `zod-json-schema.ts` beside it has to, for the
|
|
13
|
+
* build-order reason that module's header explains;
|
|
14
|
+
* `@guren/core/internal/zod-compat` re-exports it so consumers outside this
|
|
15
|
+
* package keep writing the core specifier.
|
|
16
|
+
*
|
|
17
|
+
* Zod 4 only. The zod 3 API (whether from the old `zod@3` package or the
|
|
18
|
+
* `zod/v3` subpath that zod 4 ships for migration) tags every node with
|
|
19
|
+
* `_def.typeName` and overloads `_def.type` to hold a nested schema — the
|
|
20
|
+
* ambiguity behind a bug this module's predecessors fixed twice. Rather than
|
|
21
|
+
* carrying both dialects forever, a v3 node is detected up front
|
|
22
|
+
* (`isZod3Schema`) and refused with `ZOD3_UNSUPPORTED_MESSAGE`; everything
|
|
23
|
+
* below it assumes the v4 layout, where `_def.type` is always the type name.
|
|
24
|
+
*
|
|
25
|
+
* What does NOT belong here: the two type switches that turn a node into an
|
|
26
|
+
* output (a TypeScript type string vs. a JSON Schema object). Their leaf
|
|
27
|
+
* vocabularies have legitimately diverged — the CLI renders `void`/`any`/
|
|
28
|
+
* `never`, which JSON Schema has no way to express — and that is a rendering
|
|
29
|
+
* decision, not schema-reading knowledge.
|
|
30
|
+
*
|
|
31
|
+
* No caller's `isOptional` belongs here either, but for a weaker reason than
|
|
32
|
+
* "they are all right": the CLI's type renderer reads only the side of a
|
|
33
|
+
* `.pipe()` it renders, while the JSON Schema walker and the CLI's route
|
|
34
|
+
* contract check require both sides to permit omission, and *every* one of them
|
|
35
|
+
* is an approximation that a sufficiently odd pipeline can fool. Fixing them
|
|
36
|
+
* properly means simulating a parse, which is well beyond reading a `_def`.
|
|
37
|
+
* They stay with their callers until someone does that. Applying the wrapper
|
|
38
|
+
* vocabulary is not policy, though, which is why `unwrapSingleChild` does live
|
|
39
|
+
* here: reaching a wrapper's child is schema-reading, while what a caller
|
|
40
|
+
* *concludes* from that wrapper is the caller's to decide.
|
|
41
|
+
*/
|
|
42
|
+
export interface ZodSchemaLike {
|
|
43
|
+
_def?: Record<string, unknown>;
|
|
44
|
+
/**
|
|
45
|
+
* zod 4's internal container; `values` is its own computed set of accepted
|
|
46
|
+
* literals, `def` the definition of whatever the node is (for a check entry,
|
|
47
|
+
* the check itself — see `schemaChecks`).
|
|
48
|
+
*/
|
|
49
|
+
_zod?: {
|
|
50
|
+
values?: Set<unknown>;
|
|
51
|
+
def?: Record<string, unknown>;
|
|
52
|
+
};
|
|
53
|
+
type?: string;
|
|
54
|
+
shape?: Record<string, ZodSchemaLike>;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* One entry of `_def.checks`, as zod stores it: a `check` discriminator plus
|
|
58
|
+
* whatever that kind carries (`minimum`, `value`, `inclusive`, `pattern`, …).
|
|
59
|
+
* Left open rather than modelled as a union — the kinds are zod's to add, and
|
|
60
|
+
* a reader that does not recognise one must simply ignore it.
|
|
61
|
+
*/
|
|
62
|
+
export interface ZodCheckDef extends Record<string, unknown> {
|
|
63
|
+
check: string;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Which side of a schema is being read.
|
|
67
|
+
*
|
|
68
|
+
* - `output` — the parsed value, i.e. what a controller receives after
|
|
69
|
+
* validation, or what a response body looks like.
|
|
70
|
+
* - `input` — the value a client has to send over the wire. Coercing and
|
|
71
|
+
* piped schemas can differ here from their output side.
|
|
72
|
+
*/
|
|
73
|
+
export type SchemaIo = 'input' | 'output';
|
|
74
|
+
/**
|
|
75
|
+
* Whether this node was authored with the zod 3 API. Only v3 sets
|
|
76
|
+
* `_def.typeName` (`"ZodString"`), so its presence is the discriminator —
|
|
77
|
+
* checked before any other read, because on a v3 node `_def.type` holds a
|
|
78
|
+
* nested *schema* and every v4-shaped read below would misfire on it.
|
|
79
|
+
*/
|
|
80
|
+
export declare function isZod3Schema(schema: ZodSchemaLike): boolean;
|
|
81
|
+
/**
|
|
82
|
+
* The one refusal message, stated once so the CLI's console warning and the
|
|
83
|
+
* OpenAPI document's warnings array cannot drift apart.
|
|
84
|
+
*/
|
|
85
|
+
export declare const ZOD3_UNSUPPORTED_MESSAGE = "this schema was authored with the zod v3 API (zod@3 or the zod/v3 subpath), which Guren does not support. Rewrite it with the zod 4 API (`import { z } from 'zod'`).";
|
|
86
|
+
/** The node's type name: `_def.type` (`"string"`, `"object"`, …) or the schema's own `.type`. */
|
|
87
|
+
export declare function getTypeName(schema: ZodSchemaLike): string | undefined;
|
|
88
|
+
/** `getTypeName` with `'unknown'` for a node that has no readable name. */
|
|
89
|
+
export declare function typeOf(schema: ZodSchemaLike): string;
|
|
90
|
+
/**
|
|
91
|
+
* The schema at `def[key]`, if it actually holds one. The object check is
|
|
92
|
+
* load-bearing: `_def` is untyped data from someone else's package, and a key
|
|
93
|
+
* holding a string or function must read as absent, not as a schema. (The
|
|
94
|
+
* v3-era version of this helper took a key *list* and returned the first
|
|
95
|
+
* match; with one dialect there is no precedence left to encode.)
|
|
96
|
+
*/
|
|
97
|
+
export declare function schemaAt(def: Record<string, unknown>, key: string): ZodSchemaLike | undefined;
|
|
98
|
+
/** The schema wrapped by a single-child wrapper (`.optional()`, `.readonly()`, `.catch()`, …) — always `_def.innerType` in zod 4. */
|
|
99
|
+
export declare function innerSchema(def: Record<string, unknown>): ZodSchemaLike | undefined;
|
|
100
|
+
/** An array's element schema — `_def.element`, never `_def.type`, which holds the string `'array'`. */
|
|
101
|
+
export declare function arrayElement(def: Record<string, unknown>): ZodSchemaLike | undefined;
|
|
102
|
+
/** A record's value schema — `_def.valueType`. */
|
|
103
|
+
export declare function recordValueType(def: Record<string, unknown>): ZodSchemaLike | undefined;
|
|
104
|
+
/**
|
|
105
|
+
* Whether this node is a `.transform()`'s output half — a wrapped function
|
|
106
|
+
* with no type to read, as opposed to a schema that genuinely parses to
|
|
107
|
+
* `unknown`.
|
|
108
|
+
*/
|
|
109
|
+
export declare function isTransform(schema: ZodSchemaLike): boolean;
|
|
110
|
+
/**
|
|
111
|
+
* Both halves of a `.pipe()`. Zod 4 uses one `pipe` node for both `.pipe()`
|
|
112
|
+
* and `.transform()`: `_def.in` is what a caller sends, `_def.out` what a
|
|
113
|
+
* controller receives — except for a transform, whose out side is the
|
|
114
|
+
* transform function itself and so has no type to read. `to` is therefore
|
|
115
|
+
* absent for a transform, leaving `from` as the only readable answer.
|
|
116
|
+
*/
|
|
117
|
+
export declare function pipeSides(def: Record<string, unknown>): {
|
|
118
|
+
from: ZodSchemaLike | undefined;
|
|
119
|
+
to: ZodSchemaLike | undefined;
|
|
120
|
+
};
|
|
121
|
+
/** The one side of a `.pipe()` that describes the `io` direction being rendered. */
|
|
122
|
+
export declare function pipeSide(def: Record<string, unknown>, io: SchemaIo): ZodSchemaLike | undefined;
|
|
123
|
+
/** An object's property map — `_def.shape`, or the schema's own `.shape`. */
|
|
124
|
+
export declare function objectShape(schema: ZodSchemaLike): Record<string, ZodSchemaLike> | undefined;
|
|
125
|
+
/**
|
|
126
|
+
* An enum's accepted values, read from zod's own computed set at
|
|
127
|
+
* `_zod.values` rather than re-derived from `_def.entries`. The distinction
|
|
128
|
+
* matters because `z.nativeEnum` produces the same node and a real TypeScript
|
|
129
|
+
* numeric enum's runtime object carries reverse mappings (`{ A: 0, '0': 'A' }`)
|
|
130
|
+
* — and any hand-rolled filter for those has a false positive: in
|
|
131
|
+
* `{ A: 'B', B: 1 }`, the key `A` *looks* like a reverse entry (`entries['B']`
|
|
132
|
+
* is a number) but zod accepts `'B'`. Reading zod's set makes what we document
|
|
133
|
+
* what zod parses, by construction. The `entries` fallback (values unfiltered)
|
|
134
|
+
* only runs if a future zod 4.x stops exposing the set.
|
|
135
|
+
*/
|
|
136
|
+
export declare function enumValues(schema: ZodSchemaLike): Array<string | number>;
|
|
137
|
+
/**
|
|
138
|
+
* The refinements attached to a node (`.min()`, `.regex()`, `.multipleOf()`, …),
|
|
139
|
+
* normalized to the definition objects zod keeps at each entry's `_zod.def`.
|
|
140
|
+
*
|
|
141
|
+
* Reading through `_zod.def` rather than the entry itself is what makes the
|
|
142
|
+
* list uniform: `_def.checks` is heterogeneous by construction. A plain
|
|
143
|
+
* refinement (`z.string().min(2)`) is stored as a bare check object, while a
|
|
144
|
+
* format method (`z.string().url()`) stores the *format schema* — a full node
|
|
145
|
+
* with `parse`, `safeParse` and the rest — in the same array. Both carry the
|
|
146
|
+
* check definition at `_zod.def`, and nothing else about them is shared.
|
|
147
|
+
*
|
|
148
|
+
* Entries without a string `check` are dropped rather than passed through: a
|
|
149
|
+
* caller switches on that discriminator, so an entry that has none can only be
|
|
150
|
+
* misread.
|
|
151
|
+
*/
|
|
152
|
+
export declare function schemaChecks(schema: ZodSchemaLike): ZodCheckDef[];
|
|
153
|
+
/**
|
|
154
|
+
* The node's declared format, if it has one — `'email'` for `z.email()`,
|
|
155
|
+
* `'safeint'` for `z.int()`.
|
|
156
|
+
*
|
|
157
|
+
* This is only *half* of how zod 4 records a format, and the half a caller is
|
|
158
|
+
* likeliest to forget. The top-level constructors (`z.email()`, `z.iso.datetime()`)
|
|
159
|
+
* set `_def.format` and attach no check; the equivalent string methods
|
|
160
|
+
* (`z.string().email()`, `z.string().datetime()`) attach a `string_format`
|
|
161
|
+
* check and leave `_def.format` undefined. A reader that wants "the format of
|
|
162
|
+
* this schema" has to consult both this and `schemaChecks`.
|
|
163
|
+
*/
|
|
164
|
+
export declare function schemaFormat(schema: ZodSchemaLike): string | undefined;
|
|
165
|
+
/** A literal's values — always the `_def.values` array in zod 4, which may hold more than one. */
|
|
166
|
+
export declare function literalValues(def: Record<string, unknown>): unknown[];
|
|
167
|
+
/**
|
|
168
|
+
* Wrappers that neither add to a rendered type nor decide whether a field may
|
|
169
|
+
* be omitted — whatever they wrap answers both questions. (`lazy` is here for
|
|
170
|
+
* membership only: its child hides behind `_def.getter`, which no walker
|
|
171
|
+
* calls, so looking through it reads as "contents unavailable" rather than
|
|
172
|
+
* "unsupported type".)
|
|
173
|
+
*/
|
|
174
|
+
export declare const TRANSPARENT_WRAPPERS: ReadonlySet<string>;
|
|
175
|
+
/**
|
|
176
|
+
* Wrappers that pass their type through but *do* decide presence: each makes a
|
|
177
|
+
* field omissible, or (in `nonoptional`'s case) re-requires one.
|
|
178
|
+
*/
|
|
179
|
+
export declare const PRESENCE_WRAPPERS: ReadonlySet<string>;
|
|
180
|
+
/**
|
|
181
|
+
* Every type name that carries exactly one nested schema and no shape of its
|
|
182
|
+
* own — the union of the two sets above plus the two that render specially
|
|
183
|
+
* (`nullable` becomes a union with null; a pipe holds one schema per side).
|
|
184
|
+
*
|
|
185
|
+
* This is the vocabulary, not a policy: callers partition it however their
|
|
186
|
+
* rendering needs (the CLI splits transparent from presence-deciding because
|
|
187
|
+
* it walks types and presence separately; the JSON Schema walker looks through all
|
|
188
|
+
* of them uniformly). What none of them may do is disagree about *membership*
|
|
189
|
+
* — a name known to one walker and not the other silently changes an output,
|
|
190
|
+
* which is why the list lives here rather than once per package.
|
|
191
|
+
*/
|
|
192
|
+
export declare const SINGLE_CHILD_WRAPPERS: ReadonlySet<string>;
|
|
193
|
+
/**
|
|
194
|
+
* The schema a single-child wrapper wraps, in the direction being read; absent
|
|
195
|
+
* for a node that is not a wrapper, or one whose child cannot be reached
|
|
196
|
+
* (`z.lazy()` hides its schema behind a getter no walker calls).
|
|
197
|
+
*
|
|
198
|
+
* Membership comes from the set above, for the reason stated there; a pipe
|
|
199
|
+
* resolves per direction, for the reason stated on `pipeSides`.
|
|
200
|
+
*/
|
|
201
|
+
export declare function unwrapSingleChild(schema: ZodSchemaLike, io: SchemaIo): ZodSchemaLike | undefined;
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
//#region src/internal/zod-compat.ts
|
|
2
|
+
/**
|
|
3
|
+
* Whether this node was authored with the zod 3 API. Only v3 sets
|
|
4
|
+
* `_def.typeName` (`"ZodString"`), so its presence is the discriminator —
|
|
5
|
+
* checked before any other read, because on a v3 node `_def.type` holds a
|
|
6
|
+
* nested *schema* and every v4-shaped read below would misfire on it.
|
|
7
|
+
*/
|
|
8
|
+
function isZod3Schema(schema) {
|
|
9
|
+
return typeof schema._def?.typeName === "string";
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* The one refusal message, stated once so the CLI's console warning and the
|
|
13
|
+
* OpenAPI document's warnings array cannot drift apart.
|
|
14
|
+
*/
|
|
15
|
+
const ZOD3_UNSUPPORTED_MESSAGE = "this schema was authored with the zod v3 API (zod@3 or the zod/v3 subpath), which Guren does not support. Rewrite it with the zod 4 API (`import { z } from 'zod'`).";
|
|
16
|
+
/** The node's type name: `_def.type` (`"string"`, `"object"`, …) or the schema's own `.type`. */
|
|
17
|
+
function getTypeName(schema) {
|
|
18
|
+
const name = schema._def?.type ?? schema.type;
|
|
19
|
+
return typeof name === "string" ? name : void 0;
|
|
20
|
+
}
|
|
21
|
+
/** `getTypeName` with `'unknown'` for a node that has no readable name. */
|
|
22
|
+
function typeOf(schema) {
|
|
23
|
+
return getTypeName(schema) ?? "unknown";
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* The schema at `def[key]`, if it actually holds one. The object check is
|
|
27
|
+
* load-bearing: `_def` is untyped data from someone else's package, and a key
|
|
28
|
+
* holding a string or function must read as absent, not as a schema. (The
|
|
29
|
+
* v3-era version of this helper took a key *list* and returned the first
|
|
30
|
+
* match; with one dialect there is no precedence left to encode.)
|
|
31
|
+
*/
|
|
32
|
+
function schemaAt(def, key) {
|
|
33
|
+
const candidate = def[key];
|
|
34
|
+
return candidate && typeof candidate === "object" ? candidate : void 0;
|
|
35
|
+
}
|
|
36
|
+
/** The schema wrapped by a single-child wrapper (`.optional()`, `.readonly()`, `.catch()`, …) — always `_def.innerType` in zod 4. */
|
|
37
|
+
function innerSchema(def) {
|
|
38
|
+
return schemaAt(def, "innerType");
|
|
39
|
+
}
|
|
40
|
+
/** An array's element schema — `_def.element`, never `_def.type`, which holds the string `'array'`. */
|
|
41
|
+
function arrayElement(def) {
|
|
42
|
+
return schemaAt(def, "element");
|
|
43
|
+
}
|
|
44
|
+
/** A record's value schema — `_def.valueType`. */
|
|
45
|
+
function recordValueType(def) {
|
|
46
|
+
return schemaAt(def, "valueType");
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Whether this node is a `.transform()`'s output half — a wrapped function
|
|
50
|
+
* with no type to read, as opposed to a schema that genuinely parses to
|
|
51
|
+
* `unknown`.
|
|
52
|
+
*/
|
|
53
|
+
function isTransform(schema) {
|
|
54
|
+
return typeOf(schema) === "transform";
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Both halves of a `.pipe()`. Zod 4 uses one `pipe` node for both `.pipe()`
|
|
58
|
+
* and `.transform()`: `_def.in` is what a caller sends, `_def.out` what a
|
|
59
|
+
* controller receives — except for a transform, whose out side is the
|
|
60
|
+
* transform function itself and so has no type to read. `to` is therefore
|
|
61
|
+
* absent for a transform, leaving `from` as the only readable answer.
|
|
62
|
+
*/
|
|
63
|
+
function pipeSides(def) {
|
|
64
|
+
const to = schemaAt(def, "out");
|
|
65
|
+
return {
|
|
66
|
+
from: schemaAt(def, "in"),
|
|
67
|
+
to: to && !isTransform(to) ? to : void 0
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
/** The one side of a `.pipe()` that describes the `io` direction being rendered. */
|
|
71
|
+
function pipeSide(def, io) {
|
|
72
|
+
const { from, to } = pipeSides(def);
|
|
73
|
+
return io === "output" && to ? to : from;
|
|
74
|
+
}
|
|
75
|
+
/** An object's property map — `_def.shape`, or the schema's own `.shape`. */
|
|
76
|
+
function objectShape(schema) {
|
|
77
|
+
return (schema._def ?? {}).shape ?? schema.shape;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* An enum's accepted values, read from zod's own computed set at
|
|
81
|
+
* `_zod.values` rather than re-derived from `_def.entries`. The distinction
|
|
82
|
+
* matters because `z.nativeEnum` produces the same node and a real TypeScript
|
|
83
|
+
* numeric enum's runtime object carries reverse mappings (`{ A: 0, '0': 'A' }`)
|
|
84
|
+
* — and any hand-rolled filter for those has a false positive: in
|
|
85
|
+
* `{ A: 'B', B: 1 }`, the key `A` *looks* like a reverse entry (`entries['B']`
|
|
86
|
+
* is a number) but zod accepts `'B'`. Reading zod's set makes what we document
|
|
87
|
+
* what zod parses, by construction. The `entries` fallback (values unfiltered)
|
|
88
|
+
* only runs if a future zod 4.x stops exposing the set.
|
|
89
|
+
*/
|
|
90
|
+
function enumValues(schema) {
|
|
91
|
+
const values = schema._zod?.values;
|
|
92
|
+
if (values) return [...values].filter((value) => typeof value === "string" || typeof value === "number");
|
|
93
|
+
const entries = schema._def?.entries;
|
|
94
|
+
return entries ? Object.values(entries) : [];
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* The refinements attached to a node (`.min()`, `.regex()`, `.multipleOf()`, …),
|
|
98
|
+
* normalized to the definition objects zod keeps at each entry's `_zod.def`.
|
|
99
|
+
*
|
|
100
|
+
* Reading through `_zod.def` rather than the entry itself is what makes the
|
|
101
|
+
* list uniform: `_def.checks` is heterogeneous by construction. A plain
|
|
102
|
+
* refinement (`z.string().min(2)`) is stored as a bare check object, while a
|
|
103
|
+
* format method (`z.string().url()`) stores the *format schema* — a full node
|
|
104
|
+
* with `parse`, `safeParse` and the rest — in the same array. Both carry the
|
|
105
|
+
* check definition at `_zod.def`, and nothing else about them is shared.
|
|
106
|
+
*
|
|
107
|
+
* Entries without a string `check` are dropped rather than passed through: a
|
|
108
|
+
* caller switches on that discriminator, so an entry that has none can only be
|
|
109
|
+
* misread.
|
|
110
|
+
*/
|
|
111
|
+
function schemaChecks(schema) {
|
|
112
|
+
const checks = schema._def?.checks;
|
|
113
|
+
if (!Array.isArray(checks)) return [];
|
|
114
|
+
return checks.flatMap((entry) => {
|
|
115
|
+
const def = entry && typeof entry === "object" ? entry._zod?.def : void 0;
|
|
116
|
+
return def && typeof def.check === "string" ? [def] : [];
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* The node's declared format, if it has one — `'email'` for `z.email()`,
|
|
121
|
+
* `'safeint'` for `z.int()`.
|
|
122
|
+
*
|
|
123
|
+
* This is only *half* of how zod 4 records a format, and the half a caller is
|
|
124
|
+
* likeliest to forget. The top-level constructors (`z.email()`, `z.iso.datetime()`)
|
|
125
|
+
* set `_def.format` and attach no check; the equivalent string methods
|
|
126
|
+
* (`z.string().email()`, `z.string().datetime()`) attach a `string_format`
|
|
127
|
+
* check and leave `_def.format` undefined. A reader that wants "the format of
|
|
128
|
+
* this schema" has to consult both this and `schemaChecks`.
|
|
129
|
+
*/
|
|
130
|
+
function schemaFormat(schema) {
|
|
131
|
+
const format = schema._def?.format;
|
|
132
|
+
return typeof format === "string" ? format : void 0;
|
|
133
|
+
}
|
|
134
|
+
/** A literal's values — always the `_def.values` array in zod 4, which may hold more than one. */
|
|
135
|
+
function literalValues(def) {
|
|
136
|
+
return Array.isArray(def.values) ? def.values : [];
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Wrappers that neither add to a rendered type nor decide whether a field may
|
|
140
|
+
* be omitted — whatever they wrap answers both questions. (`lazy` is here for
|
|
141
|
+
* membership only: its child hides behind `_def.getter`, which no walker
|
|
142
|
+
* calls, so looking through it reads as "contents unavailable" rather than
|
|
143
|
+
* "unsupported type".)
|
|
144
|
+
*/
|
|
145
|
+
const TRANSPARENT_WRAPPERS = /* @__PURE__ */ new Set([
|
|
146
|
+
"catch",
|
|
147
|
+
"readonly",
|
|
148
|
+
"lazy"
|
|
149
|
+
]);
|
|
150
|
+
/**
|
|
151
|
+
* Wrappers that pass their type through but *do* decide presence: each makes a
|
|
152
|
+
* field omissible, or (in `nonoptional`'s case) re-requires one.
|
|
153
|
+
*/
|
|
154
|
+
const PRESENCE_WRAPPERS = /* @__PURE__ */ new Set([
|
|
155
|
+
"optional",
|
|
156
|
+
"default",
|
|
157
|
+
"prefault",
|
|
158
|
+
"nonoptional"
|
|
159
|
+
]);
|
|
160
|
+
/**
|
|
161
|
+
* Every type name that carries exactly one nested schema and no shape of its
|
|
162
|
+
* own — the union of the two sets above plus the two that render specially
|
|
163
|
+
* (`nullable` becomes a union with null; a pipe holds one schema per side).
|
|
164
|
+
*
|
|
165
|
+
* This is the vocabulary, not a policy: callers partition it however their
|
|
166
|
+
* rendering needs (the CLI splits transparent from presence-deciding because
|
|
167
|
+
* it walks types and presence separately; the JSON Schema walker looks through all
|
|
168
|
+
* of them uniformly). What none of them may do is disagree about *membership*
|
|
169
|
+
* — a name known to one walker and not the other silently changes an output,
|
|
170
|
+
* which is why the list lives here rather than once per package.
|
|
171
|
+
*/
|
|
172
|
+
const SINGLE_CHILD_WRAPPERS = /* @__PURE__ */ new Set([
|
|
173
|
+
...TRANSPARENT_WRAPPERS,
|
|
174
|
+
...PRESENCE_WRAPPERS,
|
|
175
|
+
"nullable",
|
|
176
|
+
"pipe"
|
|
177
|
+
]);
|
|
178
|
+
/**
|
|
179
|
+
* The schema a single-child wrapper wraps, in the direction being read; absent
|
|
180
|
+
* for a node that is not a wrapper, or one whose child cannot be reached
|
|
181
|
+
* (`z.lazy()` hides its schema behind a getter no walker calls).
|
|
182
|
+
*
|
|
183
|
+
* Membership comes from the set above, for the reason stated there; a pipe
|
|
184
|
+
* resolves per direction, for the reason stated on `pipeSides`.
|
|
185
|
+
*/
|
|
186
|
+
function unwrapSingleChild(schema, io) {
|
|
187
|
+
const def = schema._def ?? {};
|
|
188
|
+
const typeName = typeOf(schema);
|
|
189
|
+
if (typeName === "pipe") return pipeSide(def, io);
|
|
190
|
+
return SINGLE_CHILD_WRAPPERS.has(typeName) ? innerSchema(def) : void 0;
|
|
191
|
+
}
|
|
192
|
+
//#endregion
|
|
193
|
+
export { PRESENCE_WRAPPERS, SINGLE_CHILD_WRAPPERS, TRANSPARENT_WRAPPERS, ZOD3_UNSUPPORTED_MESSAGE, arrayElement, enumValues, getTypeName, innerSchema, isTransform, isZod3Schema, literalValues, objectShape, pipeSide, pipeSides, recordValueType, schemaAt, schemaChecks, schemaFormat, typeOf, unwrapSingleChild };
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one Zod → JSON Schema rule, shared by every surface that has to describe
|
|
3
|
+
* an application's contracts to something outside the process: `@guren/openapi`
|
|
4
|
+
* renders it as OpenAPI 3.1 schema objects (which *are* JSON Schema 2020-12),
|
|
5
|
+
* and RFC 0016's agent tools advertise it as MCP input/output schemas.
|
|
6
|
+
*
|
|
7
|
+
* Internal by the rules in `contributing/api-stability.md`: reachable only
|
|
8
|
+
* through a deep import under `internal/`, never re-exported from
|
|
9
|
+
* `@guren/server`'s or `@guren/core`'s index. No stability guarantee — it
|
|
10
|
+
* exists so two derivations of the same schema cannot disagree, not as a
|
|
11
|
+
* public extension point. That is the whole reason it was promoted out of
|
|
12
|
+
* `@guren/openapi`: a second walker is how an agent tool comes to advertise a
|
|
13
|
+
* schema the documented API contradicts.
|
|
14
|
+
*
|
|
15
|
+
* It lives in `@guren/server` rather than `@guren/core` (where RFC 0016 §2
|
|
16
|
+
* first placed it) for a build-order reason, not a layering one. Core's index
|
|
17
|
+
* is `export * from '@guren/server'`, so core builds *after* server and a
|
|
18
|
+
* server module cannot import a core one — the edge would close a cycle, and
|
|
19
|
+
* server's declaration build (`tsc -p tsconfig.build.json`, `paths: {}`)
|
|
20
|
+
* would look for a core `dist/` that does not exist yet. `deriveAgentTools`
|
|
21
|
+
* lives in `@guren/server`, so the walker had to move down to the package
|
|
22
|
+
* both it and the OpenAPI generator can see. `@guren/core/internal/*`
|
|
23
|
+
* re-exports this module, which keeps that the specifier every consumer
|
|
24
|
+
* outside this package writes.
|
|
25
|
+
*
|
|
26
|
+
* Every `_def` read goes through `zod-compat.ts`, including the check reads
|
|
27
|
+
* this module added. Reaching into `_def` here would put zod-layout knowledge
|
|
28
|
+
* in two places, which is exactly the split `zod-compat` exists to prevent.
|
|
29
|
+
*
|
|
30
|
+
* Zod 4 only, and a v3 node is *refused* rather than walked — on v3 `_def.type`
|
|
31
|
+
* holds a nested schema where v4 keeps the type name, so every read below would
|
|
32
|
+
* misfire and produce a confidently wrong document. The refusal is re-checked
|
|
33
|
+
* at each recursion, because a v3 node can hide inside a v4 wrapper.
|
|
34
|
+
*
|
|
35
|
+
* What this module does not decide: what a caller does with the warnings, and
|
|
36
|
+
* how the result is embedded (a `requestBody` content map, an MCP `inputSchema`).
|
|
37
|
+
* Warnings are appended to a caller-owned array so a document generator can
|
|
38
|
+
* surface them per request and a codegen step can fail on them.
|
|
39
|
+
*/
|
|
40
|
+
import { type SchemaIo, type ZodSchemaLike } from './zod-compat.js';
|
|
41
|
+
export type JsonSchemaPrimitiveType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
|
|
42
|
+
/**
|
|
43
|
+
* A JSON Schema 2020-12 object, restricted to the keywords this walker emits.
|
|
44
|
+
* OpenAPI 3.1's Schema Object is the same dialect, so `@guren/openapi` uses
|
|
45
|
+
* this type verbatim.
|
|
46
|
+
*/
|
|
47
|
+
export interface JsonSchemaObject {
|
|
48
|
+
type?: JsonSchemaPrimitiveType | JsonSchemaPrimitiveType[];
|
|
49
|
+
format?: string;
|
|
50
|
+
description?: string;
|
|
51
|
+
enum?: Array<string | number>;
|
|
52
|
+
const?: string | number | boolean | null;
|
|
53
|
+
properties?: Record<string, JsonSchemaObject>;
|
|
54
|
+
required?: string[];
|
|
55
|
+
items?: JsonSchemaObject;
|
|
56
|
+
prefixItems?: JsonSchemaObject[];
|
|
57
|
+
minItems?: number;
|
|
58
|
+
maxItems?: number;
|
|
59
|
+
minLength?: number;
|
|
60
|
+
maxLength?: number;
|
|
61
|
+
pattern?: string;
|
|
62
|
+
minimum?: number;
|
|
63
|
+
maximum?: number;
|
|
64
|
+
exclusiveMinimum?: number;
|
|
65
|
+
exclusiveMaximum?: number;
|
|
66
|
+
multipleOf?: number;
|
|
67
|
+
additionalProperties?: boolean | JsonSchemaObject;
|
|
68
|
+
anyOf?: JsonSchemaObject[];
|
|
69
|
+
oneOf?: JsonSchemaObject[];
|
|
70
|
+
allOf?: JsonSchemaObject[];
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* An object schema taken apart rather than rendered — the shape a caller needs
|
|
74
|
+
* when the properties do not stay together in one schema object (OpenAPI
|
|
75
|
+
* expands a `query` schema into one parameter per property, and RFC 0016 merges
|
|
76
|
+
* `params` + `query` + `body` into a single tool input).
|
|
77
|
+
*/
|
|
78
|
+
export interface ObjectSchemaDetails {
|
|
79
|
+
properties: Record<string, JsonSchemaObject>;
|
|
80
|
+
required: Set<string>;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Turn a Zod schema into a JSON Schema object, appending a line to `warnings`
|
|
84
|
+
* for anything it cannot express. `label` names the schema in those warnings
|
|
85
|
+
* (`"POST /posts body.title"`); `io` picks the side of coercing and piped
|
|
86
|
+
* schemas to describe — `input` is what a caller sends, `output` what a parse
|
|
87
|
+
* produces.
|
|
88
|
+
*
|
|
89
|
+
* Returns `undefined` when the node contributes nothing (a bare `z.undefined()`)
|
|
90
|
+
* or could not be read; a caller treats that as "omit this property".
|
|
91
|
+
*/
|
|
92
|
+
export declare function toJsonSchema(schema: unknown, warnings: string[], label: string, io: SchemaIo): JsonSchemaObject | undefined;
|
|
93
|
+
/**
|
|
94
|
+
* Take an object schema apart into its properties and the set of keys a caller
|
|
95
|
+
* must supply, looking through any wrappers around it. Warns and returns
|
|
96
|
+
* `undefined` when the schema is absent, not Zod, or not an object once
|
|
97
|
+
* unwrapped — a caller that expands properties into something else (query
|
|
98
|
+
* parameters, merged tool input) has nothing to expand otherwise.
|
|
99
|
+
*/
|
|
100
|
+
export declare function readObjectSchema(schema: unknown, warnings: string[], label: string, io: SchemaIo): ObjectSchemaDetails | undefined;
|
|
101
|
+
/** Whether this value looks like a Zod schema at all — the gate every walk opens with. */
|
|
102
|
+
export declare function isZodSchema(schema: unknown): schema is ZodSchemaLike;
|