canopycms 0.0.59 → 0.0.61-int.74

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

@@ -11,8 +11,8 @@ import type { PermissionPath } from '../types';
  * Any path containing '..' or other traversal sequences will be rejected.
  */
 export declare const PermissionsFileSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    contentVersion: z.ZodOptional<z.ZodNumber>;
+    version: z.ZodOptional<z.ZodNumber>;
+    writeId: z.ZodOptional<z.ZodString>;
     updatedAt: z.ZodString;
     updatedBy: z.ZodType<CanopyUserId>;
     pathPermissions: z.ZodArray<z.ZodObject<{
@@ -81,7 +81,6 @@ export declare const PermissionsFileSchema: z.ZodObject<{
         } | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    version: 1;
     updatedAt: string;
     updatedBy: string;
     pathPermissions: {
@@ -101,9 +100,9 @@ export declare const PermissionsFileSchema: z.ZodObject<{
             allowedGroups?: string[] | undefined;
         } | undefined;
     }[];
-    contentVersion?: number | undefined;
+    version?: number | undefined;
+    writeId?: string | undefined;
 }, {
-    version: 1;
     updatedAt: string;
     updatedBy: string;
     pathPermissions: {
@@ -123,11 +122,13 @@ export declare const PermissionsFileSchema: z.ZodObject<{
             allowedGroups?: string[] | undefined;
         } | undefined;
     }[];
-    contentVersion?: number | undefined;
+    version?: number | undefined;
+    writeId?: string | undefined;
 }>;
 export type PermissionsFile = z.infer<typeof PermissionsFileSchema>;
 /**
- * Default permissions file
+ * Default permissions file. Omits `version`/`writeId` — the writer
+ * (mutateSettingsJsonFile via writeOccJsonFile) manages those.
  */
 export declare function createDefaultPermissionsFile(userId: CanopyUserId): PermissionsFile;
 //# sourceMappingURL=schema.d.ts.map

package/dist/authorization/permissions/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/authorization/permissions/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,aAAa,CAAA;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAyB9C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;eAIP,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAShD,CAAA;AAEF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEnE;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAOlF"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/authorization/permissions/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,YAAY,EAAiB,MAAM,aAAa,CAAA;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAyB9C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;eAQP,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAShD,CAAA;AAEF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEnE;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAMlF"}

package/dist/authorization/permissions/schema.js

@@ -31,8 +31,12 @@ const permissionPathSchema = z
  * Any path containing '..' or other traversal sequences will be rejected.
  */
 export const PermissionsFileSchema = z.object({
-    version: z.literal(1),
-    contentVersion: z.number().optional(), // For optimistic locking
+    // 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.
+    version: z.number().int().nonnegative().optional(),
+    writeId: z.string().optional(),
     updatedAt: z.string().datetime(),
     updatedBy: z.string(),
     pathPermissions: z.array(z.object({
@@ -43,11 +47,11 @@ export const PermissionsFileSchema = z.object({
     })),
 });
 /**
- * Default permissions file
+ * Default permissions file. Omits `version`/`writeId` — the writer
+ * (mutateSettingsJsonFile via writeOccJsonFile) manages those.
  */
 export function createDefaultPermissionsFile(userId) {
     return {
-        version: 1,
         updatedAt: new Date().toISOString(),
         updatedBy: userId,
         pathPermissions: [],

package/dist/authorization/permissions/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/authorization/permissions/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAGnD,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAA6B,CAAC,CAAC,QAAQ,EAAE;IACvE,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAA8B,CAAC,CAAC,QAAQ,EAAE;CAC1E,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,oBAAoB,GAAG,CAAC;KAC3B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,SAAS,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IACtB,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAA;IACvC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;YAC3B,OAAO,EAAE,MAAM,CAAC,KAAK;SACtB,CAAC,CAAA;QACF,OAAO,CAAC,CAAC,KAAK,CAAA;IAChB,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAA;AACpB,CAAC,CAAyC,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACrB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,yBAAyB;IAChE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,MAAM,EAA6B;IAChD,eAAe,EAAE,CAAC,CAAC,KAAK,CACtB,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,oBAAoB;QAC1B,IAAI,EAAE,sBAAsB,CAAC,QAAQ,EAAE;QACvC,IAAI,EAAE,sBAAsB,CAAC,QAAQ,EAAE;QACvC,MAAM,EAAE,sBAAsB,CAAC,QAAQ,EAAE;KAC1C,CAAC,CACH;CACF,CAAC,CAAA;AAIF;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAoB;IAC/D,OAAO;QACL,OAAO,EAAE,CAAC;QACV,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,SAAS,EAAE,MAAM;QACjB,eAAe,EAAE,EAAE;KACpB,CAAA;AACH,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/authorization/permissions/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAGnD,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAA6B,CAAC,CAAC,QAAQ,EAAE;IACvE,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAA8B,CAAC,CAAC,QAAQ,EAAE;CAC1E,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,oBAAoB,GAAG,CAAC;KAC3B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,SAAS,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IACtB,MAAM,MAAM,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAA;IACvC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;YAC3B,OAAO,EAAE,MAAM,CAAC,KAAK;SACtB,CAAC,CAAA;QACF,OAAO,CAAC,CAAC,KAAK,CAAA;IAChB,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAA;AACpB,CAAC,CAAyC,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,2EAA2E;IAC3E,wEAAwE;IACxE,uEAAuE;IACvE,wEAAwE;IACxE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAClD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,MAAM,EAA6B;IAChD,eAAe,EAAE,CAAC,CAAC,KAAK,CACtB,CAAC,CAAC,MAAM,CAAC;QACP,IAAI,EAAE,oBAAoB;QAC1B,IAAI,EAAE,sBAAsB,CAAC,QAAQ,EAAE;QACvC,IAAI,EAAE,sBAAsB,CAAC,QAAQ,EAAE;QACvC,MAAM,EAAE,sBAAsB,CAAC,QAAQ,EAAE;KAC1C,CAAC,CACH;CACF,CAAC,CAAA;AAIF;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAoB;IAC/D,OAAO;QACL,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,SAAS,EAAE,MAAM;QACjB,eAAe,EAAE,EAAE;KACpB,CAAA;AACH,CAAC"}

package/dist/authorization/protected-branch.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Protected base branch predicate.
+ *
+ * The base branch (the PR base — usually `main`) can never be submitted for
+ * review (both modes: submitting it would push straight to itself, bypassing
+ * review) and is read-only in the editor in prod (dev needs the base branch
+ * editable since the developer always lands there — see ARCHITECTURE.md
+ * "Protected Base Branch"). This is the single source of truth other modules
+ * key off of; do not re-derive the comparison elsewhere.
+ */
+import type { CanopyConfig } from '../config';
+export interface BranchProtection {
+    /** True when branchName resolves to the configured base branch. */
+    isProtected: boolean;
+    /** True when the branch must never be submitted for review (both modes). */
+    submitBlocked: boolean;
+    /** True when the branch is read-only in the editor (prod only). */
+    readOnly: boolean;
+}
+/**
+ * Determine whether `branchName` is the protected base branch for `config`.
+ *
+ * Comparison is sanitization-aware: branch metadata names are sanitized
+ * (`sanitizeBranchName`) but `config.defaultBaseBranch` holds the raw git
+ * name, so both sides are sanitized before comparing.
+ *
+ * `recordedBaseBranch` (a branch's own `baseBranch` field, i.e. its recorded
+ * fork point) is an additional, independent protection clause: a branch whose
+ * fork point equals its own name IS a base workspace, regardless of what
+ * `config.defaultBaseBranch` says right now. This matters because in dev
+ * mode, `config.defaultBaseBranch` tracks live git HEAD (`refreshActiveBranch`)
+ * and can drift to a different branch after the base workspace was created --
+ * without this clause, that drift would silently un-protect the branch the
+ * base workspace was actually forked from. The clause is purely additive: it
+ * only ever adds protection the config clause didn't already grant, so a
+ * normal editing branch (`baseBranch !== name`) is never falsely protected.
+ */
+export declare function getBranchProtection(config: Pick<CanopyConfig, 'mode' | 'defaultBaseBranch'>, branchName: string, recordedBaseBranch?: string): BranchProtection;
+//# sourceMappingURL=protected-branch.d.ts.map

package/dist/authorization/protected-branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected-branch.d.ts","sourceRoot":"","sources":["../../src/authorization/protected-branch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAM7C,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAA;IACpB,4EAA4E;IAC5E,aAAa,EAAE,OAAO,CAAA;IACtB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,mBAAmB,CAAC,EACxD,UAAU,EAAE,MAAM,EAClB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,gBAAgB,CAWlB"}

package/dist/authorization/protected-branch.js

@@ -0,0 +1,43 @@
+/**
+ * Protected base branch predicate.
+ *
+ * The base branch (the PR base — usually `main`) can never be submitted for
+ * review (both modes: submitting it would push straight to itself, bypassing
+ * review) and is read-only in the editor in prod (dev needs the base branch
+ * editable since the developer always lands there — see ARCHITECTURE.md
+ * "Protected Base Branch"). This is the single source of truth other modules
+ * key off of; do not re-derive the comparison elsewhere.
+ */
+// branch-name, NOT branch: this module is client-reachable (editor bundle →
+// api/guards.ts → here), and paths/branch.ts drags node:fs into the graph,
+// which breaks adopters' production `next build`.
+import { sanitizeBranchName } from '../paths/branch-name.js';
+/**
+ * Determine whether `branchName` is the protected base branch for `config`.
+ *
+ * Comparison is sanitization-aware: branch metadata names are sanitized
+ * (`sanitizeBranchName`) but `config.defaultBaseBranch` holds the raw git
+ * name, so both sides are sanitized before comparing.
+ *
+ * `recordedBaseBranch` (a branch's own `baseBranch` field, i.e. its recorded
+ * fork point) is an additional, independent protection clause: a branch whose
+ * fork point equals its own name IS a base workspace, regardless of what
+ * `config.defaultBaseBranch` says right now. This matters because in dev
+ * mode, `config.defaultBaseBranch` tracks live git HEAD (`refreshActiveBranch`)
+ * and can drift to a different branch after the base workspace was created --
+ * without this clause, that drift would silently un-protect the branch the
+ * base workspace was actually forked from. The clause is purely additive: it
+ * only ever adds protection the config clause didn't already grant, so a
+ * normal editing branch (`baseBranch !== name`) is never falsely protected.
+ */
+export function getBranchProtection(config, branchName, recordedBaseBranch) {
+    const sanitizedName = sanitizeBranchName(branchName);
+    const isProtected = sanitizedName === sanitizeBranchName(config.defaultBaseBranch ?? 'main') ||
+        (recordedBaseBranch !== undefined && sanitizedName === sanitizeBranchName(recordedBaseBranch));
+    return {
+        isProtected,
+        submitBlocked: isProtected,
+        readOnly: isProtected && config.mode === 'prod',
+    };
+}
+//# sourceMappingURL=protected-branch.js.map

package/dist/authorization/protected-branch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protected-branch.js","sourceRoot":"","sources":["../../src/authorization/protected-branch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,4EAA4E;AAC5E,2EAA2E;AAC3E,kDAAkD;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAWzD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAwD,EACxD,UAAkB,EAClB,kBAA2B;IAE3B,MAAM,aAAa,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAA;IACpD,MAAM,WAAW,GACf,aAAa,KAAK,kBAAkB,CAAC,MAAM,CAAC,iBAAiB,IAAI,MAAM,CAAC;QACxE,CAAC,kBAAkB,KAAK,SAAS,IAAI,aAAa,KAAK,kBAAkB,CAAC,kBAAkB,CAAC,CAAC,CAAA;IAEhG,OAAO;QACL,WAAW;QACX,aAAa,EAAE,WAAW;QAC1B,QAAQ,EAAE,WAAW,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;KAChD,CAAA;AACH,CAAC"}

package/dist/authorization/settings-file-store.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Cross-host layered locking for settings JSON files (permissions.json,
+ * groups.json) in the settings workspace — a single global orphan-git-branch
+ * checkout at `{settingsRoot}` shared by every branch (see
+ * `api/settings-helpers.ts`'s `getSettingsBranchContext`).
+ *
+ * Without this helper, the write path is a classic unprotected TOCTOU: load
+ * -> compare -> mutate -> write with no lock spanning the cycle, so two warm
+ * Lambda containers (separate NFS clients on EFS) can each read the same
+ * pre-mutation file and have the second write silently clobber the first.
+ * `mutateSettingsJsonFile` closes that with the standard 3-layer recipe from
+ * docs/concurrency.md, structured identically to {@link CommentStore}'s
+ * `withMutation` (see comment-store.ts) and `BranchMetadataFileManager.save()`
+ * (see branch-metadata.ts):
+ *
+ * 1. {@link withLock} - an in-process FIFO mutex keyed by the resolved file
+ *    path. Deterministic same-process serialization.
+ * 2. {@link withOccFileLock} - a server-enforced, cross-process/cross-host
+ *    lock (proper-lockfile, mkdir-based), immune to NFS client dentry/
+ *    attribute caching. This is the actual fix for a lost permission/group
+ *    edit across two warm Lambda containers on EFS.
+ * 3. {@link withOccRetry} around {@link writeOccJsonFile} - version/writeId
+ *    based optimistic concurrency control, reloading the file fresh on
+ *    EVERY retry attempt. With layers 1-2 in place this is defense-in-depth
+ *    (e.g. a stale process from a rolling deploy writing without the lock),
+ *    not the primary safety mechanism.
+ *
+ * `writeOccJsonFile`'s managed `version`/`writeId` pair is now THE single
+ * counter for these files: the old hand-rolled `version: 1` format literal
+ * and the separate `contentVersion` field are gone. A pre-existing file on
+ * disk that still says `"version": 1` simply reads as OCC version 1 and
+ * continues incrementing from there; a leftover `contentVersion` key is
+ * silently stripped by the (non-strict, extra-keys-stripped) zod parse.
+ *
+ * Three caveats specific to these files, on top of the generic guarantee
+ * documented on `utils/occ-json-write.ts`:
+ *
+ * (a) UNLIKE comments.json/branch.json (which never leave the branch
+ *     workspace), permissions.json/groups.json are git-committed on the
+ *     settings orphan branch. `commitSettings()` (api/settings-helpers.ts)
+ *     calls `commitToSettingsBranch`, whose `pullCurrentBranch()` merge runs
+ *     AFTER this helper has released its lock, and that merge can rewrite
+ *     the file's `version` from upstream. So, unlike branch.json, `version`
+ *     here is NOT guaranteed monotonic — it remains a correctness aid (it
+ *     still catches the common same-host and short-window cross-host races)
+ *     but is advisory/defense-in-depth, not a hard guarantee. The LOCKFILE
+ *     (layer 2) is the actual cross-host correctness mechanism.
+ * (b) The git commit+push deliberately happens OUTSIDE this lock (mirrors
+ *     branch-metadata.ts keeping registry invalidation outside the lock it
+ *     protects): committing/pushing is comparatively slow network/process
+ *     I/O, and holding a mkdir-based lock across it would serialize
+ *     unrelated requests behind that I/O for no correctness gain — only the
+ *     write to the working tree needs the lock.
+ * (c) Because commit+push is outside the lock, two writers' save-then-commit
+ *     sequences can interleave (A saves+commits+pushes, B's save lands and
+ *     commits before A's push is visible, or similar), and the second
+ *     `git commit` can run against an already-clean tree. Verified benign
+ *     with simple-git 3.36: its task-error detection depends on stderr
+ *     output, and a clean-tree `git commit` exits 1 with "nothing to
+ *     commit" on STDOUT only, so `git.commit()` resolves rather than
+ *     throwing. Re-verify this on any simple-git upgrade.
+ */
+import { type OccWriteResult } from '../utils/occ-json-write';
+/**
+ * Thrown when the lock/OCC-retry stack in {@link mutateSettingsJsonFile}
+ * exhausts every attempt without landing a write — the file is busy with
+ * another writer. Callers translate this into a 409 ("try again").
+ */
+export declare class SettingsFileConflictError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown by a caller's `mutate` callback when an app-level
+ * `expectedContentVersion` sent by a client doesn't match the file's current
+ * `version`. A different concern from {@link SettingsFileConflictError}:
+ * this is a real edit conflict the user must resolve by reloading, not
+ * transient lock contention a retry can fix — and indeed it never IS
+ * retried, since {@link withOccRetry} only recognizes
+ * {@link OccWriteConflictError} as retryable, so this propagates on the
+ * very first attempt.
+ */
+export declare class SettingsVersionConflictError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Structural shape `mutateSettingsJsonFile` needs from a parsed settings
+ * file: just enough to read the OCC version off it without resorting to
+ * `any`. Concrete file types (e.g. `PermissionsFile`, `GroupsFile`) satisfy
+ * this automatically since `version` is optional on both.
+ */
+interface VersionedSettingsFile {
+    version?: number;
+}
+export interface MutateSettingsFileOptions<TFile extends VersionedSettingsFile> {
+    /** Path to the settings JSON file (resolved internally; need not be absolute). */
+    filePath: string;
+    /** JSON.parse + zod-parse the raw file contents. Throws propagate untouched (never retried). */
+    parse: (raw: string) => TFile;
+    /**
+     * Compute the next payload from the current parsed file (`null` on
+     * ENOENT) and the version to write it under. Return `null` for a
+     * deliberate no-op — the write is skipped entirely. Called once per
+     * retry attempt against freshly reloaded state, so it must be safe to
+     * call more than once; anything it throws (besides the retried
+     * `OccWriteConflictError`, which it should never throw itself) propagates
+     * out of `mutateSettingsJsonFile` untouched.
+     */
+    mutate: (current: TFile | null, version: number) => Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
+    /** Forwarded to writeOccJsonFile. Pass 0 in tests. */
+    settleMs?: number;
+    /** Forwarded to withOccRetry. */
+    maxAttempts?: number;
+}
+/**
+ * Run a load -> mutate -> write cycle for a settings JSON file under the
+ * full lock + OCC-retry stack described in the module doc comment above. A
+ * conflict that survives every retry surfaces as
+ * {@link SettingsFileConflictError}; everything else — including
+ * {@link SettingsVersionConflictError} thrown by `mutate`, and any
+ * parse/validation error — propagates untouched.
+ *
+ * Returns the `writeOccJsonFile` result, or `null` if `mutate` chose a
+ * no-op (no write happened).
+ */
+export declare function mutateSettingsJsonFile<TFile extends VersionedSettingsFile>(opts: MutateSettingsFileOptions<TFile>): Promise<OccWriteResult | null>;
+export {};
+//# sourceMappingURL=settings-file-store.d.ts.map

package/dist/authorization/settings-file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-file-store.d.ts","sourceRoot":"","sources":["../../src/authorization/settings-file-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAMH,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAA;AAGhC;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,SAAwC;CAI5D;AAED;;;;;;;;;GASG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;gBACzC,OAAO,SAAyE;CAI7F;AAED;;;;;GAKG;AACH,UAAU,qBAAqB;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,yBAAyB,CAAC,KAAK,SAAS,qBAAqB;IAC5E,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAA;IAChB,gGAAgG;IAChG,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,KAAK,CAAA;IAC7B;;;;;;;;OAQG;IACH,MAAM,EAAE,CACN,OAAO,EAAE,KAAK,GAAG,IAAI,EACrB,OAAO,EAAE,MAAM,KACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;IAC7E,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAgCD;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,SAAS,qBAAqB,EAC9E,IAAI,EAAE,yBAAyB,CAAC,KAAK,CAAC,GACrC,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA6BhC"}

package/dist/authorization/settings-file-store.js

@@ -0,0 +1,156 @@
+/**
+ * Cross-host layered locking for settings JSON files (permissions.json,
+ * groups.json) in the settings workspace — a single global orphan-git-branch
+ * checkout at `{settingsRoot}` shared by every branch (see
+ * `api/settings-helpers.ts`'s `getSettingsBranchContext`).
+ *
+ * Without this helper, the write path is a classic unprotected TOCTOU: load
+ * -> compare -> mutate -> write with no lock spanning the cycle, so two warm
+ * Lambda containers (separate NFS clients on EFS) can each read the same
+ * pre-mutation file and have the second write silently clobber the first.
+ * `mutateSettingsJsonFile` closes that with the standard 3-layer recipe from
+ * docs/concurrency.md, structured identically to {@link CommentStore}'s
+ * `withMutation` (see comment-store.ts) and `BranchMetadataFileManager.save()`
+ * (see branch-metadata.ts):
+ *
+ * 1. {@link withLock} - an in-process FIFO mutex keyed by the resolved file
+ *    path. Deterministic same-process serialization.
+ * 2. {@link withOccFileLock} - a server-enforced, cross-process/cross-host
+ *    lock (proper-lockfile, mkdir-based), immune to NFS client dentry/
+ *    attribute caching. This is the actual fix for a lost permission/group
+ *    edit across two warm Lambda containers on EFS.
+ * 3. {@link withOccRetry} around {@link writeOccJsonFile} - version/writeId
+ *    based optimistic concurrency control, reloading the file fresh on
+ *    EVERY retry attempt. With layers 1-2 in place this is defense-in-depth
+ *    (e.g. a stale process from a rolling deploy writing without the lock),
+ *    not the primary safety mechanism.
+ *
+ * `writeOccJsonFile`'s managed `version`/`writeId` pair is now THE single
+ * counter for these files: the old hand-rolled `version: 1` format literal
+ * and the separate `contentVersion` field are gone. A pre-existing file on
+ * disk that still says `"version": 1` simply reads as OCC version 1 and
+ * continues incrementing from there; a leftover `contentVersion` key is
+ * silently stripped by the (non-strict, extra-keys-stripped) zod parse.
+ *
+ * Three caveats specific to these files, on top of the generic guarantee
+ * documented on `utils/occ-json-write.ts`:
+ *
+ * (a) UNLIKE comments.json/branch.json (which never leave the branch
+ *     workspace), permissions.json/groups.json are git-committed on the
+ *     settings orphan branch. `commitSettings()` (api/settings-helpers.ts)
+ *     calls `commitToSettingsBranch`, whose `pullCurrentBranch()` merge runs
+ *     AFTER this helper has released its lock, and that merge can rewrite
+ *     the file's `version` from upstream. So, unlike branch.json, `version`
+ *     here is NOT guaranteed monotonic — it remains a correctness aid (it
+ *     still catches the common same-host and short-window cross-host races)
+ *     but is advisory/defense-in-depth, not a hard guarantee. The LOCKFILE
+ *     (layer 2) is the actual cross-host correctness mechanism.
+ * (b) The git commit+push deliberately happens OUTSIDE this lock (mirrors
+ *     branch-metadata.ts keeping registry invalidation outside the lock it
+ *     protects): committing/pushing is comparatively slow network/process
+ *     I/O, and holding a mkdir-based lock across it would serialize
+ *     unrelated requests behind that I/O for no correctness gain — only the
+ *     write to the working tree needs the lock.
+ * (c) Because commit+push is outside the lock, two writers' save-then-commit
+ *     sequences can interleave (A saves+commits+pushes, B's save lands and
+ *     commits before A's push is visible, or similar), and the second
+ *     `git commit` can run against an already-clean tree. Verified benign
+ *     with simple-git 3.36: its task-error detection depends on stderr
+ *     output, and a clean-tree `git commit` exits 1 with "nothing to
+ *     commit" on STDOUT only, so `git.commit()` resolves rather than
+ *     throwing. Re-verify this on any simple-git upgrade.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { withLock } from '../utils/async-mutex.js';
+import { writeOccJsonFile, withOccRetry, withOccFileLock, OccWriteConflictError, } from '../utils/occ-json-write.js';
+import { isNotFoundError } from '../utils/error.js';
+/**
+ * Thrown when the lock/OCC-retry stack in {@link mutateSettingsJsonFile}
+ * exhausts every attempt without landing a write — the file is busy with
+ * another writer. Callers translate this into a 409 ("try again").
+ */
+export class SettingsFileConflictError extends Error {
+    constructor(message = 'Settings are busy, please try again') {
+        super(message);
+        this.name = 'SettingsFileConflictError';
+    }
+}
+/**
+ * Thrown by a caller's `mutate` callback when an app-level
+ * `expectedContentVersion` sent by a client doesn't match the file's current
+ * `version`. A different concern from {@link SettingsFileConflictError}:
+ * this is a real edit conflict the user must resolve by reloading, not
+ * transient lock contention a retry can fix — and indeed it never IS
+ * retried, since {@link withOccRetry} only recognizes
+ * {@link OccWriteConflictError} as retryable, so this propagates on the
+ * very first attempt.
+ */
+export class SettingsVersionConflictError extends Error {
+    constructor(message = 'Settings were modified by another user. Please reload and try again.') {
+        super(message);
+        this.name = 'SettingsVersionConflictError';
+    }
+}
+/**
+ * Reload the file fresh and report the version to feed both `mutate()` and
+ * `writeOccJsonFile`'s `expectedVersion`.
+ *
+ * ENOENT is the ONLY case that maps to a `null` `occExpectedVersion` (the
+ * create-via-link path in {@link writeOccJsonFile}): an EXISTING file —
+ * even one hand-written without a `version` field — maps to `0` and takes
+ * the rename-based update path instead. Conflating the two would make
+ * `writeOccJsonFile` attempt a `link()` create against a file that already
+ * exists, spuriously failing with EEXIST instead of doing a normal
+ * versioned update. (Same contract as `CommentStore`'s `loadWithVersion` in
+ * comment-store.ts.)
+ */
+async function loadCurrent(filePath, parse) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (isNotFoundError(err)) {
+            return { current: null, occExpectedVersion: null };
+        }
+        throw err;
+    }
+    const parsed = parse(raw);
+    return { current: parsed, occExpectedVersion: parsed.version ?? 0 };
+}
+/**
+ * Run a load -> mutate -> write cycle for a settings JSON file under the
+ * full lock + OCC-retry stack described in the module doc comment above. A
+ * conflict that survives every retry surfaces as
+ * {@link SettingsFileConflictError}; everything else — including
+ * {@link SettingsVersionConflictError} thrown by `mutate`, and any
+ * parse/validation error — propagates untouched.
+ *
+ * Returns the `writeOccJsonFile` result, or `null` if `mutate` chose a
+ * no-op (no write happened).
+ */
+export async function mutateSettingsJsonFile(opts) {
+    const resolved = path.resolve(opts.filePath);
+    try {
+        return await withLock(resolved, () => withOccFileLock(resolved, () => withOccRetry(async () => {
+            const { current, occExpectedVersion } = await loadCurrent(resolved, opts.parse);
+            const version = occExpectedVersion ?? 0;
+            const payload = await opts.mutate(current, version);
+            if (payload === null) {
+                return null;
+            }
+            return writeOccJsonFile(resolved, payload, {
+                expectedVersion: occExpectedVersion,
+                settleMs: opts.settleMs,
+            });
+        }, { maxAttempts: opts.maxAttempts })));
+    }
+    catch (err) {
+        if (err instanceof OccWriteConflictError) {
+            throw new SettingsFileConflictError();
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=settings-file-store.js.map

package/dist/authorization/settings-file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-file-store.js","sourceRoot":"","sources":["../../src/authorization/settings-file-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAA;AACjC,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAC/C,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,qBAAqB,GAEtB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEhD;;;;GAIG;AACH,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAY,OAAO,GAAG,qCAAqC;QACzD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAA;IACzC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACrD,YAAY,OAAO,GAAG,sEAAsE;QAC1F,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAA;IAC5C,CAAC;CACF;AAoCD;;;;;;;;;;;;GAYG;AACH,KAAK,UAAU,WAAW,CACxB,QAAgB,EAChB,KAA6B;IAE7B,IAAI,GAAW,CAAA;IACf,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC5C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAA;QACpD,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;IACzB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,CAAC,OAAO,IAAI,CAAC,EAAE,CAAA;AACrE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAsC;IAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAE5C,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,CACnC,eAAe,CAAC,QAAQ,EAAE,GAAG,EAAE,CAC7B,YAAY,CACV,KAAK,IAAI,EAAE;YACT,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;YAC/E,MAAM,OAAO,GAAG,kBAAkB,IAAI,CAAC,CAAA;YACvC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;YACnD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,gBAAgB,CAAC,QAAQ,EAAE,OAAO,EAAE;gBACzC,eAAe,EAAE,kBAAkB;gBACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB,CAAC,CAAA;QACJ,CAAC,EACD,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAClC,CACF,CACF,CAAA;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;YACzC,MAAM,IAAI,yBAAyB,EAAE,CAAA;QACvC,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC"}

package/dist/branch-health.d.ts

@@ -0,0 +1,78 @@
+import type { BranchMetadata } from './types';
+/**
+ * Admin-facing health classification of every directory under a branches
+ * root (`baseRoot`), including ones the {@link BranchRegistry} quarantines
+ * out of normal listings. Two stuck states have no in-product recovery
+ * without this: a branch dir whose `.canopy-meta/branch.json` is corrupt
+ * (registry now silently drops it — see branch-registry.ts's
+ * `scanBranchDirectories` quarantine), and an orphan dir with no
+ * `branch.json` at all (left behind by a partial delete crash — see
+ * `api/branch.ts`'s delete handler). Both are invisible to admins in prod,
+ * who have no filesystem access.
+ *
+ * `scanBranchHealth` mirrors the registry's own directory-listing rules
+ * (skip non-directories and dot-prefixed names) so its classification never
+ * disagrees with what the registry itself would show as "missing".
+ */
+export type BranchHealthKind = 'healthy' | 'corrupt-metadata' | 'orphan';
+export interface BranchHealthEntry {
+    dirName: string;
+    kind: BranchHealthKind;
+    /** True when this directory is the sanitized base-branch directory. */
+    isBaseBranch?: boolean;
+    /** healthy only */
+    branch?: BranchMetadata;
+    /** corrupt-metadata only: message describing why the file failed to load. */
+    parseError?: string;
+    /** corrupt-metadata only: branch.json's mtime, ISO. Omitted if branch.json itself couldn't be stat'd. */
+    metaMtime?: string;
+    /** orphan only: whether a `.git` directory is present (partial clone vs. fully-provisioned). */
+    hasGitDir?: boolean;
+    /** orphan only: the directory's own mtime, ISO. */
+    dirMtime?: string;
+    /** orphan only: age of the directory's mtime in ms, clamped to >= 0. */
+    ageMs?: number;
+    /**
+     * [H1] Present iff the dir's provisioning init-lock marker exists on disk,
+     * for orphan and corrupt-metadata entries only. Presence alone means
+     * nothing -- a crashed provisioner's lock lingers forever (proper-lockfile
+     * stale locks are only reaped by a later acquisition attempt, and a health
+     * scan never acquires). Freshness (`ageMs`) is the actual signal admin
+     * actions gate on.
+     */
+    provisioningLock?: {
+        mtime: string;
+        ageMs: number;
+    };
+}
+/**
+ * The on-disk path of the cross-process provisioning lock marker for a
+ * given branch directory, matching `branch-workspace.ts`'s
+ * `ensureGitWorkspace()` exactly:
+ *
+ * ```ts
+ * acquireProvisioningLock(
+ *   path.dirname(branchRoot),         // === baseRoot
+ *   `.${path.basename(branchRoot)}.init.lock`,
+ * )
+ * ```
+ *
+ * `acquireProvisioningLock` passes this name as `lockfilePath`, which
+ * overrides proper-lockfile's default `${target}.lock` naming, so the lock
+ * marker itself (a directory, mkdir-based) lives at exactly this path -- no
+ * extra `.lock` suffix.
+ */
+export declare function provisioningLockPath(baseRoot: string, dirName: string): string;
+/**
+ * Scan every directory under `baseRoot` and classify it as healthy,
+ * corrupt-metadata, or orphan. Never throws for a single bad directory --
+ * one dir's unreadable/unparseable metadata must not take down the whole
+ * scan (same rationale as the registry's own quarantine behavior).
+ *
+ * Tolerates a missing `baseRoot` (returns `[]`) so the admin endpoint can
+ * call this unconditionally without a pre-existence check.
+ */
+export declare function scanBranchHealth(baseRoot: string, opts: {
+    baseBranchName: string;
+}): Promise<BranchHealthEntry[]>;
+//# sourceMappingURL=branch-health.d.ts.map

package/dist/branch-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-health.d.ts","sourceRoot":"","sources":["../src/branch-health.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAK7C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,kBAAkB,GAAG,QAAQ,CAAA;AAExE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,gBAAgB,CAAA;IACtB,uEAAuE;IACvE,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,mBAAmB;IACnB,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yGAAyG;IACzG,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gGAAgG;IAChG,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CACpD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9E;AA2BD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GAC/B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAmG9B"}