@spfn/core 0.2.0-beta.9 → 0.3.0-beta.2

package/dist/ops/index.d.ts

@@ -0,0 +1,152 @@
+import { a as NamedMiddleware } from '../define-middleware-DfDP39Nq.js';
+import { a as RouteDef, R as Router, b as RouteBuilder } from '../router-Qbssr11H.js';
+import { J as JsonSchema } from '../types-D1c57Ko-.js';
+import { HttpMethod } from '../route/types.js';
+import 'hono';
+import '@sinclair/typebox';
+import 'hono/utils/http-status';
+
+/**
+ * Ops Router
+ *
+ * The structure half of SPFN's CLI-first operations surface. An app develops
+ * its own ops as ordinary routes — domain operations only that app can name —
+ * and this factory turns them into a mountable package router that:
+ *
+ * - requires every route to come from `opsRoute`, which applies the `/_ops`
+ *   namespace, so the surface is recognizable and an ops route can never
+ *   shadow an app route;
+ * - injects the given auth middleware into every route, the manifest
+ *   included, so an unauthenticated ops surface cannot be created by
+ *   accident — there is no opt-out;
+ * - serves `GET /_ops/_manifest`, the self-description the `spfn ops` CLI
+ *   discovers commands from, registered first so no app route takes its URL.
+ *
+ * What the path looks like after the namespace is the app's business, decided
+ * when the ops route is written — this factory does not audit its shape.
+ *
+ * The auth middleware itself lives with the app's auth stack (`@spfn/auth`
+ * ships `opsTokenAuth`); core owns only the structure, so the ops surface has
+ * no opinion about how a token is stored or verified.
+ *
+ * @example
+ * ```ts
+ * import { createOpsRouter, opsRoute } from '@spfn/core/ops';
+ * import { opsTokenAuth, requireOpsScope } from '@spfn/auth/server';
+ *
+ * export const opsRouter = createOpsRouter({
+ *     listSignups: opsRoute.get('/signups')            // GET /_ops/signups
+ *         .use([requireOpsScope('waitlist:read')])
+ *         .handler(async () => signupsRepository.list()),
+ * }, { auth: opsTokenAuth });
+ *
+ * // mounted like any package router:
+ * export const appRouter = defineRouter({ ... }).packages([opsRouter]);
+ * ```
+ */
+
+/** Every ops route lives under this prefix. */
+declare const OPS_PATH_PREFIX = "/_ops/";
+/** Where the manifest is served. Reserved — an app route cannot claim it. */
+declare const OPS_MANIFEST_PATH = "/_ops/_manifest";
+interface OpsRouterOptions {
+    /**
+     * The middleware that authenticates every ops request. Required — an ops
+     * surface without authentication is refused at definition time, not
+     * discovered in production.
+     */
+    auth: NamedMiddleware<string>;
+}
+/**
+ * Build the app's ops surface from its ops routes.
+ *
+ * Returns an ordinary `Router` meant to be mounted with `.packages()`, so ops
+ * routes stay out of the app's client types exactly like other package
+ * routes.
+ */
+declare function createOpsRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes, options: OpsRouterOptions): Router<any>;
+
+/**
+ * Ops Route Builder
+ *
+ * `route` with the ops namespace already applied. An ops route lives under
+ * `/_ops/` without exception, so the prefix is the helper's business rather
+ * than something every definition retypes and the factory then checks:
+ *
+ * ```ts
+ * const countExamples = opsRoute.get('/examples/count')   // GET /_ops/examples/count
+ *     .handler(async () => ({ count: await repo.countAll() }));
+ * ```
+ *
+ * Everything after the prefix belongs to the app. What the paths look like,
+ * how they nest, which segments are parameters — those are the app author's
+ * 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.
+ */
+
+/** The ops namespace, without the trailing slash. */
+declare const OPS_PATH_ROOT = "/_ops";
+/**
+ * Ops route builder entry point — `route`, namespaced under `/_ops`.
+ *
+ * @example
+ * ```ts
+ * const listRecent = opsRoute.get('/examples')
+ *     .use([requireOpsScope('example:read')])
+ *     .input({ query: Type.Object({ limit: Type.Optional(Type.Number()) }) })
+ *     .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;
+};
+
+/**
+ * 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.
+ */
+
+/** One invokable ops command, as the CLI sees it. */
+interface OpsCommand {
+    name: string;
+    method: HttpMethod;
+    path: string;
+    /** Input sections the route declares, each as JSON Schema. */
+    input: {
+        params?: JsonSchema;
+        query?: JsonSchema;
+        body?: JsonSchema;
+    };
+}
+/** What `GET /_ops/_manifest` answers. */
+interface OpsManifest {
+    manifestVersion: 1;
+    commands: OpsCommand[];
+}
+/** Thrown when a route cannot be part of an ops surface. */
+declare class OpsRouterError extends Error {
+    constructor(message: string);
+}
+/**
+ * Walk a routes record (nested routers included) and collect every RouteDef
+ * as an ops command. Validation of paths and names happens in
+ * `createOpsRouter` before this runs.
+ */
+declare function collectOpsCommands(routes: Record<string, RouteDef<any> | Router<any>>): OpsCommand[];
+
+export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, type OpsCommand, type OpsManifest, OpsRouterError, type OpsRouterOptions, collectOpsCommands, createOpsRouter, opsRoute };

package/dist/ops/index.js

@@ -0,0 +1,500 @@
+// src/route/route-builder.ts
+var RouteBuilder = class _RouteBuilder {
+  _method;
+  _path;
+  _input;
+  _interceptor;
+  _middlewares;
+  _skipMiddlewares;
+  _contract;
+  /**
+   * Create a new RouteBuilder with copied properties and optional overrides
+   */
+  clone(overrides) {
+    const builder = new _RouteBuilder();
+    builder._method = this._method;
+    builder._path = this._path;
+    builder._input = overrides?.input ?? this._input;
+    builder._interceptor = overrides?.interceptor ?? this._interceptor;
+    builder._middlewares = overrides?.middlewares ?? this._middlewares;
+    builder._skipMiddlewares = overrides?.skipMiddlewares ?? this._skipMiddlewares;
+    builder._contract = overrides?.contract ?? this._contract;
+    return builder;
+  }
+  /**
+   * Define input schemas
+   *
+   * @example
+   * ```ts
+   * route.get('/users/:id')
+   *   .input({
+   *     params: Type.Object({ id: Type.String() }),
+   *     query: Type.Object({ page: Type.Number() }),
+   *     headers: Type.Object({ authorization: Type.String() })
+   *   })
+   *   .handler(async (c) => {
+   *     const { params, query, headers } = await c.data();
+   *     // params = { id: string }
+   *     // query = { page: number }
+   *     // headers = { authorization: string }
+   *   })
+   * ```
+   */
+  input(input) {
+    return this.clone({ input });
+  }
+  /**
+   * Define fields injected by interceptors
+   *
+   * These fields are:
+   * - Available in the handler (merged with input)
+   * - Excluded from client types (codegen uses only input)
+   * - Not validated by route input schema (injected by middleware)
+   *
+   * Use this when middleware/interceptors add fields to the request
+   * before it reaches the handler.
+   *
+   * @example
+   * ```ts
+   * // Auth interceptor injects crypto key fields
+   * route.post('/_auth/login')
+   *   .input({
+   *     body: Type.Object({
+   *       email: Type.String(),
+   *       password: Type.String()
+   *     })
+   *   })
+   *   .interceptor({
+   *     body: Type.Object({
+   *       publicKey: Type.String(),
+   *       keyId: Type.String(),
+   *       fingerprint: Type.String()
+   *     })
+   *   })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     // body type: { email, password, publicKey, keyId, fingerprint }
+   *     // Client only sees: { email, password }
+   *     return loginService(body);
+   *   });
+   * ```
+   */
+  interceptor(interceptor) {
+    return this.clone({ interceptor });
+  }
+  /**
+   * Add middlewares to the route
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  middleware(middlewares) {
+    return this.clone({ middlewares });
+  }
+  /**
+   * Add middlewares to the route (alias for `.middleware()`)
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  use(middlewares) {
+    return this.middleware(middlewares);
+  }
+  /**
+   * Skip server-level named middlewares
+   *
+   * Useful for public endpoints that should bypass auth or rate limiting
+   *
+   * @param middlewareNames - Array of middleware names to skip, or '*' to skip all
+   *
+   * @example
+   * ```ts
+   * // Skip specific middlewares
+   * route.get('/health')
+   *   .skip(['auth', 'rateLimit'])
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   *
+   * // Skip only auth (still apply rate limiting)
+   * route.get('/public-data')
+   *   .skip(['auth'])
+   *   .handler(async (c) => { ... });
+   *
+   * // Skip all middlewares
+   * route.get('/public-health')
+   *   .skip('*')
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   * ```
+   */
+  skip(middlewareNames) {
+    return this.clone({ skipMiddlewares: middlewareNames });
+  }
+  /**
+   * Publish this route as a versioned contract operation
+   *
+   * Marks the route as a promise to clients that are compiled and deployed
+   * separately from the server — a mobile app, an external API consumer.
+   * The `@spfn/core:contract` generator writes every contracted route into
+   * `contracts/current.json`, and the build refuses a change that would break
+   * an already-released client.
+   *
+   * Routes without `.contract()` are unaffected: they simply do not appear in
+   * the contract. A web client needs nothing here — it derives its types from
+   * the router in the same build.
+   *
+   * @example
+   * ```ts
+   * export const getUser = route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .contract({
+   *     since: '1.2.0',
+   *     auth: 'clientProofV1',
+   *     requiresSession: true,
+   *     response: Type.Object({
+   *       id: Type.String(),
+   *       name: Type.String(),
+   *       email: Type.Optional(Type.String()),
+   *     }),
+   *   })
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  contract(contract) {
+    return this.clone({ contract });
+  }
+  /**
+   * Define handler function
+   *
+   * Response type is automatically inferred from the return value.
+   * Use helper methods like `c.created()`, `c.paginated()` for proper type inference.
+   *
+   * @example
+   * ```ts
+   * // Direct return - type inferred from data
+   * route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { params } = await c.data();
+   *     return await getUser(params.id); // Type: User
+   *   })
+   *
+   * // Using c.created() - returns data with 201 status, type preserved
+   * route.post('/users')
+   *   .input({ body: Type.Object({ name: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     return c.created(await createUser(body)); // Type: User
+   *   })
+   *
+   * // Using c.paginated() - returns PaginatedResult<T>
+   * route.get('/users')
+   *   .handler(async (c) => {
+   *     const users = await getUsers();
+   *     return c.paginated(users, 1, 20, 100); // Type: PaginatedResult<User>
+   *   })
+   *
+   * // Using c.noContent() - returns void
+   * route.delete('/users/:id')
+   *   .handler(async (c) => {
+   *     await deleteUser(params.id);
+   *     return c.noContent(); // Type: void
+   *   })
+   *
+   * // Using c.json() - returns Response (type inference lost)
+   * // Use only when you need custom status codes not covered by helpers
+   * route.get('/custom')
+   *   .handler(async (c) => {
+   *     return c.json({ data }, 418); // Type: Response
+   *   })
+   * ```
+   */
+  handler(fn) {
+    return {
+      method: this._method,
+      path: this._path,
+      input: this._input,
+      interceptor: this._interceptor,
+      middlewares: this._middlewares,
+      skipMiddlewares: this._skipMiddlewares,
+      contract: this._contract,
+      handler: fn,
+      _input: {},
+      _interceptor: {},
+      _response: {}
+    };
+  }
+};
+function createMethodRoute(method) {
+  return (path) => {
+    const builder = new RouteBuilder();
+    builder._method = method;
+    builder._path = path;
+    return builder;
+  };
+}
+var route = {
+  get: createMethodRoute("GET"),
+  post: createMethodRoute("POST"),
+  put: createMethodRoute("PUT"),
+  patch: createMethodRoute("PATCH"),
+  delete: createMethodRoute("DELETE")
+};
+
+// src/route/router.ts
+function createRouterInstance(routes, packageRouters = [], globalMiddlewares = [], contractVersion = null) {
+  return {
+    routes,
+    _routes: routes,
+    _packageRouters: packageRouters,
+    _globalMiddlewares: globalMiddlewares,
+    _contractVersion: contractVersion,
+    packages(routers) {
+      const newPackageRouters = [...this._packageRouters, ...routers];
+      for (const pkgRouter of routers) {
+        if (pkgRouter._packageRouters?.length > 0) {
+          newPackageRouters.push(...pkgRouter._packageRouters);
+        }
+      }
+      return createRouterInstance(
+        this.routes,
+        newPackageRouters,
+        this._globalMiddlewares,
+        this._contractVersion
+      );
+    },
+    use(middlewares) {
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        [...this._globalMiddlewares, ...middlewares],
+        this._contractVersion
+      );
+    },
+    contractVersion(version) {
+      assertContractVersion(version);
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        this._globalMiddlewares,
+        version
+      );
+    }
+  };
+}
+function assertContractVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/.test(version)) {
+    throw new Error(
+      `contractVersion("${version}") is not a version of the form major.minor.patch. The released snapshot is named from this value and releases are compared by it.`
+    );
+  }
+}
+function defineRouter(routes) {
+  return createRouterInstance(routes);
+}
+
+// src/ops/manifest.ts
+var OpsRouterError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OpsRouterError";
+  }
+};
+function isRouter(value) {
+  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
+}
+function isRouteDef(value) {
+  return value !== null && typeof value === "object" && "handler" in value;
+}
+function toJsonSchema(schema) {
+  return JSON.parse(JSON.stringify(schema));
+}
+var INPUT_SECTIONS = ["params", "query", "body"];
+function toCommandInput(input) {
+  const sections = {};
+  if (!input) {
+    return sections;
+  }
+  for (const section of INPUT_SECTIONS) {
+    const schema = input[section];
+    if (schema) {
+      sections[section] = toJsonSchema(schema);
+    }
+  }
+  return sections;
+}
+function collectOpsCommands(routes) {
+  const commands = [];
+  visit(routes, commands, /* @__PURE__ */ new Map());
+  commands.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  return commands;
+}
+function visit(routes, commands, claimed) {
+  for (const [name, entry] of Object.entries(routes)) {
+    if (isRouter(entry)) {
+      visit(entry.routes, commands, claimed);
+      continue;
+    }
+    if (!isRouteDef(entry) || !entry.method || !entry.path) {
+      continue;
+    }
+    assertUnclaimedName(name, entry.path, claimed);
+    commands.push({
+      name,
+      method: entry.method,
+      path: entry.path,
+      input: toCommandInput(entry.input)
+    });
+  }
+}
+function assertUnclaimedName(name, path, claimed) {
+  const existing = claimed.get(name);
+  if (existing !== void 0) {
+    throw new OpsRouterError(
+      `Two ops routes are named "${name}" ("${existing}" and "${path}"). Command names are flattened across nested routers, so each must be unique for the CLI to resolve the one an operator asked for.`
+    );
+  }
+  claimed.set(name, path);
+}
+
+// src/ops/create-ops-router.ts
+var OPS_PATH_PREFIX = "/_ops/";
+var OPS_MANIFEST_PATH = "/_ops/_manifest";
+var OPS_MANIFEST_NAME = "getOpsManifest";
+function isRouter2(value) {
+  return value !== null && typeof value === "object" && "routes" in value && "_routes" in value;
+}
+function isRouteDef2(value) {
+  return value !== null && typeof value === "object" && "handler" in value;
+}
+function assertOpsRoute(name, def) {
+  if (!def.method || !def.path) {
+    throw new OpsRouterError(
+      `Ops route "${name}" has no method or path. An ops command is invoked on the wire, so both are required.`
+    );
+  }
+  if (!def.path.startsWith(OPS_PATH_PREFIX)) {
+    throw new OpsRouterError(
+      `Ops route "${name}" is at "${def.path}", outside "${OPS_PATH_PREFIX}". Build ops routes with \`opsRoute\` rather than \`route\` \u2014 it applies the namespace, so the path a definition carries is only the part the app owns.`
+    );
+  }
+  if (def.path === OPS_MANIFEST_PATH) {
+    throw new OpsRouterError(
+      `Ops route "${name}" claims "${OPS_MANIFEST_PATH}", which is reserved for the manifest. The manifest is registered first, so this route would never answer.`
+    );
+  }
+}
+function assertOpsName(name) {
+  if (name === OPS_MANIFEST_NAME) {
+    throw new OpsRouterError(
+      `Ops route name "${OPS_MANIFEST_NAME}" is reserved for the manifest route.`
+    );
+  }
+}
+function rebuildNestedRouter(name, router, auth, inherited) {
+  if (router._packageRouters?.length > 0) {
+    throw new OpsRouterError(
+      `Ops router "${name}" mounts package routers with .packages(). Their routes bypass the prefix check and the auth injection, so an ops surface cannot carry them.`
+    );
+  }
+  const handedDown = [...inherited, ...router._globalMiddlewares ?? []];
+  let rebuilt = defineRouter(
+    secureRoutes(router.routes, auth, handedDown)
+  );
+  if (router._contractVersion) {
+    rebuilt = rebuilt.contractVersion(router._contractVersion);
+  }
+  return rebuilt;
+}
+function secureRoutes(routes, auth, inherited = []) {
+  const secured = {};
+  for (const [name, entry] of Object.entries(routes)) {
+    assertOpsName(name);
+    if (isRouter2(entry)) {
+      secured[name] = rebuildNestedRouter(name, entry, auth, inherited);
+      continue;
+    }
+    if (!isRouteDef2(entry)) {
+      throw new OpsRouterError(`Ops router entry "${name}" is neither a route nor a router.`);
+    }
+    assertOpsRoute(name, entry);
+    secured[name] = {
+      ...entry,
+      middlewares: [auth, ...inherited, ...entry.middlewares ?? []]
+    };
+  }
+  return secured;
+}
+function createOpsRouter(routes, options) {
+  if (!options?.auth) {
+    throw new OpsRouterError(
+      "createOpsRouter requires an auth middleware ({ auth: ... }). An ops surface reachable without authentication cannot be created."
+    );
+  }
+  const manifest = {
+    manifestVersion: 1,
+    commands: collectOpsCommands(routes)
+  };
+  const secured = secureRoutes(routes, options.auth);
+  const manifestRoute = route.get(OPS_MANIFEST_PATH).use([options.auth]).handler(async () => manifest);
+  return defineRouter({
+    [OPS_MANIFEST_NAME]: manifestRoute,
+    ...secured
+  });
+}
+
+// src/ops/ops-route.ts
+var OPS_PATH_ROOT = "/_ops";
+function toOpsPath(path) {
+  if (!path.startsWith("/")) {
+    throw new OpsRouterError(
+      `Ops route path "${path}" must start with "/". It is appended to "${OPS_PATH_ROOT}", so "${path}" would read as "${OPS_PATH_ROOT}${path}".`
+    );
+  }
+  if (path === "/") {
+    throw new OpsRouterError(
+      `Ops route path "/" names no command \u2014 "${OPS_PATH_ROOT}" itself is not a command.`
+    );
+  }
+  return OPS_PATH_ROOT + path;
+}
+function opsMethod(method) {
+  return (path) => route[method](toOpsPath(path));
+}
+var opsRoute = {
+  get: opsMethod("get"),
+  post: opsMethod("post"),
+  put: opsMethod("put"),
+  patch: opsMethod("patch"),
+  delete: opsMethod("delete")
+};
+
+export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, OpsRouterError, collectOpsCommands, createOpsRouter, opsRoute };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map