@guren/server 2.5.0 → 2.6.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.
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  McpServiceProvider
3
- } from "./chunk-5WL2FTC4.js";
3
+ } from "./chunk-YSOJKAAU.js";
4
4
  import "./chunk-Q2P6YLRR.js";
5
5
  import "./chunk-LHR6OHI7.js";
6
6
  export {
@@ -6,7 +6,7 @@ import standard from "figlet/importable-fonts/Standard.js";
6
6
  // package.json
7
7
  var package_default = {
8
8
  name: "@guren/server",
9
- version: "2.5.0",
9
+ version: "2.6.0",
10
10
  type: "module",
11
11
  license: "MIT",
12
12
  repository: {
@@ -119,7 +119,7 @@ var package_default = {
119
119
  test: "bun test"
120
120
  },
121
121
  dependencies: {
122
- "@guren/orm": "^2.3.0",
122
+ "@guren/orm": "^2.4.0",
123
123
  "@modelcontextprotocol/sdk": "^1.30.0",
124
124
  chalk: "^5.3.0",
125
125
  consola: "^3.4.2",
@@ -190,6 +190,7 @@ function createMcpServer(options) {
190
190
  const options2 = { cwd, force: true };
191
191
  const generated = [];
192
192
  const skipped = [];
193
+ const warnings = [];
193
194
  let failed = false;
194
195
  const run = async (artifacts, generate) => {
195
196
  try {
@@ -199,6 +200,7 @@ function createMcpServer(options) {
199
200
  } else {
200
201
  generated.push(...artifacts);
201
202
  }
203
+ if (result?.warnings) warnings.push(...result.warnings);
202
204
  return result;
203
205
  } catch (error) {
204
206
  failed = true;
@@ -213,16 +215,16 @@ function createMcpServer(options) {
213
215
  () => cli.generateRouteTypes(options2)
214
216
  );
215
217
  await run([".guren/pages.gen.ts"], () => cli.generatePageTypes(options2));
216
- await run([".guren/data.gen.ts"], () => cli.generateDataTypes(options2));
218
+ const data = await run([".guren/data.gen.ts"], () => cli.generateDataTypes(options2));
217
219
  await run([".guren/channels.gen.ts"], () => cli.generateChannelTypes(options2));
218
220
  await run([".guren/api-client.gen.ts"], () => {
219
221
  if (!routes?.definitions) {
220
222
  throw new Error("route generation produced no manifest to build a client from");
221
223
  }
222
- return cli.generateApiClientTypes(routes.definitions, options2);
224
+ return cli.generateApiClientTypes(routes.definitions, { ...options2, resources: data?.definitions });
223
225
  });
224
226
  return {
225
- content: [{ type: "text", text: JSON.stringify({ generated, skipped }, null, 2) }],
227
+ content: [{ type: "text", text: JSON.stringify({ generated, skipped, warnings }, null, 2) }],
226
228
  // A generator that found nothing to describe is not a failure — an
227
229
  // app with no page components is a normal shape — so only a thrown
228
230
  // one makes the run an error, even when other artifacts landed.
package/dist/index.d.ts CHANGED
@@ -4,7 +4,7 @@ export { parseRequestPayload, formatValidationErrors } from './http/request.js';
4
4
  export { Controller } from './mvc/Controller.js';
5
5
  export type { InertiaResponse, InferInertiaProps, ControllerInertiaProps, AuthPayload } from './mvc/Controller.js';
6
6
  export { Router } from './mvc/Router.js';
7
- export type { RouteBuilder, RouteContractOptions, RouteDefinition, RouteMiddlewareInput, RouteOpenApiMetadata, ResourceAction as RouteResourceAction, ResourceRouteOptions, } from './mvc/Router.js';
7
+ export type { RouteBuilder, RouteContractOptions, RouteDefinition, RouteMiddlewareInput, RouteOpenApiMetadata, ResourceAction as RouteResourceAction, ResourceResponseHint, ResourceResponseShape, ResourceRouteOptions, } from './mvc/Router.js';
8
8
  export { ViewEngine } from './mvc/ViewEngine.js';
9
9
  export { inertia, setInertiaSsrRenderer, setInertiaDocument } from './mvc/inertia/InertiaEngine.js';
10
10
  export { setInertiaSharedProps, getInertiaSharedPropsResolver, shareInertiaProps } from './mvc/inertia/shared.js';
package/dist/index.js CHANGED
@@ -5,7 +5,7 @@ import {
5
5
  logDevServerBanner,
6
6
  parseImportMap,
7
7
  startViteDevServer
8
- } from "./chunk-62AB24ZU.js";
8
+ } from "./chunk-RGGEGXOE.js";
9
9
  import {
10
10
  PendingSchedule,
11
11
  Schedule,
@@ -552,11 +552,12 @@ var Router = class {
552
552
  this.modelBindingNames.clear();
553
553
  }
554
554
  definitions() {
555
- return this.registry.map(({ method, path, name, schemas, openapi, routeMiddlewareNames, middlewares, scopedMiddlewares, handler, bindings }) => ({
555
+ return this.registry.map(({ method, path, name, schemas, resource, openapi, routeMiddlewareNames, middlewares, scopedMiddlewares, handler, bindings }) => ({
556
556
  method,
557
557
  path,
558
558
  name,
559
559
  schemas,
560
+ resource: serializeResourceHint(resource),
560
561
  middlewareNames: [...routeMiddlewareNames],
561
562
  // Route-local only, so a group-scoped handler does not make every route
562
563
  // in the group report middleware it never attached (`guren audit` warns
@@ -675,6 +676,7 @@ var Router = class {
675
676
  };
676
677
  function applyRouteContract(route, options) {
677
678
  route.schemas = { params: options.params, query: options.query, body: options.body, output: options.output };
679
+ route.resource = options.resource;
678
680
  route.openapi = {
679
681
  summary: options.summary,
680
682
  description: options.description,
@@ -736,12 +738,16 @@ function createRouteBuilder(route, namedRoutes) {
736
738
  }
737
739
  };
738
740
  }
741
+ var PATH_PARAM_PATTERN = /(^|\/):([A-Za-z0-9_-]+\*?)(?:\{[^{}]*\{[^{}]*\}[^{}]*\}|\{[^{}]*\})?\??/gu;
742
+ function extractPathParamNames(path) {
743
+ return Array.from(path.matchAll(PATH_PARAM_PATTERN), (match) => match[2]);
744
+ }
739
745
  function substituteParams(path, params) {
740
- return path.replace(/:([A-Za-z0-9_-]+)/gu, (match, key) => {
746
+ return path.replace(PATH_PARAM_PATTERN, (match, prefix, key) => {
741
747
  if (!Object.prototype.hasOwnProperty.call(params, key)) {
742
748
  return match;
743
749
  }
744
- return encodeURIComponent(String(params[key]));
750
+ return `${prefix}${encodeURIComponent(String(params[key]))}`;
745
751
  });
746
752
  }
747
753
  function createContractHandler(path, options, handler) {
@@ -919,7 +925,7 @@ async function resolveModelBindings(c, modelBindings, path) {
919
925
  }
920
926
  const resolved = [];
921
927
  const params = c.req.param();
922
- const pathParams = path?.match(/:([a-zA-Z0-9_-]+)/g)?.map((p) => p.slice(1)) ?? [];
928
+ const pathParams = path ? extractPathParamNames(path) : [];
923
929
  for (const param of pathParams) {
924
930
  const resolver = modelBindings.get(param);
925
931
  if (!resolver) continue;
@@ -959,15 +965,34 @@ function buildResponse(result) {
959
965
  }
960
966
  function serializeBindings(path, routeBindings, routerBindingNames) {
961
967
  const entries = /* @__PURE__ */ new Map();
962
- for (const param of path.match(/:(\w+)/g) ?? []) {
963
- const name = routerBindingNames.get(param.slice(1));
964
- if (name) entries.set(param.slice(1), name);
968
+ for (const param of extractPathParamNames(path)) {
969
+ const name = routerBindingNames.get(param);
970
+ if (name) entries.set(param, name);
965
971
  }
966
972
  for (const [param, model] of routeBindings ?? []) {
967
973
  if (model.name) entries.set(param, model.name);
968
974
  }
969
975
  return entries.size > 0 ? Object.fromEntries(entries) : void 0;
970
976
  }
977
+ function serializeResourceHint(hint) {
978
+ if (hint === void 0) {
979
+ return void 0;
980
+ }
981
+ if (typeof hint === "function") {
982
+ return hint.name || void 0;
983
+ }
984
+ if (Array.isArray(hint)) {
985
+ const inner = serializeResourceHint(hint[0]);
986
+ return inner === void 0 ? void 0 : [inner];
987
+ }
988
+ const entries = [];
989
+ for (const [key, value] of Object.entries(hint)) {
990
+ const serialized = serializeResourceHint(value);
991
+ if (serialized === void 0) return void 0;
992
+ entries.push([key, serialized]);
993
+ }
994
+ return Object.fromEntries(entries);
995
+ }
971
996
  function isControllerAction(action) {
972
997
  return Array.isArray(action);
973
998
  }
@@ -975,7 +1000,7 @@ function isRouteContractOptions(value) {
975
1000
  if (!value || typeof value !== "object" || Array.isArray(value)) {
976
1001
  return false;
977
1002
  }
978
- return "params" in value || "query" in value || "body" in value || "output" in value || "bind" in value || "name" in value || "middlewares" in value || "summary" in value || "description" in value || "tags" in value || "operationId" in value || "deprecated" in value;
1003
+ return "params" in value || "query" in value || "body" in value || "output" in value || "resource" in value || "bind" in value || "name" in value || "middlewares" in value || "summary" in value || "description" in value || "tags" in value || "operationId" in value || "deprecated" in value;
979
1004
  }
980
1005
  function joinPaths(prefixStack, path) {
981
1006
  const segments = [...prefixStack, path].filter(Boolean).map(trimSlashes).filter(Boolean);
@@ -2988,7 +3013,7 @@ var Application = class {
2988
3013
  await this.mountRoutes();
2989
3014
  await this.mountDevEndpoint(
2990
3015
  isMcpEndpointEnabled(),
2991
- async () => (await import("./McpServiceProvider-FRJ5O7LT.js")).McpServiceProvider,
3016
+ async () => (await import("./McpServiceProvider-SL7DUZ4G.js")).McpServiceProvider,
2992
3017
  "GUREN_MCP=1 but the MCP endpoint could not load \u2014 is @modelcontextprotocol/sdk installed?"
2993
3018
  );
2994
3019
  await this.mountDevEndpoint(
@@ -27,10 +27,12 @@ export interface ScaffoldOptions {
27
27
  * a manifest into an app that cannot compile one, and an agent reading this
28
28
  * result is exactly who needs to hear that a page it just wrote was ignored.
29
29
  *
30
- * `definitions` is the route manifest `generateRouteTypes` builds. It stays
31
- * opaque here — this package only carries it from one CLI call to the next
32
- * (`generateApiClientTypes` consumes it) and never reads inside it, so
33
- * mirroring the CLI's route shape would only create something to keep in sync.
30
+ * `definitions` is what a generator extracted: the route manifest from
31
+ * `generateRouteTypes`, the Resource definitions from `generateDataTypes`.
32
+ * It stays opaque here — this package only carries it from one CLI call to
33
+ * the next (`generateApiClientTypes` consumes both) and never reads inside
34
+ * it, so mirroring the CLI's shapes would only create something to keep in
35
+ * sync.
34
36
  */
35
37
  export interface CodegenResult {
36
38
  outputPath?: string;
@@ -38,6 +40,12 @@ export interface CodegenResult {
38
40
  skipped?: {
39
41
  message: string;
40
42
  } | null;
43
+ /**
44
+ * Diagnostics the generator wants surfaced to whoever asked for the run —
45
+ * a `resource` response hint naming an unknown Resource class, for
46
+ * instance. Non-fatal: the artifact was still written.
47
+ */
48
+ warnings?: string[];
41
49
  }
42
50
  /**
43
51
  * CLI functions that the MCP server wraps.
@@ -124,9 +132,13 @@ export interface GurenCliApi {
124
132
  generateChannelTypes(opts: CodegenOptions): Promise<CodegenResult | void>;
125
133
  /**
126
134
  * Takes the route manifest `generateRouteTypes` returns, so it can only run
127
- * after that succeeded.
135
+ * after that succeeded. `resources` is the Resource set `generateDataTypes`
136
+ * extracted — without it every `resource` response hint is "unknown
137
+ * Resource" and the client's `json()` stays untyped.
128
138
  */
129
- generateApiClientTypes(definitions: unknown[], opts: CodegenOptions): Promise<CodegenResult | void>;
139
+ generateApiClientTypes(definitions: unknown[], opts: CodegenOptions & {
140
+ resources?: unknown[];
141
+ }): Promise<CodegenResult | void>;
130
142
  /**
131
143
  * Route-dependent context generation that re-runs the CLI in a fresh
132
144
  * process. Optional because `@guren/cli` is resolved from the app at
package/dist/mcp/index.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  McpServiceProvider,
3
3
  createMcpServer
4
- } from "../chunk-5WL2FTC4.js";
4
+ } from "../chunk-YSOJKAAU.js";
5
5
  import "../chunk-Q2P6YLRR.js";
6
6
  import "../chunk-LHR6OHI7.js";
7
7
  export {
@@ -34,6 +34,34 @@ interface BindableModel {
34
34
  /** Bound values are model classes at runtime; the constructor name is the introspection payload. */
35
35
  readonly name?: string;
36
36
  }
37
+ /**
38
+ * A Resource class accepted as a response hint. Only the constructor name is
39
+ * introspected — the router never instantiates it, so any class whose
40
+ * instances expose `toJSON()` (every `Resource` subclass) qualifies.
41
+ */
42
+ interface ResponseResourceClass {
43
+ new (resource: any): {
44
+ toJSON(): unknown;
45
+ };
46
+ }
47
+ /**
48
+ * Type-level response hint for a route: a Resource class, a single-element
49
+ * array of a hint (a collection), or a plain object of hints (an envelope,
50
+ * e.g. `{ data: [PostResource] }`). Purely declarative — nothing is validated
51
+ * at runtime. `guren codegen` maps each Resource class to the `Data` type it
52
+ * extracts from `app/Http/Resources` and types the API client's `json()`
53
+ * with the assembled shape.
54
+ */
55
+ export type ResourceResponseHint = ResponseResourceClass | readonly [ResourceResponseHint] | {
56
+ readonly [key: string]: ResourceResponseHint;
57
+ };
58
+ /**
59
+ * Serialized form of {@link ResourceResponseHint} carried by
60
+ * {@link RouteDefinition}: Resource classes become their class names.
61
+ */
62
+ export type ResourceResponseShape = string | [ResourceResponseShape] | {
63
+ [key: string]: ResourceResponseShape;
64
+ };
37
65
  type SchemaLike<T = unknown> = ValidationSchema<T> | undefined;
38
66
  type InferSchema<TSchema extends SchemaLike<unknown>> = TSchema extends ValidationSchema<infer TValue> ? TValue : never;
39
67
  type RouteParamsFor<TSchema extends SchemaLike<unknown>> = [
@@ -59,6 +87,13 @@ export interface RouteContractOptions<TParamsSchema extends SchemaLike<unknown>
59
87
  query?: TQuerySchema;
60
88
  body?: TBodySchema;
61
89
  output?: TOutputSchema;
90
+ /**
91
+ * Type-level response hint (see {@link ResourceResponseHint}). Unlike
92
+ * `output`, nothing runs at request time — the route's JSON is assumed to
93
+ * follow the shape. When both are set, `output` wins in generated types:
94
+ * it is the one actually enforced.
95
+ */
96
+ resource?: ResourceResponseHint;
62
97
  bind?: Record<string, BindableModel>;
63
98
  }
64
99
  export interface RouteOpenApiMetadata {
@@ -85,6 +120,13 @@ export interface RouteDefinition {
85
120
  body?: SchemaLike<unknown>;
86
121
  output?: SchemaLike<unknown>;
87
122
  };
123
+ /**
124
+ * Serialized response hint from `RouteContractOptions.resource` — Resource
125
+ * class names in place of the classes. Absent when no hint was declared or
126
+ * when any class in the hint has no usable name (a partially-typed response
127
+ * would claim a shape the wire does not have).
128
+ */
129
+ resource?: ResourceResponseShape;
88
130
  /** Named middleware (aliases or groups) applied to this route */
89
131
  middlewareNames?: string[];
90
132
  /** Whether inline (unnamed) middleware handlers are attached */
@@ -4,7 +4,7 @@ import {
4
4
  logDevServerBanner,
5
5
  parseImportMap,
6
6
  startViteDevServer
7
- } from "../chunk-62AB24ZU.js";
7
+ } from "../chunk-RGGEGXOE.js";
8
8
  import {
9
9
  trimTrailingSlashes
10
10
  } from "../chunk-AZOYI43J.js";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guren/server",
3
- "version": "2.5.0",
3
+ "version": "2.6.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -113,7 +113,7 @@
113
113
  "test": "bun test"
114
114
  },
115
115
  "dependencies": {
116
- "@guren/orm": "^2.3.0",
116
+ "@guren/orm": "^2.4.0",
117
117
  "@modelcontextprotocol/sdk": "^1.30.0",
118
118
  "chalk": "^5.3.0",
119
119
  "consola": "^3.4.2",