@guren/server 2.13.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.
Files changed (45) hide show
  1. package/dist/{McpServiceProvider-D6D9nhgn.js → McpServiceProvider-BawsYjgN.js} +72 -0
  2. package/dist/agent/derive.d.ts +155 -0
  3. package/dist/agent/dispatch.d.ts +123 -0
  4. package/dist/agent/events.d.ts +80 -0
  5. package/dist/agent/redact.d.ts +55 -0
  6. package/dist/agent/scopes.d.ts +115 -0
  7. package/dist/auth/AuthManager.d.ts +64 -0
  8. package/dist/auth/RequestAuthContext.d.ts +3 -5
  9. package/dist/auth/TokenGuard.d.ts +61 -0
  10. package/dist/auth/api-token.d.ts +25 -5
  11. package/dist/auth/context.d.ts +24 -0
  12. package/dist/auth/index.d.ts +5 -2
  13. package/dist/auth/index.js +2 -2
  14. package/dist/auth/providers/UserProvider.d.ts +7 -0
  15. package/dist/auth/types.d.ts +6 -0
  16. package/dist/{auth-C7sVmYgc.js → auth-BSUc14CD.js} +313 -122
  17. package/dist/authorization/index.js +1 -1
  18. package/dist/authorization/middleware.d.ts +28 -1
  19. package/dist/{authorization-Dbcuc5ZK.js → authorization-CdfbCj8J.js} +119 -12
  20. package/dist/broadcasting/index.js +1 -1
  21. package/dist/{broadcasting-Dw-FhyjN.js → broadcasting-BxU-LIfF.js} +2 -45
  22. package/dist/context-DoD0c7J_.js +26 -0
  23. package/dist/http/middleware/auth.d.ts +2 -2
  24. package/dist/http/middleware/capabilities.d.ts +57 -0
  25. package/dist/http/middleware/csrf.d.ts +3 -0
  26. package/dist/http/request.d.ts +51 -2
  27. package/dist/index.d.ts +12 -3
  28. package/dist/index.js +1015 -84
  29. package/dist/internal/agent-preflight.d.ts +28 -0
  30. package/dist/internal/request.d.ts +19 -0
  31. package/dist/internal/request.js +2 -0
  32. package/dist/internal/route-path.d.ts +28 -0
  33. package/dist/internal/route-path.js +33 -0
  34. package/dist/internal/zod-compat.d.ts +201 -0
  35. package/dist/internal/zod-compat.js +193 -0
  36. package/dist/internal/zod-json-schema.d.ts +102 -0
  37. package/dist/internal/zod-json-schema.js +461 -0
  38. package/dist/mcp/create-mcp-server.d.ts +29 -0
  39. package/dist/mcp/index.js +1 -1
  40. package/dist/mvc/Controller.d.ts +46 -0
  41. package/dist/mvc/Router.d.ts +53 -0
  42. package/dist/request-CRVuIiQr.js +78 -0
  43. package/dist/runtime/index.js +5 -2
  44. package/dist/{vite-manifest-gdONBsM3.js → vite-manifest-BGfWbPYp.js} +1 -1
  45. 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,2 @@
1
+ import { i as parseRequestBody, t as asRecord } from "../request-CRVuIiQr.js";
2
+ export { asRecord, parseRequestBody };
@@ -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;