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

package/dist/ops/index.js

@@ -0,0 +1,800 @@
+// 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('/status')
+   *   .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/error.ts
+var OpsRouterError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OpsRouterError";
+  }
+};
+
+// src/ops/manifest.ts
+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/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")
+};
+
+// src/ops/route-overlap.ts
+function routeSegments(path) {
+  return path.split("/").slice(1).map((raw) => {
+    if (raw === "*" || raw.endsWith("*")) {
+      return { kind: "wildcard", value: raw, optional: true };
+    }
+    if (raw.startsWith(":")) {
+      return {
+        kind: "parameter",
+        value: raw.slice(1).replace(/\?$/, ""),
+        optional: raw.endsWith("?")
+      };
+    }
+    return { kind: "static", value: raw, optional: false };
+  });
+}
+function customPattern(parameter) {
+  const openingBrace = parameter.indexOf("{");
+  return openingBrace >= 0 && parameter.endsWith("}") ? parameter.slice(openingBrace + 1, -1) : null;
+}
+function parameterAccepts(parameter, value) {
+  const pattern = customPattern(parameter);
+  if (pattern === null) {
+    return value.length > 0 && !value.includes("/");
+  }
+  try {
+    return new RegExp(`^(?:${pattern})$`).test(value);
+  } catch {
+    return true;
+  }
+}
+function remainingStaticPath(segments, from) {
+  const remaining = segments.slice(from);
+  return remaining.every((segment) => segment.kind === "static") ? remaining.map((segment) => segment.value).join("/") : null;
+}
+function opsRoutePatternsOverlap(firstPath, secondPath) {
+  const first = routeSegments(firstPath);
+  const second = routeSegments(secondPath);
+  const length = Math.max(first.length, second.length);
+  for (let index = 0; index < length; index++) {
+    const left = first[index];
+    const right = second[index];
+    if (!left || !right) {
+      const remaining = left ? first.slice(index) : second.slice(index);
+      return remaining.every((segment) => segment.optional || segment.kind === "wildcard");
+    }
+    if (left.kind === "wildcard" || right.kind === "wildcard") {
+      return true;
+    }
+    if (left.kind === "static" && right.kind === "static") {
+      if (left.value !== right.value) {
+        return false;
+      }
+      continue;
+    }
+    if (left.kind === "parameter" && right.kind === "static") {
+      const remaining = remainingStaticPath(second, index);
+      if (customPattern(left.value) !== null && remaining !== null && parameterAccepts(left.value, remaining)) {
+        return true;
+      }
+      if (!parameterAccepts(left.value, right.value)) {
+        return customPattern(left.value) !== null && remaining === null;
+      }
+      if (customPattern(left.value) !== null && first.length !== second.length) {
+        return true;
+      }
+      continue;
+    }
+    if (left.kind === "static" && right.kind === "parameter") {
+      const remaining = remainingStaticPath(first, index);
+      if (customPattern(right.value) !== null && remaining !== null && parameterAccepts(right.value, remaining)) {
+        return true;
+      }
+      if (!parameterAccepts(right.value, left.value)) {
+        return customPattern(right.value) !== null && remaining === null;
+      }
+      if (customPattern(right.value) !== null && first.length !== second.length) {
+        return true;
+      }
+      continue;
+    }
+    return true;
+  }
+  return true;
+}
+
+// src/ops/module.ts
+var MODULE_ID = /^[a-z][a-z0-9]*(?:-[a-z0-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 OPS_PATH_BASE = "https://spfn.invalid";
+function assertText(label, value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new OpsRouterError(`${label} must be a non-empty string.`);
+  }
+}
+function assertStableModulePath(moduleId, commandName, path) {
+  const label = `Ops command "${moduleId}.${commandName}" path "${path}"`;
+  const transportPath = path.replace(/[{}?#]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+  let url;
+  try {
+    url = new URL(transportPath, OPS_PATH_BASE);
+  } catch {
+    throw new OpsRouterError(`${label} is not a valid URL path.`);
+  }
+  if (url.origin !== OPS_PATH_BASE || url.search !== "" || url.hash !== "" || url.pathname !== transportPath) {
+    throw new OpsRouterError(`${label} is not a stable plain absolute path.`);
+  }
+  const slashCount = (path.match(/\//g) ?? []).length;
+  let decoded = path;
+  for (let depth = 0; depth < 8; depth++) {
+    let next;
+    try {
+      next = decodeURIComponent(decoded);
+    } catch {
+      throw new OpsRouterError(`${label} contains malformed percent encoding.`);
+    }
+    if (next.includes("\\") || (next.match(/\//g) ?? []).length !== slashCount || next.split("/").some((segment) => segment === "." || segment === "..")) {
+      throw new OpsRouterError(`${label} contains encoded path separators or dot segments.`);
+    }
+    if (next === decoded) {
+      return;
+    }
+    decoded = next;
+  }
+  throw new OpsRouterError(`${label} uses too many percent-encoding layers.`);
+}
+function assertCliCallableModulePath(moduleId, commandName, path) {
+  const unsupported = path.split("/").slice(1).find((segment) => segment === "*" || segment.includes("*") || (segment.startsWith(":") ? !/^:[A-Za-z0-9_]+$/.test(segment) : !/^[A-Za-z0-9._~-]+$/.test(segment)));
+  if (unsupported !== void 0) {
+    throw new OpsRouterError(
+      `Ops command "${moduleId}.${commandName}" path segment "${unsupported}" is not CLI-callable. Module routes support URL-safe static segments and simple :name parameters only; optional, wildcard, and custom-regex parameters are not supported.`
+    );
+  }
+}
+function assertCommand(moduleId, name, command) {
+  if (!COMMAND_NAME.test(name)) {
+    throw new OpsRouterError(
+      `Ops module "${moduleId}" has invalid command name "${name}". Use dot-separated alphanumeric names.`
+    );
+  }
+  assertText(`Ops command "${moduleId}.${name}" summary`, command?.summary);
+  if (!EFFECTS.has(command?.effect)) {
+    throw new OpsRouterError(
+      `Ops command "${moduleId}.${name}" has invalid effect ${JSON.stringify(command?.effect)}.`
+    );
+  }
+  if (!Array.isArray(command?.scopes) || command.scopes.length === 0 || command.scopes.some((scope) => typeof scope !== "string" || scope.trim().length === 0)) {
+    throw new OpsRouterError(`Ops command "${moduleId}.${name}" must declare at least one non-empty scope.`);
+  }
+  const route2 = command?.route;
+  if (!route2 || typeof route2.handler !== "function" || !route2.method || !route2.path) {
+    throw new OpsRouterError(`Ops command "${moduleId}.${name}" must carry a complete ops route.`);
+  }
+  assertStableModulePath(moduleId, name, route2.path);
+  assertCliCallableModulePath(moduleId, name, route2.path);
+  const modulePath = `${OPS_PATH_ROOT}/${moduleId}/`;
+  if (!route2.path.startsWith(modulePath)) {
+    throw new OpsRouterError(
+      `Ops command "${moduleId}.${name}" is at "${route2.path}", outside "${modulePath}".`
+    );
+  }
+  if (route2.path.split("/").includes("..")) {
+    throw new OpsRouterError(`Ops command "${moduleId}.${name}" path climbs out of its module namespace.`);
+  }
+}
+function defineOpsModule(module) {
+  if (!MODULE_ID.test(module?.id ?? "")) {
+    throw new OpsRouterError(
+      `Ops module id ${JSON.stringify(module?.id)} is invalid. Use lower-kebab-case.`
+    );
+  }
+  assertText(`Ops module "${module.id}" source`, module.source);
+  assertText(`Ops module "${module.id}" summary`, module.summary);
+  if (!CONTRACT_VERSION.test(module.contractVersion)) {
+    throw new OpsRouterError(
+      `Ops module "${module.id}" contractVersion must be a semantic version.`
+    );
+  }
+  if (!module.commands || typeof module.commands !== "object" || Array.isArray(module.commands)) {
+    throw new OpsRouterError(`Ops module "${module.id}" commands must be an object.`);
+  }
+  const signatures = /* @__PURE__ */ new Map();
+  const claimedRoutes = [];
+  for (const [name, command] of Object.entries(module.commands)) {
+    assertCommand(module.id, name, command);
+    const signature = `${command.route.method} ${command.route.path}`;
+    const existing = signatures.get(signature);
+    if (existing) {
+      throw new OpsRouterError(
+        `Ops module "${module.id}" commands "${existing}" and "${name}" both use ${signature}.`
+      );
+    }
+    signatures.set(signature, name);
+    const overlapping = claimedRoutes.find((claim) => claim.method === command.route.method && opsRoutePatternsOverlap(claim.path, command.route.path));
+    if (overlapping) {
+      throw new OpsRouterError(
+        `Ops module "${module.id}" commands "${overlapping.name}" and "${name}" have overlapping ${command.route.method} routes ("${overlapping.path}" and "${command.route.path}").`
+      );
+    }
+    claimedRoutes.push({
+      name,
+      method: command.route.method,
+      path: command.route.path
+    });
+  }
+  return module;
+}
+
+// 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 compileModules(modules, appCommands) {
+  const descriptors = [];
+  const commands = [];
+  const routes = {};
+  const moduleIds = /* @__PURE__ */ new Set();
+  const commandNames = new Set(appCommands.map((command) => command.name));
+  const routeSignatures = new Map(
+    appCommands.map((command) => [`${command.method} ${command.path}`, command.name])
+  );
+  for (const rawModule of modules) {
+    const module = defineOpsModule(rawModule);
+    if (moduleIds.has(module.id)) {
+      throw new OpsRouterError(`Two ops modules use id "${module.id}".`);
+    }
+    moduleIds.add(module.id);
+    descriptors.push({
+      id: module.id,
+      source: module.source,
+      contractVersion: module.contractVersion,
+      summary: module.summary
+    });
+    for (const [localName, definition] of Object.entries(module.commands)) {
+      const name = `${module.id}.${localName}`;
+      if (commandNames.has(name)) {
+        throw new OpsRouterError(`Two ops commands are named "${name}".`);
+      }
+      commandNames.add(name);
+      const method = definition.route.method;
+      const path = definition.route.path;
+      const signature = `${method} ${path}`;
+      const existing = routeSignatures.get(signature);
+      if (existing) {
+        throw new OpsRouterError(
+          `Ops commands "${existing}" and "${name}" both use ${signature}.`
+        );
+      }
+      const overlappingAppCommand = appCommands.find((command) => command.method === method && opsRoutePatternsOverlap(command.path, path));
+      if (overlappingAppCommand) {
+        throw new OpsRouterError(
+          `App ops command "${overlappingAppCommand.name}" at ${method} ${overlappingAppCommand.path} overlaps module command "${name}" at ${method} ${path}. Which one answers cannot depend on route registration order.`
+        );
+      }
+      routeSignatures.set(signature, name);
+      commands.push({
+        name,
+        module: module.id,
+        summary: definition.summary,
+        effect: definition.effect,
+        scopes: [...definition.scopes],
+        method,
+        path,
+        input: collectOpsCommands({ [localName]: definition.route })[0].input
+      });
+      routes[name] = { route: definition.route, scopes: definition.scopes };
+    }
+  }
+  descriptors.sort((a, b) => a.id.localeCompare(b.id));
+  commands.sort((a, b) => a.name.localeCompare(b.name));
+  return { descriptors, commands, routes };
+}
+function secureModuleRoutes(routes, auth, authorize) {
+  const secured = {};
+  for (const [name, definition] of Object.entries(routes)) {
+    assertOpsName(name);
+    assertOpsRoute(name, definition.route);
+    secured[name] = {
+      ...definition.route,
+      middlewares: [
+        auth,
+        authorize(...definition.scopes),
+        ...definition.route.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 modules = options.modules ?? [];
+  if (modules.length > 0 && !options.authorize) {
+    throw new OpsRouterError(
+      "createOpsRouter requires an authorize scope factory when modules are mounted."
+    );
+  }
+  const appCommands = collectOpsCommands(routes);
+  const moduleSurface = compileModules(modules, appCommands);
+  const commands = [...appCommands, ...moduleSurface.commands].sort((a, b) => a.name.localeCompare(b.name));
+  const manifest = {
+    manifestVersion: 1,
+    ...moduleSurface.descriptors.length > 0 ? { modules: moduleSurface.descriptors } : {},
+    commands
+  };
+  const secured = secureRoutes(routes, options.auth);
+  const securedModules = moduleSurface.descriptors.length > 0 ? secureModuleRoutes(moduleSurface.routes, options.auth, options.authorize) : {};
+  const manifestRoute = route.get(OPS_MANIFEST_PATH).use([options.auth]).handler(async () => manifest);
+  return defineRouter({
+    [OPS_MANIFEST_NAME]: manifestRoute,
+    ...secured,
+    ...securedModules
+  });
+}
+
+export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, OpsRouterError, collectOpsCommands, createOpsRouter, defineOpsModule, opsRoute };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map