canopycms 0.0.65 → 0.0.66-int.82

package/dist/content-id-index.js

@@ -1,3 +1,25 @@
+/**
+ * The ContentId -> file path index.
+ *
+ * Every entry file carries a stable id in its filename (`<type>.<slug>.<id>.md`),
+ * and this index is what makes an id-based lookup cheap instead of a directory
+ * walk. `ContentStore` owns an instance and consults it on every id-addressed
+ * read.
+ *
+ * Coherency is the whole problem here, and it is cross-process: two Lambdas and
+ * the worker can all mutate one branch on shared storage. The design is an
+ * on-disk generation marker (`content-index-generation.ts`) plus an in-process
+ * registry (`content-index-registry.ts`) — two files whose names read as
+ * near-synonyms and do unrelated jobs. Read
+ * ../../../docs/concurrency.md before changing any of the three.
+ *
+ * Also here: the filename-grammar helpers (`extractIdFromFilename`,
+ * `extractEntryTypeFromFilename`, `extractSlugFromFilename`). Note that this
+ * grammar is LOOSER than what `parseSlug` accepts, which is the gap
+ * `static/`'s `assertRoutableSlugs` exists to catch at build time.
+ *
+ * Module map: ./AGENTS.md.
+ */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { isValidId } from './id.js';

package/dist/content-listing.js

@@ -44,6 +44,9 @@ export const readEntryData = async (filePath, format, bodyFieldName = 'body') =>
         if (format === 'yaml') {
             return asRecord(yamlParse(raw));
         }
+        // Read-only here, and the result is copied immediately below before anything
+        // is written into it -- see that comment for the hazard being avoided.
+        // eslint-disable-next-line no-restricted-syntax
         const parsed = matter(raw);
         // Copy before writing the body in. gray-matter keeps a PROCESS-GLOBAL cache keyed by file
         // content and hands every caller the same `data` object instance, so mutating it in place

package/dist/content-reader.d.ts

@@ -11,7 +11,11 @@ export interface ContentReaderOptions {
     getBranchContext?: (branch: string) => Promise<BranchContext | null>;
 }
 export interface ReadContentInput {
-    /** Resolved schema path (e.g., content/posts or content/home). */
+    /**
+     * Resolved schema path (e.g., content/posts or content/home). An entry-TYPE path like
+     * `content/home` is valid and resolves that singleton -- except under `urlAddressableOnly`
+     * below, which rejects it.
+     */
     entryPath: LogicalPath;
     slug?: Slug;
     branch?: string;
@@ -21,6 +25,26 @@ export interface ReadContentInput {
     resolveReferences?: boolean;
     /** Whether to resolve entry:ID links in body/markdown fields. Defaults to true. */
     resolveEntryLinks?: boolean;
+    /**
+     * This read is addressing an entry by its PUBLISHED URL, so accept only what enumeration
+     * publishes. Two rules, both off by default:
+     *
+     * 1. `entryPath` must be a COLLECTION. A published URL is `/<collectionSegments>/<slug>` (or
+     *    the collapsed collection path, for an index entry), so its non-slug segments are always
+     *    collection names. An `entryPath` that resolves to an entry-TYPE item instead would be
+     *    delegated by `ContentStore.buildPaths` to the parent collection -- answering at
+     *    `/<collection>/<typeName>` and `/<collection>/<typeName>/<slug>`, neither of which any
+     *    forward surface emits.
+     * 2. The resolved entry's type must be one its collection declares, matching the
+     *    `parseTypedFilename(filename, collection.entries)` check `listEntries` applies. A legacy
+     *    untyped file has no type token to fail on -- see `declaresEntryType`.
+     *
+     * Set by `readByUrlPath` and nothing else. Note what it does NOT do: `read({ entryPath:
+     * 'content/home' })` and direct `ContentStore` use keep the entry-type delegation, which is a
+     * supported API and the only way to address a singleton structurally. Misusing this flag can
+     * only make a read stricter, never looser.
+     */
+    urlAddressableOnly?: boolean;
 }
 /**
  * Structural metadata surfaced alongside a resolved content read. Shared by

package/dist/content-reader.js

@@ -122,6 +122,13 @@ export const createContentReader = (options) => {
     const readDocument = async (input) => {
         const { entryPath, slug, branchName, user } = resolveTarget(input);
         const { context, branchRoot, store } = await resolveStore(branchName);
+        // Rule 1 of urlAddressableOnly (see ReadContentInput): a published URL's non-slug segments
+        // are collection names, so a candidate landing on an entry-TYPE item can only ever produce a
+        // URL enumeration never emits. NO_SCHEMA_ITEM is what assertCollection raises for exactly
+        // this condition, and readByUrlPath treats it as a miss and tries the next candidate.
+        if (input.urlAddressableOnly && !store.isCollectionPath(entryPath)) {
+            throw new ContentStoreError(`Path is not a collection: ${entryPath}`, 'NO_SCHEMA_ITEM');
+        }
         // Get the path WITHOUT reading the file
         let relativePath;
         // Absolute filesystem path to the entry file. Surfaced on read() / readByUrlPath()
@@ -151,6 +158,14 @@ export const createContentReader = (options) => {
             const code = err instanceof ContentStoreError ? err.code : 'VALIDATION';
             throw new ContentStoreError(message, code);
         }
+        // Rule 2 of urlAddressableOnly (see ReadContentInput): buildPaths' directory scan matches on
+        // slug alone, so it happily returns a file whose type token the collection no longer (or
+        // never did) declare -- a file listEntries skips. Checked here rather than inside the scan so
+        // the write path can still find, edit and rename it; making it unfindable would make the
+        // mistake unrecoverable through the editor.
+        if (input.urlAddressableOnly && !store.declaresEntryType(entryPath, entryType)) {
+            throw new ContentStoreError(`Entry type '${entryType}' is not declared by ${entryPath}`, 'NO_SCHEMA_ITEM');
+        }
         // Check permissions BEFORE reading the file (security)
         const shouldCheckPermissions = !(isDeployedStatic(services.config) || isBuildMode());
         if (shouldCheckPermissions) {

package/dist/content-store.d.ts

@@ -130,7 +130,17 @@ export interface ContentStoreOptions {
      * non-default content root would otherwise get an index built from a
      * directory that does not exist: empty, so every ID-based lookup (reference
      * resolution, entry links, order cleanup, rename) silently misses while
-     * path-based reads keep working. Defaults to 'content'.
+     * path-based reads keep working.
+     *
+     * Defaults to 'content'.
+     *
+     * ENFORCED BY LINT, not by the type. Omitting it is silent and data-shaped
+     * when wrong -- nothing throws, nothing logs, and only ID-addressed lookups
+     * miss -- so every production construction must pass it. That is checked by
+     * the `no-restricted-syntax` rule on `new ContentStore(...)` in
+     * eslint.config.mjs, which is scoped to non-test sources: making the field
+     * required in the TYPE would have forced the argument on 61 test call sites
+     * that legitimately want the default, for no gain in the 11 production ones.
      */
     contentRootName?: string;
     /**
@@ -289,6 +299,45 @@ export declare class ContentStore {
      */
     getSchemaItems(): IterableIterator<FlatSchemaItem>;
     private assertSchemaItem;
+    /**
+     * Is this path a COLLECTION schema item?
+     *
+     * The non-throwing form of `assertCollection`, reading the same `schemaIndex` -- which is the
+     * point. A caller that gates on this cannot disagree with what `buildPaths` will then do: the
+     * Map is last-wins, so where a subcollection's path collides with a parent's entry-type name
+     * both this and `buildPaths` see the collection. A `find` over the flat schema LIST is
+     * first-wins and would not.
+     *
+     * Type-only, deliberately -- `resolvePath` additionally requires `entries`, but a collection
+     * with subcollections and no entries of its own is legal, and mirroring that stricter test here
+     * would reject something `buildPaths` accepts.
+     *
+     * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
+     * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+     */
+    isCollectionPath(collectionPath: LogicalPath): boolean;
+    /**
+     * Does this collection declare `entryTypeName` in its `entries` config?
+     *
+     * Mirrors `parseTypedFilename(filename, collection.entries)`, which is how `listEntries` decides
+     * whether a file on disk is one of the collection's entries at all. `buildPaths`' own directory
+     * scan deliberately does NOT check this -- it matches on slug alone, so that an entry whose type
+     * was renamed out of the schema stays findable and therefore still editable, renameable and
+     * deletable. Only URL resolution consults this, so what enumeration hides is not served.
+     *
+     * Returns FALSE when the collection declares no `entries` at all, which is stricter than
+     * `parseTypedFilename`'s own `if (entryTypes && ...)` guard and deliberately so: the enumerating
+     * surface is not `parseTypedFilename`, it is `listCollectionEntries`, and that returns `[]`
+     * outright for a collection with no `entries`. A collections-only container therefore publishes
+     * nothing, so a URL read that resolved a file sitting in one would be answering where nothing is
+     * advertised -- the exact disagreement this predicate exists to close. Such a file cannot have
+     * been created by the CMS (there is no entry type to create it as); it arrived by hand, by merge
+     * or by retrofit, and it is invisible to the sitemap and to static params either way.
+     *
+     * Returns true for a path that is not a collection at all, because that is rule 1's question,
+     * not this one's -- and under `urlAddressableOnly` rule 1 has already rejected it.
+     */
+    declaresEntryType(collectionPath: LogicalPath, entryTypeName: string): boolean;
     private assertCollection;
     /**
      * Lock key for an existing entry, addressed by its permanent content ID

package/dist/content-store.js

@@ -1,3 +1,32 @@
+/**
+ * ContentStore — the authoritative read/write boundary for entry content.
+ *
+ * Everything that creates, reads, updates, renames or deletes an entry file goes
+ * through here. `api/content.ts` is its HTTP front door.
+ *
+ * ORIENTATION — this is one of seven `content-*` modules, and picking the wrong
+ * one costs more time than reading this comment:
+ *
+ *   content-store.ts       (this file) the write boundary, plus path-and-id resolution
+ *   content-reader.ts      branch-aware read facade over this store
+ *   content-listing.ts     batch listing (`listEntries`) for adopters
+ *   content-tree.ts        the adopter-facing navigable tree
+ *   content-id-index.ts    the id -> path index this store consults
+ *   content-index-registry.ts    IN-PROCESS cache invalidation registry
+ *   content-index-generation.ts  ON-DISK generation marker  <- near-homonym of the line above,
+ *                                unrelated job; check which one you want
+ *
+ * SHAPE — the CRUD/path/lock core is genuinely interwoven (`buildPaths` alone has
+ * ~25 call sites in this file), but two clusters are only loosely attached and are the ones
+ * to read in isolation: reference resolution (`resolveReferences` and friends, at
+ * the end of the file) and ID-index coherency (`idIndex`, `recordOwnMutation`,
+ * `refreshIndexForSuspiciousLookup`).
+ *
+ * The load-bearing rules are documented at the point of the rule, not here — see
+ * in particular `ContentStoreOptions.contentRootName`, the `[SLUG]` guard in
+ * `write()`, and the read-path note on `parseSlug`. Those comments are
+ * authoritative. Module map: ./AGENTS.md.
+ */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import matter from 'gray-matter';
@@ -391,6 +420,54 @@ export class ContentStore {
         }
         return item;
     }
+    /**
+     * Is this path a COLLECTION schema item?
+     *
+     * The non-throwing form of `assertCollection`, reading the same `schemaIndex` -- which is the
+     * point. A caller that gates on this cannot disagree with what `buildPaths` will then do: the
+     * Map is last-wins, so where a subcollection's path collides with a parent's entry-type name
+     * both this and `buildPaths` see the collection. A `find` over the flat schema LIST is
+     * first-wins and would not.
+     *
+     * Type-only, deliberately -- `resolvePath` additionally requires `entries`, but a collection
+     * with subcollections and no entries of its own is legal, and mirroring that stricter test here
+     * would reject something `buildPaths` accepts.
+     *
+     * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
+     * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+     */
+    isCollectionPath(collectionPath) {
+        return this.schemaIndex.get(normalizeFilesystemPath(collectionPath))?.type === 'collection';
+    }
+    /**
+     * Does this collection declare `entryTypeName` in its `entries` config?
+     *
+     * Mirrors `parseTypedFilename(filename, collection.entries)`, which is how `listEntries` decides
+     * whether a file on disk is one of the collection's entries at all. `buildPaths`' own directory
+     * scan deliberately does NOT check this -- it matches on slug alone, so that an entry whose type
+     * was renamed out of the schema stays findable and therefore still editable, renameable and
+     * deletable. Only URL resolution consults this, so what enumeration hides is not served.
+     *
+     * Returns FALSE when the collection declares no `entries` at all, which is stricter than
+     * `parseTypedFilename`'s own `if (entryTypes && ...)` guard and deliberately so: the enumerating
+     * surface is not `parseTypedFilename`, it is `listCollectionEntries`, and that returns `[]`
+     * outright for a collection with no `entries`. A collections-only container therefore publishes
+     * nothing, so a URL read that resolved a file sitting in one would be answering where nothing is
+     * advertised -- the exact disagreement this predicate exists to close. Such a file cannot have
+     * been created by the CMS (there is no entry type to create it as); it arrived by hand, by merge
+     * or by retrofit, and it is invisible to the sitemap and to static params either way.
+     *
+     * Returns true for a path that is not a collection at all, because that is rule 1's question,
+     * not this one's -- and under `urlAddressableOnly` rule 1 has already rejected it.
+     */
+    declaresEntryType(collectionPath, entryTypeName) {
+        const item = this.schemaIndex.get(normalizeFilesystemPath(collectionPath));
+        if (item?.type !== 'collection')
+            return true;
+        if (!item.entries)
+            return false;
+        return item.entries.some((e) => e.name === entryTypeName);
+    }
     assertCollection(collectionPath) {
         const item = this.assertSchemaItem(collectionPath);
         if (item.type !== 'collection') {
@@ -499,9 +576,20 @@ export class ContentStore {
         const rootWithSep = this.root.endsWith(path.sep) ? this.root : `${this.root}${path.sep}`;
         // Entry-type items: delegate to their parent collection.
         // Uses the same {type}.{slug}.{id}.{ext} pattern as all entries.
-        // NOTE: The API layer always resolves paths via resolvePath(), which returns
-        // the parent collection directly, so this branch may only fire on direct
-        // ContentStore usage (e.g., store.read('content/home', '')).
+        //
+        // This branch is for DIRECT ContentStore usage -- store.read('content/home', ''), and the
+        // read({ entryPath: 'content/home' }) API built on it, where the slug defaults to the entry
+        // type's own name. The API layer resolves paths via resolvePath(), which returns the parent
+        // collection directly and so never lands here.
+        //
+        // That used to be an observation, and it was WRONG: readByUrlPath reached this branch too,
+        // because `resolveUrlPathCandidates` happily produces `content/<typeName>` for the URL
+        // `/<typeName>` and the delegation below then answered it with the parent collection's index
+        // entry -- a URL no forward surface publishes. It is now enforced rather than assumed:
+        // readByUrlPath requires every candidate's entryPath to be a collection (see
+        // `isCollectionPath` and `ReadContentInput.urlAddressableOnly`). Narrowing the delegation
+        // ITSELF was the wrong fix -- write()/renameEntry()/delete() resolve through here as well,
+        // and the by-URL rule has no business constraining them.
         if (schemaItem.type === 'entry-type') {
             const parentPath = schemaItem.parentPath || '';
             const parentCollection = this.schemaIndex.get(parentPath);
@@ -697,12 +785,22 @@ export class ContentStore {
             };
         }
         else {
+            // eslint-disable-next-line no-restricted-syntax -- see the copy below
             const parsed = matter(raw);
             doc = {
                 collection: schemaItem.logicalPath,
                 collectionName: schemaItem.name,
                 format: format,
-                data: parsed.data ?? {},
+                // Copy, never the object gray-matter hands back: its cache is
+                // process-global and keyed by file content, so every caller parsing the
+                // same bytes gets the SAME `data` instance (the hazard content-listing.ts
+                // documents at length). Assigning it straight into `doc.data` was safe
+                // only by accident -- `resolveReferencesInData` spreads its input, so the
+                // shared object got replaced a few lines down. But that only happens when
+                // resolution runs: with `resolveReferences: false` the caller was handed
+                // the shared instance itself, and one mutation would poison every later
+                // parse of those bytes.
+                data: { ...(parsed.data ?? {}) },
                 body: parsed.content,
                 bodyFieldName: findBodyFieldName(fields),
                 relativePath,

package/dist/context.d.ts

@@ -1,3 +1,25 @@
+/**
+ * `createCanopyContext` — the per-REQUEST content facade.
+ *
+ * Binds a user and a branch to the long-lived `CanopyServices` (see
+ * `services.ts`) and exposes the read surface page code and API handlers
+ * actually call: `read`, `readByUrlPath`, listing and tree helpers. This is the
+ * layer where authorization is applied, so a read that bypasses it bypasses
+ * path ACLs.
+ *
+ * PHASE-AWARE: at build time (`isBuildMode`) or for a static deployment
+ * (`isDeployedStatic`) it authorizes as `STATIC_DEPLOY_USER` instead of a real
+ * user. Note that this changes WHO the read is authorized as, not WHERE it reads
+ * from — in dev mode every read resolves to the branch clone under
+ * `.canopy-dev/content-branches/`, during `next build` exactly as during
+ * `next dev`. See DEVELOPING.md's "Dev Content Sync" section; this has cost
+ * several people real time.
+ *
+ * The Next.js adapter wraps this in React `cache()` for per-request memoization
+ * (`canopycms-next/src/context-wrapper.ts`).
+ *
+ * Module map: ./AGENTS.md.
+ */
 import type { CanopyUser } from './user.js';
 import type { CanopyServices } from './services.js';
 import type { ContentReadMeta } from './content-reader.js';
@@ -76,12 +98,22 @@ export interface CanopyBuildContext {
      * Read content by URL path, resolving the collection/entry split automatically.
      *
      * Tries direct entry match first (last segment = slug, rest = collection path),
-     * then falls back to index entry (full path = collection, slug = 'index').
+     * then falls back to index entry (full path = collection, slug = 'index'). Both attempts
+     * require the collection part to be a real collection — see below.
      * Root path '/' resolves to the content root's index entry.
      *
-     * The direct-entry attempt is SKIPPED when the last segment is an index slug (any case), so
-     * `/x/index` returns null rather than a second URL for the entry that already answers at `/x`.
-     * A collection literally named `index` is unaffected — the fallback resolves it.
+     * Resolves ONLY what `listEntries` publishes — `readByUrlPath(item.urlPath)` reaches the entry,
+     * and no other spelling does. Three shapes that used to resolve are therefore null now:
+     * `/x/index` (the literal spelling of an index entry's collapsed URL, in any case),
+     * `/<collection>/<entryTypeName>` and `/<collection>/<entryTypeName>/<slug>` (an entry-type
+     * path is not a collection, so it is not part of any published URL), and an entry whose
+     * on-disk type token its collection does not declare (`listEntries` skips those too). A
+     * collection literally named `index` is unaffected — the index fallback resolves it.
+     *
+     * `read({ entryPath: 'content/home' })` is deliberately NOT narrowed: addressing an entry
+     * structurally, by its schema path, is a different question from addressing it by its
+     * published URL, and it is the only way to reach a singleton without knowing its slug.
+     *
      * Returns null if no content matches the path — including collection URLs that have no
      * index entry (use buildContentTree for those) and non-entry/invalid paths such as
      * `/favicon.ico` or Next internals (the slug validator rejects them, treated as a miss).

package/dist/context.js

@@ -60,8 +60,12 @@ export function createCanopyContext(options) {
         const user = await getUser();
         // Create base content reader
         const baseReader = createContentReader({ services });
-        // Wrap reader to inject user automatically, validating strings → branded types at this boundary
-        const read = async (input) => {
+        // Wrap reader to inject user automatically, validating strings → branded types at this
+        // boundary. `extra` carries options that are NOT part of the public `read` surface -- today
+        // just readByUrlPath's URL-addressability gate. Kept as a separate inner function rather than
+        // an optional second parameter on the `CanopyContext['read']`-typed closure so the two call
+        // sites stay visible and nobody widens the public API by accident.
+        const readWithOptions = async (input, extra) => {
             const entryPath = createLogicalPath(input.entryPath);
             let slug;
             if (input.slug) {
@@ -77,9 +81,11 @@ export function createCanopyContext(options) {
                 branch: input.branch,
                 user,
                 resolveReferences: input.resolveReferences ?? true,
+                ...extra,
             };
             return baseReader.read(readInput);
         };
+        const read = (input) => readWithOptions(input);
         const readByUrlPath = async (urlPath, options) => {
             const contentRoot = services.config.contentRoot || 'content';
             const candidates = resolveUrlPathCandidates(urlPath, contentRoot);
@@ -93,12 +99,17 @@ export function createCanopyContext(options) {
                 if (!parseSlug(candidate.slug).ok)
                     continue;
                 try {
-                    return await read({
+                    return await readWithOptions({
                         entryPath: candidate.entryPath,
                         slug: candidate.slug,
                         branch,
                         resolveReferences,
-                    });
+                    }, 
+                    // This is a read BY PUBLISHED URL, so it must accept only what listEntries publishes.
+                    // See ReadContentInput.urlAddressableOnly for the two rules and why they live in the
+                    // reader (which holds the branch-correct schema) rather than in the candidate builder
+                    // (which is pure and schema-free by design).
+                    { urlAddressableOnly: true });
                 }
                 catch (err) {
                     // Swallow "not found" errors from trying candidate paths, and FORBIDDEN (a denied

package/dist/editor/admin/SystemHealthPanel.js

@@ -37,7 +37,7 @@ function formatAgeMs(ms) {
     return `${totalDays}d ${totalHours % 24}h`;
 }
 /**
- * [LOW-2] Whether the Purge button should be disabled for a corrupt-metadata
+ * Whether the Purge button should be disabled for a corrupt-metadata
  * or orphan row, and the tooltip explaining why.
  * - Base branch: never purgeable -- the server already 400s
  *   ('The base branch directory can never be purged', see
@@ -214,7 +214,7 @@ function BranchesTab({ health }) {
 function BranchHealthRow({ entry, onMarkMerged, onRepair, onPurge, }) {
     if (entry.kind === 'healthy' && entry.branch) {
         const b = entry.branch;
-        // [LOW-3] Mirror rebaseActiveBranches' skip logic (worker/cms-worker.ts):
+        // Mirror the rebase loop's skip logic (worker/rebase.ts):
         // the worker rebases every branch except 'submitted'/'approved' (under an
         // active PR) and 'archived' (already merged). Stated as an exclusion list
         // rather than `status === 'editing'` so that a status added later shows its

package/dist/entry-schema.d.ts

@@ -1,3 +1,25 @@
+/**
+ * The entry-schema authoring API — the surface ADOPTERS write against.
+ *
+ * `defineEntrySchema`, `defineInlineFieldGroup`, `defineNestedFieldGroup` and
+ * `defineSeoFieldGroup` are how a host app declares its content model in
+ * TypeScript, with the field list inferring the entry's data type. Changing a
+ * signature here is an adopter-facing breaking change, not an internal one.
+ *
+ * This is the type-level half of the schema story. The runtime half — loading
+ * `.collection.json`, resolving it, and validating content against it — lives in
+ * `schema/` and `validation/`.
+ *
+ * `RESOLVED_REFERENCE_KEYS`/`buildResolvedReference` define the shape a resolved
+ * reference takes; `validation/entry-validator.ts`'s `normalizeReferenceValues`
+ * is the inverse, and the two must agree.
+ *
+ * `DEFAULT_SEO_FIELD_NAMES` is imported from `static/seo.ts` rather than
+ * redeclared, so the schema this module emits and the fields that module reads
+ * cannot drift apart.
+ *
+ * Module map: ./AGENTS.md.
+ */
 import type { ComponentType } from 'react';
 /** Structural constraint for fields that can be inferred by TypeFromEntrySchema. */
 type InferableField = {

package/dist/git-manager.d.ts

@@ -2,8 +2,9 @@ import { type SimpleGitOptions, type StatusResult } from 'simple-git';
 import type { OperatingMode } from './operating-mode/index.js';
 /**
  * Exported for GitManager's own use (see `this.git.env(...)` above),
- * worker/cms-worker.ts's push-rejection-classified GitHub calls
- * (`pushBranchToGitHub`, `syncGit`'s fetch/`pushSettingsBranches` instance),
+ * the worker's push-rejection-classified GitHub calls
+ * (`pushBranchToGitHub` in worker/task-runner.ts, `syncGit`'s
+ * fetch/`pushSettingsBranches` instance in worker/git-sync.ts),
  * and tests.
  */
 export declare function gitChildEnv(overrides: Record<string, string>): Record<string, string>;
@@ -16,8 +17,8 @@ export declare function gitNetworkChildEnv(): Record<string, string>;
  * `remote.git`'s `refs/heads/*` is NOT a throwaway mirror: it's the
  * deployment's local origin. `GitManager.push()` writes editor work into it
  * (`target:target`), branch-workspace clones are cloned FROM it, and the CMS
- * worker itself pushes it on to GitHub (`pushBranchToGitHub`,
- * `pushSettingsBranches` in worker/cms-worker.ts). A fetch that force-writes
+ * worker itself pushes it on to GitHub (`pushBranchToGitHub` in
+ * worker/task-runner.ts, `pushSettingsBranches` in worker/git-sync.ts). A fetch that force-writes
  * GitHub's refs straight into `refs/heads/*` (the old
  * `+refs/heads/*:refs/heads/*` refspec) can therefore destroy work that
  * reached `remote.git` but not GitHub yet: with `--prune`, a branch pushed
@@ -30,10 +31,10 @@ export declare function gitNetworkChildEnv(): Record<string, string>;
  * Fetching into this remote-tracking namespace instead makes `--prune`/`+`
  * safe again -- they now only ever affect GitHub's-view-of-the-world refs,
  * never the local heads other code depends on. `reconcileTrackedBranches()`
- * (worker/cms-worker.ts) is what subsequently, and non-destructively, brings
+ * (worker/git-sync.ts) is what subsequently, and non-destructively, brings
  * `refs/heads/*` toward what's tracked here.
  *
- * Lives here (not worker/cms-worker.ts, where this constant originated) so
+ * Lives here (not the worker, where this constant originated) so
  * `GitManager.bareRemoteHasBranch` -- which must recognize this namespace
  * too, since it's what a branch pushed by another CanopyCMS deployment (or
  * pushed directly to GitHub) shows up in before/without ever gaining a local
@@ -172,7 +173,7 @@ export declare class GitManager {
      * guard, which also needs the tracking namespace: `syncGit()` fetches
      * GitHub into `GITHUB_TRACKING_REF_PREFIX*` rather than `refs/heads/*`
      * directly (see that constant's doc comment above), and
-     * `reconcileTrackedBranches()` (worker/cms-worker.ts) only
+     * `reconcileTrackedBranches()` (worker/git-sync.ts) only
      * non-destructively brings `refs/heads/*` toward what's tracked there — so
      * a branch that another CanopyCMS deployment sharing this repo (or a
      * direct push to GitHub) just created can sit in the tracking namespace
@@ -229,7 +230,7 @@ export declare class GitManager {
      * "absent" deterministic instead of parsing update-ref's locale-dependent
      * failure text, and its captured SHA is passed to `update-ref -d` as the
      * expected old value -- same pattern as reconcileTrackedBranches'
-     * guarded updates (worker/cms-worker.ts): a concurrent Lambda push
+     * guarded updates (worker/git-sync.ts): a concurrent Lambda push
      * re-creating/moving this branch between the read and the delete makes
      * update-ref throw (surfaced as the caller's best-effort warning) instead
      * of silently deleting a commit that was just pushed. No

package/dist/git-manager.js

@@ -1,3 +1,28 @@
+/**
+ * Git operations for branch workspaces.
+ *
+ * This file is effectively TWO modules sharing a class name, split cleanly by
+ * line number:
+ *
+ *   Everything from `cloneRepo` down to `initializeWorkspace` is `static` —
+ *     workspace PROVISIONING (also ensureLocalSimulatedRemote, bareRemoteHasBranch,
+ *     deleteBareRemoteHead, findGitRoot, resolveRemoteUrl). These share no instance
+ *     state; the class is acting as a namespace.
+ *   Everything from `status()` onward is an INSTANCE method — per-repo operations
+ *     on one already-provisioned workspace (checkoutBranch, pullBase,
+ *     rebaseOntoBase, add/commit/push, ...), needing
+ *     `repoPath`/`baseBranch`/`remote`.
+ *
+ * `status()` is the dividing line. If you are here to change provisioning, nothing
+ * after it concerns you, and vice versa.
+ *
+ * Every git invocation is argv-based with `--end-of-options`, and `gitChildEnv`
+ * forces `LC_ALL=C`/`LANG=C` so git's own message text stays English — several
+ * callers classify errors by matching it (see `utils/git.ts`'s
+ * `isNonFastForwardRejection`). Do not remove that.
+ *
+ * Module map: ./AGENTS.md. Locking rules: ../../../docs/concurrency.md.
+ */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { simpleGit, } from 'simple-git';
@@ -44,8 +69,9 @@ const GIT_ENV_PASSTHROUGH = /^(PATH|HOME|USER|LANG|LC_[A-Z]+|TZ|TMPDIR|GIT_(AUTH
 const FORCE_C_LOCALE = { LC_ALL: 'C', LANG: 'C' };
 /**
  * Exported for GitManager's own use (see `this.git.env(...)` above),
- * worker/cms-worker.ts's push-rejection-classified GitHub calls
- * (`pushBranchToGitHub`, `syncGit`'s fetch/`pushSettingsBranches` instance),
+ * the worker's push-rejection-classified GitHub calls
+ * (`pushBranchToGitHub` in worker/task-runner.ts, `syncGit`'s
+ * fetch/`pushSettingsBranches` instance in worker/git-sync.ts),
  * and tests.
  */
 export function gitChildEnv(overrides) {
@@ -100,8 +126,8 @@ const remoteInitLocks = new Map();
  * `remote.git`'s `refs/heads/*` is NOT a throwaway mirror: it's the
  * deployment's local origin. `GitManager.push()` writes editor work into it
  * (`target:target`), branch-workspace clones are cloned FROM it, and the CMS
- * worker itself pushes it on to GitHub (`pushBranchToGitHub`,
- * `pushSettingsBranches` in worker/cms-worker.ts). A fetch that force-writes
+ * worker itself pushes it on to GitHub (`pushBranchToGitHub` in
+ * worker/task-runner.ts, `pushSettingsBranches` in worker/git-sync.ts). A fetch that force-writes
  * GitHub's refs straight into `refs/heads/*` (the old
  * `+refs/heads/*:refs/heads/*` refspec) can therefore destroy work that
  * reached `remote.git` but not GitHub yet: with `--prune`, a branch pushed
@@ -114,10 +140,10 @@ const remoteInitLocks = new Map();
  * Fetching into this remote-tracking namespace instead makes `--prune`/`+`
  * safe again -- they now only ever affect GitHub's-view-of-the-world refs,
  * never the local heads other code depends on. `reconcileTrackedBranches()`
- * (worker/cms-worker.ts) is what subsequently, and non-destructively, brings
+ * (worker/git-sync.ts) is what subsequently, and non-destructively, brings
  * `refs/heads/*` toward what's tracked here.
  *
- * Lives here (not worker/cms-worker.ts, where this constant originated) so
+ * Lives here (not the worker, where this constant originated) so
  * `GitManager.bareRemoteHasBranch` -- which must recognize this namespace
  * too, since it's what a branch pushed by another CanopyCMS deployment (or
  * pushed directly to GitHub) shows up in before/without ever gaining a local
@@ -388,7 +414,7 @@ export class GitManager {
      * guard, which also needs the tracking namespace: `syncGit()` fetches
      * GitHub into `GITHUB_TRACKING_REF_PREFIX*` rather than `refs/heads/*`
      * directly (see that constant's doc comment above), and
-     * `reconcileTrackedBranches()` (worker/cms-worker.ts) only
+     * `reconcileTrackedBranches()` (worker/git-sync.ts) only
      * non-destructively brings `refs/heads/*` toward what's tracked there — so
      * a branch that another CanopyCMS deployment sharing this repo (or a
      * direct push to GitHub) just created can sit in the tracking namespace
@@ -485,7 +511,7 @@ export class GitManager {
      * "absent" deterministic instead of parsing update-ref's locale-dependent
      * failure text, and its captured SHA is passed to `update-ref -d` as the
      * expected old value -- same pattern as reconcileTrackedBranches'
-     * guarded updates (worker/cms-worker.ts): a concurrent Lambda push
+     * guarded updates (worker/git-sync.ts): a concurrent Lambda push
      * re-creating/moving this branch between the read and the delete makes
      * update-ref throw (surfaced as the caller's best-effort warning) instead
      * of silently deleting a commit that was just pushed. No
@@ -965,7 +991,7 @@ export class GitManager {
         // Merge the just-fetched tip (pinned to a SHA), not <remote>/<base>:
         // workspaces are cloned --single-branch, so the remote-tracking ref for
         // any branch other than the cloned one never exists (same fix as the
-        // worker's rebase loop — see cms-worker.ts), and FETCH_HEAD itself is a
+        // worker's rebase loop — see worker/rebase.ts), and FETCH_HEAD itself is a
         // shared mutable file repointed by any other fetch in this clone.
         const fetchedTip = (await this.git.revparse(['FETCH_HEAD'])).trim();
         try {

package/dist/github-service.d.ts

@@ -16,7 +16,7 @@ export declare const shouldRetrySecondaryRateLimit: (retryAfter: number, retryCo
 /**
  * Create an Octokit instance with the throttling plugin attached, so it
  * proactively respects GitHub's `retry-after` guidance on rate limits
- * instead of failing immediately (see cms-worker.ts isPermanentTaskFailure
+ * instead of failing immediately (see worker/task-runner.ts's isPermanentTaskFailure
  * for the safety net this doesn't cover: exhausted plugin retries and
  * errors the plugin never sees, like non-403 network failures).
  */

package/dist/github-service.js

@@ -25,7 +25,7 @@ export const shouldRetrySecondaryRateLimit = (retryAfter, retryCount) => retryCo
 /**
  * Create an Octokit instance with the throttling plugin attached, so it
  * proactively respects GitHub's `retry-after` guidance on rate limits
- * instead of failing immediately (see cms-worker.ts isPermanentTaskFailure
+ * instead of failing immediately (see worker/task-runner.ts's isPermanentTaskFailure
  * for the safety net this doesn't cover: exhausted plugin retries and
  * errors the plugin never sees, like non-403 network failures).
  */

package/dist/paths/branch-name.d.ts

@@ -23,7 +23,7 @@ export declare function sanitizeBranchName(branchName: string): SanitizedBranchN
  * operating-mode/deployment-name.ts's `resolveDeploymentName`). Exported from
  * this dependency-free module -- not constructed ad hoc at each call site --
  * so every consumer that needs to recognize the settings-branch namespace
- * agrees on the exact string: worker/cms-worker.ts's `pushSettingsBranches`
+ * agrees on the exact string: worker/git-sync.ts's `pushSettingsBranches`
  * (never push a `canopycms-settings-*` branch this deployment doesn't own),
  * and api/branch.ts's `createBranchHandler` (reject a user-requested branch
  * whose SANITIZED name falls in this namespace).