@spfn/core 0.3.0-beta.1 → 0.3.0-beta.10

package/dist/ops/index.js

@@ -138,7 +138,7 @@ var RouteBuilder = class _RouteBuilder {
    * @example
    * ```ts
    * // Skip specific middlewares
-   * route.get('/health')
+   * route.get('/status')
    *   .skip(['auth', 'rateLimit'])
    *   .handler(async (c) => c.json({ status: 'ok' }));
    *
@@ -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";
@@ -401,12 +639,12 @@ function assertOpsRoute(name, def) {
   }
   if (!def.path.startsWith(OPS_PATH_PREFIX)) {
     throw new OpsRouterError(
-      `Ops route "${name}" is at "${def.path}", outside "${OPS_PATH_PREFIX}". Every ops route lives under the prefix so the surface stays recognizable and can never shadow an app route.`
+      `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.`
+      `Ops route "${name}" claims "${OPS_MANIFEST_PATH}", which is reserved for the manifest. The manifest is registered first, so this route would never answer.`
     );
   }
 }
@@ -417,29 +655,27 @@ function assertOpsName(name) {
     );
   }
 }
-function rebuildNestedRouter(name, router, auth) {
+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)
+    secureRoutes(router.routes, auth, handedDown)
   );
-  if (router._globalMiddlewares?.length > 0) {
-    rebuilt = rebuilt.use(router._globalMiddlewares);
-  }
   if (router._contractVersion) {
     rebuilt = rebuilt.contractVersion(router._contractVersion);
   }
   return rebuilt;
 }
-function secureRoutes(routes, auth) {
+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);
+      secured[name] = rebuildNestedRouter(name, entry, auth, inherited);
       continue;
     }
     if (!isRouteDef2(entry)) {
@@ -448,7 +684,83 @@ function secureRoutes(routes, auth) {
     assertOpsRoute(name, entry);
     secured[name] = {
       ...entry,
-      middlewares: [auth, ...entry.middlewares ?? []]
+      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;
@@ -459,18 +771,30 @@ function createOpsRouter(routes, options) {
       "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,
-    [OPS_MANIFEST_NAME]: manifestRoute
+    ...securedModules
   });
 }
 
-export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OpsRouterError, collectOpsCommands, createOpsRouter };
+export { OPS_MANIFEST_PATH, OPS_PATH_PREFIX, OPS_PATH_ROOT, OpsRouterError, collectOpsCommands, createOpsRouter, defineOpsModule, opsRoute };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map