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

package/dist/{route-builder-BHKgGkwI.d.ts → route-builder-DRW-MSCJ.d.ts}

@@ -2,7 +2,7 @@ import { Context, MiddlewareHandler } from 'hono';
 import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
 import { TSchema, Static } from '@sinclair/typebox';
 import { ContentfulStatusCode, RedirectStatusCode } from 'hono/utils/http-status';
-import { HttpMethod } from './route/types.js';
+import { HttpMethod, RouteEffect } from './route/types.js';
 
 /**
  * Route Input Types
@@ -296,6 +296,13 @@ type RouteDef<TInput extends RouteInput = RouteInput, TInterceptor extends Route
      * the compatibility gate read it.
      */
     contract?: RouteContract;
+    /**
+     * What invoking this route does. Read by a command surface, which
+     * announces it in its manifest; codegen and the contract ignore it.
+     */
+    effect?: RouteEffect;
+    /** One line a command surface announces beside the route; codegen and the contract ignore it. */
+    summary?: string;
     handler: RouteHandlerFn<TInput, TInterceptor, TResponse>;
     _input: TInput;
     _interceptor: TInterceptor;
@@ -312,6 +319,8 @@ declare class RouteBuilder<TInput extends RouteInput = {}, TInterceptor extends
     _middlewares?: (MiddlewareHandler | NamedMiddleware<string>)[];
     _skipMiddlewares?: string[] | '*';
     _contract?: RouteContract;
+    _effect?: RouteEffect;
+    _summary?: string;
     /**
      * Create a new RouteBuilder with copied properties and optional overrides
      */
@@ -472,6 +481,45 @@ declare class RouteBuilder<TInput extends RouteInput = {}, TInterceptor extends
      * ```
      */
     contract(contract: RouteContract): RouteBuilder<TInput, TInterceptor, TResponse>;
+    /**
+     * 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: RouteEffect): RouteBuilder<TInput, TInterceptor, TResponse>;
+    /**
+     * 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: string): RouteBuilder<TInput, TInterceptor, TResponse>;
     /**
      * Define handler function
      *

package/dist/{router-DaDrprJd.d.ts → router-4YoIy5fN.d.ts}

@@ -1,5 +1,5 @@
 import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
-import { R as RouteDef } from './route-builder-BHKgGkwI.js';
+import { R as RouteDef } from './route-builder-DRW-MSCJ.js';
 
 /**
  * Router Definition

package/dist/server/index.d.ts

@@ -12,7 +12,7 @@ import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WS
 import { DatabaseProvider, MigrationStatus, MigrationStatusDb } from '@spfn/core/db';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
-import { R as RouteDef } from '../route-builder-BHKgGkwI.js';
+import { R as RouteDef } from '../route-builder-DRW-MSCJ.js';
 import { a as EnvRegistry } from '../registry-C2KQCh0m.js';
 import 'pg-boss';
 import '../token-manager-Ckjt2-qq.js';

package/dist/server/index.js

@@ -1520,6 +1520,8 @@ var RouteBuilder = class _RouteBuilder {
   _middlewares;
   _skipMiddlewares;
   _contract;
+  _effect;
+  _summary;
   /**
    * Create a new RouteBuilder with copied properties and optional overrides
    */
@@ -1532,6 +1534,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;
   }
   /**
@@ -1702,6 +1706,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
    *
@@ -1757,6 +1804,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: {},