canopycms 0.0.67-int.90 → 0.0.67

package/dist/branch-schema-cache.js

@@ -12,16 +12,11 @@ const MTIME_CHECK_DEBOUNCE_MS = 1000;
 /** resource-generation.ts resource key for the schema cache's marker. */
 export const SCHEMA_GENERATION_RESOURCE = 'schema';
 /**
- * In dev mode, check whether any .collection.json file under dir has been
- * modified more recently than cachedAt. Returns true if stale.
+ * True when a .collection.json under `dir` is newer than `cachedAt`.
  *
- * Uses a single recursive readdir to find all .collection.json files,
- * then stats only those files.
- *
- * This is a dev-only convenience for out-of-band hand edits made directly to
- * .collection.json files outside the CMS (which don't go through SchemaOps
- * and therefore never bump the generation marker below). It is not needed for
- * prod correctness: every mutation path that matters in prod bumps the marker.
+ * Dev-only, and dev-only on purpose: it catches hand edits made outside the
+ * CMS, which bypass SchemaOps and so never bump the marker. Every prod mutation
+ * path does bump it, so the marker alone is sufficient there.
  */
 async function isStaleByMtime(dir, cachedAt) {
     let entries;
@@ -48,75 +43,18 @@ async function isStaleByMtime(dir, cachedAt) {
     return false;
 }
 /**
- * Manages per-branch schema caching with lazy loading and automatic
- * invalidation.
- *
- * ## Cross-process freshness (resource-generation.ts marker protocol)
- *
- * Several warm Lambda containers plus the EC2 worker can share one
- * branch-clone root over EFS, each with its own copy of
- * `schema-cache.json`. There is no shared memory and no cross-host file
- * watching, so freshness is coordinated via the generic on-disk generation
- * marker in resource-generation.ts: every cached snapshot embeds the marker
- * token it was resolved against, and every read cheaply re-checks the live
- * marker before trusting the cache. See that module's doc comment for the
- * full protocol and residual staleness windows (A/B/C/E).
- *
- * BranchSchemaCache is the "durable snapshot consumer" case called out there:
- * a resolve whose scan is served from stale NFS dentry/attribute caches can
- * record a FRESH token over STALE data (window E), and because the result is
- * written to `schema-cache.json`, that staleness becomes durable and shared
- * with every other host that reads the marker - not just one process's
- * memory. `loadFromCacheOrResolve` mitigates this the same way
- * BranchRegistry does:
+ * Per-branch schema cache: a file at {branchRoot}/.canopy-meta/schema-cache.json
+ * with no in-memory layer, so it stays coherent across Lambda invocations.
  *
- * - The marker is captured strictly BEFORE `resolveFresh()` runs, and the
- *   captured token (not one read after resolving) is what gets embedded in
- *   the persisted snapshot. A bump landing mid-resolve therefore leaves the
- *   embedded token older than the live marker, forcing a re-resolve on the
- *   next read instead of silently resurrecting stale schema.
- * - A snapshot is only persisted when the marker read itself succeeded
- *   (`{ ok: true }`). If the read fails for a reason other than "never
- *   bumped", we cannot attribute a token to this resolve, and stamping the
- *   snapshot with an unattributable token would make it indistinguishable
- *   from a correctly-attributed one to every future reader. The fresh result
- *   is still served to this caller; it just isn't written durably.
- * - invalidate() bumps the marker with `mustSucceed: true`: an explicit
- *   invalidation (e.g. after a schema mutation) must not silently fail and
- *   leave every reader confidently stale with no bounding backstop.
- *   invalidate() itself does NOT eager-regenerate - it isn't given the
- *   entrySchemaRegistry/contentRootName that resolveSchema needs. The
- *   eager re-resolve (window-E mitigation, mirroring BranchRegistry's
- *   eager regen) lives one level up in SchemaOps.invalidateSchemaCache()
- *   (schema/schema-store.ts), which has those arguments and calls
- *   {@link resolveAndPersist} (NOT getSchema()) right after invalidating -
- *   so every SchemaOps mutation re-resolves on the mutating host via a scan
- *   that is GUARANTEED to run, not merely likely to run. getSchema() would
- *   be the wrong call here: its cache-read fast path can short-circuit
- *   through a snapshot a DIFFERENT concurrent host just wrote (see
- *   resolveAndPersist()'s doc comment for the exact race), silently
- *   skipping the one scan this eager re-resolve exists to guarantee. (The
- *   editor's follow-up schema GET is a separate Lambda invocation with no
- *   container affinity, so it could not serve this purpose either.)
- *   Callers of invalidate() that bypass SchemaOps (api/schema.ts's explicit
- *   invalidate endpoint; the bulk-mutation bump in
- *   invalidateBranchContentCaches) accept the lazy next-read regen.
- *
- * This is also why prod needs no mtime walk: the dev-only mtime check below
- * exists solely to catch hand edits to .collection.json made outside the CMS
- * (which bypass SchemaOps and therefore never bump the marker). Every
- * mutation path that matters in prod - SchemaOps writes, git working-tree
- * rewrites (checkout/merge/rebase/sync/migrate) - bumps the marker via
- * SchemaOps.invalidateSchemaCache() or the combined
- * invalidateBranchContentCaches() helper in content-index-generation.ts, so
- * the marker alone is a sufficient prod backstop.
- *
- * Caching Strategy:
- * - File-based cache at {branchRoot}/.canopy-meta/schema-cache.json (no
- *   in-memory layer - intentional: matches prod behavior and keeps cache
- *   coherent across Lambda invocations)
- * - Invalidation: invalidate() bumps the cross-process generation marker;
- *   every reader sharing this branchRoot re-resolves at its next access.
+ * Freshness follows the generation-marker protocol owned by
+ * resource-generation.ts, and this is one of that protocol's durable-snapshot
+ * consumers. Its eager re-resolve lives one level up, in
+ * `SchemaOps.invalidateSchemaCache()` (schema/schema-store.ts), because that is
+ * where the entrySchemaRegistry/contentRootName arguments {@link invalidate}
+ * lacks are available; it calls {@link resolveAndPersist}, never getSchema().
+ * Callers that bypass SchemaOps (api/schema.ts's invalidate endpoint, and the
+ * bulk git-op bump in invalidateBranchContentCaches) accept the lazy
+ * next-read regen instead.
  */
 export class BranchSchemaCache {
     constructor(mode = 'prod') {
@@ -127,42 +65,28 @@ export class BranchSchemaCache {
     /**
      * Whether to skip the on-disk cache for this branchRoot.
      *
-     * branchRoot equals the project root (process.cwd()) only in the synthetic
-     * contexts used by static deployments and build phases — real branch roots are
-     * always nested under the workspace (.canopy-dev/content-branches/<name> in dev,
-     * <workspaceRoot>/content-branches/<name> in prod). Never write .canopy-meta/ at
-     * the project root, regardless of which entrypoint produced the cwd branchRoot.
+     * Never write `.canopy-meta/` at the project root, whichever entrypoint
+     * produced the cwd branchRoot. branchRoot equals process.cwd() only in the
+     * synthetic contexts static deployments and build phases use; a real branch
+     * root is always nested under the workspace.
      */
     skipDiskCache(branchRoot) {
         return isBuildMode() || path.resolve(branchRoot) === path.resolve(process.cwd());
     }
-    /**
-     * Get schema for a branch (loads from cache or resolves fresh).
-     *
-     * @param branchRoot - Root directory of the branch (e.g., .canopy-dev/content-branches/main)
-     * @param entrySchemaRegistry - Map of schema names to field definitions
-     * @param contentRootName - Name of content directory (e.g., "content") from config
-     * @returns Resolved schema tree and flattened schema
-     */
+    /** Get schema for a branch, from the cache when fresh, else resolved fresh. */
     async getSchema(branchRoot, entrySchemaRegistry, contentRootName = 'content') {
         return this.loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName);
     }
     /**
-     * Resolve the schema from disk. Wrapped in a protected method (rather than
-     * calling the imported resolveSchema directly) so tests can subclass and
-     * override with a deferred/blocking implementation to simulate cross-process
+     * Resolve the schema from disk. Protected rather than a direct resolveSchema
+     * call so tests can subclass and block it to simulate cross-process
      * interleavings — mirrors BranchRegistry's scanBranchDirectories() hook.
      */
     async resolveFresh(contentRoot, entrySchemaRegistry) {
         return resolveSchema(contentRoot, entrySchemaRegistry);
     }
-    /**
-     * Load schema from cache or resolve fresh if cache is missing or stale.
-     */
     async loadFromCacheOrResolve(branchRoot, entrySchemaRegistry, contentRootName) {
         const contentRoot = path.join(branchRoot, contentRootName);
-        // In static/build mode, branchRoot is process.cwd() (the project root).
-        // Skip disk cache to avoid creating .canopy-meta/ at the project root.
         const skipDiskCache = this.skipDiskCache(branchRoot);
         if (!skipDiskCache) {
             const cacheDir = path.join(branchRoot, '.canopy-meta');
@@ -176,16 +100,13 @@ export class BranchSchemaCache {
                 // Cache doesn't exist or can't be read
                 cacheData = null;
             }
-            // Strict version check: a truthy-only check would accept a persisted
-            // pre-marker snapshot (no `generation` field) left on EFS after a
-            // rolling deploy, and `cacheData.generation` would then be `undefined`
-            // rather than a real token or explicit `null`, breaking the freshness
-            // comparison below.
+            // Strict version check, not truthiness: a snapshot from an older version
+            // left on EFS by a rolling deploy has no `generation` field, and an
+            // `undefined` token breaks the freshness comparison below.
             if (cacheData && cacheData.version === SCHEMA_CACHE_VERSION) {
                 const read = await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
                 if (isGenerationCurrent(cacheData.generation, read)) {
-                    // In dev mode, also check file mtimes so direct schema edits (outside the CMS) are picked up.
-                    // Debounce: skip the walk if we checked this contentRoot within the last second.
+                    // Dev also walks mtimes, debounced, to catch edits made outside the CMS.
                     const now = Date.now();
                     const lastCheck = this.lastMtimeCheck.get(contentRoot) ?? 0;
                     if (this.devMode &&
@@ -209,8 +130,6 @@ export class BranchSchemaCache {
                 cacheData = null;
             }
         }
-        // Cache miss, stale, or build mode - resolve fresh (and persist, subject
-        // to the same skip-persist rule) via the shared resolve half.
         return this.resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, {
             skipDiskCache,
         });
@@ -224,10 +143,9 @@ export class BranchSchemaCache {
     async resolveFreshAndPersist(branchRoot, entrySchemaRegistry, contentRootName, options) {
         const { skipDiskCache } = options;
         const contentRoot = path.join(branchRoot, contentRootName);
-        // Capture the marker strictly BEFORE resolving: a bump landing mid-resolve
-        // then differs from the token recorded below, forcing a re-resolve on the
-        // next read instead of silently persisting a snapshot that embeds a fresh
-        // token over pre-mutation data.
+        // Capture the marker strictly BEFORE resolving, so a bump landing
+        // mid-resolve differs from the token persisted below and forces a
+        // re-resolve on the next read.
         const read = skipDiskCache
             ? null
             : await readResourceGeneration(branchRoot, SCHEMA_GENERATION_RESOURCE);
@@ -250,9 +168,8 @@ export class BranchSchemaCache {
         if (!skipDiskCache) {
             const cacheDir = path.join(branchRoot, '.canopy-meta');
             const cachePath = path.join(cacheDir, 'schema-cache.json');
-            // Opportunistic cleanup of the legacy .stale marker file from the old
-            // rename-based invalidation scheme (e.g. a process upgraded mid-flight
-            // may find one left over from before the deploy). Not load-bearing.
+            // Opportunistic cleanup of the retired .stale marker file, which a
+            // mid-flight deploy can leave behind. Not load-bearing.
             await fs.unlink(path.join(cacheDir, 'schema-cache.stale')).catch(() => { });
             if (read && read.ok) {
                 const newCache = {
@@ -262,10 +179,8 @@ export class BranchSchemaCache {
                     cachedAt: new Date().toISOString(),
                     generation: read.token,
                 };
-                // Atomic write: write to temp file, then rename. Clean up the temp
-                // file on a failed rename (matches every other atomic write in the
-                // codebase, e.g. utils/atomic-write.ts) so a transient rename error
-                // doesn't leak a stray `.tmp` file into `.canopy-meta/` forever.
+                // Temp file then rename, with the temp file unlinked on a failed
+                // rename so a transient error leaves no stray `.tmp` in `.canopy-meta/`.
                 await fs.mkdir(cacheDir, { recursive: true });
                 const tmpPath = path.join(cacheDir, `schema-cache.tmp.${Date.now()}.${Math.random()}.json`);
                 await fs.writeFile(tmpPath, JSON.stringify(newCache, null, 2), 'utf-8');
@@ -277,34 +192,21 @@ export class BranchSchemaCache {
                     throw err;
                 }
             }
-            // else: the marker couldn't be read for a reason other than "never
-            // bumped" - we cannot attribute a token to this resolve, and stamping
-            // the snapshot with an unattributable token would make it
-            // indistinguishable from a correctly-attributed one to every future
-            // reader. Serve the fresh result without persisting it; the next read
-            // retries the marker read and, on success, resolves and persists
-            // normally.
+            // else: the marker read failed for a reason other than "never bumped",
+            // so no token can be attributed to this resolve, and a snapshot stamped
+            // with an unattributable one would look correctly attributed to every
+            // future reader. Serve the fresh result without persisting it.
         }
         return { schema: result.schema, flatSchema };
     }
     /**
-     * Resolve the schema fresh from disk and persist it, SKIPPING the cache
-     * read entirely -- unlike {@link getSchema}, which can short-circuit
-     * through a cache HIT. That distinction matters for eager re-resolve after
-     * invalidation (see {@link invalidate}'s doc comment and
-     * `SchemaOps.invalidateSchemaCache()` in schema/schema-store.ts, the sole
-     * intended caller): the whole point of an eager re-resolve is to guarantee
-     * ONE scan that is coherent with the mutation this host just made. A plain
-     * `getSchema()` call right after `invalidate()` is NOT that guarantee --
-     * `getSchema()`'s cache-read fast path (`loadFromCacheOrResolve`) can still
-     * return a snapshot written by a DIFFERENT, concurrent host: if that
-     * foreign host's own eager re-resolve raced this one and embedded the
-     * (now-current) marker token over ITS OWN stale-NFS-cache scan (the
-     * window-E case this class's doc comment describes), this host's
-     * `getSchema()` would happily accept that foreign snapshot as "current"
-     * and skip the one scan this call was specifically trying to guarantee.
-     * `resolveAndPersist()` never reads the cache file at all, so it cannot be
-     * short-circuited that way.
+     * Resolve fresh from disk and persist, SKIPPING the cache read entirely.
+     * That is what makes it, and not {@link getSchema}, the right call for the
+     * eager re-resolve in `SchemaOps.invalidateSchemaCache()` (its sole intended
+     * caller): an eager re-resolve exists to guarantee ONE scan coherent with the
+     * mutation this host just made, and getSchema()'s cache-read fast path can
+     * instead return a snapshot a concurrent host wrote — possibly one embedding
+     * the now-current token over ITS own stale-NFS scan — skipping that scan.
      */
     async resolveAndPersist(branchRoot, entrySchemaRegistry, contentRootName = 'content') {
         const skipDiskCache = this.skipDiskCache(branchRoot);
@@ -313,20 +215,12 @@ export class BranchSchemaCache {
         });
     }
     /**
-     * Invalidate cache for a branch by bumping the cross-process generation
-     * marker (resource-generation.ts). Every process sharing this branchRoot
-     * will re-resolve at its next read.
-     *
-     * The bump must succeed: a swallowed failure here would leave the schema
-     * cache stale indefinitely with no bounding backstop (unlike
-     * BranchRegistry, there is no get-miss backstop for a resolved schema).
-     *
-     * No eager regeneration here (unlike BranchRegistry.invalidate()): this
-     * method isn't given the entrySchemaRegistry/contentRootName resolveSchema
-     * needs. See the class doc comment for why the mutating request's own
-     * follow-up schema read closes the same window-E gap instead.
+     * Invalidate a branch's cache by bumping the marker; every process sharing
+     * this branchRoot re-resolves at its next read. The bump must succeed —
+     * swallowing that failure leaves the schema cache stale indefinitely, and
+     * unlike BranchRegistry there is no get-miss backstop for a resolved schema.
      *
-     * @param branchRoot - Root directory of the branch
+     * No eager re-resolve here; it lives in SchemaOps (see the class doc).
      */
     async invalidate(branchRoot) {
         if (this.skipDiskCache(branchRoot))

package/dist/branch-workspace.d.ts

@@ -23,12 +23,12 @@ export declare class BranchWorkspaceManager {
 }
 export { loadBranchContext } from './branch-metadata.js';
 /**
- * Load an existing branch context, or create the workspace if it doesn't exist yet.
+ * Load an existing branch context, provisioning the workspace if there is none.
  *
  * When content is read from the checkout (`readsFromCheckout`: a static
- * deployment, or any build) this skips every git and branch-workspace
- * operation and returns a synthetic context rooted at the current working
- * directory. `branchName` is echoed back on that context but selects nothing.
+ * deployment, or any build) this skips every git and branch-workspace operation
+ * and returns a synthetic context rooted at the current working directory,
+ * where `branchName` is echoed back but selects nothing.
  */
 export declare function loadOrCreateBranchContext(options: {
     config: CanopyConfig;

package/dist/branch-workspace.js

@@ -20,23 +20,21 @@ export class BranchWorkspaceManager {
     }
     async ensureGitWorkspace(options) {
         return log.timed('workspace', 'ensureGitWorkspace', async () => {
-            // Serialize access per branch workspace to prevent race conditions
+            // One initialization per branch workspace per process.
             const existingLock = workspaceInitLocks.get(options.branchRoot);
             if (existingLock) {
                 await existingLock;
                 return;
             }
-            // Create new lock promise
             const lockPromise = (async () => {
-                // The in-memory lock above only serializes within one process. Separate
-                // processes can provision the same branch workspace at once -- several
-                // Lambda containers sharing one EFS workspace root in prod, or the dev
-                // server beside a content-reading script run outside a build in dev --
-                // and would otherwise both clone into it ("destination path already
-                // exists"), so guard the workspace init with a cross-process lock too.
-                // initializeWorkspace is idempotent, so the waiter simply finds the
-                // workspace already cloned. (A build's content reads never get here:
-                // loadOrCreateBranchContext returns the checkout before provisioning.)
+                // The in-memory lock above only serializes one process, and separate
+                // processes can provision the same workspace at once (several Lambda
+                // containers on one EFS root; the dev server beside a content-reading
+                // script), which without a cross-process lock means both cloning into
+                // it: "destination path already exists". initializeWorkspace is
+                // idempotent, so the waiter finds the workspace already cloned. A
+                // build's content reads never get here — loadOrCreateBranchContext
+                // returns the checkout before provisioning.
                 let releaseLock;
                 try {
                     log.debug('workspace', 'Ensuring git workspace', {
@@ -44,7 +42,6 @@ export class BranchWorkspaceManager {
                         mode: options.mode,
                     });
                     releaseLock = await acquireProvisioningLock(path.dirname(options.branchRoot), `.${path.basename(options.branchRoot)}.init.lock`);
-                    // Delegate git initialization to GitManager
                     await GitManager.initializeWorkspace({
                         workspacePath: options.branchRoot,
                         branchName: options.branchName,
@@ -74,9 +71,7 @@ export class BranchWorkspaceManager {
                     workspaceInitLocks.delete(options.branchRoot);
                 }
             })();
-            // Store the lock promise
             workspaceInitLocks.set(options.branchRoot, lockPromise);
-            // Wait for initialization to complete
             await lockPromise;
         });
     }
@@ -103,7 +98,8 @@ export class BranchWorkspaceManager {
             baseBranch,
             remoteUrl,
         });
-        // save() handles both creation and updates, preserving existing values and invalidating registry
+        // save() covers creation and update, keeping existing values and
+        // invalidating the registry.
         const metadata = getBranchMetadataFileManager(branchRoot, baseRoot);
         const meta = await metadata.save({
             branch: {
@@ -124,12 +120,12 @@ export class BranchWorkspaceManager {
 }
 export { loadBranchContext } from './branch-metadata.js';
 /**
- * Load an existing branch context, or create the workspace if it doesn't exist yet.
+ * Load an existing branch context, provisioning the workspace if there is none.
  *
  * When content is read from the checkout (`readsFromCheckout`: a static
- * deployment, or any build) this skips every git and branch-workspace
- * operation and returns a synthetic context rooted at the current working
- * directory. `branchName` is echoed back on that context but selects nothing.
+ * deployment, or any build) this skips every git and branch-workspace operation
+ * and returns a synthetic context rooted at the current working directory,
+ * where `branchName` is echoed back but selects nothing.
  */
 export async function loadOrCreateBranchContext(options) {
     // Static deployments and builds read content directly from the checkout — no git ops

package/dist/build/generate-ai-content.d.ts

@@ -16,6 +16,7 @@ import type { AIContentConfig } from '../ai/types.js';
  * consumers. Overloading it with a build-time file list would change a contract adopters read.
  *
  * Dot-prefixed so it sorts out of the way and reads as machine bookkeeping rather than content.
+ * @internal Exported for tests.
  */
 export declare const GENERATED_RECORD_FILENAME = ".canopy-generated.json";
 export interface GenerateAIContentFilesOptions {

package/dist/build/generate-ai-content.js

@@ -22,6 +22,7 @@ import { assertBuildEntriesValid } from '../static/index.js';
  * consumers. Overloading it with a build-time file list would change a contract adopters read.
  *
  * Dot-prefixed so it sorts out of the way and reads as machine bookkeeping rather than content.
+ * @internal Exported for tests.
  */
 export const GENERATED_RECORD_FILENAME = '.canopy-generated.json';
 /** Read the previous run's record. A missing, unreadable or malformed record means "know nothing". */
@@ -102,30 +103,20 @@ function unpinnedConsequence(buildId) {
 /**
  * Resolve the manifest's build stamp from the environment.
  *
- * This lives at the BUILD boundary, not inside `generateAIContent`, because the same generator
- * also serves the runtime route — where a live clock is the correct answer and a
- * `SOURCE_DATE_EPOCH` that happens to be exported in a server environment must not freeze a
- * response's timestamp.
+ * Lives at the BUILD boundary, not inside `generateAIContent`: the same generator also serves
+ * the runtime route, where a live clock is correct and a `SOURCE_DATE_EPOCH` exported in a
+ * server environment must not freeze a response's timestamp.
  *
- * `SOURCE_DATE_EPOCH` is the Reproducible Builds convention (decimal seconds since the epoch),
- * kept under its standard name so a harness that already exports it for tar/gzip/rpm gets this
- * for free. `CANOPY_BUILD_ID` is ours: Next has no such variable of its own.
+ * `SOURCE_DATE_EPOCH` is the Reproducible Builds convention (decimal seconds since the epoch).
+ * `CANOPY_BUILD_ID` is validated against the same rule as `SAFE_BUILD_ID` above, since the
+ * manifest's `buildId` and Next's build id must name the SAME artifact.
  *
- * That id is validated here against a rule justified by Next's `_next/static/<id>/` layout, even
- * though this module is framework-agnostic. Deliberate: the variable's whole purpose is that the
- * manifest's `buildId` and the framework's build id name the SAME artifact, so a value one reader
- * would reject is not useful to the other. The cost is that a non-Next adopter cannot use, say, an
- * ISO timestamp as a build id — revisit this rule, in both copies, when a second framework lands.
+ * Both variables warn and are ignored when set but unusable, rather than failing the build —
+ * same stance as `readGeneratedRecord` above; "unset" is a deliberate opt-out and warns nothing.
  *
- * Every rejection warns and is ignored rather than failing the build — same stance as
- * `readGeneratedRecord` above. Both variables treat "set but unusable" as a broken pipeline
- * (`SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)` with a failing command) and say so, while
- * "unset" is a deliberate opt-out and says nothing.
- *
- * Note what ignoring a bad `SOURCE_DATE_EPOCH` means when a build id IS set: `generatedAt` stays
- * undefined, so `generated` is omitted rather than falling back to a live clock. A bad value must
- * not resurrect a field the adopter's configuration says is meaningless — which is also why that
- * case warns rather than failing silently, since the field simply disappears.
+ * When `SOURCE_DATE_EPOCH` is bad and a build id IS set, `generatedAt` stays undefined so
+ * `generated` is omitted rather than falling back to a live clock — a bad value must not
+ * resurrect a field the adopter's configuration says is meaningless.
  */
 function resolveBuildStamp() {
     // Trimmed and shape-checked with the same rule `withCanopy` applies, so that when an adopter
@@ -182,9 +173,7 @@ function resolveBuildStamp() {
 export async function generateAIContentFiles(options) {
     const { config, entrySchemaRegistry, outputDir, aiConfig, _testFlatSchema } = options;
     const contentRootName = config.contentRoot || 'content';
-    // Resolve branch root
     const branchRoot = await resolveBranchRoot(config);
-    // Load schema
     let flatSchema;
     if (_testFlatSchema) {
         flatSchema = _testFlatSchema;
@@ -199,7 +188,6 @@ export async function generateAIContentFiles(options) {
     // command, not something `next dev` runs incidentally.
     const entriesForValidation = await listEntries(branchRoot, flatSchema, contentRootName);
     assertBuildEntriesValid(entriesForValidation, 'AI content generation');
-    // Create store and generate
     const store = new ContentStore(branchRoot, flatSchema, { contentRootName });
     const result = await generateAIContent({
         store,
@@ -209,7 +197,6 @@ export async function generateAIContentFiles(options) {
         entryLinkUrl: config.entryLinkUrl,
         ...resolveBuildStamp(),
     });
-    // Write files to disk
     const absoluteOutputDir = path.resolve(outputDir) + path.sep;
     /** Resolve an output-relative path, refusing anything that escapes the output directory. */
     const resolveOutputPath = (filePath) => {

package/dist/build-canopy.d.ts

@@ -2,41 +2,31 @@ import type { CanopyConfig } from './config/index.js';
 import type { EntrySchemaRegistry } from './schema/types.js';
 import { type CanopyBuildContext } from './context.js';
 export interface CreateBuildCanopyOptions {
-    /**
-     * Entry schema registry for resolving `.collection.json` references.
-     * Same shape as `createCanopyServices`'s option of the same name.
-     */
+    /** Entry schema registry for `.collection.json` references; `createCanopyServices`'s shape. */
     entrySchemaRegistry?: EntrySchemaRegistry;
 }
 /**
- * One-call factory for a **build/admin** Canopy context — for standalone
- * scripts that run entirely outside a Next.js request or build phase (index
- * builders, content audits, codegen, ad hoc reports).
+ * One-call factory for a **build/admin** Canopy context, for standalone scripts
+ * that run entirely outside a Next.js request or build phase (index builders,
+ * content audits, codegen, ad hoc reports).
  *
- * **This is a build/admin context: it reads the filesystem directly as a
- * synthetic admin user (`STATIC_DEPLOY_USER`) and bypasses ALL branch and
- * path ACLs.** There is no per-request auth to enforce because there is no
- * request. Do not reach for this from request-handling code (an API route,
- * a server component rendering for a specific visitor, anything with a real
- * user on the other end) — there, use `createNextCanopyContext(...)`'s
- * `getCanopy()` (or its phase-selecting `read`/`readByUrlPath`), which
- * enforce branch/path permissions per user. This factory mirrors the same
- * `createCanopyServices` + `createCanopyContext` + `STATIC_DEPLOY_USER` boot
- * sequence that `createNextCanopyContext`'s own `getCanopyForBuild()` uses
- * internally, minus the Next.js pieces (no `next/headers`, no React
- * `cache()`, no request-time misuse guard — there is no request phase for
- * it to guard against) — so it works in a plain script run with `tsx`/`node`.
+ * **Bypasses ALL branch and path ACLs: it reads the filesystem directly as the
+ * synthetic admin user `STATIC_DEPLOY_USER`.** That is safe only because there
+ * is no request, and so no per-request auth to enforce. Never reach for it from
+ * request-handling code (an API route, a server component rendering for a
+ * specific visitor); there, use `createNextCanopyContext(...)`'s `getCanopy()`
+ * or its phase-selecting `read`/`readByUrlPath`, which enforce branch and path
+ * permissions per user.
  *
- * Trivially stubbable by design: the boot sequence is one function call
- * taking a plain config object and returning a plain context, so a script
- * that calls it can be imported and exercised from a test with the config
- * (or this function itself) swapped out. Contrast with a hand-rolled
- * top-level-`await` boot block, which can never be imported by a test at
- * all — that's the concrete problem this factory removes.
+ * Mirrors the `createCanopyServices` + `createCanopyContext` +
+ * `STATIC_DEPLOY_USER` boot sequence of `createNextCanopyContext`'s own
+ * `getCanopyForBuild()`, minus the Next.js pieces (no `next/headers`, no React
+ * `cache()`, no request-time misuse guard — there is no request phase to guard
+ * against), so it runs in a plain `tsx`/`node` script and can be stubbed from a
+ * test the way a top-level-`await` boot block cannot.
  *
  * @example
  * ```ts
- * // scripts/build-search-index.ts
  * import { createBuildCanopy } from 'canopycms/server'
  * import config from '../canopycms.config.js'
  * import { entrySchemaRegistry } from '../src/schemas.js'

package/dist/build-canopy.js

@@ -2,34 +2,27 @@ import { createCanopyServices } from './services.js';
 import { createCanopyContext } from './context.js';
 import { STATIC_DEPLOY_USER } from './build-mode.js';
 /**
- * One-call factory for a **build/admin** Canopy context — for standalone
- * scripts that run entirely outside a Next.js request or build phase (index
- * builders, content audits, codegen, ad hoc reports).
+ * One-call factory for a **build/admin** Canopy context, for standalone scripts
+ * that run entirely outside a Next.js request or build phase (index builders,
+ * content audits, codegen, ad hoc reports).
  *
- * **This is a build/admin context: it reads the filesystem directly as a
- * synthetic admin user (`STATIC_DEPLOY_USER`) and bypasses ALL branch and
- * path ACLs.** There is no per-request auth to enforce because there is no
- * request. Do not reach for this from request-handling code (an API route,
- * a server component rendering for a specific visitor, anything with a real
- * user on the other end) — there, use `createNextCanopyContext(...)`'s
- * `getCanopy()` (or its phase-selecting `read`/`readByUrlPath`), which
- * enforce branch/path permissions per user. This factory mirrors the same
- * `createCanopyServices` + `createCanopyContext` + `STATIC_DEPLOY_USER` boot
- * sequence that `createNextCanopyContext`'s own `getCanopyForBuild()` uses
- * internally, minus the Next.js pieces (no `next/headers`, no React
- * `cache()`, no request-time misuse guard — there is no request phase for
- * it to guard against) — so it works in a plain script run with `tsx`/`node`.
+ * **Bypasses ALL branch and path ACLs: it reads the filesystem directly as the
+ * synthetic admin user `STATIC_DEPLOY_USER`.** That is safe only because there
+ * is no request, and so no per-request auth to enforce. Never reach for it from
+ * request-handling code (an API route, a server component rendering for a
+ * specific visitor); there, use `createNextCanopyContext(...)`'s `getCanopy()`
+ * or its phase-selecting `read`/`readByUrlPath`, which enforce branch and path
+ * permissions per user.
  *
- * Trivially stubbable by design: the boot sequence is one function call
- * taking a plain config object and returning a plain context, so a script
- * that calls it can be imported and exercised from a test with the config
- * (or this function itself) swapped out. Contrast with a hand-rolled
- * top-level-`await` boot block, which can never be imported by a test at
- * all — that's the concrete problem this factory removes.
+ * Mirrors the `createCanopyServices` + `createCanopyContext` +
+ * `STATIC_DEPLOY_USER` boot sequence of `createNextCanopyContext`'s own
+ * `getCanopyForBuild()`, minus the Next.js pieces (no `next/headers`, no React
+ * `cache()`, no request-time misuse guard — there is no request phase to guard
+ * against), so it runs in a plain `tsx`/`node` script and can be stubbed from a
+ * test the way a top-level-`await` boot block cannot.
  *
  * @example
  * ```ts
- * // scripts/build-search-index.ts
  * import { createBuildCanopy } from 'canopycms/server'
  * import config from '../canopycms.config.js'
  * import { entrySchemaRegistry } from '../src/schemas.js'