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

package/README.md

@@ -356,6 +356,7 @@ Each module has its own README with the API detail.
 | `@spfn/core/codegen` | The codegen orchestrator and the built-in generators: `@spfn/core:route-map` for the proxy's route map, `@spfn/core:contract` for the client contract. | [src/codegen](./src/codegen/README.md) |
 | `@spfn/core/contract` | Route contracts for clients that ship separately: collect, snapshot, and the build gate that refuses a breaking change. | [src/contract](./src/contract/README.md) |
 | `@spfn/core/ops` | The operations surface `spfn ops` drives: `opsRoute`, `createOpsRouter`, `defineOpsModule`, and the manifest the CLI discovers commands from. Structure only — the router is always authenticated, and token verification lives in `@spfn/auth`. | [How do I operate the app from the terminal?](#how-do-i-operate-the-app-from-the-terminal) |
+| `@spfn/core/surface` | `defineSurface`: a command surface on any namespace — the same authenticated router, manifest and modules `@spfn/core/ops` is on `/_ops`, for a caller other than an operator. | [Can a second surface sit beside `/_ops`?](#can-a-second-surface-sit-beside-_ops) |
 
 `db/manager`, `db/schema` and `db/transaction` are **not** package subpaths of their own.
 They are internal modules re-exported by `@spfn/core/db` — import their symbols from
@@ -703,6 +704,66 @@ CLI keeps the token in the keychain (`spfn ops token store`), and resolution ord
 `--token` → `SPFN_OPS_TOKEN` → keychain. The `--app` URL must be https, since every command
 carries a secret; `http` is accepted only against a loopback host.
 
+### Can a second surface sit beside `/_ops`?
+
+Yes. `/_ops` is one command surface; `defineSurface` from `@spfn/core/surface` builds
+another on a namespace of your choosing, for a caller that is not an operator — a service
+holding a token some issuer signed, say. It is the same structure: a `route` with the
+namespace applied, auth injected into every command, a manifest at `<namespace>/_manifest`
+registered first, and modules mounted only when you name them. `createOpsRouter` is
+`defineSurface({ namespace: '/_ops', ... }).router(...)`.
+
+```typescript
+// src/server/app-surface.ts
+import { Type } from '@sinclair/typebox';
+import { defineSurface } from '@spfn/core/surface';
+import { signedTokenAuth } from '@spfn/auth/server';
+
+export const app = defineSurface({
+    namespace: '/_app',                                     // required
+    auth: signedTokenAuth({                                 // required
+        keysUrl: 'https://issuer.example/.well-known/keys',
+        iss: 'https://issuer.example',
+        aud: 'my-app',
+    }),
+    manifest: 'public',                                     // 'authenticated' (default) | 'public'
+});
+
+export const pageAdd = app.route.post('/pages')            // POST /_app/pages
+    .input({ body: Type.Object({ title: Type.String() }) })
+    .handler(async (c) => pagesRepository.add((await c.data()).body.title));
+
+// src/server/router.ts — both surfaces, side by side
+export const appRouter = defineRouter({ ... }).packages([app.router({ pageAdd }), opsRouter]);
+```
+
+- **Namespace.** An absolute path of `[A-Za-z0-9_-]` segments with no trailing slash —
+  `/_app`, `/machine/v1`. Anything else (`app`, `/_app/`, `/`, a `%`, a `:param`) is refused
+  at `defineSurface`.
+- **Manifest.** Served at `<namespace>/_manifest` under the reserved route name
+  `get<Namespace>Manifest` — `getAppManifest` for `/_app`, `getOpsManifest` for `/_ops`,
+  `getappManifest` for `/app`. The namespace is encoded one-to-one (`_x` → `X`; any other
+  `_`, `-`, `/` or uppercase letter is escaped with `_`), so two surfaces never register one
+  name. Two surfaces on one namespace are refused by `.packages()`. `manifest: 'public'`
+  drops `auth` from that one route and skips a server-level `auth` middleware on it, so a
+  caller can discover commands before it holds a token; every command stays behind `auth`
+  regardless.
+- **`authorize`.** Optional, `(command) => middleware | undefined`, called once per command
+  (module commands included) when the router is built. The middleware runs after `auth` and
+  before the command's own: `[auth, authorize?, ...group, ...own]`. Required as soon as a
+  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.
+- **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
+  refused, and the message names the namespace.
+- **Errors.** Every refusal is a `SurfaceError`. `@spfn/core/ops` exports the same class as
+  `OpsRouterError`, so `instanceof` holds under either name.
+
+The client for any surface is the CLI's library export,
+[`spfn/surface`](../cli/README.md#can-i-call-a-surface-from-my-own-code).
+
 ---
 
 ## How is this different from NestJS or tRPC?

package/dist/contract/index.d.ts

@@ -1,11 +1,11 @@
 import { E as EventRouterDef } from '../router-CysBmgv3.js';
-import { R as Router } from '../router-BqyEARoY.js';
-import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-B4DuGCyM.js';
-export { d as CompatibilityPolicy, e as ContractEvent, f as ContractEvents, g as ContractRequest, h as ContractViolationKind, J as JsonSchema } from '../types-B4DuGCyM.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 '@sinclair/typebox';
 import '../define-middleware-CVKgqo8S.js';
 import 'hono';
-import '../route-builder-2ani2jEI.js';
+import '../route-builder-BHKgGkwI.js';
 import 'hono/utils/http-status';
 import '../route/types.js';
 

package/dist/error-BcdBVfRA.d.ts

@@ -0,0 +1,150 @@
+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';
+
+/**
+ * How refusals name the surface they come from.
+ *
+ * A command surface is generic, but the ops surface predates it and its
+ * refusals already say "ops route" and point at `opsRoute`. The ops layer
+ * passes its own wording so an operator reading an ops refusal sees the same
+ * text as before; every other surface reads the neutral one.
+ */
+interface SurfaceWording {
+    /** What a route on this surface is called: "ops route", "surface route". */
+    noun: string;
+    /** The builder that applies the namespace, as named in a refusal. */
+    builder: string;
+    /** The function that builds the surface, as named in a refusal. */
+    factory: string;
+}
+
+/**
+ * Capability module contract
+ *
+ * A package describes commands here, but an adopter application decides
+ * whether to mount the resulting module, and on which surface. Validation
+ * keeps an installed package from becoming a command surface merely by
+ * existing, and gives the surface enough metadata to enforce scopes and
+ * describe the module to a client from one declaration.
+ *
+ * A module's paths are written for one namespace — `/_ops/<id>/...` for an
+ * ops module — so it is validated against the namespace of the surface that
+ * mounts it. A module written for `/_ops` mounted on `/_app` is refused rather
+ * than registered at paths outside the surface that is supposed to guard them.
+ */
+
+type SurfaceEffect = 'read' | 'write' | 'destructive';
+interface SurfaceModuleCommand<TRoute extends RouteDef<any> = RouteDef<any>> {
+    summary: string;
+    effect: SurfaceEffect;
+    scopes: readonly string[];
+    route: TRoute;
+}
+interface SurfaceModule<TCommands extends Record<string, SurfaceModuleCommand<any>> = Record<string, SurfaceModuleCommand<any>>> {
+    id: string;
+    source: string;
+    contractVersion: string;
+    summary: string;
+    commands: TCommands;
+}
+/**
+ * Validate and return a capability module written for a surface on
+ * `namespace` — every command under `<namespace>/<id>/`. The surface checks
+ * it again against its own namespace when it mounts it, so a module defined
+ * for one namespace and mounted on another is still refused.
+ */
+declare function defineSurfaceModule<TCommands extends Record<string, SurfaceModuleCommand<any>>>(module: SurfaceModule<TCommands>, namespace: string): SurfaceModule<TCommands>;
+
+/**
+ * Surface namespace and route builder
+ *
+ * A namespace is the path every command on a surface lives under — `/_ops`
+ * for operators, `/_app` or anything else an app chooses for another caller.
+ * It is refused at definition time unless it is a plain absolute path of
+ * URL-safe segments: no trailing slash, no dots, no percent signs, no
+ * parameters. Every check downstream — the prefix a route must carry, the
+ * module paths, the manifest URL, the CLI's own path checks — is a string
+ * comparison against it, and only a literal path keeps those comparisons
+ * honest.
+ *
+ * The route builder is `route` with the namespace applied, so a definition
+ * carries only the part of the path the app owns:
+ *
+ * ```ts
+ * const pageAdd = app.route.post('/pages')   // POST /_app/pages
+ *     .handler(async () => ({ ok: true }));
+ * ```
+ */
+
+/** `route`, with a surface's namespace applied. */
+interface SurfaceRouteBuilder {
+    get: (path: string) => RouteBuilder;
+    post: (path: string) => RouteBuilder;
+    put: (path: string) => RouteBuilder;
+    patch: (path: string) => RouteBuilder;
+    delete: (path: string) => RouteBuilder;
+}
+
+/**
+ * Surface Manifest
+ *
+ * The server's self-description of a command surface: every command an app
+ * exposes under the surface's namespace, with each command's input schemas as
+ * plain JSON Schema. A client fetches this from the running server, so command
+ * discovery needs neither the app's source nor a generated artifact on the
+ * caller's machine.
+ *
+ * The router is loaded and walked (the contract collector's approach) rather
+ * than parsed from source: route schemas built from imported values resolve,
+ * and TypeBox schemas serialize to JSON Schema by construction.
+ */
+
+/** One explicitly mounted capability module, as a client sees it. */
+interface SurfaceModuleDescriptor {
+    id: string;
+    source: string;
+    contractVersion: string;
+    summary: string;
+}
+/** One invokable command, as a client sees it. */
+interface SurfaceCommand {
+    name: string;
+    method: HttpMethod;
+    path: string;
+    /** Present for commands contributed by an explicitly mounted module. */
+    module?: string;
+    summary?: string;
+    effect?: SurfaceEffect;
+    scopes?: string[];
+    /** Input sections the route declares, each as JSON Schema. */
+    input: {
+        params?: JsonSchema;
+        query?: JsonSchema;
+        body?: JsonSchema;
+    };
+}
+/** What `GET <namespace>/_manifest` answers. */
+interface SurfaceManifest {
+    manifestVersion: 1;
+    /** Additive module metadata. Omitted for an app-only v1 surface. */
+    modules?: SurfaceModuleDescriptor[];
+    commands: SurfaceCommand[];
+}
+/**
+ * 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.
+ */
+declare function collectSurfaceCommands(routes: Record<string, RouteDef<any> | Router<any>>, wording?: SurfaceWording): SurfaceCommand[];
+
+/**
+ * Thrown when a namespace, route, or module cannot be part of a command
+ * surface. `@spfn/core/ops` exports the same class as `OpsRouterError`.
+ */
+declare class SurfaceError extends Error {
+    constructor(message: string);
+}
+
+export { type SurfaceEffect as S, type SurfaceModuleCommand as a, type SurfaceModule as b, type SurfaceRouteBuilder as c, type SurfaceCommand as d, type SurfaceManifest as e, type SurfaceModuleDescriptor as f, SurfaceError as g, collectSurfaceCommands as h, defineSurfaceModule as i };

package/dist/ops/index.d.ts

@@ -1,11 +1,13 @@
 import { MiddlewareHandler } from 'hono';
 import { a as NamedMiddleware } from '../define-middleware-CVKgqo8S.js';
-import { R as RouteDef, a as RouteBuilder } from '../route-builder-2ani2jEI.js';
-import { R as Router } from '../router-BqyEARoY.js';
-import { J as JsonSchema } from '../types-B4DuGCyM.js';
-import { HttpMethod } from '../route/types.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 '@sinclair/typebox';
 import 'hono/utils/http-status';
+import '../route/types.js';
+import '../types-D52SokSM.js';
 
 /**
  * Capability ops module contract
@@ -15,24 +17,17 @@ import 'hono/utils/http-status';
  * installed package from becoming an ops surface merely by existing, and
  * gives `createOpsRouter` enough metadata to enforce scopes and describe the
  * module to the CLI from one declaration.
+ *
+ * The contract is the command surface's (`@spfn/core/surface`);
+ * `defineOpsModule` is its validator fixed to the `/_ops` namespace.
  */
 
-type OpsEffect = 'read' | 'write' | 'destructive';
-interface OpsModuleCommand<TRoute extends RouteDef<any> = RouteDef<any>> {
-    summary: string;
-    effect: OpsEffect;
-    scopes: readonly string[];
-    route: TRoute;
-}
-interface OpsModule<TCommands extends Record<string, OpsModuleCommand<any>> = Record<string, OpsModuleCommand<any>>> {
-    id: string;
-    source: string;
-    contractVersion: string;
-    summary: string;
-    commands: TCommands;
-}
+type OpsEffect = SurfaceEffect;
+type OpsModuleCommand<TRoute extends RouteDef<any> = RouteDef<any>> = SurfaceModuleCommand<TRoute>;
+type OpsModule<TCommands extends Record<string, OpsModuleCommand<any>> = Record<string, OpsModuleCommand<any>>> = SurfaceModule<TCommands>;
 /**
- * Validate and return a capability ops module.
+ * Validate and return a capability ops module — every command under
+ * `/_ops/<id>/`.
  *
  * This function intentionally does not register anything. Only an adopter's
  * explicit `createOpsRouter({ modules: [...] })` composition exposes it.
@@ -62,6 +57,11 @@ declare function defineOpsModule<TCommands extends Record<string, OpsModuleComma
  * ships `opsTokenAuth`); core owns only the structure, so the ops surface has
  * no opinion about how a token is stored or verified.
  *
+ * 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.
+ *
  * @example
  * ```ts
  * import { createOpsRouter, opsRoute } from '@spfn/core/ops';
@@ -124,9 +124,9 @@ declare function createOpsRouter<TRoutes extends Record<string, RouteDef<any, an
  * decisions, made when the ops route is written.
  *
  * The builder returned is an ordinary `RouteBuilder`, so `.use()`, `.input()`
- * and `.handler()` work exactly as they do elsewhere.
+ * and `.handler()` work exactly as they do elsewhere. It is the `/_ops`
+ * surface's `route` (`@spfn/core/surface`).
  */
-
 /** The ops namespace, without the trailing slash. */
 declare const OPS_PATH_ROOT = "/_ops";
 /**
@@ -140,64 +140,24 @@ declare const OPS_PATH_ROOT = "/_ops";
  *     .handler(async (c) => ({ items: await repo.findAll((await c.data()).query.limit ?? 10, 0) }));
  * ```
  */
-declare const opsRoute: {
-    get: (path: string) => RouteBuilder;
-    post: (path: string) => RouteBuilder;
-    put: (path: string) => RouteBuilder;
-    patch: (path: string) => RouteBuilder;
-    delete: (path: string) => RouteBuilder;
-};
-
-/** Thrown when a route or module cannot be part of an ops surface. */
-declare class OpsRouterError extends Error {
-    constructor(message: string);
-}
+declare const opsRoute: SurfaceRouteBuilder;
 
 /**
  * Ops Manifest
  *
- * The server's self-description of its ops surface: every command an app
- * exposes under `/_ops`, with each command's input schemas as plain JSON
- * Schema. The ops CLI fetches this from the running server, so command
- * discovery needs neither the app's source nor a generated artifact on the
- * operator's machine.
- *
- * The router is loaded and walked (the contract collector's approach) rather
- * than parsed from source: route schemas built from imported values resolve,
- * and TypeBox schemas serialize to JSON Schema by construction.
+ * The ops surface's self-description: every command an app exposes under
+ * `/_ops`, with each command's input schemas as plain JSON Schema. The
+ * `spfn ops` CLI fetches it from the running server. The collector and the
+ * shapes are the command surface's (`@spfn/core/surface`); these are their
+ * ops names, kept so existing imports read as they always did.
  */
 
 /** One explicitly mounted capability module, as the CLI sees it. */
-interface OpsModuleDescriptor {
-    id: string;
-    source: string;
-    contractVersion: string;
-    summary: string;
-}
+type OpsModuleDescriptor = SurfaceModuleDescriptor;
 /** One invokable ops command, as the CLI sees it. */
-interface OpsCommand {
-    name: string;
-    method: HttpMethod;
-    path: string;
-    /** Present for commands contributed by an explicitly mounted ops module. */
-    module?: string;
-    summary?: string;
-    effect?: OpsEffect;
-    scopes?: string[];
-    /** Input sections the route declares, each as JSON Schema. */
-    input: {
-        params?: JsonSchema;
-        query?: JsonSchema;
-        body?: JsonSchema;
-    };
-}
+type OpsCommand = SurfaceCommand;
 /** What `GET /_ops/_manifest` answers. */
-interface OpsManifest {
-    manifestVersion: 1;
-    /** Additive module metadata. Omitted for an app-only v1 surface. */
-    modules?: OpsModuleDescriptor[];
-    commands: OpsCommand[];
-}
+type OpsManifest = SurfaceManifest;
 /**
  * Walk a routes record (nested routers included) and collect every RouteDef
  * as an ops command. Validation of paths and names happens in
@@ -205,4 +165,4 @@ interface OpsManifest {
  */
 declare function collectOpsCommands(routes: Record<string, RouteDef<any> | Router<any>>): OpsCommand[];
 
-export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, type OpsCommand, type OpsEffect, type OpsManifest, type OpsModule, type OpsModuleCommand, type OpsModuleDescriptor, OpsRouterError, type OpsRouterOptions, collectOpsCommands, createOpsRouter, defineOpsModule, opsRoute };
+export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, type OpsCommand, type OpsEffect, type OpsManifest, type OpsModule, type OpsModuleCommand, type OpsModuleDescriptor, type OpsRouterOptions, collectOpsCommands, createOpsRouter, defineOpsModule, opsRoute };