canopycms 0.0.67-int.90 → 0.0.67

package/dist/authorization/branch.d.ts

@@ -1,37 +1,28 @@
-/**
- * Branch-level authorization
- *
- * Handles checking if a user can access a branch based on ACLs.
- */
 import type { BranchContext } from '../types.js';
 import type { CanopyConfig, DefaultBranchAccess } from '../config/index.js';
 import type { CanopyUser } from '../user.js';
 import type { BranchAccessResult } from './types.js';
 /** Options narrowing {@link checkBranchAccessWithDefault} to a specific branch's nature. */
-export interface BranchAccessOptions {
+interface BranchAccessOptions {
     /**
      * Whether this is the protected base branch -- pass
-     * `getBranchProtection(...).isProtected`. When true, the branch passes this
-     * layer wherever no explicit ACL decided the question, and the PATH layer alone
-     * decides what is readable. Explicit ACL verdicts still win in both directions
-     * (see the comment at the fallback site).
+     * `getBranchProtection(...).isProtected`. When true the branch passes this
+     * layer wherever no explicit ACL decided the question, leaving the PATH layer
+     * to decide what is readable; explicit ACL verdicts still win in both
+     * directions (see the fallback site below).
      *
-     * This grant is load-bearing, not a convenience. The base branch takes no ACL
-     * (`updateBranchAccessHandler` rejects one outright, because an entry there
-     * would feed `allowed_by_acl` and confer Withdraw rights) and its `createdBy`
-     * is `canopycms-system`, so nobody is its creator. Without this, the branch
-     * every user lands on is unreachable under `defaultBranchAccess: 'deny'` with
-     * no way to configure around it -- which is what made 'deny' unusable for any
-     * site with non-admin editors.
-     *
-     * It cannot widen anything dangerous: workflow actions stay blocked because
-     * {@link canPerformWorkflowAction} disables its system-branch grant on the
-     * same flag, prod writes stay blocked by `getBranchWriteProtection().readOnly`,
-     * and the editor API 401s anonymous callers before authorization runs. What it
-     * buys is that a public-read `deployedAs: 'server'` site can run 'deny' with
+     * The grant is load-bearing: the base branch takes no ACL
+     * (`updateBranchAccessHandler` rejects one, since an entry there would feed
+     * `allowed_by_acl` and confer Withdraw rights) and its `createdBy` is
+     * `canopycms-system`, so nobody is its creator -- without this it is
+     * unreachable under `defaultBranchAccess: 'deny'` with no way to configure
+     * around it. It widens nothing dangerous: {@link canPerformWorkflowAction}
+     * disables its system-branch grant on the same flag, prod writes stay blocked
+     * by `getBranchWriteProtection().readOnly`, and the editor API 401s anonymous
+     * callers before authorization runs. What it buys: a public-read
+     * `deployedAs: 'server'` site can run 'deny' with
      * `defaultPathAccess: { read: 'allow' }` and still keep un-ACL'd work branches
-     * private -- previously that required the blunt `defaultBranchAccess: 'allow'`,
-     * which opened every work branch too.
+     * private.
      */
     isProtectedBranch?: boolean;
 }
@@ -46,14 +37,13 @@ export interface BranchAccessOptions {
  * 4. With no ACL: the branch creator, then `defaultAccess`, and only where that
  *    would deny, the protected base branch grant
  *    (see {@link BranchAccessOptions.isProtectedBranch})
+ * @internal Exported for tests.
  */
 export declare function checkBranchAccessWithDefault(context: BranchContext, user: CanopyUser, defaultAccess?: DefaultBranchAccess, options?: BranchAccessOptions): BranchAccessResult;
 /**
- * Create a branch access checker with bound default access.
- *
- * `config` is needed to resolve whether a branch is the protected base branch;
- * it routes through `getBranchProtection`, the single source of truth for that
- * question, rather than repeating the base-branch test here.
+ * Bind a default access level. `config` is needed only to resolve the
+ * protected-base-branch question, which routes through `getBranchProtection`,
+ * its single source of truth, rather than repeating the comparison here.
  */
 export declare function createCheckBranchAccess(defaultAccess?: DefaultBranchAccess, config?: Pick<CanopyConfig, 'mode' | 'defaultBaseBranch'>): (context: BranchContext, user: CanopyUser) => BranchAccessResult;
 /** Options tightening {@link canPerformWorkflowAction} beyond the default hybrid model. */
@@ -65,29 +55,20 @@ export interface WorkflowActionOptions {
      * -- pass `getBranchProtection(...).isProtected` here so only
      * admins/reviewers/explicit-ACL users retain workflow rights on it.
      *
-     * It is also forwarded to {@link checkBranchAccessWithDefault}, where the same
-     * flag GRANTS access (see {@link BranchAccessOptions.isProtectedBranch}). The
-     * two pull in opposite directions on purpose, and that is exactly the intended
-     * base-branch posture: readable by anyone the path layer permits, submittable
-     * by no one. The access layer says yes, then `isSystemBranch` below is false,
-     * so a non-creator/non-ACL/non-privileged user still gets `false` here.
+     * The same flag GRANTS access in {@link checkBranchAccessWithDefault} (see
+     * {@link BranchAccessOptions.isProtectedBranch}); pulling in opposite
+     * directions is the intended base-branch posture -- readable by anyone the
+     * path layer permits, submittable by no one.
      */
     isProtectedBranch?: boolean;
 }
 /**
- * Check if user can perform workflow actions (submit/withdraw) on a branch.
- * Allowed if: user is creator OR user has ACL access OR (system branch AND user has general access).
- *
- * This implements a hybrid permission model:
- * - Branch creators can always submit/withdraw their branches
- * - Users explicitly listed in branch ACLs can also submit/withdraw
- * - For system branches (createdBy: 'canopycms-system'), anyone with general access can submit/withdraw
- * - Admins and Reviewers always have access (via checkBranchAccess)
- * - Unless `options.isProtectedBranch` is set, in which case the system-branch
- *   grant above is disabled (see {@link WorkflowActionOptions})
+ * Whether a user may submit/withdraw a branch: creator, OR ACL access, OR a
+ * system branch plus general access.
  *
- * The creator grant is enforced twice over: `checkBranchAccessWithDefault` now
- * admits the creator (so the gate below no longer swallows them under
- * `defaultBranchAccess: 'deny'`), and `userIsCreator` still decides the result.
+ * The creator grant is enforced twice: `checkBranchAccessWithDefault` admits
+ * the creator, so the gate below cannot swallow them under
+ * `defaultBranchAccess: 'deny'`, and `userIsCreator` decides the result.
  */
 export declare function canPerformWorkflowAction(context: BranchContext, user: CanopyUser, defaultAccess?: DefaultBranchAccess, options?: WorkflowActionOptions): boolean;
+export {};

package/dist/authorization/branch.js

@@ -1,8 +1,3 @@
-/**
- * Branch-level authorization
- *
- * Handles checking if a user can access a branch based on ACLs.
- */
 import { isAdmin, isReviewer } from './helpers.js';
 import { getBranchProtection } from './protected-branch.js';
 /**
@@ -16,9 +11,9 @@ import { getBranchProtection } from './protected-branch.js';
  * 4. With no ACL: the branch creator, then `defaultAccess`, and only where that
  *    would deny, the protected base branch grant
  *    (see {@link BranchAccessOptions.isProtectedBranch})
+ * @internal Exported for tests.
  */
 export function checkBranchAccessWithDefault(context, user, defaultAccess = 'deny', options) {
-    // Admins and Reviewers have full branch access
     if (isAdmin(user.groups) || isReviewer(user.groups)) {
         return { allowed: true, reason: 'privileged' };
     }
@@ -30,16 +25,13 @@ export function checkBranchAccessWithDefault(context, user, defaultAccess = 'den
         return { allowed: false, reason: 'denied_by_acl' };
     }
     if (!hasUserConstraint && !hasGroupConstraint) {
-        // The branch creator owns their own un-ACL'd branch. This matches the three
-        // places the server already grants on creator-ownership independently of
-        // branch access (listBranchesHandler, canDeleteBranch, canModifyBranchAccess)
-        // -- without it, under 'deny' a creator could delete their branch and rewrite
-        // its ACL but not read a single file on it.
-        //
-        // Deliberately scoped to the no-ACL case: an EXPLICIT allowlist that omits
-        // the creator still denies them, because that is how an admin locks down a
-        // branch someone else created. Granting creator ahead of the ACL would make
-        // that lockdown silently ineffective.
+        // The branch creator owns their own un-ACL'd branch, matching the three
+        // places that already grant on creator-ownership independently of branch
+        // access (listBranchesHandler, canDeleteBranch, canModifyBranchAccess):
+        // without it, under 'deny' a creator could delete their branch and rewrite
+        // its ACL but not read a file on it. Scoped to the no-ACL case on purpose --
+        // an EXPLICIT allowlist omitting the creator still denies them, which is how
+        // an admin locks down a branch someone else created.
         if (context.branch.createdBy === user.userId) {
             return { allowed: true, reason: 'creator' };
         }
@@ -61,11 +53,9 @@ export function checkBranchAccessWithDefault(context, user, defaultAccess = 'den
     return { allowed, reason: allowed ? 'allowed_by_acl' : 'denied_by_acl' };
 }
 /**
- * Create a branch access checker with bound default access.
- *
- * `config` is needed to resolve whether a branch is the protected base branch;
- * it routes through `getBranchProtection`, the single source of truth for that
- * question, rather than repeating the base-branch test here.
+ * Bind a default access level. `config` is needed only to resolve the
+ * protected-base-branch question, which routes through `getBranchProtection`,
+ * its single source of truth, rather than repeating the comparison here.
  */
 export function createCheckBranchAccess(defaultAccess = 'deny', config) {
     return (context, user) => checkBranchAccessWithDefault(context, user, defaultAccess, {
@@ -75,38 +65,22 @@ export function createCheckBranchAccess(defaultAccess = 'deny', config) {
     });
 }
 /**
- * Check if user can perform workflow actions (submit/withdraw) on a branch.
- * Allowed if: user is creator OR user has ACL access OR (system branch AND user has general access).
- *
- * This implements a hybrid permission model:
- * - Branch creators can always submit/withdraw their branches
- * - Users explicitly listed in branch ACLs can also submit/withdraw
- * - For system branches (createdBy: 'canopycms-system'), anyone with general access can submit/withdraw
- * - Admins and Reviewers always have access (via checkBranchAccess)
- * - Unless `options.isProtectedBranch` is set, in which case the system-branch
- *   grant above is disabled (see {@link WorkflowActionOptions})
+ * Whether a user may submit/withdraw a branch: creator, OR ACL access, OR a
+ * system branch plus general access.
  *
- * The creator grant is enforced twice over: `checkBranchAccessWithDefault` now
- * admits the creator (so the gate below no longer swallows them under
- * `defaultBranchAccess: 'deny'`), and `userIsCreator` still decides the result.
+ * The creator grant is enforced twice: `checkBranchAccessWithDefault` admits
+ * the creator, so the gate below cannot swallow them under
+ * `defaultBranchAccess: 'deny'`, and `userIsCreator` decides the result.
  */
 export function canPerformWorkflowAction(context, user, defaultAccess = 'deny', options) {
-    // Check if user has general branch access (handles admins, reviewers, creator, ACLs)
     const accessResult = checkBranchAccessWithDefault(context, user, defaultAccess, {
         isProtectedBranch: options?.isProtectedBranch,
     });
-    // If user doesn't have basic branch access, deny immediately
     if (!accessResult.allowed) {
         return false;
     }
-    // Check if user is the branch creator
     const userIsCreator = context.branch.createdBy === user.userId;
-    // Check if this is a system-created branch (grant disabled on protected branches)
     const isSystemBranch = !options?.isProtectedBranch && context.branch.createdBy === 'canopycms-system';
-    // Allow if:
-    // 1. User is the creator, OR
-    // 2. User has ACL access (reason: 'privileged' or 'allowed_by_acl'), OR
-    // 3. System branch with general access
     return (userIsCreator ||
         accessResult.reason === 'privileged' ||
         accessResult.reason === 'allowed_by_acl' ||

package/dist/authorization/content.d.ts

@@ -1,18 +1,6 @@
 /**
- * Content access authorization
- *
- * This is the main entry point for authorization checks. It combines
- * branch-level and path-level access checks into a single API.
- *
- * Usage:
- * ```ts
- * import { checkContentAccess } from './authorization.js'
- *
- * const result = await checkContentAccess(deps, context, branchRoot, 'content/posts/my-post.mdx', user, 'edit')
- * if (result.allowed) {
- *   // User can edit the file
- * }
- * ```
+ * Main entry point for authorization checks: combines branch-level and
+ * path-level access into a single API.
  */
 import type { BranchContext } from '../types.js';
 import type { PermissionLevel } from '../config/index.js';
@@ -25,35 +13,18 @@ import type { PhysicalPath } from '../paths/types.js';
  */
 export type ContentAccessChecker = (relativePath: PhysicalPath, level: PermissionLevel) => ContentAccessResult;
 /**
- * Create a content-access checker that resolves the request-constant work once
- * (branch access, the settings/permissions root, and the path-permission rules)
- * and returns a synchronous per-path checker.
- *
- * Branch access, the resolved permissions root, and the loaded rules are identical
- * for a fixed `(context, branchRoot, user)`, so hoisting them out of the per-path
- * check avoids re-reading the permissions file (and, in modes with a separate
- * settings branch, re-ensuring the settings workspace) for every entry. This is
- * the batch primitive used by listing endpoints that check many paths per request.
- *
- * @param deps - Dependencies including branch access checker and path permissions loader
- * @param context - Branch context containing branch metadata
- * @param branchRoot - Root directory of the branch
- * @param user - User to check access for
+ * Resolve the request-constant work once -- branch access, the
+ * settings/permissions root and the path-permission rules, all identical for a
+ * fixed `(context, branchRoot, user)` -- and return a synchronous per-path
+ * checker. Hoisting it avoids re-reading the permissions file (and, in modes
+ * with a separate settings branch, re-ensuring the settings workspace) for
+ * every entry. This is the batch primitive for listing endpoints that check
+ * many paths per request.
  */
 export declare function createContentAccessChecker(deps: ContentAccessDeps, context: BranchContext, branchRoot: string, user: CanopyUser): Promise<ContentAccessChecker>;
 /**
- * Check content access by evaluating both branch and path permissions.
- * Path permissions are loaded dynamically from the branch root.
- *
- * @param deps - Dependencies including branch access checker and path permissions loader
- * @param context - Branch context containing branch metadata
- * @param branchRoot - Root directory of the branch
- * @param relativePath - Physical path relative to branch root (with embedded IDs)
- * @param user - User to check access for
- * @param level - Permission level to check ('read', 'edit', or 'review')
+ * Single-path check; loads the path permissions from the branch root per call.
+ * @internal Exported for tests.
  */
 export declare function checkContentAccess(deps: ContentAccessDeps, context: BranchContext, branchRoot: string, relativePath: PhysicalPath, user: CanopyUser, level: PermissionLevel): Promise<ContentAccessResult>;
-/**
- * Create a content access checker with bound dependencies.
- */
 export declare function createCheckContentAccess(deps: ContentAccessDeps): (context: BranchContext, branchRoot: string, relativePath: PhysicalPath, user: CanopyUser, level: PermissionLevel) => Promise<ContentAccessResult>;

package/dist/authorization/content.js

@@ -1,42 +1,20 @@
 /**
- * Content access authorization
- *
- * This is the main entry point for authorization checks. It combines
- * branch-level and path-level access checks into a single API.
- *
- * Usage:
- * ```ts
- * import { checkContentAccess } from './authorization.js'
- *
- * const result = await checkContentAccess(deps, context, branchRoot, 'content/posts/my-post.mdx', user, 'edit')
- * if (result.allowed) {
- *   // User can edit the file
- * }
- * ```
+ * Main entry point for authorization checks: combines branch-level and
+ * path-level access into a single API.
  */
 import { operatingStrategy } from '../operating-mode/index.js';
 import { createCheckPathAccess } from './path.js';
 /**
- * Create a content-access checker that resolves the request-constant work once
- * (branch access, the settings/permissions root, and the path-permission rules)
- * and returns a synchronous per-path checker.
- *
- * Branch access, the resolved permissions root, and the loaded rules are identical
- * for a fixed `(context, branchRoot, user)`, so hoisting them out of the per-path
- * check avoids re-reading the permissions file (and, in modes with a separate
- * settings branch, re-ensuring the settings workspace) for every entry. This is
- * the batch primitive used by listing endpoints that check many paths per request.
- *
- * @param deps - Dependencies including branch access checker and path permissions loader
- * @param context - Branch context containing branch metadata
- * @param branchRoot - Root directory of the branch
- * @param user - User to check access for
+ * Resolve the request-constant work once -- branch access, the
+ * settings/permissions root and the path-permission rules, all identical for a
+ * fixed `(context, branchRoot, user)` -- and return a synchronous per-path
+ * checker. Hoisting it avoids re-reading the permissions file (and, in modes
+ * with a separate settings branch, re-ensuring the settings workspace) for
+ * every entry. This is the batch primitive for listing endpoints that check
+ * many paths per request.
  */
 export async function createContentAccessChecker(deps, context, branchRoot, user) {
     const branch = deps.checkBranchAccess(context, user);
-    // Load permissions from appropriate location based on operating mode
-    // Modes with separate settings branch: load from settings branch
-    // Other modes: load from the current branch
     let permissionsRoot = branchRoot;
     const mode = deps.mode;
     const strategy = operatingStrategy(mode);
@@ -44,8 +22,8 @@ export async function createContentAccessChecker(deps, context, branchRoot, user
         if (!deps.getSettingsBranchRoot) {
             throw new Error('getSettingsBranchRoot is required for modes that use separate settings branch');
         }
-        // getSettingsBranchRoot must throw if it cannot load the settings branch
-        // This ensures we never fall back to reading permissions from the current branch
+        // getSettingsBranchRoot must throw if it cannot load the settings branch:
+        // falling back would read permissions from the branch being edited.
         permissionsRoot = await deps.getSettingsBranchRoot();
     }
     const rules = await deps.loadPathPermissions(permissionsRoot, deps.mode);
@@ -64,23 +42,13 @@ export async function createContentAccessChecker(deps, context, branchRoot, user
     };
 }
 /**
- * Check content access by evaluating both branch and path permissions.
- * Path permissions are loaded dynamically from the branch root.
- *
- * @param deps - Dependencies including branch access checker and path permissions loader
- * @param context - Branch context containing branch metadata
- * @param branchRoot - Root directory of the branch
- * @param relativePath - Physical path relative to branch root (with embedded IDs)
- * @param user - User to check access for
- * @param level - Permission level to check ('read', 'edit', or 'review')
+ * Single-path check; loads the path permissions from the branch root per call.
+ * @internal Exported for tests.
  */
 export async function checkContentAccess(deps, context, branchRoot, relativePath, user, level) {
     const check = await createContentAccessChecker(deps, context, branchRoot, user);
     return check(relativePath, level);
 }
-/**
- * Create a content access checker with bound dependencies.
- */
 export function createCheckContentAccess(deps) {
     return (context, branchRoot, relativePath, user, level) => checkContentAccess(deps, context, branchRoot, relativePath, user, level);
 }

package/dist/authorization/groups/index.d.ts

@@ -1,5 +1,2 @@
-/**
- * Groups module exports
- */
 export { GroupsFileSchema, createDefaultGroupsFile, type GroupsFile, type InternalGroup, } from './schema.js';
 export { loadGroupsFile, loadInternalGroups, deriveInternalGroups, mutateGroupsFile, } from './loader.js';

package/dist/authorization/groups/index.js

@@ -1,5 +1,2 @@
-/**
- * Groups module exports
- */
 export { GroupsFileSchema, createDefaultGroupsFile, } from './schema.js';
 export { loadGroupsFile, loadInternalGroups, deriveInternalGroups, mutateGroupsFile, } from './loader.js';

package/dist/authorization/groups/loader.d.ts

@@ -1,42 +1,28 @@
 /**
- * Groups file loader
- *
- * Handles loading internal groups from the filesystem and mutating
- * groups.json under the cross-host layered lock in
- * authorization/settings-file-store.ts.
+ * Loads internal groups, and mutates groups.json under the cross-host layered
+ * lock in authorization/settings-file-store.ts.
  */
 import { type InternalGroup, type GroupsFile } from './schema.js';
 import type { OperatingMode } from '../../operating-mode/index.js';
 import type { OccWriteResult } from '../../utils/occ-json-write.js';
-/**
- * Load full groups file (for version checking)
- * Returns null if file doesn't exist.
- */
+/** Returns null when the file doesn't exist. */
 export declare function loadGroupsFile(branchRoot: string, mode: OperatingMode): Promise<GroupsFile | null>;
 /**
- * Derive the effective internal groups list from the raw groups array
- * stored on disk: ensures the reserved Admins/Reviewers groups always exist
- * (synthesizing defaults when absent) and merges bootstrap admin IDs into
- * Admins. Pure — no disk I/O — so a caller that already holds a freshly
- * loaded file (e.g. a settings-file mutator, which reloads on every retry
- * attempt) can reconcile against it without a second read.
+ * The effective internal groups for a raw on-disk groups array: the reserved
+ * Admins/Reviewers groups always exist (synthesized when absent) and bootstrap
+ * admin IDs merge into Admins. Pure — no disk I/O — so a caller holding a
+ * freshly loaded file (e.g. a settings-file mutator, which reloads on every
+ * retry attempt) can reconcile against it without a second read.
  */
 export declare function deriveInternalGroups(fileGroups: InternalGroup[], bootstrapAdminIds?: Set<string>): InternalGroup[];
-/**
- * Load internal groups from .canopycms/groups.json (or .local.json in dev mode)
- * Ensures Admins and Reviewers groups always exist, adding them dynamically if not present.
- * If Admins group exists in file, merges with bootstrap admin IDs.
- */
+/** Loads .canopycms/groups.json (groups.local.json in dev mode). */
 export declare function loadInternalGroups(branchRoot: string, mode: OperatingMode, bootstrapAdminIds?: Set<string>): Promise<InternalGroup[]>;
 /**
- * Mutate groups.json (or .local.json in dev mode) under the full cross-host
- * lock + OCC-retry stack (see authorization/settings-file-store.ts).
- * `mutate` is called with the current parsed file (`null` if it doesn't
- * exist yet) and the version to write under; it returns the next raw
- * payload, or `null` for a deliberate no-op. The returned payload is
- * validated against {@link GroupsFileSchema} before being written,
- * preserving the previous validate-before-write behavior of the old
- * `saveInternalGroups`.
+ * Mutate groups.json (groups.local.json in dev mode) under the full cross-host
+ * lock + OCC-retry stack (see authorization/settings-file-store.ts). `mutate`
+ * receives the current parsed file (`null` if absent) and the version to write
+ * under, and returns the next raw payload or `null` for a deliberate no-op.
+ * The payload is validated against {@link GroupsFileSchema} before writing.
  */
 export declare function mutateGroupsFile(branchRoot: string, mode: OperatingMode, mutate: (current: GroupsFile | null, version: number) => Record<string, unknown> | null, options?: {
     settleMs?: number;

package/dist/authorization/groups/loader.js

@@ -1,25 +1,16 @@
 /**
- * Groups file loader
- *
- * Handles loading internal groups from the filesystem and mutating
- * groups.json under the cross-host layered lock in
- * authorization/settings-file-store.ts.
+ * Loads internal groups, and mutates groups.json under the cross-host layered
+ * lock in authorization/settings-file-store.ts.
  */
 import { promises as fs } from 'node:fs';
 import { GroupsFileSchema } from './schema.js';
 import { operatingStrategy } from '../../operating-mode/index.js';
 import { RESERVED_GROUPS } from '../helpers.js';
 import { mutateSettingsJsonFile } from '../settings-file-store.js';
-/**
- * Get the appropriate groups file path based on mode
- */
 function getGroupsFilePath(branchRoot, mode) {
     return operatingStrategy(mode).getGroupsFilePath(branchRoot);
 }
-/**
- * Load full groups file (for version checking)
- * Returns null if file doesn't exist.
- */
+/** Returns null when the file doesn't exist. */
 export async function loadGroupsFile(branchRoot, mode) {
     const groupsPath = getGroupsFilePath(branchRoot, mode);
     try {
@@ -29,7 +20,6 @@ export async function loadGroupsFile(branchRoot, mode) {
         return validated;
     }
     catch (error) {
-        // File doesn't exist
         if (error.code === 'ENOENT') {
             return null;
         }
@@ -37,20 +27,16 @@ export async function loadGroupsFile(branchRoot, mode) {
     }
 }
 /**
- * Derive the effective internal groups list from the raw groups array
- * stored on disk: ensures the reserved Admins/Reviewers groups always exist
- * (synthesizing defaults when absent) and merges bootstrap admin IDs into
- * Admins. Pure — no disk I/O — so a caller that already holds a freshly
- * loaded file (e.g. a settings-file mutator, which reloads on every retry
- * attempt) can reconcile against it without a second read.
+ * The effective internal groups for a raw on-disk groups array: the reserved
+ * Admins/Reviewers groups always exist (synthesized when absent) and bootstrap
+ * admin IDs merge into Admins. Pure — no disk I/O — so a caller holding a
+ * freshly loaded file (e.g. a settings-file mutator, which reloads on every
+ * retry attempt) can reconcile against it without a second read.
  */
 export function deriveInternalGroups(fileGroups, bootstrapAdminIds = new Set()) {
-    // Find existing Admins and Reviewers groups
     let adminsGroup = fileGroups.find((g) => g.id === RESERVED_GROUPS.ADMINS);
     let reviewersGroup = fileGroups.find((g) => g.id === RESERVED_GROUPS.REVIEWERS);
-    // Ensure Admins group exists and includes bootstrap admins
     if (adminsGroup) {
-        // Merge bootstrap admin IDs with existing members
         const allAdmins = new Set([...adminsGroup.members, ...bootstrapAdminIds]);
         adminsGroup = {
             ...adminsGroup,
@@ -58,7 +44,6 @@ export function deriveInternalGroups(fileGroups, bootstrapAdminIds = new Set())
         };
     }
     else {
-        // Create Admins group with bootstrap admins
         adminsGroup = {
             id: RESERVED_GROUPS.ADMINS,
             name: RESERVED_GROUPS.ADMINS,
@@ -66,7 +51,6 @@ export function deriveInternalGroups(fileGroups, bootstrapAdminIds = new Set())
             members: Array.from(bootstrapAdminIds),
         };
     }
-    // Ensure Reviewers group exists
     if (!reviewersGroup) {
         reviewersGroup = {
             id: RESERVED_GROUPS.REVIEWERS,
@@ -75,28 +59,20 @@ export function deriveInternalGroups(fileGroups, bootstrapAdminIds = new Set())
             members: [],
         };
     }
-    // Return all groups: reserved groups first, then other groups
     const otherGroups = fileGroups.filter((g) => g.id !== RESERVED_GROUPS.ADMINS && g.id !== RESERVED_GROUPS.REVIEWERS);
     return [adminsGroup, reviewersGroup, ...otherGroups];
 }
-/**
- * Load internal groups from .canopycms/groups.json (or .local.json in dev mode)
- * Ensures Admins and Reviewers groups always exist, adding them dynamically if not present.
- * If Admins group exists in file, merges with bootstrap admin IDs.
- */
+/** Loads .canopycms/groups.json (groups.local.json in dev mode). */
 export async function loadInternalGroups(branchRoot, mode, bootstrapAdminIds = new Set()) {
     const file = await loadGroupsFile(branchRoot, mode);
     return deriveInternalGroups(file?.groups ?? [], bootstrapAdminIds);
 }
 /**
- * Mutate groups.json (or .local.json in dev mode) under the full cross-host
- * lock + OCC-retry stack (see authorization/settings-file-store.ts).
- * `mutate` is called with the current parsed file (`null` if it doesn't
- * exist yet) and the version to write under; it returns the next raw
- * payload, or `null` for a deliberate no-op. The returned payload is
- * validated against {@link GroupsFileSchema} before being written,
- * preserving the previous validate-before-write behavior of the old
- * `saveInternalGroups`.
+ * Mutate groups.json (groups.local.json in dev mode) under the full cross-host
+ * lock + OCC-retry stack (see authorization/settings-file-store.ts). `mutate`
+ * receives the current parsed file (`null` if absent) and the version to write
+ * under, and returns the next raw payload or `null` for a deliberate no-op.
+ * The payload is validated against {@link GroupsFileSchema} before writing.
  */
 export async function mutateGroupsFile(branchRoot, mode, mutate, options) {
     const groupsPath = getGroupsFilePath(branchRoot, mode);

package/dist/authorization/groups/schema.d.ts

@@ -1,6 +1,3 @@
-/**
- * Schema for groups.json file
- */
 import { z } from 'zod';
 import type { CanopyUserId, CanopyGroupId } from '../../types.js';
 /**
@@ -51,9 +48,6 @@ export declare const GroupsFileSchema: z.ZodObject<{
     writeId?: string | undefined;
 }>;
 export type GroupsFile = z.infer<typeof GroupsFileSchema>;
-/**
- * Internal group representation
- */
 export interface InternalGroup {
     id: CanopyGroupId;
     name: string;

package/dist/authorization/groups/schema.js

@@ -1,15 +1,12 @@
-/**
- * Schema for groups.json file
- */
 import { z } from 'zod';
 /**
  * Schema for .canopycms/groups.json
  */
 export const GroupsFileSchema = z.object({
-    // Managed by writeOccJsonFile (see authorization/settings-file-store.ts) —
-    // the single OCC counter for this file. Optional so a hand-written file
-    // with no version field parses as version 0. A legacy `contentVersion`
-    // field (if present) is silently stripped by this non-strict zod parse.
+    // Managed by writeOccJsonFile (see authorization/settings-file-store.ts):
+    // the single OCC counter for this file. Optional so a hand-written file with
+    // no version field parses as version 0; a stray `contentVersion` key is
+    // silently stripped by this non-strict zod parse.
     version: z.number().int().nonnegative().optional(),
     writeId: z.string().optional(),
     updatedAt: z.string().datetime(),