@spfn/core 0.3.0-beta.3 → 0.3.0-beta.31

package/dist/surface/index.js

@@ -0,0 +1,1013 @@
+// src/route/route-builder.ts
+var RouteBuilder = class _RouteBuilder {
+  _method;
+  _path;
+  _input;
+  _interceptor;
+  _middlewares;
+  _skipMiddlewares;
+  _contract;
+  _effect;
+  _summary;
+  /**
+   * 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;
+    builder._effect = overrides?.effect ?? this._effect;
+    builder._summary = overrides?.summary ?? this._summary;
+    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 });
+  }
+  /**
+   * Declare what invoking this route does
+   *
+   * Read by a command surface (`@spfn/core/surface`, `@spfn/core/ops`),
+   * which announces it in its manifest so a machine caller can tell a read
+   * from a write before it calls — `spfn ops call` asks for `--yes` before a
+   * `destructive` command. A surface built with `defineSurface` refuses an
+   * app command that does not declare one; on `/_ops` it is optional.
+   *
+   * Nothing else reads it: codegen, the route map, and the contract are
+   * unaffected, and a route outside any surface simply carries it.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .input({ body: PageAddBody })
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  effect(effect) {
+    return this.clone({ effect });
+  }
+  /**
+   * Describe this route in one line for a command surface's manifest
+   *
+   * A surface announces it beside the command in `spfn ops list` and
+   * `--describe`, and refuses one that is empty or longer than 500
+   * characters. Codegen, the route map, and the contract ignore it. On a
+   * module command the module's own summary wins.
+   *
+   * @example
+   * ```ts
+   * export const pageAdd = app.route.post('/pages')
+   *   .effect('write')
+   *   .summary('Add a page to the blueprint')
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  summary(summary) {
+    return this.clone({ summary });
+  }
+  /**
+   * 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,
+      ...this._effect !== void 0 ? { effect: this._effect } : {},
+      ...this._summary !== void 0 ? { summary: this._summary } : {},
+      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(state) {
+  const router = {
+    routes: state.routes,
+    _routes: state.routes,
+    _packageRouters: state.packageRouters,
+    _globalMiddlewares: state.globalMiddlewares,
+    _contractVersion: state.contractVersion,
+    _publishesRouteMap: state.publishesRouteMap,
+    packages(routers) {
+      const newPackageRouters = [...state.packageRouters, ...routers];
+      for (const pkgRouter of routers) {
+        if (pkgRouter._packageRouters?.length > 0) {
+          newPackageRouters.push(...pkgRouter._packageRouters);
+        }
+      }
+      assertDistinctSurfaces(newPackageRouters);
+      return carryMarkers(router, createRouterInstance({ ...state, packageRouters: newPackageRouters }));
+    },
+    use(middlewares) {
+      return carryMarkers(router, createRouterInstance({
+        ...state,
+        globalMiddlewares: [...state.globalMiddlewares, ...middlewares]
+      }));
+    },
+    contractVersion(version) {
+      assertContractVersion(version);
+      return carryMarkers(router, createRouterInstance({ ...state, contractVersion: version }));
+    }
+  };
+  return router;
+}
+var MARKERS = ["_surfaceNamespace", "_stateManifest"];
+function carryMarkers(from, to) {
+  for (const marker of MARKERS) {
+    if (from[marker] !== void 0) {
+      Object.defineProperty(to, marker, { value: from[marker], enumerable: false });
+    }
+  }
+  return to;
+}
+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 assertDistinctSurfaces(packageRouters) {
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const router of packageRouters) {
+    const namespace = router._surfaceNamespace;
+    if (namespace === void 0) {
+      continue;
+    }
+    if (namespaces.has(namespace)) {
+      throw new Error(
+        `.packages() mounts two command surfaces on "${namespace}". Both serve ${namespace}/_manifest, so the second one's commands would answer while no manifest lists them. Mount one router per namespace.`
+      );
+    }
+    namespaces.add(namespace);
+  }
+}
+function defineUnmappedRouter(routes) {
+  return createRouterInstance({
+    routes,
+    packageRouters: [],
+    globalMiddlewares: [],
+    contractVersion: null,
+    publishesRouteMap: false
+  });
+}
+
+// src/surface/error.ts
+var SurfaceError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SurfaceError";
+  }
+};
+
+// src/surface/wording.ts
+var SURFACE_WORDING = {
+  noun: "surface",
+  builder: "`<surface>.route`",
+  factory: "defineSurface"
+};
+function capitalized(noun) {
+  return noun.charAt(0).toUpperCase() + noun.slice(1);
+}
+
+// src/surface/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 collectSurfaceCommands(routes, wording = SURFACE_WORDING) {
+  const commands = [];
+  visit(routes, commands, /* @__PURE__ */ new Map(), wording);
+  commands.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  return commands;
+}
+function visit(routes, commands, claimed, wording) {
+  for (const [name, entry] of Object.entries(routes)) {
+    if (isRouter(entry)) {
+      visit(entry.routes, commands, claimed, wording);
+      continue;
+    }
+    if (!isRouteDef(entry) || !entry.method || !entry.path) {
+      continue;
+    }
+    assertUnclaimedName(name, entry.path, claimed, wording);
+    commands.push({
+      name,
+      method: entry.method,
+      path: entry.path,
+      ...entry.summary !== void 0 ? { summary: entry.summary } : {},
+      ...entry.effect !== void 0 ? { effect: entry.effect } : {},
+      input: toCommandInput(entry.input)
+    });
+  }
+}
+function assertUnclaimedName(name, path, claimed, wording) {
+  const existing = claimed.get(name);
+  if (existing !== void 0) {
+    throw new SurfaceError(
+      `Two ${wording.noun} routes are named "${name}" ("${existing}" and "${path}"). Command names are flattened across nested routers, so each must be unique for a client to resolve the one its caller asked for.`
+    );
+  }
+  claimed.set(name, path);
+}
+
+// src/surface/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 routePatternsOverlap(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/surface/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 PATH_BASE = "https://spfn.invalid";
+function isSurfaceEffect(value) {
+  return EFFECTS.has(value);
+}
+function assertText(label, value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new SurfaceError(`${label} must be a non-empty string.`);
+  }
+}
+function assertStableModulePath(at, moduleId, commandName, path) {
+  const label = `${at.label} command "${moduleId}.${commandName}" path "${path}"`;
+  const transportPath = path.replace(/[{}?#]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+  let url;
+  try {
+    url = new URL(transportPath, PATH_BASE);
+  } catch {
+    throw new SurfaceError(`${label} is not a valid URL path.`);
+  }
+  if (url.origin !== PATH_BASE || url.search !== "" || url.hash !== "" || url.pathname !== transportPath) {
+    throw new SurfaceError(`${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 SurfaceError(`${label} contains malformed percent encoding.`);
+    }
+    if (next.includes("\\") || (next.match(/\//g) ?? []).length !== slashCount || next.split("/").some((segment) => segment === "." || segment === "..")) {
+      throw new SurfaceError(`${label} contains encoded path separators or dot segments.`);
+    }
+    if (next === decoded) {
+      return;
+    }
+    decoded = next;
+  }
+  throw new SurfaceError(`${label} uses too many percent-encoding layers.`);
+}
+function assertCliCallableModulePath(at, 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 SurfaceError(
+      `${at.label} 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(at, moduleId, name, command) {
+  if (!COMMAND_NAME.test(name)) {
+    throw new SurfaceError(
+      `${at.label} module "${moduleId}" has invalid command name "${name}". Use dot-separated alphanumeric names.`
+    );
+  }
+  assertText(`${at.label} command "${moduleId}.${name}" summary`, command?.summary);
+  if (!EFFECTS.has(command?.effect)) {
+    throw new SurfaceError(
+      `${at.label} 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 SurfaceError(`${at.label} 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 SurfaceError(`${at.label} command "${moduleId}.${name}" must carry a complete route.`);
+  }
+  assertStableModulePath(at, moduleId, name, route2.path);
+  assertCliCallableModulePath(at, moduleId, name, route2.path);
+  const modulePath = `${at.namespace}/${moduleId}/`;
+  if (!route2.path.startsWith(modulePath)) {
+    throw new SurfaceError(
+      `${at.label} command "${moduleId}.${name}" is at "${route2.path}", outside "${modulePath}". A module mounted on "${at.namespace}" keeps every command under "${modulePath}".`
+    );
+  }
+  if (route2.path.split("/").includes("..")) {
+    throw new SurfaceError(`${at.label} command "${moduleId}.${name}" path climbs out of its module namespace.`);
+  }
+}
+function validateSurfaceModule(module, namespace, wording = SURFACE_WORDING) {
+  const at = { namespace, label: capitalized(wording.noun) };
+  if (!MODULE_ID.test(module?.id ?? "")) {
+    throw new SurfaceError(
+      `${at.label} module id ${JSON.stringify(module?.id)} is invalid. Use lower-kebab-case.`
+    );
+  }
+  assertText(`${at.label} module "${module.id}" source`, module.source);
+  assertText(`${at.label} module "${module.id}" summary`, module.summary);
+  if (!CONTRACT_VERSION.test(module.contractVersion)) {
+    throw new SurfaceError(
+      `${at.label} module "${module.id}" contractVersion must be a semantic version.`
+    );
+  }
+  if (!module.commands || typeof module.commands !== "object" || Array.isArray(module.commands)) {
+    throw new SurfaceError(`${at.label} 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(at, module.id, name, command);
+    const signature = `${command.route.method} ${command.route.path}`;
+    const existing = signatures.get(signature);
+    if (existing) {
+      throw new SurfaceError(
+        `${at.label} module "${module.id}" commands "${existing}" and "${name}" both use ${signature}.`
+      );
+    }
+    signatures.set(signature, name);
+    const overlapping = claimedRoutes.find((claim) => claim.method === command.route.method && routePatternsOverlap(claim.path, command.route.path));
+    if (overlapping) {
+      throw new SurfaceError(
+        `${at.label} 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;
+}
+function defineSurfaceModule(module, namespace) {
+  return validateSurfaceModule(module, namespace);
+}
+
+// src/surface/namespace.ts
+var NAMESPACE = /^(?:\/[A-Za-z0-9_-]+)+$/;
+function assertNamespace(namespace) {
+  if (typeof namespace !== "string" || !NAMESPACE.test(namespace)) {
+    throw new SurfaceError(
+      `Surface namespace ${JSON.stringify(namespace)} is invalid. Use an absolute path of [A-Za-z0-9_-] segments without a trailing slash, such as "/_app".`
+    );
+  }
+}
+function manifestPathOf(namespace) {
+  return `${namespace}/_manifest`;
+}
+function manifestNameOf(namespace) {
+  return `get${namespace.slice(1).replace(/_[a-z]|[A-Z_/-]/g, encodedCharacter)}Manifest`;
+}
+var ESCAPES = { "_": "_", "-": "d", "/": "s" };
+function encodedCharacter(match) {
+  if (match.length === 2) {
+    return match.charAt(1).toUpperCase();
+  }
+  return `_${ESCAPES[match] ?? match}`;
+}
+function toSurfacePath(namespace, path, wording) {
+  const label = capitalized(wording.noun);
+  if (!path.startsWith("/")) {
+    throw new SurfaceError(
+      `${label} route path "${path}" must start with "/". It is appended to "${namespace}", so "${path}" would read as "${namespace}${path}".`
+    );
+  }
+  if (path === "/") {
+    throw new SurfaceError(
+      `${label} route path "/" names no command \u2014 "${namespace}" itself is not a command.`
+    );
+  }
+  return namespace + path;
+}
+function surfaceRouteBuilder(namespace, wording) {
+  const method = (name) => (path) => route[name](toSurfacePath(namespace, path, wording));
+  return {
+    get: method("get"),
+    post: method("post"),
+    put: method("put"),
+    patch: method("patch"),
+    delete: method("delete")
+  };
+}
+
+// src/surface/define-surface.ts
+var MAX_COMMAND_SUMMARY_LENGTH = 500;
+var EFFECT_METHOD = ".effect('read' | 'write' | 'destructive')";
+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 assertSurfaceRoute(plan, name, def) {
+  const label = capitalized(plan.wording.noun);
+  if (!def.method || !def.path) {
+    throw new SurfaceError(
+      `${label} route "${name}" has no method or path. A command is invoked on the wire, so both are required.`
+    );
+  }
+  if (!def.path.startsWith(plan.prefix)) {
+    throw new SurfaceError(
+      `${label} route "${name}" is at "${def.path}", outside "${plan.prefix}". Build ${plan.wording.noun} routes with ${plan.wording.builder} rather than \`route\` \u2014 it applies the namespace, so the path a definition carries is only the part the app owns.`
+    );
+  }
+  if (def.path === plan.manifestPath) {
+    throw new SurfaceError(
+      `${label} route "${name}" claims "${plan.manifestPath}", which is reserved for the manifest. The manifest is registered first, so this route would never answer.`
+    );
+  }
+}
+function assertCommandMetadata(plan, name, def) {
+  const label = `${capitalized(plan.wording.noun)} command "${name}"`;
+  if (def.effect === void 0 && plan.requireEffect) {
+    throw new SurfaceError(
+      `${label} declares no effect. A client reads it to decide whether to call, retry, or ask for confirmation, so ${plan.wording.factory} refuses a command without one. Declare it on the route with ${EFFECT_METHOD}.`
+    );
+  }
+  if (def.effect !== void 0 && !isSurfaceEffect(def.effect)) {
+    throw new SurfaceError(
+      `${label} has invalid effect ${JSON.stringify(def.effect)}. A client knows no other, so declare it with ${EFFECT_METHOD}.`
+    );
+  }
+  assertCommandSummary(label, def.summary);
+}
+function assertCommandSummary(label, summary) {
+  if (summary === void 0) {
+    return;
+  }
+  if (typeof summary !== "string" || summary.trim().length === 0) {
+    throw new SurfaceError(
+      `${label} has an empty summary. A client would list it as a command described by nothing; give .summary() one line of text, or leave it out.`
+    );
+  }
+  if (summary.length > MAX_COMMAND_SUMMARY_LENGTH) {
+    throw new SurfaceError(
+      `${label} has a summary of ${summary.length} characters, over the ${MAX_COMMAND_SUMMARY_LENGTH} a client accepts \u2014 it would drop the command's metadata and treat it as destructive. Shorten it.`
+    );
+  }
+}
+function assertModuleRouteEffect(plan, name, definition) {
+  const routeEffect = definition.route.effect;
+  if (routeEffect !== void 0 && routeEffect !== definition.effect) {
+    throw new SurfaceError(
+      `${capitalized(plan.wording.noun)} command "${name}" is declared ${JSON.stringify(definition.effect)} by its module, but its route says .effect(${JSON.stringify(routeEffect)}). The manifest announces the module's declaration, so the two cannot disagree. Drop the route's .effect() or make it match.`
+    );
+  }
+}
+function assertSurfaceName(plan, name) {
+  if (name === plan.manifestName) {
+    throw new SurfaceError(
+      `${capitalized(plan.wording.noun)} route name "${plan.manifestName}" is reserved for the manifest route.`
+    );
+  }
+}
+function rebuildNestedRouter(plan, name, router, commandsByName, inherited) {
+  if (router._packageRouters?.length > 0) {
+    throw new SurfaceError(
+      `${capitalized(plan.wording.noun)} router "${name}" mounts package routers with .packages(). Their routes bypass the prefix check and the auth injection, so a surface cannot carry them.`
+    );
+  }
+  const handedDown = [...inherited, ...router._globalMiddlewares ?? []];
+  let rebuilt = defineUnmappedRouter(
+    secureRoutes(plan, router.routes, commandsByName, handedDown)
+  );
+  if (router._contractVersion) {
+    rebuilt = rebuilt.contractVersion(router._contractVersion);
+  }
+  return rebuilt;
+}
+function secureRoutes(plan, routes, commandsByName, inherited = []) {
+  const secured = {};
+  for (const [name, entry] of Object.entries(routes)) {
+    assertSurfaceName(plan, name);
+    if (isRouter2(entry)) {
+      secured[name] = rebuildNestedRouter(plan, name, entry, commandsByName, inherited);
+      continue;
+    }
+    if (!isRouteDef2(entry)) {
+      throw new SurfaceError(
+        `${capitalized(plan.wording.noun)} router entry "${name}" is neither a route nor a router.`
+      );
+    }
+    assertSurfaceRoute(plan, name, entry);
+    assertCommandMetadata(plan, name, entry);
+    const guard = plan.authorize?.(commandsByName.get(name));
+    secured[name] = {
+      ...entry,
+      middlewares: commandChain(plan, name, guard, [...inherited, ...entry.middlewares ?? []])
+    };
+  }
+  return secured;
+}
+function commandChain(plan, name, guard, declared) {
+  if (guard === void 0) {
+    return [plan.auth, ...declared];
+  }
+  const guardName = middlewareNameOf(guard);
+  if (guardName !== void 0) {
+    refuseGuardCollision(plan, name, guardName, declared);
+  }
+  return [plan.auth, guard, ...declared];
+}
+function refuseGuardCollision(plan, name, guardName, declared) {
+  const noun = capitalized(plan.wording.noun);
+  if (middlewareNameOf(plan.auth) === guardName) {
+    throw new SurfaceError(
+      `${noun} command "${name}"'s guard shares the name "${guardName}" with the surface's auth middleware. Route registration keeps one middleware per name, so the command's guard would never run. Give one of the two a distinct name.`
+    );
+  }
+  if (declared.some((middleware) => middlewareNameOf(middleware) === guardName)) {
+    throw new SurfaceError(
+      `${noun} command "${name}" declares a middleware named "${guardName}", the name of the guard authorize gave it. Route registration keeps one middleware per name, so the command's own guard would never run. Give one of the two a distinct name.`
+    );
+  }
+}
+function middlewareNameOf(middleware) {
+  return typeof middleware === "function" ? void 0 : middleware.name;
+}
+function assertModuleCommandFree(plan, command, appCommands, claimed) {
+  const noun = plan.wording.noun;
+  if (claimed.names.has(command.name)) {
+    throw new SurfaceError(`Two ${noun} commands are named "${command.name}".`);
+  }
+  const signature = `${command.method} ${command.path}`;
+  const existing = claimed.signatures.get(signature);
+  if (existing) {
+    throw new SurfaceError(
+      `${capitalized(noun)} commands "${existing}" and "${command.name}" both use ${signature}.`
+    );
+  }
+  const overlapping = appCommands.find((app) => app.method === command.method && routePatternsOverlap(app.path, command.path));
+  if (overlapping) {
+    throw new SurfaceError(
+      `App ${noun} command "${overlapping.name}" at ${command.method} ${overlapping.path} overlaps module command "${command.name}" at ${command.method} ${command.path}. Which one answers cannot depend on route registration order.`
+    );
+  }
+  claimed.names.add(command.name);
+  claimed.signatures.set(signature, command.name);
+}
+function compileModules(plan, appCommands) {
+  const compiled = { descriptors: [], commands: [], routes: {} };
+  const moduleIds = /* @__PURE__ */ new Set();
+  const claimed = {
+    names: new Set(appCommands.map((command) => command.name)),
+    signatures: new Map(appCommands.map((command) => [`${command.method} ${command.path}`, command.name]))
+  };
+  for (const rawModule of plan.modules) {
+    const module = validateSurfaceModule(rawModule, plan.namespace, plan.wording);
+    if (moduleIds.has(module.id)) {
+      throw new SurfaceError(`Two ${plan.wording.noun} modules use id "${module.id}".`);
+    }
+    moduleIds.add(module.id);
+    compiled.descriptors.push({
+      id: module.id,
+      source: module.source,
+      contractVersion: module.contractVersion,
+      summary: module.summary
+    });
+    for (const [localName, definition] of Object.entries(module.commands)) {
+      const command = {
+        name: `${module.id}.${localName}`,
+        module: module.id,
+        summary: definition.summary,
+        effect: definition.effect,
+        scopes: [...definition.scopes],
+        method: definition.route.method,
+        path: definition.route.path,
+        input: collectSurfaceCommands({ [localName]: definition.route }, plan.wording)[0].input
+      };
+      assertModuleRouteEffect(plan, command.name, definition);
+      assertModuleCommandFree(plan, command, appCommands, claimed);
+      compiled.commands.push(command);
+      compiled.routes[command.name] = { route: definition.route, command };
+    }
+  }
+  compiled.descriptors.sort((a, b) => a.id.localeCompare(b.id));
+  compiled.commands.sort((a, b) => a.name.localeCompare(b.name));
+  return compiled;
+}
+function secureModuleRoutes(plan, routes) {
+  const secured = {};
+  for (const [name, definition] of Object.entries(routes)) {
+    assertSurfaceName(plan, name);
+    assertSurfaceRoute(plan, name, definition.route);
+    secured[name] = {
+      ...definition.route,
+      middlewares: commandChain(
+        plan,
+        name,
+        plan.authorize?.(definition.command),
+        definition.route.middlewares ?? []
+      )
+    };
+  }
+  return secured;
+}
+function manifestRoute(plan, manifest) {
+  const builder = route.get(plan.manifestPath);
+  return (plan.manifest === "public" ? builder.skip(["auth"]) : builder.use([plan.auth])).handler(async () => manifest);
+}
+function buildRouter(plan, routes) {
+  const appCommands = collectSurfaceCommands(routes, plan.wording);
+  const moduleSurface = compileModules(plan, 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 commandsByName = new Map(appCommands.map((command) => [command.name, command]));
+  const secured = secureRoutes(plan, routes, commandsByName);
+  const securedModules = secureModuleRoutes(plan, moduleSurface.routes);
+  return Object.defineProperty(defineUnmappedRouter({
+    [plan.manifestName]: manifestRoute(plan, manifest),
+    ...secured,
+    ...securedModules
+  }), "_surfaceNamespace", { value: plan.namespace, enumerable: false });
+}
+function planOf(options, wording, rules) {
+  assertNamespace(options?.namespace);
+  if (!options.auth) {
+    throw new SurfaceError(
+      `${wording.factory} requires an auth middleware ({ auth: ... }). A surface reachable without authentication cannot be created.`
+    );
+  }
+  const modules = options.modules ?? [];
+  if (modules.length > 0 && !options.authorize) {
+    throw new SurfaceError(`${wording.factory} requires an authorize function when modules are mounted.`);
+  }
+  const manifest = options.manifest ?? "authenticated";
+  if (manifest !== "authenticated" && manifest !== "public") {
+    throw new SurfaceError(
+      `${wording.factory} manifest must be 'authenticated' or 'public', got ${JSON.stringify(manifest)}.`
+    );
+  }
+  return {
+    namespace: options.namespace,
+    prefix: `${options.namespace}/`,
+    manifestPath: manifestPathOf(options.namespace),
+    manifestName: manifestNameOf(options.namespace),
+    auth: options.auth,
+    authorize: options.authorize,
+    manifest,
+    modules,
+    wording,
+    requireEffect: rules.requireEffect
+  };
+}
+function createSurface(options, wording, rules) {
+  const plan = planOf(options, wording, rules);
+  return {
+    namespace: plan.namespace,
+    route: surfaceRouteBuilder(plan.namespace, wording),
+    router: (routes) => buildRouter(plan, routes)
+  };
+}
+function defineSurface(options) {
+  return createSurface(options, SURFACE_WORDING, { requireEffect: true });
+}
+
+export { SurfaceError, collectSurfaceCommands, defineSurface, defineSurfaceModule };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map