canopycms 0.0.68-int.110 → 0.0.68-int.112

package/dist/api/admin-branch-health.d.ts

@@ -13,9 +13,26 @@ import { z } from 'zod';
 import type { BranchAccessControl, BranchMetadata, BranchStatus } from '../types.js';
 import { type BranchHealthEntry } from '../branch-health.js';
 import type { ApiResponse } from './types.js';
+/**
+ * Wall-clock budget the opt-in duplicate-ID scan shares across every healthy
+ * branch: well inside the CMS Lambda's default 60 s timeout
+ * (`DEFAULT_CMS_LAMBDA_TIMEOUT` in canopycms-cdk), leaving the rest of the
+ * request its headroom.
+ * @internal Exported for tests.
+ */
+export declare const DUPLICATE_ID_SCAN_BUDGET_MS = 20000;
 export interface BranchHealthData {
     entries: BranchHealthEntry[];
     generatedAt: string;
+    /**
+     * Present only when the request asked for the duplicate-ID scan. `truncated`
+     * is true when the budget ran out before every healthy branch was scanned;
+     * those branches report `duplicateIdScan.state === 'unknown'`.
+     */
+    duplicateIdScan?: {
+        budgetMs: number;
+        truncated: boolean;
+    };
 }
 /** Response type for GET /admin/branch-health */
 export type BranchHealthResponse = ApiResponse<BranchHealthData>;
@@ -65,7 +82,13 @@ export type RepairContentDuplicatesResponse = ApiResponse<RepairContentDuplicate
  * router/generate-client import.
  */
 export declare const ADMIN_BRANCH_HEALTH_ROUTES: {
-    readonly branchHealth: import("./route-builder.js").RouteDefinition<undefined, undefined, BranchHealthResponse>;
+    readonly branchHealth: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        duplicates: z.ZodOptional<z.ZodLiteral<"1">>;
+    }, "strip", z.ZodTypeAny, {
+        duplicates?: "1" | undefined;
+    }, {
+        duplicates?: "1" | undefined;
+    }>, undefined, BranchHealthResponse>;
     readonly purgeBranchDir: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         dirName: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
     }, "strip", z.ZodTypeAny, {

package/dist/api/admin-branch-health.js

@@ -30,6 +30,14 @@ import { defineEndpoint } from './route-builder.js';
 import { baseBranchOf } from '../utils/base-branch.js';
 /** [H1] A fresh (< 5 min old) init lock blocks purge -- provisioning may be running. */
 const PROVISIONING_LOCK_FRESH_MS = 5 * 60_000;
+/**
+ * Wall-clock budget the opt-in duplicate-ID scan shares across every healthy
+ * branch: well inside the CMS Lambda's default 60 s timeout
+ * (`DEFAULT_CMS_LAMBDA_TIMEOUT` in canopycms-cdk), leaving the rest of the
+ * request its headroom.
+ * @internal Exported for tests.
+ */
+export const DUPLICATE_ID_SCAN_BUDGET_MS = 20_000;
 // Mirrors deleteTaskHandler's fileName pattern in admin.ts: conservative
 // charset plus explicit traversal/dot-prefix refinements (the regex alone
 // technically excludes '/' already, but the refinements keep intent explicit
@@ -40,6 +48,11 @@ const dirNameSchema = z
     .refine((v) => !v.includes('..'), { message: 'dirName must not contain ..' })
     .refine((v) => !v.startsWith('.'), { message: 'dirName must not be dot-prefixed' });
 const branchDirParamsSchema = z.object({ dirName: dirNameSchema });
+/**
+ * `duplicates=1` opts in to the duplicate-ID scan, a full content-tree readdir
+ * per healthy branch. The panel's 30 s poll leaves it off.
+ */
+const branchHealthParamsSchema = z.object({ duplicates: z.literal('1').optional() });
 /**
  * Re-resolve dirName under baseRoot and enforce containment (belt-and-
  * suspenders on top of the zod regex, matching deleteTaskHandler's pattern
@@ -61,19 +74,31 @@ class RepairPreconditionError extends Error {
         this.status = status;
     }
 }
-const getBranchHealthHandler = async (_gc, ctx, _req) => {
+const getBranchHealthHandler = async (_gc, ctx, _req, params) => {
     // Same derivation services.ts uses to construct the BranchRegistry --
     // admin handlers must agree with it or the scan silently looks at the
     // wrong directory.
     const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
     const baseBranchName = baseBranchOf(ctx.services.config);
     const contentRootName = ctx.services.config.contentRoot || 'content';
+    const scanDuplicates = params.duplicates === '1';
     try {
-        const entries = await scanBranchHealth(baseRoot, { baseBranchName, contentRootName });
+        const entries = await scanBranchHealth(baseRoot, {
+            baseBranchName,
+            contentRootName,
+            ...(scanDuplicates ? { duplicateIdScan: { budgetMs: DUPLICATE_ID_SCAN_BUDGET_MS } } : {}),
+        });
+        const truncated = entries.some((e) => e.duplicateIdScan?.state === 'unknown' && e.duplicateIdScan.reason === 'out-of-time');
         return {
             ok: true,
             status: 200,
-            data: { entries, generatedAt: new Date().toISOString() },
+            data: {
+                entries,
+                generatedAt: new Date().toISOString(),
+                ...(scanDuplicates
+                    ? { duplicateIdScan: { budgetMs: DUPLICATE_ID_SCAN_BUDGET_MS, truncated } }
+                    : {}),
+            },
         };
     }
     catch (err) {
@@ -496,13 +521,15 @@ const repairContentDuplicatesHandler = async (_gc, ctx, req, params) => {
     }
 };
 /**
- * Branch directory health scan (healthy/corrupt-metadata/orphan)
+ * Branch directory health scan (healthy/corrupt-metadata/orphan); `duplicates=1`
+ * adds the bounded duplicate-ID scan
  */
 const getBranchHealth = defineEndpoint({
     namespace: 'admin',
     name: 'branchHealth',
     method: 'GET',
     path: '/admin/branch-health',
+    params: branchHealthParamsSchema,
     responseType: 'BranchHealthResponse',
     response: {},
     defaultMockData: { entries: [], generatedAt: '2024-01-01T00:00:00.000Z' },

package/dist/api/admin.d.ts

@@ -105,7 +105,13 @@ export type DeleteTaskParams = z.infer<typeof deleteTaskParamsSchema>;
  * `ADMIN_ROUTES` import.
  */
 export declare const ADMIN_ROUTES: {
-    readonly branchHealth: import("./route-builder.js").RouteDefinition<undefined, undefined, import("./admin-branch-health.js").BranchHealthResponse>;
+    readonly branchHealth: import("./route-builder.js").RouteDefinition<z.ZodObject<{
+        duplicates: z.ZodOptional<z.ZodLiteral<"1">>;
+    }, "strip", z.ZodTypeAny, {
+        duplicates?: "1" | undefined;
+    }, {
+        duplicates?: "1" | undefined;
+    }>, undefined, import("./admin-branch-health.js").BranchHealthResponse>;
     readonly purgeBranchDir: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         dirName: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
     }, "strip", z.ZodTypeAny, {

package/dist/api/client.d.ts

@@ -5,6 +5,7 @@
  * AUTO-GENERATED by scripts/generate-client.ts; do not edit this file manually
  * (changes will be overwritten), edit the generator's templates instead.
  */
+import type { OperatingMode } from '../operating-mode/types.js';
 import type { BranchDeleteResponse, BranchListItemResponse, BranchListResponse, BranchResponse, CreateBranchBody, UpdateBranchAccessBody } from './branch.js';
 import type { BranchMergeResponse } from './branch-status.js';
 import type { AddCommentBody, AddCommentResponse, CommentsResponse, ResolveCommentResponse } from './comments.js';
@@ -13,7 +14,7 @@ import type { ReferenceOptionsResponse } from './reference-options.js';
 import type { ResolveReferencesBody, ResolveReferencesResponse } from './resolve-references.js';
 import type { DeleteEntryResponse, EntriesResponse } from './entries.js';
 import type { AssetDeleteResponse, AssetsListResponse, FinalizeAssetBody, FinalizeAssetResponse, PresignAssetBody, PresignAssetResponse } from './assets.js';
-import type { GetUserMetadataResponse, ListGroupsResponse, PermissionsResponse, SearchUsersResponse, UpdatePermissionsBody } from './permissions.js';
+import type { BatchGetUserMetadataBody, BatchGetUserMetadataResponse, GetUserMetadataResponse, ListGroupsResponse, PermissionsResponse, SearchUsersResponse, UpdatePermissionsBody } from './permissions.js';
 import type { ExternalGroupsResponse, InternalGroupsResponse, UpdateInternalGroupsBody, UpdateInternalGroupsResponse } from './groups.js';
 import type { UserInfoResponse } from './user.js';
 import type { AddEntryTypeApiResponse, CreateCollectionApiResponse, DeleteCollectionApiResponse, GetCollectionApiResponse, GetSchemaApiResponse, InvalidateSchemaCacheApiResponse, RemoveEntryTypeApiResponse, UpdateCollectionApiResponse, UpdateEntryTypeApiResponse, UpdateOrderApiResponse, UpdateOrderBody } from './schema.js';
@@ -37,6 +38,15 @@ export interface ApiClientOptions {
      * notification, not a retry; the editor's auth gate uses it to show sign-in.
      */
     onUnauthorized?: () => void;
+    /**
+     * The mode this bundle was built for, sent on every request so the server refuses a bundle built
+     * for the other mode (operating-mode/editor-mode-check.ts). Set by the editor from
+     * `config.mode`; a client without it is not checked.
+     * @internal
+     */
+    editorMode?: OperatingMode;
+    /** Called whenever the server refuses `editorMode` (code `EDITOR_MODE_MISMATCH`). @internal */
+    onEditorModeMismatch?: () => void;
 }
 /**
  * Typed client for the CanopyCMS API: one method per endpoint, grouped by namespace, each
@@ -53,6 +63,8 @@ export declare class CanopyApiClient {
     private fetchFn;
     private trailingSlash;
     private onUnauthorized;
+    private editorMode;
+    private onEditorModeMismatch;
     readonly branches: {
         /** GET /branches */
         list: () => Promise<BranchListResponse>;
@@ -130,6 +142,8 @@ export declare class CanopyApiClient {
         listGroups: () => Promise<ListGroupsResponse>;
         /** GET /users/:userId */
         getUserMetadata: (params: Record<string, string>) => Promise<GetUserMetadataResponse>;
+        /** POST /users/batch */
+        batchGetUserMetadata: (body: BatchGetUserMetadataBody) => Promise<BatchGetUserMetadataResponse>;
     };
     readonly groups: {
         /** GET /groups/internal */
@@ -167,7 +181,7 @@ export declare class CanopyApiClient {
     };
     readonly admin: {
         /** GET /admin/branch-health */
-        branchHealth: () => Promise<BranchHealthResponse>;
+        branchHealth: (params: Record<string, string>) => Promise<BranchHealthResponse>;
         /** POST /admin/branch-dirs/:dirName/purge */
         purgeBranchDir: (params: Record<string, string>) => Promise<PurgeBranchDirResponse>;
         /** POST /admin/branch-dirs/:dirName/repair-metadata */

package/dist/api/client.js

@@ -7,6 +7,7 @@
  */
 import { computeContentSha256Hex } from './request-body-hash.js';
 import { readTrailingSlashEnv, withTrailingSlash } from '../utils/url-prefix.js';
+import { EDITOR_MODE_HEADER, EDITOR_MODE_MISMATCH_STATUS } from '../operating-mode/editor-mode-check.js';
 /**
  * Typed client for the CanopyCMS API: one method per endpoint, grouped by namespace, each
  * returning that endpoint's ApiResponse.
@@ -161,6 +162,10 @@ export class CanopyApiClient {
             getUserMetadata: (params) => {
                 return this.request('GET', this.buildPath('/users/:userId', params));
             },
+            /** POST /users/batch */
+            batchGetUserMetadata: (body) => {
+                return this.request('POST', '/users/batch', body);
+            },
         };
         this.groups = {
             /** GET /groups/internal */
@@ -226,8 +231,8 @@ export class CanopyApiClient {
         };
         this.admin = {
             /** GET /admin/branch-health */
-            branchHealth: () => {
-                return this.request('GET', '/admin/branch-health');
+            branchHealth: (params) => {
+                return this.request('GET', this.buildPath('/admin/branch-health', params));
             },
             /** POST /admin/branch-dirs/:dirName/purge */
             purgeBranchDir: (params) => {
@@ -263,6 +268,8 @@ export class CanopyApiClient {
         this.fetchFn = options.fetch ?? (typeof window !== 'undefined' ? fetch.bind(window) : fetch);
         this.trailingSlash = options.trailingSlash ?? readTrailingSlashEnv();
         this.onUnauthorized = options.onUnauthorized;
+        this.editorMode = options.editorMode;
+        this.onEditorModeMismatch = options.onEditorModeMismatch;
     }
     buildPath(template, params) {
         let result = template;
@@ -298,6 +305,8 @@ export class CanopyApiClient {
         const requestHeaders = {
             ...headers,
         };
+        if (this.editorMode)
+            requestHeaders[EDITOR_MODE_HEADER] = this.editorMode;
         let requestBody;
         if (body !== undefined) {
             if (body instanceof FormData) {
@@ -346,6 +355,11 @@ export class CanopyApiClient {
             this.onUnauthorized?.();
             return { ok: false, status: 401, error: errorFromBody(parsed) ?? 'Unauthorized' };
         }
+        if (isApiResponseBody(parsed) &&
+            parsed.status === EDITOR_MODE_MISMATCH_STATUS &&
+            parsed.code === 'EDITOR_MODE_MISMATCH') {
+            this.onEditorModeMismatch?.();
+        }
         if (isApiResponseBody(parsed))
             return parsed;
         const converted = {

package/dist/api/permissions.d.ts

@@ -19,6 +19,10 @@ export type ListGroupsResponse = ApiResponse<{
 export type GetUserMetadataResponse = ApiResponse<{
     user: UserSearchResult | null;
 }>;
+/** Response type for batch user metadata: the users found, in no guaranteed order; unknown ids are absent */
+export type BatchGetUserMetadataResponse = ApiResponse<{
+    users: UserSearchResult[];
+}>;
 declare const updatePermissionsBodySchema: z.ZodObject<{
     permissions: z.ZodArray<z.ZodObject<{
         path: z.ZodType<import("../authorization/index.js").PermissionPath, z.ZodTypeDef, import("../authorization/index.js").PermissionPath>;
@@ -142,9 +146,17 @@ declare const getUserMetadataParamsSchema: z.ZodObject<{
 }, {
     userId: string;
 }>;
+declare const batchGetUserMetadataBodySchema: z.ZodObject<{
+    userIds: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    userIds: string[];
+}, {
+    userIds: 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>;
+export type BatchGetUserMetadataBody = z.infer<typeof batchGetUserMetadataBodySchema>;
 /** @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md. */
 export type GetUserMetadataParams = z.infer<typeof getUserMetadataParamsSchema>;
 /**
@@ -276,5 +288,12 @@ export declare const PERMISSION_ROUTES: {
     }, {
         userId: string;
     }>, undefined, GetUserMetadataResponse>;
+    readonly batchGetUserMetadata: import("./route-builder.js").RouteDefinition<undefined, z.ZodObject<{
+        userIds: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        userIds: string[];
+    }, {
+        userIds: string[];
+    }>, BatchGetUserMetadataResponse>;
 };
 export {};

package/dist/api/permissions.js

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { loadPermissionsFile, mutatePermissionsFile, loadGroupsFile, deriveInternalGroups, SettingsVersionConflictError, SettingsFileConflictError, } from '../authorization/index.js';
 import { permissionPathSchema } from './validators.js';
 import { MAX_ENTRIES_PER_PAGE } from './entries-constants.js';
+import { MAX_USER_METADATA_BATCH } from './users-constants.js';
+import { lookupUsersMetadata } from '../auth/user-metadata-lookup.js';
 import { defineEndpoint } from './route-builder.js';
 import { getSettingsBranchContext, commitSettings } from './settings-helpers.js';
 import { getErrorMessage, sanitizeErrorMessage } from '../utils/error.js';
@@ -29,6 +31,10 @@ const searchUsersParamsSchema = z.object({
 const getUserMetadataParamsSchema = z.object({
     userId: z.string(),
 });
+const userIdSchema = z.string().min(1).max(256);
+const batchGetUserMetadataBodySchema = z.object({
+    userIds: z.array(userIdSchema).min(1).max(MAX_USER_METADATA_BATCH),
+});
 const getPermissionsHandler = async (_gc, ctx, _req) => {
     try {
         const result = await getSettingsBranchContext(ctx);
@@ -199,8 +205,29 @@ const getUserMetadataHandler = async (_gc, ctx, req, params) => {
         return { ok: false, status: 501, error: 'Auth plugin not configured' };
     }
     try {
-        const user = await authPlugin.getUserMetadata(params.userId);
-        return { ok: true, status: 200, data: { user } };
+        const users = await lookupUsersMetadata(authPlugin, [params.userId]);
+        return { ok: true, status: 200, data: { user: users.get(params.userId) ?? null } };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: 500,
+            error: sanitizeErrorMessage(getErrorMessage(error)),
+        };
+    }
+};
+/**
+ * Get metadata for many users at once (for UI display)
+ */
+const batchGetUserMetadataHandler = async (_gc, ctx, _req, body) => {
+    const authPlugin = ctx.authPlugin;
+    if (!authPlugin) {
+        return { ok: false, status: 501, error: 'Auth plugin not configured' };
+    }
+    try {
+        const found = await lookupUsersMetadata(authPlugin, body.userIds);
+        const users = [...found.values()].filter((user) => user !== null);
+        return { ok: true, status: 200, data: { users } };
     }
     catch (error) {
         return {
@@ -289,6 +316,23 @@ const getUserMetadata = defineEndpoint({
     guards: ['privileged'],
     handler: getUserMetadataHandler,
 });
+/**
+ * Get metadata for up to MAX_USER_METADATA_BATCH users (admin/reviewer only)
+ * POST /users/batch
+ */
+const batchGetUserMetadata = defineEndpoint({
+    namespace: 'permissions',
+    name: 'batchGetUserMetadata',
+    method: 'POST',
+    path: '/users/batch',
+    body: batchGetUserMetadataBodySchema,
+    bodyType: 'BatchGetUserMetadataBody',
+    responseType: 'BatchGetUserMetadataResponse',
+    response: {},
+    defaultMockData: { users: [] },
+    guards: ['privileged'],
+    handler: batchGetUserMetadataHandler,
+});
 /**
  * Exported routes for router registration
  */
@@ -298,4 +342,5 @@ export const PERMISSION_ROUTES = {
     searchUsers: searchUsers,
     listGroups: listGroups,
     getUserMetadata: getUserMetadata,
+    batchGetUserMetadata: batchGetUserMetadata,
 };

package/dist/api/types.d.ts

@@ -57,5 +57,7 @@ export interface ApiResponse<TData = unknown> {
  * failed, so a retry will not help until an admin fixes it (a 503 with no `Retry-After`).
  * `WRITE_OUTCOME_UNKNOWN`: an entry save ran but lost its branch lock mid-write, so it may have
  * landed (a 409); the version the caller holds may be stale, so it must re-read before retrying.
+ * `EDITOR_MODE_MISMATCH`: the editor bundle was built for the other operating mode than the
+ * server runs (a 412, see operating-mode/editor-mode-check.ts); only a rebuild fixes it.
  */
-export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED' | 'WRITE_OUTCOME_UNKNOWN';
+export type ApiErrorCode = 'SCHEMA_UNAVAILABLE' | 'WORKER_FAILED' | 'WRITE_OUTCOME_UNKNOWN' | 'EDITOR_MODE_MISMATCH';

package/dist/api/users-constants.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Constants the user endpoints share with the editor, kept dependency-free so the editor's
+ * browser bundle can import them without pulling in `permissions.ts` and its server-only deps.
+ */
+/** Most user ids one `POST /users/batch` request may carry; the editor splits larger sets. */
+export declare const MAX_USER_METADATA_BATCH = 100;

package/dist/api/users-constants.js

@@ -0,0 +1,6 @@
+/**
+ * Constants the user endpoints share with the editor, kept dependency-free so the editor's
+ * browser bundle can import them without pulling in `permissions.ts` and its server-only deps.
+ */
+/** Most user ids one `POST /users/batch` request may carry; the editor splits larger sets. */
+export const MAX_USER_METADATA_BATCH = 100;

package/dist/auth/caching-auth-plugin.d.ts

@@ -38,6 +38,8 @@ export declare class CachingAuthPlugin implements AuthPlugin {
     authenticate(context: unknown): Promise<AuthenticationResult>;
     searchUsers(query: string, limit?: number): Promise<UserSearchResult[]>;
     getUserMetadata(userId: CanopyUserId): Promise<UserSearchResult | null>;
+    /** One cache read for the whole set, where `getUserMetadata` per id re-stats the files each time. */
+    getUsersMetadata(userIds: CanopyUserId[]): Promise<UserSearchResult[]>;
     getGroupMetadata(groupId: CanopyGroupId): Promise<GroupMetadata | null>;
     listGroups(limit?: number): Promise<GroupMetadata[]>;
 }

package/dist/auth/caching-auth-plugin.js

@@ -88,6 +88,16 @@ export class CachingAuthPlugin {
             return null;
         }
     }
+    /** One cache read for the whole set, where `getUserMetadata` per id re-stats the files each time. */
+    async getUsersMetadata(userIds) {
+        try {
+            const wanted = new Set(userIds);
+            return (await this.cache.getAllUsers()).filter((u) => wanted.has(u.id));
+        }
+        catch {
+            return [];
+        }
+    }
     async getGroupMetadata(groupId) {
         try {
             return await this.cache.getGroup(groupId);

package/dist/auth/plugin.d.ts

@@ -23,6 +23,15 @@ export interface AuthPlugin {
     /** For the permission-management UI. */
     searchUsers(query: string, limit?: number): Promise<UserSearchResult[]>;
     getUserMetadata(userId: CanopyUserId): Promise<UserSearchResult | null>;
+    /**
+     * Looks up many users in as few provider calls as possible, resolving to the users found, in
+     * any order; unknown ids are omitted. Core never passes more than 100 ids at once. Without
+     * it, core falls back to concurrent `getUserMetadata` calls, a few at a time.
+     *
+     * Reject on a provider failure rather than omitting ids: core caches an omitted id as unknown,
+     * as it does a `null` from the `getUserMetadata` fallback.
+     */
+    getUsersMetadata?(userIds: CanopyUserId[]): Promise<UserSearchResult[]>;
     getGroupMetadata(groupId: CanopyGroupId): Promise<GroupMetadata | null>;
     /** For permission UI dropdowns. */
     listGroups(limit?: number): Promise<GroupMetadata[]>;

package/dist/auth/user-metadata-lookup.d.ts

@@ -0,0 +1,15 @@
+import type { AuthPlugin } from './plugin.js';
+import type { UserSearchResult } from './types.js';
+import type { CanopyUserId } from '../types.js';
+/**
+ * How long a looked-up user, or the fact that an id is unknown, is served without asking again.
+ * @internal Exported for tests.
+ */
+export declare const USER_METADATA_TTL_MS: number;
+/**
+ * Resolves each id to its user, or `null` when the provider does not know it. Unknown ids are
+ * cached like found ones, so a stale id in permissions.json costs a process one provider call
+ * per TTL. A rejection caches nothing; a `getUserMetadata` that answers `null` on failure is
+ * cached as unknown.
+ */
+export declare function lookupUsersMetadata(plugin: AuthPlugin, userIds: readonly CanopyUserId[]): Promise<Map<CanopyUserId, UserSearchResult | null>>;

package/dist/auth/user-metadata-lookup.js

@@ -0,0 +1,78 @@
+import { LRUCache } from 'lru-cache';
+import { CachingAuthPlugin } from './caching-auth-plugin.js';
+import { MAX_USER_METADATA_BATCH } from '../api/users-constants.js';
+/**
+ * How long a looked-up user, or the fact that an id is unknown, is served without asking again.
+ * @internal Exported for tests.
+ */
+export const USER_METADATA_TTL_MS = 5 * 60 * 1000;
+const MAX_CACHED_USERS = 5000;
+/** Concurrent `getUserMetadata` calls for a plugin without `getUsersMetadata`. */
+const SINGLE_LOOKUP_CONCURRENCY = 8;
+/**
+ * Per-process, in-memory, never persisted: each process keeps its own copy, so a changed name or
+ * avatar shows everywhere within one TTL. Keyed by plugin so two plugins never share answers.
+ */
+const caches = new WeakMap();
+function cacheFor(plugin) {
+    let cache = caches.get(plugin);
+    if (!cache) {
+        cache = new LRUCache({ max: MAX_CACHED_USERS, ttl: USER_METADATA_TTL_MS });
+        caches.set(plugin, cache);
+    }
+    return cache;
+}
+/**
+ * Resolves each id to its user, or `null` when the provider does not know it. Unknown ids are
+ * cached like found ones, so a stale id in permissions.json costs a process one provider call
+ * per TTL. A rejection caches nothing; a `getUserMetadata` that answers `null` on failure is
+ * cached as unknown.
+ */
+export async function lookupUsersMetadata(plugin, userIds) {
+    const unique = [...new Set(userIds)];
+    // Answered from an in-memory copy of the worker-written file cache; a TTL on top would only
+    // delay the worker's refreshes. canopycms-next wraps every plugin with `verifyTokenOnly`.
+    if (plugin instanceof CachingAuthPlugin)
+        return fetchFromPlugin(plugin, unique);
+    const cache = cacheFor(plugin);
+    const result = new Map();
+    const missing = [];
+    for (const id of unique) {
+        const hit = cache.get(id);
+        if (hit)
+            result.set(id, hit.user);
+        else
+            missing.push(id);
+    }
+    if (missing.length === 0)
+        return result;
+    const fetched = await fetchFromPlugin(plugin, missing);
+    for (const [id, user] of fetched) {
+        cache.set(id, { user });
+        result.set(id, user);
+    }
+    return result;
+}
+async function fetchFromPlugin(plugin, ids) {
+    const result = new Map(ids.map((id) => [id, null]));
+    const getUsersMetadata = plugin.getUsersMetadata?.bind(plugin);
+    if (getUsersMetadata) {
+        for (let i = 0; i < ids.length; i += MAX_USER_METADATA_BATCH) {
+            const users = await getUsersMetadata(ids.slice(i, i + MAX_USER_METADATA_BATCH));
+            // A provider answering for an id nobody asked about must not plant it in the cache.
+            for (const user of users)
+                if (result.has(user.id))
+                    result.set(user.id, user);
+        }
+        return result;
+    }
+    let next = 0;
+    const worker = async () => {
+        while (next < ids.length) {
+            const id = ids[next++];
+            result.set(id, await plugin.getUserMetadata(id));
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(SINGLE_LOOKUP_CONCURRENCY, ids.length) }, worker));
+    return result;
+}

package/dist/branch-health.d.ts

@@ -19,6 +19,20 @@ type BranchHealthKind = 'healthy' | 'corrupt-metadata' | 'orphan';
  * worker does not quarantine it. Corrupt-metadata dirs are exempt.
  */
 export declare const ORPHAN_YOUTH_THRESHOLD_MS: number;
+/**
+ * One healthy branch's duplicate-content-ID scan (see content-id-index.ts).
+ * `unknown` means the scan did not finish — it failed, or the request's time
+ * budget ran out first — and must never be read as `none`.
+ */
+export type DuplicateIdScan = {
+    state: 'none';
+} | {
+    state: 'found';
+    duplicates: DuplicateContentId[];
+} | {
+    state: 'unknown';
+    reason: 'failed' | 'out-of-time';
+};
 export interface BranchHealthEntry {
     dirName: string;
     kind: BranchHealthKind;
@@ -27,19 +41,19 @@ export interface BranchHealthEntry {
     /** healthy only */
     branch?: BranchMetadata;
     /**
-     * healthy only, non-empty only: duplicate content IDs in this branch's
-     * content tree (see content-id-index.ts). The branch stays usable — only the
-     * quarantined IDs degrade, dropping out of ID-based lookups and refusing
-     * saves (`DuplicateContentIdError`, a 409 naming the repair action) rather
-     * than mutating an ambiguous target.
+     * healthy only, and only when the caller asked for the duplicate-ID scan: see
+     * {@link DuplicateIdScan}. The branch stays usable while IDs are duplicated —
+     * only the quarantined IDs degrade, dropping out of ID-based lookups and
+     * refusing saves (`DuplicateContentIdError`) rather than mutating an
+     * ambiguous target.
      */
-    duplicateContentIds?: DuplicateContentId[];
+    duplicateIdScan?: DuplicateIdScan;
     /**
      * healthy only, true only: this clone has an interrupted rebase on disk
      * (`.git/rebase-merge` / `.git/rebase-apply`).
      *
      * Advisory on `healthy` rather than its own `BranchHealthKind`, like
-     * `duplicateContentIds`: the metadata is intact and the state is usually
+     * `duplicateIdScan`: the metadata is intact and the state is usually
      * transient, since the worker's sync loop aborts an interrupted rebase at the
      * top of its next per-branch pass. The flag buys visibility in the window
      * before that, where the branch otherwise scans as plain `healthy` while
@@ -80,9 +94,16 @@ export interface BranchHealthEntry {
  * metadata must not take down the whole scan, as in the registry's quarantine.
  * A missing `baseRoot` returns `[]`, so the admin endpoint can call this
  * without a pre-existence check.
+ *
+ * `duplicateIdScan` opts in to the per-branch duplicate-ID scan, which shares
+ * one `budgetMs` across every healthy branch, scanned in turn; a branch
+ * reached after the budget is spent reports `unknown`/`out-of-time`.
  */
 export declare function scanBranchHealth(baseRoot: string, opts: {
     baseBranchName: string;
     contentRootName?: string;
+    duplicateIdScan?: {
+        budgetMs: number;
+    };
 }): Promise<BranchHealthEntry[]>;
 export {};