@spfn/core 0.3.0-beta.20 → 0.3.0-beta.22

package/dist/surface/index.d.ts

@@ -1,13 +1,13 @@
 import { MiddlewareHandler } from 'hono';
 import { a as NamedMiddleware } from '../define-middleware-CVKgqo8S.js';
-import { R as RouteDef } from '../route-builder-BHKgGkwI.js';
-import { R as Router } from '../router-DaDrprJd.js';
-import { c as SurfaceRouteBuilder, d as SurfaceCommand, b as SurfaceModule } from '../error-BcdBVfRA.js';
-export { S as SurfaceEffect, g as SurfaceError, e as SurfaceManifest, a as SurfaceModuleCommand, f as SurfaceModuleDescriptor, h as collectSurfaceCommands, i as defineSurfaceModule } from '../error-BcdBVfRA.js';
+import { R as RouteDef } from '../route-builder-DRW-MSCJ.js';
+import { R as Router } from '../router-4YoIy5fN.js';
+import { c as SurfaceRouteBuilder, d as SurfaceCommand, b as SurfaceModule } from '../error-TsUIjp_x.js';
+export { S as SurfaceEffect, g as SurfaceError, e as SurfaceManifest, a as SurfaceModuleCommand, f as SurfaceModuleDescriptor, h as collectSurfaceCommands, i as defineSurfaceModule } from '../error-TsUIjp_x.js';
 import '@sinclair/typebox';
 import 'hono/utils/http-status';
 import '../route/types.js';
-import '../types-D52SokSM.js';
+import '../types-5Rl11_Nb.js';
 
 /**
  * Command Surface
@@ -62,6 +62,9 @@ type SurfaceMiddleware = NamedMiddleware<string> | MiddlewareHandler;
  * Build the guard for one command, or `undefined` for none. Called once per
  * command when the router is built; the guard runs after `auth` and before the
  * command's own middlewares.
+ *
+ * The command is the manifest entry, so its `effect` is there to read — a
+ * guard can be stricter for a `destructive` command than for a `read`.
  */
 type SurfaceAuthorize = (command: SurfaceCommand) => SurfaceMiddleware | undefined;
 interface SurfaceOptions {
@@ -100,6 +103,9 @@ interface Surface {
  *
  * The namespace, the auth middleware, and the `authorize` requirement are
  * checked here; routes and modules when `router()` builds the package router.
+ * Every app command must declare its effect with
+ * `.effect('read' | 'write' | 'destructive')` — `router()` refuses one that
+ * does not, so a client is never handed a command it cannot classify.
  * The router is an ordinary `Router` meant to be mounted with `.packages()`,
  * so its routes stay out of the app's client types exactly like other
  * package routes.

package/dist/surface/index.js

@@ -7,6 +7,8 @@ var RouteBuilder = class _RouteBuilder {
   _middlewares;
   _skipMiddlewares;
   _contract;
+  _effect;
+  _summary;
   /**
    * Create a new RouteBuilder with copied properties and optional overrides
    */
@@ -19,6 +21,8 @@ var RouteBuilder = class _RouteBuilder {
     builder._middlewares = overrides?.middlewares ?? this._middlewares;
     builder._skipMiddlewares = overrides?.skipMiddlewares ?? this._skipMiddlewares;
     builder._contract = overrides?.contract ?? this._contract;
+    builder._effect = overrides?.effect ?? this._effect;
+    builder._summary = overrides?.summary ?? this._summary;
     return builder;
   }
   /**
@@ -189,6 +193,49 @@ var RouteBuilder = class _RouteBuilder {
   contract(contract) {
     return this.clone({ contract });
   }
+  /**
+   * Declare what invoking this route does
+   *
+   * Read by a command surface (`@spfn/core/surface`, `@spfn/core/ops`),
+   * which announces it in its manifest so a machine caller can tell a read
+   * from a write before it calls — `spfn ops call` asks for `--yes` before a
+   * `destructive` command. A surface built with `defineSurface` refuses an
+   * app command that does not declare one; on `/_ops` it is optional.
+   *
+   * Nothing else reads it: codegen, the route map, and the contract are
+   * unaffected, and a route outside any surface simply carries it.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .input({ body: PageAddBody })
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  effect(effect) {
+    return this.clone({ effect });
+  }
+  /**
+   * Describe this route in one line for a command surface's manifest
+   *
+   * A surface announces it beside the command in `spfn ops list` and
+   * `--describe`, and refuses one that is empty or longer than 500
+   * characters. Codegen, the route map, and the contract ignore it. On a
+   * module command the module's own summary wins.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  summary(summary) {
+    return this.clone({ summary });
+  }
   /**
    * Define handler function
    *
@@ -244,6 +291,8 @@ var RouteBuilder = class _RouteBuilder {
       middlewares: this._middlewares,
       skipMiddlewares: this._skipMiddlewares,
       contract: this._contract,
+      ...this._effect !== void 0 ? { effect: this._effect } : {},
+      ...this._summary !== void 0 ? { summary: this._summary } : {},
       handler: fn,
       _input: {},
       _interceptor: {},
@@ -392,6 +441,8 @@ function visit(routes, commands, claimed, wording) {
       name,
       method: entry.method,
       path: entry.path,
+      ...entry.summary !== void 0 ? { summary: entry.summary } : {},
+      ...entry.effect !== void 0 ? { effect: entry.effect } : {},
       input: toCommandInput(entry.input)
     });
   }
@@ -498,6 +549,9 @@ var COMMAND_NAME = /^[A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*$/;
 var CONTRACT_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/;
 var EFFECTS = /* @__PURE__ */ new Set(["read", "write", "destructive"]);
 var PATH_BASE = "https://spfn.invalid";
+function isSurfaceEffect(value) {
+  return EFFECTS.has(value);
+}
 function assertText(label, value) {
   if (typeof value !== "string" || value.trim().length === 0) {
     throw new SurfaceError(`${label} must be a non-empty string.`);
@@ -668,6 +722,8 @@ function surfaceRouteBuilder(namespace, wording) {
 }
 
 // src/surface/define-surface.ts
+var MAX_COMMAND_SUMMARY_LENGTH = 500;
+var EFFECT_METHOD = ".effect('read' | 'write' | 'destructive')";
 function isRouter2(value) {
   return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
 }
@@ -692,6 +748,43 @@ function assertSurfaceRoute(plan, name, def) {
     );
   }
 }
+function assertCommandMetadata(plan, name, def) {
+  const label = `${capitalized(plan.wording.noun)} command "${name}"`;
+  if (def.effect === void 0 && plan.requireEffect) {
+    throw new SurfaceError(
+      `${label} declares no effect. A client reads it to decide whether to call, retry, or ask for confirmation, so ${plan.wording.factory} refuses a command without one. Declare it on the route with ${EFFECT_METHOD}.`
+    );
+  }
+  if (def.effect !== void 0 && !isSurfaceEffect(def.effect)) {
+    throw new SurfaceError(
+      `${label} has invalid effect ${JSON.stringify(def.effect)}. A client knows no other, so declare it with ${EFFECT_METHOD}.`
+    );
+  }
+  assertCommandSummary(label, def.summary);
+}
+function assertCommandSummary(label, summary) {
+  if (summary === void 0) {
+    return;
+  }
+  if (typeof summary !== "string" || summary.trim().length === 0) {
+    throw new SurfaceError(
+      `${label} has an empty summary. A client would list it as a command described by nothing; give .summary() one line of text, or leave it out.`
+    );
+  }
+  if (summary.length > MAX_COMMAND_SUMMARY_LENGTH) {
+    throw new SurfaceError(
+      `${label} has a summary of ${summary.length} characters, over the ${MAX_COMMAND_SUMMARY_LENGTH} a client accepts \u2014 it would drop the command's metadata and treat it as destructive. Shorten it.`
+    );
+  }
+}
+function assertModuleRouteEffect(plan, name, definition) {
+  const routeEffect = definition.route.effect;
+  if (routeEffect !== void 0 && routeEffect !== definition.effect) {
+    throw new SurfaceError(
+      `${capitalized(plan.wording.noun)} command "${name}" is declared ${JSON.stringify(definition.effect)} by its module, but its route says .effect(${JSON.stringify(routeEffect)}). The manifest announces the module's declaration, so the two cannot disagree. Drop the route's .effect() or make it match.`
+    );
+  }
+}
 function assertSurfaceName(plan, name) {
   if (name === plan.manifestName) {
     throw new SurfaceError(
@@ -699,7 +792,7 @@ function assertSurfaceName(plan, name) {
     );
   }
 }
-function rebuildNestedRouter(plan, name, router, guards, inherited) {
+function rebuildNestedRouter(plan, name, router, commandsByName, inherited) {
   if (router._packageRouters?.length > 0) {
     throw new SurfaceError(
       `${capitalized(plan.wording.noun)} router "${name}" mounts package routers with .packages(). Their routes bypass the prefix check and the auth injection, so a surface cannot carry them.`
@@ -707,19 +800,19 @@ function rebuildNestedRouter(plan, name, router, guards, inherited) {
   }
   const handedDown = [...inherited, ...router._globalMiddlewares ?? []];
   let rebuilt = defineUnmappedRouter(
-    secureRoutes(plan, router.routes, guards, handedDown)
+    secureRoutes(plan, router.routes, commandsByName, handedDown)
   );
   if (router._contractVersion) {
     rebuilt = rebuilt.contractVersion(router._contractVersion);
   }
   return rebuilt;
 }
-function secureRoutes(plan, routes, guards, inherited = []) {
+function secureRoutes(plan, routes, commandsByName, inherited = []) {
   const secured = {};
   for (const [name, entry] of Object.entries(routes)) {
     assertSurfaceName(plan, name);
     if (isRouter2(entry)) {
-      secured[name] = rebuildNestedRouter(plan, name, entry, guards, inherited);
+      secured[name] = rebuildNestedRouter(plan, name, entry, commandsByName, inherited);
       continue;
     }
     if (!isRouteDef2(entry)) {
@@ -728,9 +821,11 @@ function secureRoutes(plan, routes, guards, inherited = []) {
       );
     }
     assertSurfaceRoute(plan, name, entry);
+    assertCommandMetadata(plan, name, entry);
+    const guard = plan.authorize?.(commandsByName.get(name));
     secured[name] = {
       ...entry,
-      middlewares: commandChain(plan, name, guards.get(name), [...inherited, ...entry.middlewares ?? []])
+      middlewares: commandChain(plan, name, guard, [...inherited, ...entry.middlewares ?? []])
     };
   }
   return secured;
@@ -761,9 +856,6 @@ function refuseGuardCollision(plan, name, guardName, declared) {
 function middlewareNameOf(middleware) {
   return typeof middleware === "function" ? void 0 : middleware.name;
 }
-function guardsFor(plan, commands) {
-  return new Map(commands.map((command) => [command.name, plan.authorize?.(command)]));
-}
 function assertModuleCommandFree(plan, command, appCommands, claimed) {
   const noun = plan.wording.noun;
   if (claimed.names.has(command.name)) {
@@ -815,6 +907,7 @@ function compileModules(plan, appCommands) {
         path: definition.route.path,
         input: collectSurfaceCommands({ [localName]: definition.route }, plan.wording)[0].input
       };
+      assertModuleRouteEffect(plan, command.name, definition);
       assertModuleCommandFree(plan, command, appCommands, claimed);
       compiled.commands.push(command);
       compiled.routes[command.name] = { route: definition.route, command };
@@ -854,7 +947,8 @@ function buildRouter(plan, routes) {
     ...moduleSurface.descriptors.length > 0 ? { modules: moduleSurface.descriptors } : {},
     commands
   };
-  const secured = secureRoutes(plan, routes, guardsFor(plan, appCommands));
+  const commandsByName = new Map(appCommands.map((command) => [command.name, command]));
+  const secured = secureRoutes(plan, routes, commandsByName);
   const securedModules = secureModuleRoutes(plan, moduleSurface.routes);
   return Object.defineProperty(defineUnmappedRouter({
     [plan.manifestName]: manifestRoute(plan, manifest),
@@ -862,7 +956,7 @@ function buildRouter(plan, routes) {
     ...securedModules
   }), "_surfaceNamespace", { value: plan.namespace, enumerable: false });
 }
-function planOf(options, wording) {
+function planOf(options, wording, rules) {
   assertNamespace(options?.namespace);
   if (!options.auth) {
     throw new SurfaceError(
@@ -888,11 +982,12 @@ function planOf(options, wording) {
     authorize: options.authorize,
     manifest,
     modules,
-    wording
+    wording,
+    requireEffect: rules.requireEffect
   };
 }
-function createSurface(options, wording) {
-  const plan = planOf(options, wording);
+function createSurface(options, wording, rules) {
+  const plan = planOf(options, wording, rules);
   return {
     namespace: plan.namespace,
     route: surfaceRouteBuilder(plan.namespace, wording),
@@ -900,7 +995,7 @@ function createSurface(options, wording) {
   };
 }
 function defineSurface(options) {
-  return createSurface(options, SURFACE_WORDING);
+  return createSurface(options, SURFACE_WORDING, { requireEffect: true });
 }
 
 export { SurfaceError, collectSurfaceCommands, defineSurface, defineSurfaceModule };