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

package/README.md

@@ -43,7 +43,7 @@ Next.js owns the frontend, Drizzle owns the SQL, and your services own the rules
 
 ```bash
 pnpm add @spfn/core@beta drizzle-orm@1.0.0-rc.4 postgres pg
-# optional peer: next ^16.3.3   (only for the Next.js bridge)
+# optional peer: next ^16.3.8   (only for the Next.js bridge)
 ```
 
 Node `>=20.0.0`. ESM only.
@@ -691,6 +691,10 @@ The manifest gains a `modules` array and per-command `module`, `summary`, `effec
 `scopes`. All of it is additive — an app that mounts no modules serves exactly the v1
 manifest it served before.
 
+An app's own ops routes may declare `.effect()` and `.summary()` too, and the manifest
+carries both for that command. On `/_ops` they are optional: a route declaring neither is
+announced exactly as before.
+
 ```bash
 spfn ops modules                                      # what is mounted, and from where
 spfn ops list --module ledger                         # just that module's commands
@@ -731,6 +735,8 @@ export const app = defineSurface({
 
 export const pageAdd = app.route.post('/pages')            // POST /_app/pages
     .input({ body: Type.Object({ title: Type.String() }) })
+    .effect('write')                                        // required: read | write | destructive
+    .summary('Add a page to the blueprint')                 // optional, at most 500 characters
     .handler(async (c) => pagesRepository.add((await c.data()).body.title));
 
 // src/server/router.ts — both surfaces, side by side
@@ -754,6 +760,12 @@ export const appRouter = defineRouter({ ... }).packages([app.router({ pageAdd })
   module is mounted. A guard named like `auth` or like one of the command's group or own
   middlewares is refused: registration keeps one middleware per name, so the other one would
   never run.
+- **Effect.** Every app command on a `defineSurface` surface declares `.effect()` on its
+  route; `router()` refuses one that does not, naming the command, so a client never
+  receives a command whose effect it cannot know. `/_ops` routes may declare it and need
+  not. The manifest announces `effect` and `summary` beside the command, and `authorize`
+  receives them on the command it is given. A module command's own declaration wins over its
+  route's: a route `.effect()` that disagrees with it is refused.
 - **Modules.** A module is validated against the namespace of the surface that mounts it —
   its commands must live under `<namespace>/<id>/`. Write one for a surface with
   `defineSurfaceModule(module, '/_app')`; a module written for `/_ops` mounted on `/_app` is

package/dist/contract/index.d.ts

@@ -1,11 +1,11 @@
 import { E as EventRouterDef } from '../router-CysBmgv3.js';
-import { R as Router } from '../router-DaDrprJd.js';
-import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-D52SokSM.js';
-export { d as CompatibilityPolicy, e as ContractEvent, f as ContractEvents, g as ContractRequest, h as ContractViolationKind, J as JsonSchema } from '../types-D52SokSM.js';
+import { R as Router } from '../router-4YoIy5fN.js';
+import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-5Rl11_Nb.js';
+export { d as CompatibilityPolicy, e as ContractEvent, f as ContractEvents, g as ContractRequest, h as ContractViolationKind, J as JsonSchema } from '../types-5Rl11_Nb.js';
 import '@sinclair/typebox';
 import '../define-middleware-CVKgqo8S.js';
 import 'hono';
-import '../route-builder-BHKgGkwI.js';
+import '../route-builder-DRW-MSCJ.js';
 import 'hono/utils/http-status';
 import '../route/types.js';
 

package/dist/{error-BcdBVfRA.d.ts → error-TsUIjp_x.d.ts}

@@ -1,7 +1,7 @@
-import { R as RouteDef, f as RouteBuilder } from './route-builder-BHKgGkwI.js';
-import { J as JsonSchema } from './types-D52SokSM.js';
-import { R as Router } from './router-DaDrprJd.js';
-import { HttpMethod } from './route/types.js';
+import { R as RouteDef, f as RouteBuilder } from './route-builder-DRW-MSCJ.js';
+import { J as JsonSchema } from './types-5Rl11_Nb.js';
+import { R as Router } from './router-4YoIy5fN.js';
+import { RouteEffect, HttpMethod } from './route/types.js';
 
 /**
  * How refusals name the surface they come from.
@@ -35,7 +35,8 @@ interface SurfaceWording {
  * than registered at paths outside the surface that is supposed to guard them.
  */
 
-type SurfaceEffect = 'read' | 'write' | 'destructive';
+/** One vocabulary for module commands and an app's own: the route's `.effect()`. */
+type SurfaceEffect = RouteEffect;
 interface SurfaceModuleCommand<TRoute extends RouteDef<any> = RouteDef<any>> {
     summary: string;
     effect: SurfaceEffect;
@@ -115,8 +116,13 @@ interface SurfaceCommand {
     path: string;
     /** Present for commands contributed by an explicitly mounted module. */
     module?: string;
+    /**
+     * A module command's from its declaration; an app command's from the
+     * route's `.summary()` and `.effect()`, present only when declared.
+     */
     summary?: string;
     effect?: SurfaceEffect;
+    /** Present for module commands only. */
     scopes?: string[];
     /** Input sections the route declares, each as JSON Schema. */
     input: {
@@ -134,8 +140,9 @@ interface SurfaceManifest {
 }
 /**
  * Walk a routes record (nested routers included) and collect every RouteDef
- * as a command. Validation of paths happens in the surface's `router()`, so
- * nothing here is checked but the uniqueness of names.
+ * as a command, with the summary and effect its route declared. Validation of
+ * paths and of that metadata happens in the surface's `router()`, so nothing
+ * here is checked but the uniqueness of names.
  */
 declare function collectSurfaceCommands(routes: Record<string, RouteDef<any> | Router<any>>, wording?: SurfaceWording): SurfaceCommand[];
 

package/dist/ops/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 { S as SurfaceEffect, a as SurfaceModuleCommand, b as SurfaceModule, c as SurfaceRouteBuilder, d as SurfaceCommand, e as SurfaceManifest, f as SurfaceModuleDescriptor } from '../error-BcdBVfRA.js';
-export { g as OpsRouterError } from '../error-BcdBVfRA.js';
+import { R as RouteDef } from '../route-builder-DRW-MSCJ.js';
+import { R as Router } from '../router-4YoIy5fN.js';
+import { S as SurfaceEffect, a as SurfaceModuleCommand, b as SurfaceModule, c as SurfaceRouteBuilder, d as SurfaceCommand, e as SurfaceManifest, f as SurfaceModuleDescriptor } from '../error-TsUIjp_x.js';
+export { g as OpsRouterError } 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';
 
 /**
  * Capability ops module contract
@@ -60,7 +60,10 @@ declare function defineOpsModule<TCommands extends Record<string, OpsModuleComma
  * It is the command surface (`@spfn/core/surface`) fixed to `/_ops`, with the
  * scope-factory `authorize` this factory has always taken adapted to the
  * surface's per-command one: applied to module commands only, so every
- * middleware chain is what it was before surfaces existed.
+ * middleware chain is what it was before surfaces existed. An ops route may
+ * declare `.effect()` and `.summary()` and the manifest carries them; unlike
+ * `defineSurface`, a route declaring neither is not refused, so an ops
+ * surface written before they existed boots and announces what it always did.
  *
  * @example
  * ```ts

package/dist/ops/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.`);
@@ -665,6 +719,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;
 }
@@ -689,6 +745,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(
@@ -696,7 +789,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.`
@@ -704,19 +797,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)) {
@@ -725,9 +818,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;
@@ -758,9 +853,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)) {
@@ -812,6 +904,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 };
@@ -851,7 +944,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),
@@ -859,7 +953,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(
@@ -885,11 +979,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),
@@ -928,7 +1023,7 @@ function createOpsRouter(routes, options) {
     auth: options?.auth,
     authorize: moduleScopeGuard(options?.authorize),
     modules: options?.modules
-  }, OPS_WORDING).router(routes);
+  }, OPS_WORDING, { requireEffect: false }).router(routes);
 }
 
 // src/ops/manifest.ts