@spfn/core 0.3.0-beta.4 → 0.3.0-beta.5

package/dist/ops/index.d.ts

@@ -1,12 +1,44 @@
+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-DJdpwuB6.js';
 import { J as JsonSchema } from '../types-ClQVomgV.js';
 import { HttpMethod } from '../route/types.js';
-import 'hono';
 import '@sinclair/typebox';
 import 'hono/utils/http-status';
 
+/**
+ * Capability ops module contract
+ *
+ * A package describes commands here, but an adopter application decides
+ * whether to mount the resulting module. Definition-time validation keeps an
+ * 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.
+ */
+
+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;
+}
+/**
+ * Validate and return a capability ops module.
+ *
+ * This function intentionally does not register anything. Only an adopter's
+ * explicit `createOpsRouter({ modules: [...] })` composition exposes it.
+ */
+declare function defineOpsModule<TCommands extends Record<string, OpsModuleCommand<any>>>(module: OpsModule<TCommands>): OpsModule<TCommands>;
+
 /**
  * Ops Router
  *
@@ -57,6 +89,14 @@ interface OpsRouterOptions {
      * discovered in production.
      */
     auth: NamedMiddleware<string>;
+    /**
+     * Build the server-side scope guard for a module command. Required when
+     * modules are mounted. `@spfn/auth`'s `requireOpsScope` is the standard
+     * implementation, but core remains independent of that package.
+     */
+    authorize?: (...scopes: string[]) => MiddlewareHandler | NamedMiddleware<string>;
+    /** Capability ops modules this application explicitly chooses to expose. */
+    modules?: readonly OpsModule[];
 }
 /**
  * Build the app's ops surface from its ops routes.
@@ -108,6 +148,11 @@ declare const opsRoute: {
     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);
+}
+
 /**
  * Ops Manifest
  *
@@ -122,11 +167,23 @@ declare const opsRoute: {
  * and TypeBox schemas serialize to JSON Schema by construction.
  */
 
+/** One explicitly mounted capability module, as the CLI sees it. */
+interface OpsModuleDescriptor {
+    id: string;
+    source: string;
+    contractVersion: string;
+    summary: string;
+}
 /** 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;
@@ -137,12 +194,10 @@ interface OpsCommand {
 /** What `GET /_ops/_manifest` answers. */
 interface OpsManifest {
     manifestVersion: 1;
+    /** Additive module metadata. Omitted for an app-only v1 surface. */
+    modules?: OpsModuleDescriptor[];
     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
@@ -150,4 +205,4 @@ declare class OpsRouterError extends Error {
  */
 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 };
+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 };

package/dist/ops/index.js

@@ -319,13 +319,15 @@ function defineRouter(routes) {
   return createRouterInstance(routes);
 }
 
-// src/ops/manifest.ts
+// 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;
 }
@@ -383,6 +385,242 @@ function assertUnclaimedName(name, path, claimed) {
   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";
@@ -451,50 +689,112 @@ function secureRoutes(routes, auth, inherited = []) {
   }
   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,
-    commands: collectOpsCommands(routes)
+    ...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
+    ...secured,
+    ...securedModules
   });
 }
 
-// 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 };
+export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, OpsRouterError, collectOpsCommands, createOpsRouter, defineOpsModule, opsRoute };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map