canopycms 0.0.67-int.90 → 0.0.67

package/dist/http/handler.js

@@ -9,35 +9,27 @@ import { authResultToCanopyUser } from '../user.js';
 import { isAdmin } from '../authorization/index.js';
 import { clientOperatingStrategy, operatingStrategy } from '../operating-mode/index.js';
 import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../utils/error.js';
-// canopyLogError, not console.error: http/handler.ts is shared code and not
-// guaranteed to stay out of the worker's runtime import closure (see
-// utils/logger.ts) — new log lines here should go through the indirection.
+// canopyLogError, not console.error: this is shared code and not guaranteed to
+// stay out of the worker's runtime import closure, so new log lines here go
+// through the indirection (utils/logger.ts).
 import { canopyLogError } from '../utils/logger.js';
-/**
- * Build API context from options.
- */
 const buildContext = async (options) => {
     const services = options.services ?? (options.config ? await createCanopyServices(options.config) : undefined);
     if (!services) {
         throw new Error('CanopyCMS: config or services is required');
     }
     const operatingMode = services.config.mode;
-    // Derive from the strategy (which resolves deploymentName via
-    // resolveDeploymentName), not a hardcoded literal — a third, independent
-    // default here that never accounted for deploymentName meant a
-    // deployment-namespaced settings branch (e.g. canopycms-settings-acme)
-    // never matched this check, so `getBranchContext(settingsBranch)` could
-    // never auto-create it.
+    // Derive from the strategy, which resolves deploymentName; a literal here
+    // would not match a deployment-namespaced settings branch (say
+    // canopycms-settings-acme), so getBranchContext could never auto-create it.
     const settingsBranch = operatingStrategy(operatingMode).getSettingsBranchName(services.config);
     const getBranchContext = options.getBranchContext ??
         (async (branch, opts) => {
-            // Try to load existing branch
             const existing = await loadBranchContext({
                 branchName: branch,
                 mode: operatingMode,
             });
             if (existing) {
-                // Optionally load per-branch schema
                 if (opts?.loadSchema) {
                     const contentRootName = services.config.contentRoot || 'content';
                     const cached = await services.branchSchemaCache.getSchema(existing.branchRoot, services.entrySchemaRegistry, contentRootName);
@@ -45,9 +37,8 @@ const buildContext = async (options) => {
                 }
                 return existing;
             }
-            // In modes that support branching, auto-create system branches if they don't exist.
-            // Read from services.config per-request (not a captured variable) so that
-            // refreshActiveBranch() updates are reflected immediately.
+            // Read from services.config per-request, not a captured variable, so a
+            // refreshActiveBranch() update takes effect immediately.
             const baseBranch = services.config.defaultBaseBranch ?? 'main';
             const activeBranch = services.config.defaultActiveBranch ?? baseBranch;
             const shouldAutoCreate = clientOperatingStrategy(operatingMode).supportsBranching() &&
@@ -59,7 +50,6 @@ const buildContext = async (options) => {
                     mode: operatingMode,
                     createdBy: 'canopycms-system',
                 });
-                // Optionally load per-branch schema for auto-created branches
                 if (opts?.loadSchema && context) {
                     const contentRootName = services.config.contentRoot || 'content';
                     const cached = await services.branchSchemaCache.getSchema(context.branchRoot, services.entrySchemaRegistry, contentRootName);
@@ -76,9 +66,6 @@ const buildContext = async (options) => {
         authPlugin: options.authPlugin,
     };
 };
-/**
- * Parse query parameters from URL.
- */
 const parseQueryParams = (url) => {
     try {
         const urlObj = new URL(url, 'http://localhost');
@@ -89,31 +76,9 @@ const parseQueryParams = (url) => {
     }
 };
 /**
- * Create a framework-agnostic Canopy request handler.
- *
- * This is the core handler that processes all Canopy API requests.
- * Framework adapters (Next.js, Express, Hono, etc.) should:
- * 1. Convert their framework's request to CanopyRequest
- * 2. Extract path segments from the URL
- * 3. Call this handler
- * 4. Convert the CanopyResponse to their framework's response
- *
- * @example
- * ```ts
- * // In a framework adapter
- * const coreHandler = createCanopyRequestHandler({
- *   config: myConfig,
- *   authPlugin: myAuthPlugin,
- * })
- *
- * // Framework-specific handler
- * async function handleRequest(frameworkReq) {
- *   const canopyReq = convertToCanopyRequest(frameworkReq)
- *   const segments = extractPathSegments(frameworkReq)
- *   const response = await coreHandler(canopyReq, segments)
- *   return convertToFrameworkResponse(response)
- * }
- * ```
+ * The core handler behind every Canopy API request. A framework adapter
+ * (Next.js, Express, Hono) converts its request to a CanopyRequest, extracts
+ * the path segments, calls this, and converts the CanopyResponse back.
  */
 export function createCanopyRequestHandler(options) {
     // Fail closed (SEC-C1): a dev/insecure auth plugin must never serve prod traffic.
@@ -121,10 +86,9 @@ export function createCanopyRequestHandler(options) {
     const mode = options.services?.config.mode ?? options.config?.mode;
     assertAuthPluginAllowedForMode(options.authPlugin, mode);
     const router = createCanopyRouter();
-    // Build context once (memoized) and reuse across requests in the same warm
-    // container/process. On rejection (e.g. transient cold-start / EFS not yet
-    // mounted), the cache is cleared (API-H3) so the NEXT request retries
-    // buildContext() instead of replaying the same rejection forever.
+    // Built once and reused across requests in the same warm container. On
+    // rejection (transient cold start, EFS not yet mounted) the cache is cleared
+    // (API-H3) so the NEXT request retries instead of replaying the rejection.
     let apiCtxPromise = null;
     const getContext = () => {
         if (!apiCtxPromise) {
@@ -135,37 +99,30 @@ export function createCanopyRequestHandler(options) {
         }
         return apiCtxPromise;
     };
-    // Core request-handling logic, wrapped below by a top-level try/catch (API-C1).
-    // getContext()/refreshActiveBranch()/authenticate()/match.handler() are NOT
-    // individually try/catched here, and some handlers deliberately re-throw
-    // unrecognized errors (e.g. api/content.ts, api/entries.ts) — without an outer
-    // boundary, an unhandled throw would escape the framework adapter as a generic
-    // 500 that breaks the uniform { ok, status, error } contract the editor depends on.
+    // Wrapped below by a top-level try/catch (API-C1). Nothing in here is
+    // individually try/catched, and some handlers deliberately re-throw
+    // unrecognized errors, so without that outer boundary an unhandled throw
+    // would escape the adapter as a generic 500 and break the uniform
+    // { ok, status, error } contract the editor depends on.
     const handleRequest = async (req, pathSegments) => {
-        // Route matching (fast, do first before async work)
         const match = router.match(req.method, pathSegments);
         if (!match) {
             return jsonResponse({ ok: false, status: 404, error: 'Not found' }, 404);
         }
-        // Get cached context
         const apiCtx = await getContext();
         // In dev mode, re-check if the developer switched git branches
         await apiCtx.services.refreshActiveBranch();
-        // Authenticate and convert to CanopyUser
         const authResult = await options.authPlugin.authenticate(req);
-        // API routes require authentication. Reject anonymous callers BEFORE any
-        // workspace provisioning below, so they can neither trigger expensive git
-        // operations nor read provisioning error details.
+        // API routes require authentication. Anonymous callers are rejected BEFORE
+        // any workspace provisioning below, so they can neither trigger expensive
+        // git operations nor read provisioning error details.
         if (!authResult.success || !authResult.user) {
             return jsonResponse({ ok: false, status: 401, error: authResult.error ?? 'Unauthorized' }, 401);
         }
-        // Ensure the base/active branch workspace is provisioned on first
-        // request. Internal groups no longer come from this branch (see
-        // resolveCanopyUser below) — this call is purely so many endpoints that
-        // assume the base/active workspace already exists (registry reads, etc.)
-        // don't return confusing empty results on a cold start, so fail loudly
-        // on a real provisioning error rather than let that surprise a later
-        // handler.
+        // Provision the base/active branch workspace on first request, so the many
+        // endpoints that assume it exists (registry reads and the like) don't return
+        // confusing empty results on a cold start. A real provisioning error fails
+        // loudly here rather than surprising a later handler.
         const baseBranch = apiCtx.services.config.defaultBaseBranch ?? 'main';
         try {
             await apiCtx.getBranchContext(baseBranch);
@@ -173,16 +130,16 @@ export function createCanopyRequestHandler(options) {
         catch (err) {
             const message = getErrorMessage(err);
             if (err instanceof BranchMetadataCorruptError) {
-                // Corrupt BASE branch metadata must not take down every endpoint —
-                // the /admin recovery surface is how it gets fixed. Degrade instead:
-                // keep routing (internal groups come from the settings workspace
-                // below, independent of this branch's health).
+                // Corrupt BASE branch metadata must not take down every endpoint,
+                // since /admin is how it gets fixed. Keep routing instead: internal
+                // groups come from the settings workspace below, independent of this
+                // branch's health.
                 console.error(`CanopyCMS: Base branch '${baseBranch}' has corrupt metadata; serving without base-branch provisioning until repaired: ${redactCredentials(message)}`);
             }
             else {
-                // Full path detail to server logs; sanitized detail to the
-                // (authenticated) client. Credentials (git errors can embed them) are
-                // redacted even from server logs.
+                // Full path detail to server logs, sanitized detail to the
+                // (authenticated) client. Credentials, which git errors can embed, are
+                // redacted even from the server logs.
                 console.error(`CanopyCMS: Failed to provision workspace for base branch '${baseBranch}': ${redactCredentials(message)}`);
                 return jsonResponse({
                     ok: false,
@@ -191,14 +148,13 @@ export function createCanopyRequestHandler(options) {
                 }, 503);
             }
         }
-        // Resolve the CanopyUser: internal groups are the single source of
-        // truth for group-based privileges and MUST be loaded from the settings
-        // workspace (see authorization/content.ts's createContentAccessChecker,
-        // the pattern this follows) — never from a content branch clone, which
-        // nothing in the product ever writes groups.json into. Fails loudly
-        // (throws, mapped to a 503 below) rather than degrading to an empty
-        // group list: "no groups" reads as "no privileges", so a silent
-        // fallback would be a silent authorization change.
+        // Internal groups are the single source of truth for group-based privilege
+        // and MUST come from the settings workspace (the pattern in
+        // authorization/content.ts's createContentAccessChecker), never from a
+        // content branch clone, which nothing writes groups.json into. A failure
+        // throws, mapped to a 503 below, rather than degrading to an empty group
+        // list: "no groups" reads as "no privileges", so a silent fallback would be
+        // a silent authorization change.
         let user;
         try {
             user = await resolveCanopyUser(authResult, {
@@ -210,34 +166,32 @@ export function createCanopyRequestHandler(options) {
         catch (err) {
             const message = getErrorMessage(err);
             canopyLogError(`CanopyCMS: Failed to resolve internal groups from the settings workspace: ${redactCredentials(message)}`);
-            // Same trade as the base-branch degradation above, for the same
-            // reason: /admin is the recovery surface for exactly this failure
-            // (a renamed settings branch trips assertSettingsWorkspaceIdentity
-            // permanently until a human intervenes), so 503ing it too leaves an
-            // operator with no in-product way to see why anything is down.
+            // Same trade as the base-branch degradation above: /admin is the recovery
+            // surface for exactly this failure (a renamed settings branch trips
+            // assertSettingsWorkspaceIdentity until a human intervenes), so 503ing it
+            // too would leave an operator no in-product way to see what is down.
             //
-            // Safe because it can only REMOVE privilege, never grant it.
-            // `authResultToCanopyUser` merges internal groups ADDITIVELY, and
-            // path rules select on the user matching a target (never on the user
-            // LACKING a group), so dropping them can flip allowed -> denied and
-            // not the reverse. The one privilege that survives is bootstrap
-            // admin, which comes from CANOPY_BOOTSTRAP_ADMIN_IDS in the
-            // environment and does not touch the settings workspace at all.
+            // Safe because it can only REMOVE privilege, never grant it:
+            // `authResultToCanopyUser` merges internal groups ADDITIVELY, and path
+            // rules select on the user MATCHING a target, never on the user LACKING a
+            // group, so dropping them flips allowed -> denied and not the reverse. The
+            // one surviving privilege is bootstrap admin, which comes from
+            // CANOPY_BOOTSTRAP_ADMIN_IDS and never touches the settings workspace.
             //
-            // A non-bootstrap admin still gets the 503, deliberately: the admin
-            // guard would answer them 403, and "settings workspace unavailable"
-            // is the more actionable of the two.
+            // A non-bootstrap admin still gets the 503, deliberately: the admin guard
+            // would answer them 403, and "settings workspace unavailable" is the more
+            // actionable of the two.
             const degradedUser = authResultToCanopyUser(authResult, apiCtx.services.bootstrapAdminIds);
             if (pathSegments[0] === 'admin' && isAdmin(degradedUser.groups)) {
                 canopyLogError(`CanopyCMS: Serving ${req.method} /admin for a bootstrap admin with group-based privileges UNRESOLVED (settings workspace unavailable) so the recovery endpoints stay reachable.`);
                 user = degradedUser;
             }
             else {
-                // Name the settings branch: the failure this most often means is a
-                // changed deploymentName pointing the deployment at a branch that
-                // isn't the one its workspace was cloned for, and the branch name
-                // is the part of that an operator can act on without CloudWatch
-                // (paths are redacted out of client-facing messages).
+                // Name the settings branch: this usually means a changed deploymentName
+                // pointing the deployment at a branch other than the one its workspace
+                // was cloned for, and the branch name is the part of that an operator
+                // can act on without CloudWatch (paths are redacted from client-facing
+                // messages).
                 const settingsBranch = operatingStrategy(apiCtx.services.config.mode).getSettingsBranchName(apiCtx.services.config);
                 return jsonResponse({
                     ok: false,
@@ -246,16 +200,13 @@ export function createCanopyRequestHandler(options) {
                 }, 503);
             }
         }
-        // API routes require authentication - reject anonymous users
         if (user.type === 'anonymous') {
             return jsonResponse({ ok: false, status: 401, error: authResult.error ?? 'Unauthorized' }, 401);
         }
-        // Parse query params and merge with route params
         const queryParams = parseQueryParams(req.url);
         const mergedParams = { ...queryParams, ...match.params };
-        // Parse body for non-GET requests. Multipart routes opt out (bodyFormat)
-        // so their handler can read the (single-use) body stream itself via
-        // req.formData() - calling req.json() first would consume it.
+        // Multipart routes opt out via bodyFormat so their handler can read the
+        // single-use body stream itself: calling req.json() first would consume it.
         let body;
         if (req.method !== 'GET' && match.bodyFormat !== 'multipart') {
             try {
@@ -265,17 +216,14 @@ export function createCanopyRequestHandler(options) {
                 body = undefined;
             }
         }
-        // Build API request
         const branch = mergedParams?.branch ??
             body?.branch;
         const apiReq = { user, body, branch, query: queryParams, rawRequest: req };
-        // Validate params and body using the route's validation function (if available)
         if (match.validate) {
             const validationResult = match.validate({ params: mergedParams, body });
             if (!validationResult.ok) {
                 return jsonResponse({ ok: false, status: 400, error: validationResult.error }, 400);
             }
-            // Call handler with validated params/body based on what's defined
             const handlerArgs = [apiCtx, apiReq];
             if (validationResult.params !== undefined) {
                 handlerArgs.push(validationResult.params);
@@ -284,16 +232,16 @@ export function createCanopyRequestHandler(options) {
                 handlerArgs.push(validationResult.body);
             }
             const result = await match.handler(...handlerArgs);
-            // Binary routes (e.g. asset serving) carry their own status/headers and
-            // must reach the adapter untouched - wrapping them in jsonResponse would
-            // JSON-serialize raw bytes and lose contentType/contentDisposition/etc.
+            // Binary routes carry their own status and headers and MUST reach the
+            // adapter untouched: jsonResponse would serialize raw bytes and drop
+            // contentType/contentDisposition.
             if (isCanopyBinaryResponse(result))
                 return result;
             return jsonResponse(result, result.status);
         }
         else {
-            // Should not happen - all routes should use defineEndpoint now
-            // This is here for safety in case any route doesn't have validation
+            // Every route should use defineEndpoint; this is the safety net for one
+            // that carries no validate function.
             const result = await match.handler(apiCtx, apiReq, mergedParams);
             if (isCanopyBinaryResponse(result))
                 return result;
@@ -312,9 +260,6 @@ export function createCanopyRequestHandler(options) {
         }
     };
 }
-/**
- * Create a handler with pre-built services from config.
- */
 export async function createCanopyRequestHandlerFromConfig(options) {
     return createCanopyRequestHandler({
         ...options,

package/dist/http/router.d.ts

@@ -1,19 +1,13 @@
 import type { ApiResponse } from '../api/types.js';
 import type { CanopyBinaryResponse } from './types.js';
 /**
- * Handler function signature for Canopy API routes.
- * Uses `any` to accommodate different handler signatures in the codebase.
- * Some handlers take (ctx, req, params), others take (ctx, params) directly.
- * Return type is widened to include `CanopyBinaryResponse` so routes that
- * stream bytes (e.g. asset serving) can be registered in the same route
- * table as ordinary JSON routes; the core handler discriminates on `kind`
- * before deciding whether to wrap the result in a JSON envelope.
+ * `any` because handler signatures differ: some take (ctx, req, params), others
+ * (ctx, params). The return type includes `CanopyBinaryResponse` so byte-
+ * streaming routes share this route table with JSON ones; http/handler.ts
+ * discriminates on `kind` before wrapping a result in a JSON envelope.
  */
 export type CanopyHandler = (...args: any[]) => Promise<ApiResponse<any> | CanopyBinaryResponse>;
-/**
- * Route definition for the Canopy API.
- * Maps HTTP method + path pattern to a handler.
- */
+/** Route definition for the Canopy API. */
 export interface RouteDefinition {
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     pattern: readonly string[];
@@ -30,43 +24,32 @@ export interface RouteDefinition {
         error: string;
     };
     /**
-     * Opt out of the core handler's default eager `req.json()` body parsing
-     * (see http/handler.ts). Set by routes that accept a non-JSON body (e.g.
-     * multipart/form-data uploads) - the handler must read the body itself via
-     * `req.formData()` instead, since a body stream can only be consumed once.
+     * Opts out of the core handler's eager `req.json()` (see http/handler.ts).
+     * Set by routes taking a non-JSON body: the body stream is single-use, so
+     * such a handler must read it itself via `req.formData()`.
      */
     bodyFormat?: 'multipart';
 }
-/**
- * Result of route matching.
- */
 export interface RouteMatch {
     handler: CanopyHandler;
     params: Record<string, string>;
     validate?: RouteDefinition['validate'];
     bodyFormat?: RouteDefinition['bodyFormat'];
 }
-/**
- * Core router - framework-agnostic route matching.
- */
+/** Core router: framework-agnostic route matching. */
 export interface CanopyRouter {
-    /** All registered routes */
     readonly routes: RouteDefinition[];
-    /** Find a matching route for the given method and path segments */
     match(method: string, segments: string[]): RouteMatch | null;
 }
 /**
  * Find the most specific matching route for a method + path.
  *
- * Scans every route (not just the first structural match) so that route
- * *registration order* can never let a broad dynamic route (e.g. `:branch`)
- * shadow a narrower, differently-guarded static route (e.g. `assets`) that
- * happens to be registered later. Exported standalone (rather than inlined
- * into `createCanopyRouter`) so the precedence rule can be unit-tested
- * against synthetic route tables, independent of the real API surface.
+ * Scans EVERY route, not just the first structural match, so registration order
+ * can never let a broad dynamic route (`:branch`) shadow a narrower,
+ * differently-guarded static one (`assets`) registered later. Exported
+ * standalone so that precedence rule can be unit-tested against synthetic route
+ * tables, independent of the real API surface.
+ * @internal Exported for tests.
  */
 export declare function matchRoute(routes: readonly RouteDefinition[], method: string, segments: string[]): RouteMatch | null;
-/**
- * Create the standard Canopy router with all API routes.
- */
 export declare function createCanopyRouter(): CanopyRouter;

package/dist/http/router.js

@@ -1,67 +1,19 @@
-import { BRANCH_ROUTES } from '../api/branch.js';
-import { WORKFLOW_ROUTES } from '../api/branch-status.js';
-import { COMMENT_ROUTES } from '../api/comments.js';
-import { CONTENT_ROUTES } from '../api/content.js';
-import { REFERENCE_OPTIONS_ROUTES } from '../api/reference-options.js';
-import { RESOLVE_REFERENCES_ROUTES } from '../api/resolve-references.js';
-import { ENTRY_ROUTES } from '../api/entries.js';
-import { ASSET_ROUTES, assetRawRoute } from '../api/assets.js';
-import { PERMISSION_ROUTES } from '../api/permissions.js';
-import { GROUP_ROUTES } from '../api/groups.js';
-import { USER_ROUTES } from '../api/user.js';
-import { SCHEMA_ROUTES } from '../api/schema.js';
-import { ADMIN_ROUTES } from '../api/admin.js';
+import { buildCanopyRoutes } from '../api/routes.js';
 /**
- * Build the standard route definitions for the Canopy API.
- * Assembled from co-located route definitions in each API module.
+ * Match a route pattern against actual path segments: `:param` takes one
+ * segment, `...slug` takes the rest.
  *
- * This is a function (not a top-level constant) to ensure all route modules
- * have been fully initialized before we try to access their exports.
- * This prevents module initialization timing issues with ES modules.
- */
-function buildCanopyRoutes() {
-    return [
-        ...Object.values(BRANCH_ROUTES),
-        ...Object.values(WORKFLOW_ROUTES),
-        ...Object.values(COMMENT_ROUTES),
-        ...Object.values(CONTENT_ROUTES),
-        ...Object.values(REFERENCE_OPTIONS_ROUTES),
-        ...Object.values(RESOLVE_REFERENCES_ROUTES),
-        ...Object.values(ENTRY_ROUTES),
-        ...Object.values(ASSET_ROUTES),
-        assetRawRoute,
-        ...Object.values(PERMISSION_ROUTES),
-        ...Object.values(GROUP_ROUTES),
-        ...Object.values(USER_ROUTES),
-        ...Object.values(SCHEMA_ROUTES),
-        ...Object.values(ADMIN_ROUTES),
-    ].map((route) => ({
-        method: route.method,
-        pattern: route.pattern,
-        handler: route.handler,
-        // Include validation function if present (new-style routes from defineEndpoint)
-        validate: 'validate' in route ? route.validate : undefined,
-        bodyFormat: 'bodyFormat' in route ? route.bodyFormat : undefined,
-    }));
-}
-/**
- * Match a route pattern against actual path segments.
- * Supports :param for single-segment params and ...slug for catch-all.
- *
- * Params are returned RAW (undecoded) here on purpose (C5): matching is
- * purely structural (segment counts, static-segment equality) and must never
- * throw. Decoding happens exactly once, uniformly for :param and catch-all
- * alike, in matchRoute() below - after the winning route has been picked, so
- * a malformed `%` escape is handled in a single place instead of aborting
- * mid-match (which previously let a URIError from a bad :param escape to
- * `decodeURIComponent` bubble all the way to http/handler.ts's top-level
- * catch and surface as a 500).
+ * Params come back RAW (undecoded) on purpose (C5): matching is purely
+ * structural and must NEVER throw. Decoding happens exactly once, uniformly for
+ * `:param` and catch-all alike, in matchRoute() below, after the winning route
+ * is picked — so a malformed `%` escape is handled in one place instead of
+ * aborting mid-match, where the URIError would reach http/handler.ts's
+ * top-level catch and surface as a 500 rather than a 400.
  */
 const matchPattern = (pattern, actual) => {
     const params = {};
     const actualCopy = [...actual];
     for (const part of pattern) {
-        // Catch-all: consume remaining segments
         if (part.startsWith('...')) {
             const paramName = part.slice(3); // Remove '...' prefix
             params[paramName] = actualCopy.join('/');
@@ -72,24 +24,21 @@ const matchPattern = (pattern, actual) => {
         if (!next)
             return null;
         if (part.startsWith(':')) {
-            // Dynamic segment - extract param (still raw; see decode note above)
+            // Still raw; see the decode note above.
             params[part.slice(1)] = next;
         }
         else if (part !== next) {
-            // Static segment - must match exactly
             return null;
         }
     }
-    // If there are leftover segments, no match
     if (actualCopy.length > 0)
         return null;
     return { params };
 };
 /**
- * Synthetic handler for a request whose matched route params contain a
- * malformed `%` escape sequence (C5) - e.g. a lone `%` or `%zz`. Reported as
- * a 400 (the request is malformed), never registered in the real route
- * table, and only ever reachable via matchRoute()'s decode step below.
+ * Synthetic handler for matched params carrying a malformed `%` escape (C5) —
+ * a lone `%`, `%zz`. The request is malformed, so it answers 400. Never
+ * registered in the route table; only matchRoute()'s decode step reaches it.
  */
 const malformedPathHandler = async () => ({
     ok: false,
@@ -97,18 +46,16 @@ const malformedPathHandler = async () => ({
     error: 'Malformed URL-encoded path segment',
 });
 /**
- * Specificity rank of a pattern segment. Higher wins.
- * A literal ("static") segment is more specific than a `:param`, which is
- * more specific than a `...catchall`.
+ * Specificity rank of a pattern segment, higher wins: a literal beats a
+ * `:param`, which beats a `...catchall`.
  */
 const STATIC_RANK = 2;
 const DYNAMIC_RANK = 1;
 const CATCHALL_RANK = 0;
 /**
- * Rank of the pattern segment governing position `index`.
- * A catch-all at or before `index` governs every position from there on
- * (in this codebase a catch-all is always the last pattern segment, so it
- * effectively "consumes" every subsequent position).
+ * Rank of the pattern segment governing position `index`. A catch-all at or
+ * before `index` governs every position from there on — it is always the last
+ * pattern segment here, so it consumes everything after itself.
  */
 const segmentRankAt = (pattern, index) => {
     for (let i = 0; i <= index && i < pattern.length; i++) {
@@ -120,13 +67,10 @@ const segmentRankAt = (pattern, index) => {
     return pattern[index].startsWith(':') ? DYNAMIC_RANK : STATIC_RANK;
 };
 /**
- * Compare two route patterns for specificity, position by position, for
- * routes that both matched the same actual segments.
- *
- * Returns a negative number if `a` is more specific than `b`, positive if
- * `b` is more specific than `a`, and 0 if they are tied (in which case the
- * caller should keep whichever route it already picked, so registration
- * order acts as the final, deterministic tiebreaker).
+ * Compare two patterns that both matched, position by position: negative when
+ * `a` is more specific, positive when `b` is, 0 when tied. On a tie the caller
+ * keeps the route it already picked, so registration order is the final,
+ * deterministic tiebreaker.
  */
 const compareSpecificity = (a, b) => {
     const maxLen = Math.max(a.length, b.length);
@@ -145,12 +89,12 @@ const compareSpecificity = (a, b) => {
 /**
  * Find the most specific matching route for a method + path.
  *
- * Scans every route (not just the first structural match) so that route
- * *registration order* can never let a broad dynamic route (e.g. `:branch`)
- * shadow a narrower, differently-guarded static route (e.g. `assets`) that
- * happens to be registered later. Exported standalone (rather than inlined
- * into `createCanopyRouter`) so the precedence rule can be unit-tested
- * against synthetic route tables, independent of the real API surface.
+ * Scans EVERY route, not just the first structural match, so registration order
+ * can never let a broad dynamic route (`:branch`) shadow a narrower,
+ * differently-guarded static one (`assets`) registered later. Exported
+ * standalone so that precedence rule can be unit-tested against synthetic route
+ * tables, independent of the real API surface.
+ * @internal Exported for tests.
  */
 export function matchRoute(routes, method, segments) {
     const upperMethod = method.toUpperCase();
@@ -161,24 +105,18 @@ export function matchRoute(routes, method, segments) {
         const match = matchPattern(route.pattern, segments);
         if (!match)
             continue;
-        // Among all routes that match this request, pick the most specific one
-        // (static segments beat :params, which beat ...catchalls).
         if (!best || compareSpecificity(route.pattern, best.route.pattern) < 0) {
             best = { route, params: match.params };
         }
     }
     if (!best)
         return null;
-    // Decode every matched param exactly once, here - uniformly for :param and
-    // catch-all values alike (C5). A malformed escape must produce a 400, not
-    // an uncaught URIError that would otherwise reach http/handler.ts's
-    // top-level catch and get reported as a 500. Downstream consumers
-    // (Zod's logicalPathSchema/branchNameSchema etc. in each route's
-    // `validate`, and any handler-local re-check such as entries.ts's
-    // parseLogicalPath call) still run their own traversal validation against
-    // this same final decoded value - decoding centrally here does not skip
-    // that, it just removes the redundant second decode that used to run
-    // alongside it in a few handlers.
+    // Decode every matched param exactly once, here, uniformly for :param and
+    // catch-all alike (C5). A malformed escape MUST produce a 400, not an
+    // uncaught URIError reaching http/handler.ts's top-level catch as a 500.
+    // Decoding centrally does not replace downstream validation: each route's
+    // `validate` (Zod's logicalPathSchema/branchNameSchema) and any handler-local
+    // re-check still run their own traversal checks against this decoded value.
     let decodedParams;
     try {
         decodedParams = Object.fromEntries(Object.entries(best.params).map(([key, value]) => [key, decodeURIComponent(value)]));
@@ -193,9 +131,6 @@ export function matchRoute(routes, method, segments) {
         bodyFormat: best.route.bodyFormat,
     };
 }
-/**
- * Create the standard Canopy router with all API routes.
- */
 export function createCanopyRouter() {
     const routes = buildCanopyRoutes();
     return {