@guren/server 2.5.0 → 2.7.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.7.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",
@@ -16,6 +16,18 @@ import {
16
16
  } from "fs/promises";
17
17
  import { existsSync } from "fs";
18
18
  import { join, dirname, resolve, sep } from "path";
19
+
20
+ // src/support/warn-once.ts
21
+ var warned = /* @__PURE__ */ new Set();
22
+ function warnOnce(key, message) {
23
+ if (warned.has(key)) {
24
+ return;
25
+ }
26
+ warned.add(key);
27
+ console.warn(message);
28
+ }
29
+
30
+ // src/storage/drivers/LocalDriver.ts
19
31
  var LocalDriver = class {
20
32
  root;
21
33
  baseUrl;
@@ -47,6 +59,9 @@ var LocalDriver = class {
47
59
  }
48
60
  }
49
61
  async put(path, content, options) {
62
+ if (options?.visibility) {
63
+ this.warnUnsupportedVisibility(options.visibility, "put");
64
+ }
50
65
  const fullPath = this.fullPath(path);
51
66
  await this.ensureDirectory(fullPath);
52
67
  const buffer = typeof content === "string" ? Buffer.from(content) : content;
@@ -181,10 +196,31 @@ var LocalDriver = class {
181
196
  }
182
197
  }
183
198
  async setVisibility(path, visibility) {
199
+ await this.warnIfMissing(path, "setVisibility");
200
+ this.warnUnsupportedVisibility(visibility, "setVisibility");
184
201
  }
185
202
  async getVisibility(path) {
203
+ await this.warnIfMissing(path, "getVisibility");
186
204
  return this.defaultVisibility;
187
205
  }
206
+ async warnIfMissing(path, operation) {
207
+ if (await this.exists(path)) {
208
+ return;
209
+ }
210
+ warnOnce(
211
+ `local-visibility-missing:${operation}`,
212
+ `[guren] LocalDriver.${operation}("${path}") was called for a file that does not exist and returned as if it had succeeded. Every other storage driver throws \`File not found\` here, and LocalDriver will too in the next major \u2014 check \`exists()\` first, or handle the error.`
213
+ );
214
+ }
215
+ warnUnsupportedVisibility(requested, operation) {
216
+ if (requested === this.defaultVisibility) {
217
+ return;
218
+ }
219
+ warnOnce(
220
+ `local-visibility-per-object:${operation}`,
221
+ `[guren] LocalDriver.${operation}() was asked to make an object ${requested} on a ${this.defaultVisibility} disk, and did nothing. A local disk has no per-object visibility \u2014 what makes a file reachable is the disk root and whatever serves it \u2014 so the request was never carried out, it only looked like it was. Declare the disk's "visibility" option to match, or keep restricted files on a disk that is not served. This becomes an error in the next major.`
222
+ );
223
+ }
188
224
  /**
189
225
  * Get the root directory.
190
226
  */
@@ -193,6 +229,22 @@ var LocalDriver = class {
193
229
  }
194
230
  };
195
231
 
232
+ // src/storage/drivers/s3-acl.ts
233
+ function cannedAcl(visibility) {
234
+ return visibility === "public" ? "public-read" : "private";
235
+ }
236
+ function putAclFields(acl, visibility) {
237
+ return acl ? { ACL: cannedAcl(visibility) } : {};
238
+ }
239
+ function assertVisibilitySupported(acl, diskVisibility, requested, operation) {
240
+ if (acl || !requested || requested === diskVisibility) {
241
+ return;
242
+ }
243
+ throw new Error(
244
+ `S3Driver.${operation}: cannot make an object ${requested} on a ${diskVisibility} disk configured with acl: false. This endpoint does not implement S3 object ACLs, so visibility is a property of the bucket. Declare it with the driver's "visibility" option, or serve restricted files through your own route.`
245
+ );
246
+ }
247
+
196
248
  // src/storage/drivers/S3Driver.ts
197
249
  var S3Driver = class {
198
250
  constructor(options) {
@@ -206,6 +258,7 @@ var S3Driver = class {
206
258
  this.prefix = options.prefix ?? "";
207
259
  this.baseUrl = options.url ?? `https://${this.bucket}.s3.${this.region}.amazonaws.com`;
208
260
  this.defaultVisibility = options.visibility ?? "private";
261
+ this.acl = options.acl ?? true;
209
262
  }
210
263
  options;
211
264
  client = null;
@@ -217,6 +270,7 @@ var S3Driver = class {
217
270
  prefix;
218
271
  baseUrl;
219
272
  defaultVisibility;
273
+ acl;
220
274
  /**
221
275
  * Get or create the S3 client.
222
276
  */
@@ -247,13 +301,8 @@ var S3Driver = class {
247
301
  prefixKey(path) {
248
302
  return this.prefix ? `${this.prefix}/${path}` : path;
249
303
  }
250
- /**
251
- * Get ACL from visibility.
252
- */
253
- getAcl(visibility) {
254
- return visibility === "public" ? "public-read" : "private";
255
- }
256
304
  async put(path, content, options) {
305
+ assertVisibilitySupported(this.acl, this.defaultVisibility, options?.visibility, "put");
257
306
  const client = await this.getClient();
258
307
  const { PutObjectCommand } = await importAwsModule("@aws-sdk/client-s3");
259
308
  const body = typeof content === "string" ? Buffer.from(content) : content;
@@ -263,7 +312,7 @@ var S3Driver = class {
263
312
  Key: this.prefixKey(path),
264
313
  Body: body,
265
314
  ContentType: options?.contentType,
266
- ACL: this.getAcl(visibility),
315
+ ...putAclFields(this.acl, visibility),
267
316
  Metadata: options?.metadata
268
317
  });
269
318
  await client.send(command);
@@ -412,6 +461,14 @@ var S3Driver = class {
412
461
  throw error;
413
462
  }
414
463
  }
464
+ /** `metadata()`, but honouring the contract's not-found error. */
465
+ async metadataOrFail(path) {
466
+ const metadata = await this.metadata(path);
467
+ if (!metadata) {
468
+ throw new Error(`File not found: ${path}`);
469
+ }
470
+ return metadata;
471
+ }
415
472
  async files(directory) {
416
473
  const client = await this.getClient();
417
474
  const { ListObjectsV2Command } = await importAwsModule("@aws-sdk/client-s3");
@@ -459,16 +516,25 @@ var S3Driver = class {
459
516
  }
460
517
  }
461
518
  async setVisibility(path, visibility) {
519
+ assertVisibilitySupported(this.acl, this.defaultVisibility, visibility, "setVisibility");
520
+ if (!this.acl) {
521
+ await this.metadataOrFail(path);
522
+ return;
523
+ }
462
524
  const client = await this.getClient();
463
525
  const { PutObjectAclCommand } = await importAwsModule("@aws-sdk/client-s3");
464
526
  const command = new PutObjectAclCommand({
465
527
  Bucket: this.bucket,
466
528
  Key: this.prefixKey(path),
467
- ACL: this.getAcl(visibility)
529
+ ACL: cannedAcl(visibility)
468
530
  });
469
531
  await client.send(command);
470
532
  }
471
533
  async getVisibility(path) {
534
+ if (!this.acl) {
535
+ await this.metadataOrFail(path);
536
+ return this.defaultVisibility;
537
+ }
472
538
  const client = await this.getClient();
473
539
  const { GetObjectAclCommand } = await importAwsModule("@aws-sdk/client-s3");
474
540
  const command = new GetObjectAclCommand({
@@ -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,17 @@ import {
5
5
  logDevServerBanner,
6
6
  parseImportMap,
7
7
  startViteDevServer
8
- } from "./chunk-62AB24ZU.js";
8
+ } from "./chunk-AOPXIURJ.js";
9
+ import {
10
+ LocalDriver,
11
+ MemoryDriver as MemoryDriver3,
12
+ S3Driver,
13
+ StorageManager,
14
+ createStorageManager
15
+ } from "./chunk-JTNRAWQR.js";
16
+ import {
17
+ trimSlashes
18
+ } from "./chunk-AZOYI43J.js";
9
19
  import {
10
20
  PendingSchedule,
11
21
  Schedule,
@@ -20,16 +30,6 @@ import {
20
30
  parseCron,
21
31
  toTimezone
22
32
  } from "./chunk-EI5GYMAT.js";
23
- import {
24
- LocalDriver,
25
- MemoryDriver as MemoryDriver3,
26
- S3Driver,
27
- StorageManager,
28
- createStorageManager
29
- } from "./chunk-HWEWL6TE.js";
30
- import {
31
- trimSlashes
32
- } from "./chunk-AZOYI43J.js";
33
33
  import {
34
34
  isDocsViewerEnabled
35
35
  } from "./chunk-A5JJ7XTH.js";
@@ -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-AOPXIURJ.js";
8
8
  import {
9
9
  trimTrailingSlashes
10
10
  } from "../chunk-AZOYI43J.js";
@@ -48,6 +48,8 @@ export declare class LocalDriver implements StorageDriver {
48
48
  deleteDirectory(path: string): Promise<void>;
49
49
  setVisibility(path: string, visibility: 'public' | 'private'): Promise<void>;
50
50
  getVisibility(path: string): Promise<'public' | 'private'>;
51
+ private warnIfMissing;
52
+ private warnUnsupportedVisibility;
51
53
  /**
52
54
  * Get the root directory.
53
55
  */
@@ -27,6 +27,7 @@ export declare class S3Driver implements StorageDriver {
27
27
  private readonly prefix;
28
28
  private readonly baseUrl;
29
29
  private readonly defaultVisibility;
30
+ private readonly acl;
30
31
  constructor(options: S3DriverOptions);
31
32
  /**
32
33
  * Get or create the S3 client.
@@ -36,10 +37,6 @@ export declare class S3Driver implements StorageDriver {
36
37
  * Get the prefixed key.
37
38
  */
38
39
  private prefixKey;
39
- /**
40
- * Get ACL from visibility.
41
- */
42
- private getAcl;
43
40
  put(path: string, content: Buffer | string, options?: PutOptions): Promise<string>;
44
41
  putFile(path: string, localPath: string, options?: PutOptions): Promise<string>;
45
42
  get(path: string): Promise<Buffer | null>;
@@ -54,6 +51,8 @@ export declare class S3Driver implements StorageDriver {
54
51
  size(path: string): Promise<number>;
55
52
  lastModified(path: string): Promise<Date>;
56
53
  metadata(path: string): Promise<FileMetadata | null>;
54
+ /** `metadata()`, but honouring the contract's not-found error. */
55
+ private metadataOrFail;
57
56
  files(directory: string): Promise<string[]>;
58
57
  directories(directory: string): Promise<string[]>;
59
58
  allFiles(directory: string): Promise<string[]>;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * The ACL half of the S3 driver, kept out of the driver so it can be tested
3
+ * without the optional `@aws-sdk/client-s3` peer installed: these functions
4
+ * decide what goes into a command, which is exactly the part that was wrong
5
+ * for every S3-compatible endpoint without ACL support.
6
+ */
7
+ export type Visibility = 'public' | 'private';
8
+ /** The canned ACL S3 uses for each visibility. */
9
+ export declare function cannedAcl(visibility: Visibility): string;
10
+ /**
11
+ * The `ACL` field for a `PutObject` input, or nothing when the endpoint has
12
+ * no ACLs. Returned as a spreadable object so the caller never sends an
13
+ * explicit `ACL: undefined`, which some S3 implementations reject outright
14
+ * rather than treat as absent.
15
+ */
16
+ export declare function putAclFields(acl: boolean, visibility: Visibility): {
17
+ ACL?: string;
18
+ };
19
+ /**
20
+ * Guard for a per-object visibility an ACL-less endpoint cannot honour.
21
+ * Throws rather than silently dropping the request: a `setVisibility(path,
22
+ * 'private')` that does nothing on a public bucket is a leak that looks like
23
+ * success.
24
+ */
25
+ export declare function assertVisibilitySupported(acl: boolean, diskVisibility: Visibility, requested: Visibility | undefined, operation: string): void;
@@ -4,7 +4,7 @@ import {
4
4
  S3Driver,
5
5
  StorageManager,
6
6
  createStorageManager
7
- } from "../chunk-HWEWL6TE.js";
7
+ } from "../chunk-JTNRAWQR.js";
8
8
  import "../chunk-AZOYI43J.js";
9
9
  export {
10
10
  LocalDriver,
@@ -160,12 +160,29 @@ export interface StorageDriver {
160
160
  deleteDirectory(path: string): Promise<void>;
161
161
  /**
162
162
  * Set file visibility.
163
+ *
164
+ * Contract: throws when the file does not exist, so a caller cannot take
165
+ * success as proof the object is there. A driver whose backend has no
166
+ * per-object visibility (bucket-level access, a plain filesystem) reports
167
+ * the disk's configured visibility and throws when asked for the other
168
+ * value, rather than accepting a request it cannot honour — silently
169
+ * doing nothing is a leak that looks like success.
170
+ *
171
+ * `LocalDriver` is such a backend: what makes a local file reachable is
172
+ * the disk root and whatever serves it, not a flag on one file. It has
173
+ * always accepted per-object requests and done nothing, so it warns
174
+ * instead of throwing and will throw in the next major.
175
+ *
163
176
  * @param path File path
164
177
  * @param visibility Visibility setting
165
178
  */
166
179
  setVisibility(path: string, visibility: 'public' | 'private'): Promise<void>;
167
180
  /**
168
181
  * Get file visibility.
182
+ *
183
+ * Contract: throws when the file does not exist. Drivers without
184
+ * per-object visibility report the disk's configured value.
185
+ *
169
186
  * @param path File path
170
187
  */
171
188
  getVisibility(path: string): Promise<'public' | 'private'>;
@@ -233,6 +250,24 @@ export interface S3DriverOptions {
233
250
  * @default 'private'
234
251
  */
235
252
  visibility?: 'public' | 'private';
253
+ /**
254
+ * Whether the endpoint implements S3 object ACLs.
255
+ *
256
+ * AWS S3 does, so this defaults to `true` and every `put` carries an
257
+ * `x-amz-acl` header derived from the file's visibility. Several
258
+ * S3-compatible endpoints do not: Cloudflare R2 documents `x-amz-acl` and
259
+ * the ACL operations as unsupported (access is decided per bucket), and
260
+ * MinIO/others vary. Set `acl: false` for those.
261
+ *
262
+ * With `acl: false` the driver stops sending the header, and visibility
263
+ * becomes a property of the whole disk: `getVisibility()` reports the
264
+ * configured `visibility`, and `put({ visibility })` / `setVisibility()`
265
+ * throw when asked for the other value rather than silently not applying
266
+ * it. Enforce per-object access in front of the disk instead.
267
+ *
268
+ * @default true
269
+ */
270
+ acl?: boolean;
236
271
  }
237
272
  /**
238
273
  * Memory driver options.
@@ -3,8 +3,9 @@
3
3
  * quadratically on adversarial input (long slash runs mid-string), and
4
4
  * several call sites here feed request-derived paths.
5
5
  *
6
- * A twin of `trimSlashes` lives in `@guren/cli` (`src/utils.ts`); the
7
- * packages share no dependency edge, so the six lines are duplicated by
6
+ * Twins live in `@guren/cli` (`src/utils.ts`, `trimSlashes`) and
7
+ * `@guren/plugin-cloudflare` (`src/storage/R2Driver.ts`, both functions);
8
+ * neither package can import this module, so the lines are duplicated by
8
9
  * convention.
9
10
  */
10
11
  export declare function trimTrailingSlashes(value: string): string;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Emit a warning the first time a given key is seen in this process.
3
+ *
4
+ * Deprecation warnings have to be loud enough to be read once and quiet
5
+ * enough not to drown a request log, which is the same shape the OAuth
6
+ * warnings settled on (`auth/oauth/index.ts`) — this is that pattern with a
7
+ * key, so several call sites can share it.
8
+ */
9
+ export declare function warnOnce(key: string, message: string): void;
10
+ /** Test seam: forget what has already been warned about. */
11
+ export declare function resetWarnOnce(): void;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guren/server",
3
- "version": "2.5.0",
3
+ "version": "2.7.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",