canopycms 0.0.67-int.90 → 0.0.67

package/dist/api/entries.js

@@ -12,11 +12,7 @@ import { SchemaOps, SchemaStoreBusyError } from '../schema/schema-store.js';
 import { listCollectionEntries as listCollectionEntriesShared, sortByOrder, } from '../content-listing.js';
 // Re-export pagination constants from the dependency-free module so they remain
 // part of the entries API surface without pulling server deps into client bundles.
-export { MAX_ENTRIES_PER_PAGE, DEFAULT_ENTRIES_LIMIT } from './entries-constants.js';
 const log = createDebugLogger({ prefix: 'EntriesAPI' });
-// ============================================================================
-// Zod Schemas for Validation
-// ============================================================================
 const listEntriesParamsSchema = z.object({
     branch: branchNameSchema,
     collection: logicalPathSchema.optional(),
@@ -54,14 +50,11 @@ const toCollectionItem = (entry, collection) => {
 /**
  * List entries in a single collection, mapped to API CollectionItem type.
  *
- * Deliberately does NOT resolve `reference` fields, unlike the `resolveReferences` option
- * that `listEntries`/`buildContentTree` grew for the same underlying primitive. This is a
- * paginated admin table rendering slug/title/canEdit — it never reads inside a reference —
- * and resolution here would land in the worst possible place: it runs BEFORE pagination
- * (`filterWithAccessControl` walks the full collection, `slice` happens at the end), on a
- * request path, so every keystroke in the admin search box would pay a full ContentId index
- * scan plus one read per distinct referenced entry. Revisit only if a column ever needs to
- * display a reference's content.
+ * Deliberately does NOT resolve `reference` fields (unlike the `resolveReferences` option
+ * elsewhere on the same primitive): this runs BEFORE pagination (`slice` happens at the end) on
+ * a search request path, so resolving would cost a full ContentId scan plus one read per
+ * referenced entry on every keystroke. Revisit only if a column needs to display a reference's
+ * content.
  */
 const listCollectionEntries = async (root, collection) => {
     const entries = await listCollectionEntriesShared(root, collection);
@@ -179,12 +172,10 @@ const listEntriesHandler = async (gc, ctx, req, params) => {
         },
     };
 };
-// ============================================================================
-// Route Definitions with defineEndpoint
-// ============================================================================
 /**
  * List entries for a branch
  * GET /:branch/entries
+ * @internal Exported for tests.
  */
 export const listEntries = defineEndpoint({
     namespace: 'entries',
@@ -215,14 +206,10 @@ const deleteEntryParamsSchema = z.object({
  */
 const deleteEntryHandler = async (gc, ctx, req, params) => {
     const { branchContext } = gc;
-    // Parse entryPath to get collection and slug
     // Format: collectionPath/slug (e.g., "posts/hello-world" or "docs/api/getting-started")
     // params.entryPath is already decoded exactly once, uniformly with every
-    // other route param, by http/router.ts's matchRoute (C5) - re-decoding it
-    // here was the redundant second decode that made this route inconsistent
-    // with content.ts's (undecoded) catch-all and vulnerable to a malformed
-    // `%` escape throwing past this handler's try/catch. Still re-validate the
-    // final decoded value for traversal, same as before.
+    // other route param, by http/router.ts's matchRoute (C5). Still re-validate the
+    // final decoded value for traversal.
     const entryPathResult = parseLogicalPath(params.entryPath);
     if (!entryPathResult.ok) {
         return {
@@ -250,8 +237,6 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
         };
     }
     const flatSchema = branchContext.flatSchema;
-    // Check edit permission on the entry
-    // Build the physical path for permission check
     const collection = flatSchema.find((item) => item.type === 'collection' && item.logicalPath === collectionPath);
     if (!collection) {
         return { ok: false, status: 404, error: 'Collection not found' };
@@ -280,16 +265,13 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
         if (isNotFoundError(err)) {
             return { ok: false, status: 404, error: 'Entry not found' };
         }
-        // C2: only a recognized ContentStoreError is the client's fault (bad
-        // slug/path shape); anything else - a real fs error, a bug - is a
-        // server fault and must surface as a 500, not get mislabeled as
-        // "Invalid entry path".
+        // C2: same rule as content.ts's writeContentHandler catch (ContentStoreError -> 400,
+        // everything else -> 500).
         if (err instanceof ContentStoreError) {
             return { ok: false, status: 400, error: 'Invalid entry path' };
         }
         throw err;
     }
-    // Check edit access using the real physical path
     const editAccess = await ctx.services.checkContentAccess(branchContext, branchContext.branchRoot, physicalPath, req.user, 'edit');
     if (!editAccess.allowed) {
         return {
@@ -302,15 +284,11 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
     try {
         // Get the entry's content ID before deleting (for order update)
         const contentId = await contentStore.getIdForEntry(collectionLogicalPath, entrySlug);
-        // Delete the entry
         await contentStore.delete(collectionLogicalPath, entrySlug);
-        // Update the collection's order array to remove the deleted item.
-        // Construct exactly like api/schema.ts's getSchemaOps: the configured
-        // content root as the first argument, the branch root passed explicitly as
-        // the fourth, and with services, so updateOrder's .collection.json write
-        // bumps the schema generation marker. Without the bump, every host durably
-        // serves the stale cached order (still containing the deleted entry) until
-        // the next unrelated schema mutation — prod has no mtime backstop.
+        // Construct exactly like api/schema.ts's getSchemaOps (content root, registry, services,
+        // branch root) so updateOrder's write bumps the schema generation marker — without it, every
+        // host keeps serving the stale cached order (still containing the deleted entry) until the
+        // next unrelated schema mutation, since prod has no mtime backstop.
         if (contentId && collection.type === 'collection' && collection.order) {
             const contentRootName = ctx.services.config.contentRoot || 'content';
             const schemaStore = new SchemaOps(path.join(branchContext.branchRoot, contentRootName), ctx.services.entrySchemaRegistry, ctx.services, branchContext.branchRoot);
@@ -320,13 +298,9 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
                     await schemaStore.updateOrder(collectionPath, newOrder);
                 }
                 catch (err) {
-                    // C6: order cleanup is best-effort hygiene that runs AFTER the
-                    // entry is already deleted, so no failure here - busy schema lock,
-                    // ENOSPC, a bug, anything - is allowed to turn an otherwise-
-                    // successful delete into an error response (the entry is gone; a
-                    // client that sees an error and retries the delete would just get
-                    // a confusing 404). Surface it as a warning on the success
-                    // response instead (mirrors content.ts's write-path `validationWarnings`).
+                    // C6: order cleanup is best-effort hygiene after the entry is already deleted, so no
+                    // failure here may turn an otherwise-successful delete into an error (a retry would
+                    // just 404). Surface it as a warning instead (mirrors content.ts's `validationWarnings`).
                     const reason = err instanceof SchemaStoreBusyError ? 'schema is busy' : getErrorMessage(err);
                     log.warn('delete-entry', 'Skipped order cleanup', {
                         collectionPath,
@@ -347,9 +321,8 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
         if (isNotFoundError(err)) {
             return { ok: false, status: 404, error: 'Entry not found' };
         }
-        // [SYNC-C1] Contention with the worker's rebase (or another editor) is a
-        // retriable conflict, not a server fault -- 409, with the syncing
-        // variant's own "try again" message when that is what happened.
+        // [SYNC-C1] Contention with the worker's rebase (or another editor) is a retriable conflict,
+        // not a server fault — 409, with the syncing variant's own "try again" message.
         if (err instanceof ContentConflictError) {
             return {
                 ok: false,
@@ -366,11 +339,7 @@ const deleteEntryHandler = async (gc, ctx, req, params) => {
         };
     }
 };
-/**
- * Delete an entry
- * DELETE /:branch/entries/...entryPath
- * Note: Uses catch-all to support paths with slashes (e.g., content/posts/hello-world)
- */
+/** @internal Exported for tests. */
 export const deleteEntry = defineEndpoint({
     namespace: 'entries',
     name: 'delete',

package/dist/api/github-sync.d.ts

@@ -1,7 +1,6 @@
 import type { ApiContext } from './types.js';
 import type { BranchContext, SyncStatus } from '../types.js';
 /**
- * Result of a GitHub sync operation.
  * The caller uses this to update branch metadata.
  */
 export interface GitHubSyncResult {
@@ -10,12 +9,11 @@ export interface GitHubSyncResult {
     syncStatus?: SyncStatus;
 }
 /**
- * Submit a branch: create or update a PR.
  * Uses githubService directly if available, otherwise queues a task for the worker.
  */
 export declare function syncSubmitPr(ctx: ApiContext, context: BranchContext): Promise<GitHubSyncResult>;
 /**
- * Convert a PR to draft (used by withdraw and request-changes).
- * Uses githubService directly if available, otherwise queues a task.
+ * Used by withdraw and request-changes. Uses githubService directly if
+ * available, otherwise queues a task.
  */
 export declare function syncConvertToDraft(ctx: ApiContext, context: BranchContext): Promise<void>;

package/dist/api/github-sync.js

@@ -1,10 +1,9 @@
-import { enqueueTask } from '../worker/task-queue.js';
-import { getTaskQueueDir } from '../worker/task-queue-config.js';
+import { enqueueTask } from '../task-queue/cms-task-queue.js';
+import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
 import { clientOperatingStrategy } from '../operating-mode/index.js';
 import { getErrorMessage } from '../utils/error.js';
 import { sanitizeBranchName } from '../paths/branch-name.js';
 /**
- * Submit a branch: create or update a PR.
  * Uses githubService directly if available, otherwise queues a task for the worker.
  */
 export async function syncSubmitPr(ctx, context) {
@@ -118,8 +117,8 @@ export async function syncSubmitPr(ctx, context) {
     });
 }
 /**
- * Convert a PR to draft (used by withdraw and request-changes).
- * Uses githubService directly if available, otherwise queues a task.
+ * Used by withdraw and request-changes. Uses githubService directly if
+ * available, otherwise queues a task.
  */
 export async function syncConvertToDraft(ctx, context) {
     if (!context.branch.pullRequestNumber)
@@ -147,9 +146,6 @@ export async function syncConvertToDraft(ctx, context) {
         });
     }
 }
-/**
- * Enqueue a GitHub task for the EC2 worker.
- */
 async function enqueueGitHubTask(ctx, context, task) {
     const taskDir = getTaskQueueDir(ctx.services.config);
     try {

package/dist/api/groups.d.ts

@@ -16,6 +16,7 @@ export type ExternalGroupsResponse = ApiResponse<{
 /**
  * Validate that an update to internal groups doesn't remove the last admin.
  * Considers both internal Admins group members and bootstrap admins.
+ * @internal Exported for tests.
  */
 export declare const validateAdminGroupUpdate: (newGroups: InternalGroup[], bootstrapAdminIds: Set<string>) => {
     valid: boolean;
@@ -23,6 +24,7 @@ export declare const validateAdminGroupUpdate: (newGroups: InternalGroup[], boot
 };
 /**
  * Validate that reserved groups are not deleted or renamed.
+ * @internal Exported for tests.
  */
 export declare const validateReservedGroups: (newGroups: InternalGroup[]) => {
     valid: boolean;
@@ -35,6 +37,7 @@ export interface UpdateInternalGroupsBody {
 }
 /**
  * Search external groups (for group UI)
+ * @internal Exported for tests.
  */
 export interface SearchExternalGroupsParams {
     query: string;

package/dist/api/groups.js

@@ -4,9 +4,6 @@ import { defineEndpoint } from './route-builder.js';
 import { getSettingsBranchContext, commitSettings } from './settings-helpers.js';
 import { generateId } from '../id.js';
 import { getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
-// ============================================================================
-// Zod Schemas for Validation
-// ============================================================================
 const internalGroupSchema = z.object({
     id: z.string(),
     name: z.string(),
@@ -37,15 +34,14 @@ class GroupsValidationError extends Error {
 /**
  * Validate that an update to internal groups doesn't remove the last admin.
  * Considers both internal Admins group members and bootstrap admins.
+ * @internal Exported for tests.
  */
 export const validateAdminGroupUpdate = (newGroups, bootstrapAdminIds) => {
-    // Find the Admins group in the new groups
     const adminsGroup = newGroups.find((g) => g.id === RESERVED_GROUPS.ADMINS);
     const adminMembersCount = adminsGroup?.members?.length ?? 0;
     // Total admins = internal Admins group members + bootstrap admins (excluding overlap)
     const internalAdmins = new Set(adminsGroup?.members ?? []);
     let totalAdmins = adminMembersCount;
-    // Add bootstrap admins that aren't already in the internal group
     for (const bootstrapId of bootstrapAdminIds) {
         if (!internalAdmins.has(bootstrapId)) {
             totalAdmins++;
@@ -61,12 +57,11 @@ export const validateAdminGroupUpdate = (newGroups, bootstrapAdminIds) => {
 };
 /**
  * Validate that reserved groups are not deleted or renamed.
+ * @internal Exported for tests.
  */
 export const validateReservedGroups = (newGroups) => {
-    // Check if any reserved group IDs have been altered
     for (const group of newGroups) {
         if (isReservedGroup(group.id)) {
-            // Reserved group exists - make sure the name matches the ID
             if (group.name !== group.id) {
                 return {
                     valid: false,
@@ -122,11 +117,10 @@ const updateInternalGroupsHandler = async (_gc, ctx, req, body) => {
             return { ok: false, status: result.status, error: result.error };
         }
         const { context, mode } = result;
-        // Load -> compare -> reconcile -> validate -> write all happen atomically
-        // under the cross-host layered lock (see
-        // authorization/settings-file-store.ts), against the mutator's own
-        // freshly-reloaded file — no separate pre-read here, so there's no
-        // TOCTOU window between the version/reconciliation checks and the write.
+        // Load -> compare -> reconcile -> validate -> write all happen atomically under the
+        // cross-host layered lock (see authorization/settings-file-store.ts), against the mutator's
+        // own freshly-reloaded file — no separate pre-read, so no TOCTOU window between the
+        // version/reconciliation checks and the write.
         await mutateGroupsFile(context.branchRoot, mode, (currentFile, version) => {
             if (body.expectedContentVersion !== undefined && body.expectedContentVersion !== version) {
                 throw new SettingsVersionConflictError('Groups were modified by another user. Please reload and try again.');
@@ -137,16 +131,13 @@ const updateInternalGroupsHandler = async (_gc, ctx, req, body) => {
             const existingById = new Set(existingGroups.map((g) => g.id));
             // Process groups: generate IDs for new groups, keep IDs for existing groups
             const processedGroups = body.groups.map((group) => {
-                // Existing group with valid ID - keep ID
                 if (group.id && group.id.trim() !== '' && existingById.has(group.id)) {
                     return group;
                 }
-                // Check if this is a reserved group (by ID or name)
                 if (isReservedGroup(group.id) || isReservedGroup(group.name)) {
                     // Reserved groups: ID = name (e.g., "Admins", "Reviewers")
                     return { ...group, id: group.name };
                 }
-                // New regular group (empty ID or not in existing set) - generate ID
                 return { ...group, id: generateId() };
             });
             // Validate no duplicate IDs
@@ -182,9 +173,8 @@ const updateInternalGroupsHandler = async (_gc, ctx, req, body) => {
                 groups: processedGroups,
             };
         });
-        // Commit and push (mode-aware). A push failure means the change is saved
-        // to the branch working tree but NOT durably persisted (API-H1) - surface
-        // that to the client instead of reporting a bare 200.
+        // A failed push is returned to the client as an error, never a bare 200 (see
+        // CommitSettingsResult in settings-helpers.ts).
         const commitResult = await commitSettings(ctx, {
             context,
             branchRoot: context.branchRoot,
@@ -239,9 +229,6 @@ const searchExternalGroupsHandler = async (_gc, ctx, req, params) => {
         };
     }
 };
-// ============================================================================
-// Route Definitions with defineEndpoint
-// ============================================================================
 /**
  * Get internal groups
  * GET /groups/internal

package/dist/api/guards.d.ts

@@ -1,26 +1,14 @@
 /**
- * Declarative guard system for API endpoints.
- *
- * Guards run before the handler and either:
- * - Return an error response (404, 403, 500) to short-circuit
- * - Produce a guard context (e.g., branch context with schema) for the handler
- *
- * Usage in defineEndpoint:
- * ```ts
- * defineEndpoint({
- *   guards: ['branchAccessWithSchema'] as const,
- *   handler: async (gc, ctx, req, params) => {
- *     // gc.branchContext is guaranteed non-null with flatSchema
- *   }
- * })
- * ```
+ * Declarative guard system for API endpoints: guards run before the handler and either return an
+ * error response (404/403/500) to short-circuit, or produce a guard context (e.g. branch context
+ * with schema) for the handler. See api/AGENTS.md for the full guard reference.
  */
 import type { BranchContext, BranchContextWithSchema } from '../types.js';
 import type { ApiContext, ApiRequest, ApiResponse } from './types.js';
 /** All available guard identifiers */
 export type GuardId = 'branch' | 'branchAccess' | 'schema' | 'branchAccessWithSchema' | 'admin' | 'reviewer' | 'privileged' | 'writableBranch' | 'submittableBranch';
 /** Maps each guard ID to the context it contributes */
-export interface GuardContextMap {
+interface GuardContextMap {
     branch: {
         branchContext: BranchContext;
     };

package/dist/api/guards.js

@@ -1,26 +1,10 @@
 /**
- * Declarative guard system for API endpoints.
- *
- * Guards run before the handler and either:
- * - Return an error response (404, 403, 500) to short-circuit
- * - Produce a guard context (e.g., branch context with schema) for the handler
- *
- * Usage in defineEndpoint:
- * ```ts
- * defineEndpoint({
- *   guards: ['branchAccessWithSchema'] as const,
- *   handler: async (gc, ctx, req, params) => {
- *     // gc.branchContext is guaranteed non-null with flatSchema
- *   }
- * })
- * ```
+ * Declarative guard system for API endpoints: guards run before the handler and either return an
+ * error response (404/403/500) to short-circuit, or produce a guard context (e.g. branch context
+ * with schema) for the handler. See api/AGENTS.md for the full guard reference.
  */
 import { isAdmin, isReviewer, isPrivileged } from '../authorization/helpers.js';
 import { getBranchProtection, getBranchWriteProtection } from '../authorization/protected-branch.js';
-// ============================================================================
-// Guard runner implementations
-// ============================================================================
-/** Extracts branch name from params, returning error response if missing */
 function extractBranchName(params) {
     const branch = params.branch;
     if (typeof branch !== 'string' || !branch) {
@@ -193,9 +177,6 @@ const runPrivilegedGuard = async (_ctx, req) => {
     }
     return { ok: true, context: {} };
 };
-// ============================================================================
-// Guard registry
-// ============================================================================
 const GUARD_RUNNERS = {
     branch: runBranchGuard,
     branchAccess: runBranchAccessGuard,

package/dist/api/index.d.ts

@@ -1,18 +1,18 @@
 export type { ApiResponse, ApiRequest, ApiContext } from './types.js';
 export type { BranchResponse, BranchListResponse, BranchDeleteResponse, CreateBranchBody, UpdateBranchAccessBody, } from './branch.js';
 export type { BranchMergeResponse } from './branch-merge.js';
-export type { CommentsResponse, AddCommentResponse, ResolveCommentResponse, ListCommentsResponse, } from './comments.js';
+export type { CommentsResponse, AddCommentResponse, ResolveCommentResponse } from './comments.js';
 export type { EntriesResponse, ListEntriesResponse, CollectionItem, ListEntriesParams, DeleteEntryResponse, } from './entries.js';
 export type { PermissionsResponse, UpdatePermissionsBody, SearchUsersParams, GetUserMetadataResponse, GetUserMetadataParams, } from './permissions.js';
 export type { UserInfoResponse } from './user.js';
-export type { AssetRecord, AssetsListResponse, PresignAssetResponse, PresignAssetBody, FinalizeAssetResponse, FinalizeAssetBody, AssetDeleteResponse, ListAssetsParams, DeleteAssetParams, } from './assets.js';
+export type { AssetRecord, AssetsListResponse, PresignAssetResponse, PresignAssetBody, FinalizeAssetResponse, FinalizeAssetBody, AssetDeleteResponse, } from './assets.js';
 export type { InternalGroupsResponse, ExternalGroupsResponse, UpdateInternalGroupsBody, SearchExternalGroupsParams, ExternalGroup, } from './groups.js';
 export type { ReferenceOptionsResponse } from './reference-options.js';
 export type { ResolveReferencesResponse } from './resolve-references.js';
-export type { SchemaResponse, WireEntryType, WireCollectionConfig, WireFlatSchemaItem, CollectionResponse, CreateCollectionResponse, UpdateCollectionResponse, DeleteCollectionResponse, AddEntryTypeResponse, UpdateEntryTypeResponse, RemoveEntryTypeResponse, UpdateOrderResponse, GetSchemaApiResponse, GetCollectionApiResponse, CreateCollectionApiResponse, UpdateCollectionApiResponse, DeleteCollectionApiResponse, AddEntryTypeApiResponse, UpdateEntryTypeApiResponse, RemoveEntryTypeApiResponse, UpdateOrderApiResponse, } from './schema.js';
+export type { GetSchemaApiResponse, GetCollectionApiResponse, CreateCollectionApiResponse, UpdateCollectionApiResponse, DeleteCollectionApiResponse, AddEntryTypeApiResponse, UpdateEntryTypeApiResponse, RemoveEntryTypeApiResponse, UpdateOrderApiResponse, } from './schema.js';
 export type { CreateCollectionInput, UpdateCollectionInput, CreateEntryTypeInput, UpdateEntryTypeInput, } from '../schema/schema-store-types.js';
 export type { EntryTypeSummary } from './entries.js';
-export type { AdminStatusResponse, AdminStatusData, AdminTasksResponse, AdminTasksData, ListAdminTasksParams, AdminRetryTaskResponse, AdminRetryTaskData, RetryTaskParams, AdminDeleteTaskResponse, AdminDeleteTaskData, DeleteTaskParams, WorkerLiveness, WorkerLivenessState, } from './admin.js';
+export type { AdminStatusResponse, AdminStatusData, AdminTasksResponse, AdminTasksData, ListAdminTasksParams, AdminRetryTaskResponse, AdminDeleteTaskResponse, DeleteTaskParams, WorkerLiveness, } from './admin.js';
 export { USER_ROUTES } from './user.js';
 export { CanopyApiClient, createApiClient } from './client.js';
 export type { ApiClientOptions } from './client.js';

package/dist/api/permissions.d.ts

@@ -143,7 +143,9 @@ declare const getUserMetadataParamsSchema: z.ZodObject<{
     userId: string;
 }>;
 export type UpdatePermissionsBody = z.infer<typeof updatePermissionsBodySchema>;
+/** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
 export type SearchUsersParams = z.infer<typeof searchUsersParamsSchema>;
+/** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
 export type GetUserMetadataParams = z.infer<typeof getUserMetadataParamsSchema>;
 /**
  * Exported routes for router registration

package/dist/api/permissions.js

@@ -5,9 +5,6 @@ import { MAX_ENTRIES_PER_PAGE } from './entries-constants.js';
 import { defineEndpoint } from './route-builder.js';
 import { getSettingsBranchContext, commitSettings } from './settings-helpers.js';
 import { getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
-// ============================================================================
-// Zod Schemas for Validation
-// ============================================================================
 const permissionTargetSchema = z.object({
     allowedUsers: z.array(z.string()).optional(),
     allowedGroups: z.array(z.string()).optional(),
@@ -24,18 +21,14 @@ const updatePermissionsBodySchema = z.object({
 });
 const searchUsersParamsSchema = z.object({
     q: z.string(),
-    // Coerced + range-checked (consistent with api/entries.ts's listEntriesParamsSchema)
-    // rather than z.string() + an unchecked parseInt(), which silently produced NaN
-    // for a non-numeric limit (API-M2). Capped like listEntries so a caller cannot
-    // request an unbounded page from the auth provider.
+    // Coerced + range-checked, not z.string() + an unchecked parseInt() (which silently produced
+    // NaN for a non-numeric limit): capped like entries.ts's listEntriesParamsSchema so a caller
+    // can't request an unbounded page from the auth provider.
     limit: z.coerce.number().int().min(1).max(MAX_ENTRIES_PER_PAGE).optional(),
 });
 const getUserMetadataParamsSchema = z.object({
     userId: z.string(),
 });
-/**
- * Get current permissions (admin only)
- */
 const getPermissionsHandler = async (_gc, ctx, _req) => {
     try {
         const result = await getSettingsBranchContext(ctx);
@@ -58,9 +51,6 @@ const getPermissionsHandler = async (_gc, ctx, _req) => {
         };
     }
 };
-/**
- * Update permissions (admin only)
- */
 const updatePermissionsHandler = async (_gc, ctx, req, body) => {
     if (!body?.permissions) {
         return { ok: false, status: 400, error: 'permissions array required' };
@@ -85,9 +75,8 @@ const updatePermissionsHandler = async (_gc, ctx, req, body) => {
                 pathPermissions: body.permissions,
             };
         });
-        // Commit and push (mode-aware). A push failure means the change is saved
-        // to the branch working tree but NOT durably persisted (API-H1) - surface
-        // that to the client instead of reporting a bare 200.
+        // Commit and push (mode-aware): a push failure means the change is saved to the branch
+        // working tree but NOT durably persisted — surface that to the client, not a bare 200.
         const commitResult = await commitSettings(ctx, {
             context,
             branchRoot: context.branchRoot,
@@ -141,18 +130,13 @@ const searchUsersHandler = async (_gc, ctx, req, params) => {
     }
 };
 /**
- * List groups (for permission UI)
- *
- * Merges BOTH group universes, because both are valid `allowedGroups` targets:
- * the auth provider's groups and Canopy's own internal groups from groups.json
- * (see PermissionGroupOption in auth/types.ts). Feeding this endpoint from the
- * auth plugin alone made internally-created groups unreachable from the
- * Permission Manager's picker -- they could only be granted a path permission
- * by hand-editing permissions.json.
+ * List groups (for permission UI). Merges BOTH group universes — the auth provider's and
+ * Canopy's own internal groups from groups.json (see PermissionGroupOption in auth/types.ts) —
+ * since both are valid `allowedGroups` targets.
  *
- * Internal entries are name-only (no members, no memberCount): this endpoint is
- * `privileged` (admin or reviewer) whereas `groups.getInternal` is admin-only,
- * so member identities and counts must not leak through here.
+ * Internal entries are name-only (no members, no memberCount): this endpoint is `privileged`
+ * (admin or reviewer) whereas `groups.getInternal` is admin-only, so member identities and
+ * counts must not leak through here.
  */
 const listGroupsHandler = async (_gc, ctx, _req) => {
     const authPlugin = ctx.authPlugin;
@@ -168,13 +152,11 @@ const listGroupsHandler = async (_gc, ctx, _req) => {
         const { context, mode } = result;
         const file = await loadGroupsFile(context.branchRoot, mode);
         const internalGroups = deriveInternalGroups(file?.groups ?? [], ctx.services.bootstrapAdminIds);
-        // Deduplicate by ID, internal first so it wins a collision. The two ID
-        // spaces are not namespaced against each other, but `checkPathPermission`
-        // matches `allowedGroups` by ID string against one flattened `user.groups`
-        // list -- so two same-ID groups ARE a single permission target, and
-        // emitting both would misrepresent what enforcement actually does.
-        // (Reserved IDs can never arrive from the provider: stripReservedGroups in
-        // user.ts removes them before they reach `user.groups`.)
+        // Deduplicate by ID, internal first so it wins a collision: the two ID spaces aren't
+        // namespaced against each other, but `checkPathPermission` matches `allowedGroups` by ID
+        // string against one flattened `user.groups` list, so two same-ID groups ARE a single
+        // permission target — emitting both would misrepresent enforcement. (Reserved IDs never
+        // arrive from the provider: stripReservedGroups in user.ts removes them first.)
         const byId = new Map();
         for (const group of internalGroups) {
             byId.set(group.id, {
@@ -187,9 +169,8 @@ const listGroupsHandler = async (_gc, ctx, _req) => {
         for (const group of externalGroups) {
             const collision = byId.get(group.id);
             if (collision) {
-                // Keep the internal entry, but record that granting this ID ALSO
-                // reaches the provider group's membership -- the picker surfaces that
-                // so an admin isn't shown a name-and-members set narrower than the
+                // Keep the internal entry, but record that granting this ID ALSO reaches the provider
+                // group's membership, so the picker doesn't show an admin a narrower set than the
                 // grant's real reach.
                 collision.source = 'both';
                 continue;
@@ -228,9 +209,6 @@ const getUserMetadataHandler = async (_gc, ctx, req, params) => {
         };
     }
 };
-// ============================================================================
-// Route Definitions with defineEndpoint
-// ============================================================================
 /**
  * Get current permissions (admin only)
  * GET /permissions

package/dist/api/reference-options.d.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
-/** Response type for reference options */
 export type ReferenceOptionsResponse = ApiResponse<{
     options: Array<{
         id: string;

package/dist/api/reference-options.js

@@ -4,9 +4,6 @@ import { defineEndpoint } from './route-builder.js';
 import { ReferenceResolver } from '../reference-resolver.js';
 import { parseLogicalPath } from '../paths/index.js';
 import { branchNameSchema } from './validators.js';
-// ============================================================================
-// Zod Schemas for Validation
-// ============================================================================
 const getReferenceOptionsParamsSchema = z.object({
     branch: branchNameSchema,
 });
@@ -68,11 +65,9 @@ const getReferenceOptionsHandler = async (gc, ctx, req, _params) => {
             .map((t) => t.trim())
             .filter(Boolean)
         : undefined;
-    // Build the access checker once (permissions loaded a single time, reused for
-    // every candidate) and pass it into loadReferenceOptions as a filter *before*
-    // loading: a denied path is skipped outright, so it never triggers the
-    // store.read() that loadReferenceOptions would otherwise do just to compute a
-    // label for an option the caller isn't allowed to see.
+    // Build the access checker once and pass it in as a filter *before* loading: a denied path is
+    // skipped outright, so it never triggers the store.read() that would otherwise compute a label
+    // for an option the caller isn't allowed to see.
     const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
     const resolver = new ReferenceResolver(store, idIndex);
     const options = await resolver.loadReferenceOptions(collections, displayField, search, entryTypes, (relativePath) => checkAccess(relativePath, 'read').allowed);
@@ -82,9 +77,6 @@ const getReferenceOptionsHandler = async (gc, ctx, req, _params) => {
         data: { options },
     };
 };
-// ============================================================================
-// Route Definitions
-// ============================================================================
 /**
  * Get reference options for a field
  * GET /:branch/reference-options