canopycms 0.0.68-int.109 → 0.0.68-int.111

package/README.md

@@ -47,7 +47,7 @@ you misunderstood, which is why it is worth resolving the ref rather than guessi
 
 - Workspaces resolve per mode: `prod` uses `$CANOPYCMS_WORKSPACE_ROOT/content-branches` (default: `/mnt/efs/content-branches`), `dev` uses `.canopy-dev/content-branches/<branch>`.
 - For `prod` mode, you must set `defaultRemoteUrl`. For `dev`, `defaultRemoteUrl` is **optional** - if omitted, a local remote is auto-created at `.canopy-dev/remote.git`.
-- Optionally configure `defaultRemoteName` (default: `origin`) and `defaultBaseBranch` (default: `main`).
+- Optionally configure `defaultRemoteName` (default: `origin`) and `defaultBaseBranch` (unset: the checked-out git branch in dev, the repository's default branch in prod).
 - Git author identity is required for `prod` mode: set `gitBotAuthorName` and `gitBotAuthorEmail` so bot commits can be created reliably.
 - Branch names are sanitized and traversal is blocked before creating directories.
 - Metadata lives at `<workspace>/.canopy-meta/branch.json`; the registry lives at `<branchesRoot>/branches.json` and records the workspaceRoot for each branch.
@@ -515,7 +515,7 @@ export default defineCanopyConfig({
 **How it works:**
 
 1. When you create your first branch, CanopyCMS automatically creates a bare git repository at `.canopy-dev/remote.git`
-2. Your current `baseBranch` (default: `main`) is pushed to this local remote
+2. Your current `baseBranch` (unset: the checked-out branch) is pushed to this local remote
 3. Branch workspaces are cloned from this local remote into `.canopy-dev/content-branches/<branch-name>/`
 4. All git operations (push, fetch, etc.) work against the local remote
 

package/dist/ai/resolve-branch.js

@@ -4,6 +4,8 @@
  */
 import { loadOrCreateBranchContext } from '../branch-workspace.js';
 import { readsFromCheckout } from '../build-mode.js';
+import { GitManager } from '../git-manager.js';
+import { baseBranchOf } from '../utils/base-branch.js';
 import { detectHeadBranch } from '../utils/git.js';
 /**
  * Resolve the branch root directory for reading content.
@@ -15,6 +17,11 @@ export async function resolveBranchRoot(config) {
     if (readsFromCheckout(config)) {
         return process.cwd();
     }
+    // Prod reads an unset base branch from the remote's HEAD, as services does; provisioning
+    // needs it even when the active branch is configured.
+    const resolved = config.mode === 'prod' && !config.defaultBaseBranch
+        ? { ...config, defaultBaseBranch: await GitManager.detectBaseBranch(config, 'throw') }
+        : config;
     let activeBranch;
     if (config.defaultActiveBranch) {
         activeBranch = config.defaultActiveBranch;
@@ -23,10 +30,10 @@ export async function resolveBranchRoot(config) {
         activeBranch = await detectHeadBranch(process.cwd(), config.defaultBaseBranch ?? 'main');
     }
     else {
-        activeBranch = config.defaultBaseBranch ?? 'main';
+        activeBranch = baseBranchOf(resolved);
     }
     const context = await loadOrCreateBranchContext({
-        config,
+        config: resolved,
         branchName: activeBranch,
         mode: config.mode,
         createdBy: 'canopycms-ai',

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

@@ -27,8 +27,17 @@ import { branchProvisioningLockName, tryAcquireProvisioningLock } from '../utils
 import { withContentWriteLock, ContentWriteLockBusyError, DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS, } from '../utils/content-write-lock.js';
 import { getErrorMessage, isNodeError, isNotFoundError } from '../utils/error.js';
 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
@@ -39,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
@@ -60,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 = ctx.services.config.defaultBaseBranch ?? 'main';
+    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) {
@@ -102,7 +128,7 @@ const getBranchHealthHandler = async (_gc, ctx, _req) => {
  */
 const purgeBranchDirHandler = async (_gc, ctx, _req, params) => {
     const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
-    const baseBranchName = ctx.services.config.defaultBaseBranch ?? 'main';
+    const baseBranchName = baseBranchOf(ctx.services.config);
     const sanitizedBaseBranchName = sanitizeBranchName(baseBranchName);
     if (params.dirName === sanitizedBaseBranchName) {
         return { ok: false, status: 400, error: 'The base branch directory can never be purged' };
@@ -412,7 +438,7 @@ async function checkStillCorrupt(dirPath) {
  * rebuild) and invalidates any ContentStore already registered in THIS
  * process for the same root.
  */
-const repairContentDuplicatesHandler = async (_gc, ctx, _req, params) => {
+const repairContentDuplicatesHandler = async (_gc, ctx, req, params) => {
     const baseRoot = getDefaultBranchBase(ctx.services.config.mode);
     const dirPath = resolveDirWithinBase(baseRoot, params.dirName);
     if (!dirPath) {
@@ -485,15 +511,25 @@ const repairContentDuplicatesHandler = async (_gc, ctx, _req, params) => {
                 : getErrorMessage(err),
         };
     }
+    finally {
+        // Archived files leave the branch at its next submit, a partial repair's included, so the
+        // admin is one of its editors. No `writableBranch` guard can say so: this route names a
+        // directory, not a branch.
+        if (resolved.length > 0) {
+            await ctx.services.recordBranchEditor({ branchRoot: dirPath, baseRoot }, req.user);
+        }
+    }
 };
 /**
- * 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

@@ -78,10 +78,10 @@ declare const listAdminTasksParamsSchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
     limit: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    status: "failed" | "corrupt" | "pending" | "processing" | "completed";
+    status: "failed" | "pending" | "corrupt" | "processing" | "completed";
     limit?: number | undefined;
 }, {
-    status: "failed" | "corrupt" | "pending" | "processing" | "completed";
+    status: "failed" | "pending" | "corrupt" | "processing" | "completed";
     limit?: number | undefined;
 }>;
 export type ListAdminTasksParams = z.infer<typeof listAdminTasksParamsSchema>;
@@ -89,10 +89,10 @@ declare const deleteTaskParamsSchema: z.ZodObject<{
     status: z.ZodEnum<["pending", "failed", "corrupt"]>;
     fileName: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
-    status: "failed" | "corrupt" | "pending";
+    status: "failed" | "pending" | "corrupt";
     fileName: string;
 }, {
-    status: "failed" | "corrupt" | "pending";
+    status: "failed" | "pending" | "corrupt";
     fileName: string;
 }>;
 export type DeleteTaskParams = z.infer<typeof deleteTaskParamsSchema>;
@@ -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, {
@@ -132,10 +138,10 @@ export declare const ADMIN_ROUTES: {
         status: z.ZodEnum<["pending", "processing", "completed", "failed", "corrupt"]>;
         limit: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        status: "failed" | "corrupt" | "pending" | "processing" | "completed";
+        status: "failed" | "pending" | "corrupt" | "processing" | "completed";
         limit?: number | undefined;
     }, {
-        status: "failed" | "corrupt" | "pending" | "processing" | "completed";
+        status: "failed" | "pending" | "corrupt" | "processing" | "completed";
         limit?: number | undefined;
     }>, undefined, AdminTasksResponse>;
     readonly retryTask: import("./route-builder.js").RouteDefinition<z.ZodObject<{
@@ -149,10 +155,10 @@ export declare const ADMIN_ROUTES: {
         status: z.ZodEnum<["pending", "failed", "corrupt"]>;
         fileName: z.ZodEffects<z.ZodString, string, string>;
     }, "strip", z.ZodTypeAny, {
-        status: "failed" | "corrupt" | "pending";
+        status: "failed" | "pending" | "corrupt";
         fileName: string;
     }, {
-        status: "failed" | "corrupt" | "pending";
+        status: "failed" | "pending" | "corrupt";
         fileName: string;
     }>, undefined, AdminDeleteTaskResponse>;
 };

package/dist/api/admin.js

@@ -16,6 +16,7 @@ import { getErrorMessage, isNotFoundError, redactCredentials } from '../utils/er
 import { getBuildIdentity } from '../build-identity.js';
 import { loadSharp } from '../assets/sharp-loader.js';
 import { ADMIN_BRANCH_HEALTH_ROUTES } from './admin-branch-health.js';
+import { baseBranchOf } from '../utils/base-branch.js';
 /**
  * 60_000 = DEFAULT_LOCK_STALE_MS in worker/cms-worker.ts, hardcoded rather
  * than threaded through config: an adopter who overrides `lockStaleMs` skews
@@ -91,7 +92,7 @@ async function readSettingsWorkspaceError(ctx) {
 async function readBaseSchemaIssues(ctx) {
     try {
         const { config, branchSchemaCache, entrySchemaRegistry } = ctx.services;
-        const base = await ctx.getBranchContext(config.defaultBaseBranch ?? 'main');
+        const base = await ctx.getBranchContext(baseBranchOf(config));
         if (!base)
             return [];
         const { issues } = await branchSchemaCache.getSchema(base.branchRoot, entrySchemaRegistry, config.contentRoot || 'content');

package/dist/api/branch-merge.js

@@ -54,7 +54,7 @@ const markAsMergedHandler = async (gc, ctx, _req, params) => {
     //     console.error(`CanopyCMS: Failed to delete remote branch ${branchName}:`, err)
     //   }
     // }
-    // Comments.json is already in the branch workspace at .canopycms/comments.json
+    // Comments.json is already in the branch workspace at .canopy-meta/comments.json
     // It will be preserved with the archived branch - no action needed
     return {
         ok: true,

package/dist/api/branch-review.js

@@ -17,7 +17,7 @@ const requestChangesHandler = async (gc, ctx, _req, _params) => {
     const updated = await meta.save({
         branch: { name: branchContext.branch.name, status: 'editing' },
     });
-    // TODO: Optionally record comment in .canopycms/comments.json when comment system is implemented
+    // TODO: Optionally record comment in .canopy-meta/comments.json when comment system is implemented
     return {
         ok: true,
         status: 200,

package/dist/api/branch-status.js

@@ -12,6 +12,7 @@ import { isNonFastForwardRejection } from '../utils/git.js';
 import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
 import { submissionEditorFromUser } from '../submission-attribution.js';
 import { NothingToSubmitError } from '../services.js';
+import { baseBranchOf } from '../utils/base-branch.js';
 const getBranchStatusHandler = async (gc, _ctx, _req, _params) => {
     const { branchContext } = gc;
     return { ok: true, status: 200, data: { branch: branchContext.branch } };
@@ -53,10 +54,16 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
     }
     // Commit and push changes
     const submitter = submissionEditorFromUser(req.user);
+    const { authPlugin } = ctx;
     let changedPaths;
+    let editors;
     try {
         ;
-        ({ changedPaths } = await ctx.services.submitBranch({ context: branchContext, submitter }));
+        ({ changedPaths, editors } = await ctx.services.submitBranch({
+            context: branchContext,
+            submitter,
+            lookupEditor: authPlugin ? (id) => authPlugin.getUserMetadata(id) : undefined,
+        }));
     }
     catch (err) {
         if (err instanceof NothingToSubmitError) {
@@ -113,6 +120,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
     const submittedAt = new Date().toISOString();
     const prResult = await syncSubmitPr(ctx, branchContext, {
         submitter,
+        editors,
         changedPaths,
         submittedAt,
     });
@@ -123,7 +131,7 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
     // stays editable; the stamp records that it is now on GitHub, for delete.
     if (prResult.nothingToSubmit) {
         await meta.save({ branch: { name: branchContext.branch.name, ...pushed } });
-        const base = branchContext.branch.baseBranch ?? ctx.services.config.defaultBaseBranch ?? 'main';
+        const base = branchContext.branch.baseBranch ?? baseBranchOf(ctx.services.config);
         return {
             ok: false,
             status: 400,

package/dist/api/branch.js

@@ -16,6 +16,7 @@ import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, RESERVED_ROUTE_BRA
 import { GitManager } from '../git-manager.js';
 import { syncDeleteRemoteBranch } from './github-sync.js';
 import { branchNameSchema, branchParamSchema } from './validators.js';
+import { baseBranchOf } from '../utils/base-branch.js';
 const log = createDebugLogger({ prefix: 'BranchAPI' });
 const createBranchBodySchema = z.object({
     branch: branchNameSchema,
@@ -300,7 +301,7 @@ export const createBranchHandler = async (ctx, req, body) => {
         // Load path permissions from the base branch's JSON file (the resolved
         // fork point — baked into config at service creation; dev-mode git HEAD
         // when not explicitly configured)
-        const baseBranch = ctx.services.config.defaultBaseBranch ?? 'main';
+        const baseBranch = baseBranchOf(ctx.services.config);
         const baseBranchContext = await ctx.getBranchContext(baseBranch);
         let pathPermissions = [];
         if (baseBranchContext) {
@@ -377,7 +378,7 @@ export const listBranchesHandler = async (ctx, req) => {
     // but registry branch names are filesystem-sanitized ('claude-foo') — the
     // editor matches defaultBranch against registry names, so return the form
     // that can actually be found there.
-    const defaultBranch = sanitizeBranchName(ctx.services.config.defaultActiveBranch ?? ctx.services.config.defaultBaseBranch ?? 'main');
+    const defaultBranch = sanitizeBranchName(ctx.services.config.defaultActiveBranch ?? baseBranchOf(ctx.services.config));
     // Admins and Reviewers see all branches
     if (isPrivileged(req.user.groups)) {
         return {
@@ -551,7 +552,7 @@ export const deleteBranchHandler = async (ctx, req, params) => {
     const sanitizedDeleted = sanitizeBranchName(branchContext.branch.name);
     // Defense-in-depth only -- isProtected above already rejects the base
     // branch, and settings branches never resolve through getBranchContext.
-    const sanitizedBase = sanitizeBranchName(branchContext.branch.baseBranch ?? ctx.services.config.defaultBaseBranch ?? 'main');
+    const sanitizedBase = sanitizeBranchName(branchContext.branch.baseBranch ?? baseBranchOf(ctx.services.config));
     const deletableHead = sanitizedDeleted !== sanitizedBase &&
         !sanitizedDeleted.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX);
     if (deletableHead &&

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/comments.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { ApiResponse } from './types.js';
 import type { CommentThread, CommentType } from '../comment-store.js';
+import type { LogicalPath } from '../paths/types.js';
 export interface AddCommentBody {
     text: string;
     threadId?: string;
@@ -48,18 +49,18 @@ export declare const COMMENT_ROUTES: {
         text: z.ZodString;
         threadId: z.ZodOptional<z.ZodString>;
         type: z.ZodEnum<["field", "entry", "branch"]>;
-        entryPath: z.ZodOptional<z.ZodType<import("../paths/index.js").LogicalPath, z.ZodTypeDef, import("../paths/index.js").LogicalPath>>;
+        entryPath: z.ZodOptional<z.ZodType<LogicalPath, z.ZodTypeDef, LogicalPath>>;
         canopyPath: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         type: "branch" | "entry" | "field";
         text: string;
-        entryPath?: import("../paths/index.js").LogicalPath | undefined;
+        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
         canopyPath?: string | undefined;
     }, {
         type: "branch" | "entry" | "field";
         text: string;
-        entryPath?: import("../paths/index.js").LogicalPath | undefined;
+        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
         canopyPath?: string | undefined;
     }>, AddCommentResponse>;

package/dist/api/comments.js

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import { CommentStore } from '../comment-store.js';
 import { isReviewer } from '../authorization/index.js';
+import { parseLogicalPath } from '../paths/validation.js';
+import { normalizeFilesystemPath } from '../paths/normalize.js';
 import { defineEndpoint } from './route-builder.js';
 import { branchParamSchema, branchNameSchema, logicalPathSchema } from './validators.js';
 // ============================================================================
@@ -17,13 +19,47 @@ const addCommentBodySchema = z.object({
     entryPath: logicalPathSchema.optional(),
     canopyPath: z.string().optional(), // Canopy field path, not a file path
 });
-const listCommentsHandler = async (gc, _ctx, _req, _params) => {
+/**
+ * Whether `entryPath` is spelled the way path rules expect an entry's logical path: rooted at
+ * the content root, with no empty or `.` segment. Rules are globs over that spelling, so
+ * `secret/plan` (which the content API reads as `content/secret/plan`) and
+ * `content/./secret/plan` both miss a rule written for `content/secret/**`.
+ */
+const isCanonicalEntryPath = (entryPath, contentRoot) => entryPath.startsWith(`${normalizeFilesystemPath(contentRoot)}/`) &&
+    entryPath.split('/').every((segment) => segment !== '' && segment !== '.');
+/**
+ * Whether the user may see a thread: its entry's path rules at `read`, the level a content
+ * read needs, so a thread discloses nothing about an entry its reader could not open. A
+ * field thread is governed by its entry. A thread with no entry path (a branch thread) is
+ * governed by branch access alone, which the `branchAccess` guard has already passed. An
+ * entry path that is not a canonical logical path is denied: comments.json is read without
+ * schema validation.
+ */
+const canReadThreadEntry = (checkAccess, contentRoot, entryPath) => {
+    if (entryPath === undefined)
+        return true;
+    const parsed = parseLogicalPath(entryPath);
+    return (parsed.ok &&
+        isCanonicalEntryPath(parsed.path, contentRoot) &&
+        checkAccess(parsed.path, 'read').allowed);
+};
+/** One checker per request, bound to the content root its paths are canonical against. */
+const createThreadReadCheck = async (ctx, req, branchContext) => {
+    const checkAccess = await ctx.services.createContentAccessChecker(branchContext, branchContext.branchRoot, req.user);
+    const contentRoot = ctx.services.config.contentRoot || 'content';
+    return (entryPath) => canReadThreadEntry(checkAccess, contentRoot, entryPath);
+};
+const listCommentsHandler = async (gc, ctx, req, _params) => {
     const { branchContext } = gc;
     const commentStore = new CommentStore(branchContext.branchRoot);
-    const threads = await commentStore.listThreads({ includeResolved: true });
+    const [allThreads, canRead] = await Promise.all([
+        commentStore.listThreads({ includeResolved: true }),
+        createThreadReadCheck(ctx, req, branchContext),
+    ]);
+    const threads = allThreads.filter((thread) => canRead(thread.entryPath));
     return { ok: true, status: 200, data: { threads } };
 };
-const addCommentHandler = async (gc, _ctx, req, _params, body) => {
+const addCommentHandler = async (gc, ctx, req, _params, body) => {
     const { branchContext } = gc;
     // Validate required fields based on type
     if (body.type === 'field' && !body.canopyPath) {
@@ -40,22 +76,50 @@ const addCommentHandler = async (gc, _ctx, req, _params, body) => {
             error: 'entryPath required for field/entry comments',
         };
     }
+    // Commenting needs read access to the entry the comment lands on. A reply lands on the
+    // stored thread, so it is checked against that thread's entry path, which never changes
+    // once the thread exists; a reply to a thread the user cannot read answers as missing, as
+    // resolve does.
     const commentStore = new CommentStore(branchContext.branchRoot);
+    const [existing, canRead] = await Promise.all([
+        body.threadId ? commentStore.getThread(body.threadId) : Promise.resolve(null),
+        createThreadReadCheck(ctx, req, branchContext),
+    ]);
+    if (body.threadId) {
+        if (!existing || !canRead(existing.entryPath)) {
+            return { ok: false, status: 404, error: 'Thread not found' };
+        }
+        const reply = await commentStore.addReply({
+            userId: req.user.userId,
+            text: body.text,
+            threadId: body.threadId,
+        });
+        if (!reply) {
+            return { ok: false, status: 404, error: 'Thread not found' };
+        }
+        return { ok: true, status: 201, data: reply };
+    }
+    if (!canRead(body.entryPath)) {
+        return { ok: false, status: 403, error: 'Forbidden' };
+    }
     const result = await commentStore.addComment({
         userId: req.user.userId,
         text: body.text,
-        threadId: body.threadId,
         type: body.type,
         entryPath: body.entryPath,
         canopyPath: body.canopyPath,
     });
     return { ok: true, status: 201, data: result };
 };
-const resolveCommentHandler = async (gc, _ctx, req, params) => {
+const resolveCommentHandler = async (gc, ctx, req, params) => {
     const { branchContext } = gc;
     const commentStore = new CommentStore(branchContext.branchRoot);
-    const thread = await commentStore.getThread(params.threadId);
-    if (!thread) {
+    const [thread, canRead] = await Promise.all([
+        commentStore.getThread(params.threadId),
+        createThreadReadCheck(ctx, req, branchContext),
+    ]);
+    // A thread the user cannot read answers as missing, so its id does not confirm it exists.
+    if (!thread || !canRead(thread.entryPath)) {
         return { ok: false, status: 404, error: 'Thread not found' };
     }
     // Check permissions: thread author, reviewer, or admin