canopycms 0.0.67-int.90 → 0.0.67

package/dist/reference-resolver.d.ts

@@ -15,12 +15,6 @@ export interface ReferenceOption {
 }
 /**
  * ReferenceResolver resolves content IDs to display values for reference fields.
- *
- * This class provides utilities for:
- * - Resolving a single ID to its display value (e.g., title)
- * - Loading all available options for a reference field
- * - Filtering options by collection constraints
- * - Searching options by display value
  */
 export declare class ReferenceResolver {
     private store;
@@ -29,9 +23,6 @@ export declare class ReferenceResolver {
     /**
      * Resolve a content ID to a display value.
      * Returns null if the ID doesn't exist or points to a collection.
-     *
-     * @param id - The content ID to resolve
-     * @param displayField - The field to use for display value (default: 'title')
      */
     resolve(id: string, displayField?: string): Promise<ResolvedReference | null>;
     /**
@@ -40,10 +31,6 @@ export declare class ReferenceResolver {
      * Scans collections (including subcollections) and/or filters by entry type.
      * At least one of `collections` or `entryTypes` should be provided.
      *
-     * @param collections - Collection paths to search, including subcollections (e.g., ['data-catalog'])
-     * @param displayField - Field to use for option labels (default: 'title')
-     * @param search - Optional search string to filter options
-     * @param entryTypes - Optional entry type names to filter by (e.g., ['partner'])
      * @param canAccess - Optional permission predicate, called with each candidate's
      *   relative path before it is read. Returning false skips the entry entirely --
      *   no file I/O, no label, no option -- so a caller who can't read a path never

package/dist/reference-resolver.js

@@ -2,12 +2,6 @@ import nodePath from 'node:path';
 import { extractSlugFromFilename, extractEntryTypeFromFilename } from './content-id-index.js';
 /**
  * ReferenceResolver resolves content IDs to display values for reference fields.
- *
- * This class provides utilities for:
- * - Resolving a single ID to its display value (e.g., title)
- * - Loading all available options for a reference field
- * - Filtering options by collection constraints
- * - Searching options by display value
  */
 export class ReferenceResolver {
     constructor(store, idIndex) {
@@ -17,9 +11,6 @@ export class ReferenceResolver {
     /**
      * Resolve a content ID to a display value.
      * Returns null if the ID doesn't exist or points to a collection.
-     *
-     * @param id - The content ID to resolve
-     * @param displayField - The field to use for display value (default: 'title')
      */
     async resolve(id, displayField = 'title') {
         const location = this.idIndex.findById(id);
@@ -56,10 +47,6 @@ export class ReferenceResolver {
      * Scans collections (including subcollections) and/or filters by entry type.
      * At least one of `collections` or `entryTypes` should be provided.
      *
-     * @param collections - Collection paths to search, including subcollections (e.g., ['data-catalog'])
-     * @param displayField - Field to use for option labels (default: 'title')
-     * @param search - Optional search string to filter options
-     * @param entryTypes - Optional entry type names to filter by (e.g., ['partner'])
      * @param canAccess - Optional permission predicate, called with each candidate's
      *   relative path before it is read. Returning false skips the entry entirely --
      *   no file I/O, no label, no option -- so a caller who can't read a path never
@@ -69,18 +56,14 @@ export class ReferenceResolver {
         const options = [];
         let candidates;
         if (collections && collections.length > 0) {
-            // Search within specified collection trees (including subcollections)
-            // getCollectionEntryPaths handles normalization (e.g., 'authors' → 'content/authors')
             const results = await Promise.all(collections.map((col) => this.store.getCollectionEntryPaths(col)));
             candidates = results.flat();
         }
         else {
-            // No collection scope — search all entries via index
             candidates = this.idIndex
                 .getAllEntryLocations()
                 .filter((loc) => loc.type === 'entry' && !!loc.collection && !!loc.slug);
         }
-        // Filter by entry type if specified
         if (entryTypes && entryTypes.length > 0) {
             candidates = candidates.filter((loc) => {
                 const entryType = extractEntryTypeFromFilename(nodePath.basename(loc.relativePath));
@@ -101,7 +84,6 @@ export class ReferenceResolver {
                 const normalizedSlug = extractSlugFromFilename(filename);
                 const doc = await this.store.read(location.collection, normalizedSlug);
                 const label = String(doc.data[displayField] || doc.data.title || normalizedSlug);
-                // Apply search filter if provided
                 if (search && !label.toLowerCase().includes(search.toLowerCase())) {
                     continue;
                 }

package/dist/resolve-canopy-user.d.ts

@@ -1,33 +1,31 @@
 import type { AuthenticationResult } from './auth/types.js';
 import type { CanopyUser } from './user.js';
 import type { OperatingMode } from './operating-mode/index.js';
-/** Test-only: reset the once-per-process "no admins configured" warning latch. */
+/**
+ * Test-only: reset the once-per-process "no admins configured" warning latch.
+ * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ */
 export declare function resetResolveCanopyUserWarningForTests(): void;
 export interface ResolveCanopyUserDeps {
     /**
-     * Resolves (and ensures) the settings workspace root. Internal groups are
-     * the single source of truth for group-based privileges and MUST be
-     * loaded from here — the same root `createContentAccessChecker`
-     * (authorization/content.ts) uses for path permissions — never from a
-     * content branch clone.
+     * Resolves (and ensures) the settings workspace root. Internal groups are the
+     * single source of truth for group-based privileges and MUST be loaded from
+     * here — the same root `createContentAccessChecker` (authorization/content.ts)
+     * uses for path permissions — never from a content branch clone.
      *
-     * Must THROW if the settings workspace cannot be ensured, matching
-     * `createContentAccessChecker`'s fail-loud contract: a caught error here
-     * and a silent fallback to an empty group list would read as "no
-     * privileges", which is a silent authorization change, not a safe
-     * degradation.
+     * MUST THROW if the settings workspace cannot be ensured, matching
+     * `createContentAccessChecker`'s fail-loud contract: a silent fallback to an
+     * empty group list reads as "no privileges", which is a silent authorization
+     * change rather than a safe degradation.
      */
     getSettingsBranchRoot: () => Promise<string>;
     mode: OperatingMode;
     bootstrapAdminIds: Set<string>;
 }
 /**
- * Resolve the CanopyUser for a request: load internal groups from the
- * settings workspace and merge them (plus bootstrap admins) into an
- * authentication result via `authResultToCanopyUser`.
- *
- * Framework-agnostic: callers supply the already-computed `authResult` (from
- * whatever auth-plugin invocation their transport uses) and a small deps
- * bag drawn from `CanopyServices`.
+ * Resolve the CanopyUser for a request: load internal groups from the settings
+ * workspace and merge them, plus bootstrap admins, into an authentication result
+ * via `authResultToCanopyUser`. Framework-agnostic — callers supply the
+ * already-computed `authResult` and a small deps bag from `CanopyServices`.
  */
 export declare function resolveCanopyUser(authResult: AuthenticationResult, deps: ResolveCanopyUserDeps): Promise<CanopyUser>;

package/dist/resolve-canopy-user.js

@@ -1,29 +1,23 @@
 /**
- * Shared "authenticate -> resolve internal groups -> merge into CanopyUser"
- * pipeline.
+ * The shared "authenticate -> resolve internal groups -> merge into CanopyUser"
+ * pipeline: the single resolution point for `http/handler.ts` and
+ * `canopycms-next`'s `context-wrapper.ts`, so the two cannot diverge over where
+ * group-based privileges come from.
  *
- * This used to be duplicated between `http/handler.ts` (the core API
- * handler) and `canopycms-next`'s `context-wrapper.ts` (Next.js SSR user
- * extraction) - including a module-level `warnedNoAdmins` flag in each copy.
- * The duplication let the two drift: `http/handler.ts` loaded internal
- * groups from the BASE BRANCH content clone's `groups.json`, which nothing
- * in the product ever writes (writes go to the settings workspace via
- * `mutateGroupsFile` - `api/groups.ts`), so group-based privileges never
- * actually took effect. Consolidating the pipeline here means both callers
- * read from the same place and cannot silently diverge again.
- *
- * canopyLogWarn, not console.warn: this module has no worker-specific logic,
- * but nothing prevents it from becoming reachable from the worker's runtime
- * import closure later, and the existing "no admins configured" warning is
- * exactly the kind of operationally interesting line that must not be
- * silently folded into an unrelated worker.log event (see utils/logger.ts).
+ * canopyLogWarn, not console.warn: nothing prevents this module from becoming
+ * reachable from the worker's runtime import closure, and the "no admins
+ * configured" warning must not be folded silently into an unrelated worker.log
+ * event (see utils/logger.ts).
  */
 import { canopyLogWarn } from './utils/logger.js';
 import { authResultToCanopyUser } from './user.js';
 import { loadInternalGroups, RESERVED_GROUPS } from './authorization/index.js';
-/** Module-level, matching the pre-extraction behavior: warn at most once per process. */
+/** Module-level: warn at most once per process. */
 let warnedNoAdmins = false;
-/** Test-only: reset the once-per-process "no admins configured" warning latch. */
+/**
+ * Test-only: reset the once-per-process "no admins configured" warning latch.
+ * @internal No importer; deletion candidate in knip-no-importer-deletion-candidates.md.
+ */
 export function resetResolveCanopyUserWarningForTests() {
     warnedNoAdmins = false;
 }
@@ -38,13 +32,10 @@ function warnIfNoAdmins(internalGroups, bootstrapAdminIds) {
     warnedNoAdmins = true;
 }
 /**
- * Resolve the CanopyUser for a request: load internal groups from the
- * settings workspace and merge them (plus bootstrap admins) into an
- * authentication result via `authResultToCanopyUser`.
- *
- * Framework-agnostic: callers supply the already-computed `authResult` (from
- * whatever auth-plugin invocation their transport uses) and a small deps
- * bag drawn from `CanopyServices`.
+ * Resolve the CanopyUser for a request: load internal groups from the settings
+ * workspace and merge them, plus bootstrap admins, into an authentication result
+ * via `authResultToCanopyUser`. Framework-agnostic — callers supply the
+ * already-computed `authResult` and a small deps bag from `CanopyServices`.
  */
 export async function resolveCanopyUser(authResult, deps) {
     const settingsRoot = await deps.getSettingsBranchRoot();

package/dist/resource-generation.d.ts

@@ -2,13 +2,9 @@
 export declare function resourceGenerationPath(root: string, resource: string): string;
 export interface BumpResourceGenerationOptions {
     /**
-     * When true, a failed bump rethrows instead of being logged and swallowed.
-     * Use this for callers where a lost bump means indefinitely stale durable
-     * data with no bounding backstop (e.g. a registry's invalidate()) — those
-     * callers must not silently succeed while leaving stale readers unaware.
-     * Default false (hint flavor): log-warn and swallow, since the mutation
-     * itself is already durable and a lost bump only degrades to pre-marker
-     * staleness behavior plus whatever backstop the consumer has.
+     * Rethrow a failed bump instead of logging and swallowing it. Set it where a
+     * lost bump means indefinitely stale durable data with no bounding backstop
+     * (e.g. a registry's invalidate()). Default false.
      */
     mustSucceed?: boolean;
 }
@@ -17,16 +13,15 @@ export interface BumpResourceGenerationOptions {
  * processes rebuild. Must be called AFTER the filesystem mutation.
  *
  * Returns the token written, or null if the write failed and `mustSucceed`
- * was not set (logged and swallowed).
+ * was not set.
  */
 export declare function bumpResourceGeneration(root: string, resource: string, options?: BumpResourceGenerationOptions): Promise<string | null>;
 /**
- * Result of reading a generation marker. `ok: false` means the read failed
- * for a reason OTHER than "marker doesn't exist yet" — callers should treat
- * this as "force regenerate" rather than folding it into a token value,
- * because a legitimate snapshot can embed `token: null` (a fresh clone,
- * regenerated before any bump ever occurred) and that must stay
- * distinguishable from "we don't actually know the current token".
+ * Result of reading a generation marker. `ok: false` means the read failed for
+ * a reason OTHER than "marker doesn't exist yet"; callers force-regenerate
+ * rather than folding it into a token value, because a legitimate snapshot can
+ * embed `token: null` (a fresh clone regenerated before any bump) and that must
+ * stay distinguishable from "we don't know the current token".
  */
 export type GenerationReadResult = {
     ok: true;
@@ -35,19 +30,15 @@ export type GenerationReadResult = {
     ok: false;
 };
 /**
- * Read the current generation token for `resource` under `root`.
- *
- * ENOENT maps to `{ok: true, token: null}` — a valid "never bumped" state,
- * distinct from every real token. Any OTHER read error maps to `{ok: false}`
- * (logged) so callers can force-regenerate instead of trusting a null they
- * cannot actually attribute to "never bumped".
+ * Read the current generation token for `resource` under `root`. ENOENT maps to
+ * `{ok: true, token: null}`, the "never bumped" state; every other read error
+ * maps to `{ok: false}`.
  */
 export declare function readResourceGeneration(root: string, resource: string): Promise<GenerationReadResult>;
 /**
- * True when a previously-captured snapshot token is still current: the read
- * succeeded AND its token matches the snapshot's. A failed read (`ok: false`)
- * is never current, even if the snapshot's token happens to be null — an
- * unreadable marker means we cannot vouch for freshness either way, and the
- * safe default is to treat it as stale.
+ * True when a snapshot's captured token is still current: the read succeeded
+ * AND its token matches. A failed read (`ok: false`) is never current, even
+ * against a null snapshot token — an unreadable marker vouches for nothing, so
+ * the safe default is stale.
  */
 export declare function isGenerationCurrent(snapshotToken: string | null, read: GenerationReadResult): boolean;

package/dist/resource-generation.js

@@ -5,93 +5,34 @@ import { atomicWriteFile } from './utils/atomic-write.js';
 import { getErrorMessage, isNodeError } from './utils/error.js';
 import { createDebugLogger } from './utils/debug.js';
 /**
- * Generalized cross-process generation marker for any on-disk resource that
- * is durably cached under a branch-clone (or similar) root.
+ * Cross-process generation marker for an on-disk resource cached under a
+ * branch-clone root: several warm Lambda containers and the EC2 worker share
+ * those clones on EFS with no shared memory and no cross-host file watching,
+ * so the filesystem coordinates. The marker for `resource` lives at
+ * {root}/.canopy-meta/{resource}.generation — dot-prefixed so content and
+ * index scans skip it, and excluded from git via .git/info/exclude.
  *
- * Some in-process cache is kept per resource per process (an in-memory index,
- * a parsed schema, a registry snapshot). Within one process, mutating code can
- * invalidate that cache directly. Across processes (several warm Lambda
- * containers + the EC2 worker sharing branch clones on EFS) there is no
- * shared memory and no cross-host file watching, so the shared filesystem
- * itself is the coordination medium: every operation that mutates the
- * resource also rewrites a small marker file with a fresh random token, and
- * every consumer cheaply re-reads that marker (throttled) to decide whether
- * its cached snapshot is still current.
+ * - Mutators bump AFTER mutating, with a fresh random token: a counter would
+ *   need read-modify-write and lose concurrent bumps without a lock.
+ * - Regenerators capture the token BEFORE scanning and embed it in the
+ *   snapshot; readers compare that token against the live marker and
+ *   regenerate on mismatch. A regeneration racing an invalidation embeds the
+ *   old token, so it self-describes as stale and heals on the next read.
+ * - Regeneration returns its own scan result and never loops until the tokens
+ *   match, which would livelock under a bump storm.
+ * - `mustSucceed` bumps explicit invalidations, where a swallowed failure
+ *   means indefinite staleness; bulk `finally`-block callers take the default
+ *   log-and-swallow hint bump.
+ * - A marker read error other than ENOENT stays distinct from "never bumped":
+ *   the consumer serves the fresh scan but skips persisting a snapshot whose
+ *   token it cannot attribute to that scan.
  *
- * The marker for a given `resource` lives at {root}/.canopy-meta/{resource}.generation:
- * `.canopy-meta/` is the established per-clone internal dir — dot-prefixed (so
- * content and index scans skip it) and excluded from git via .git/info/exclude.
- *
- * ## Why a random token instead of a monotonic counter
- *
- * Readers only need "did it change since I captured it", so inequality against
- * the captured value suffices. A counter would need read-modify-write, which
- * silently loses concurrent bumps without a lock (two bumpers read 5, both
- * write 6 — a reader that recorded 6 after the first bump never learns of the
- * second mutation). A unique token per bump has no lost-update problem, needs
- * no lock, and avoids NFS mtime-granularity / cross-host clock-skew issues.
- * Each bump is a single atomic temp-file + rename.
- *
- * ## Ordering protocol (correctness)
- *
- * - Bumpers write the marker strictly AFTER their filesystem mutations.
- * - Readers capture the marker token strictly BEFORE scanning/rebuilding the
- *   resource, and record it only after the rebuild completes. A bump landing
- *   mid-rebuild therefore leaves the recorded token older than the file,
- *   forcing another rebuild on the next probe.
- *
- * ## Consistency guarantees and residual staleness windows (EFS/NFSv4)
- *
- * Guaranteed: any completed mutation that bumps the marker is observed by
- * every consumer on that root at its next freshness probe. Residual windows
- * (bounded in practice by per-request lifetimes and, where implemented, a
- * suspicious-lookup backstop):
- *
- * - (A) NFS attribute caching (benign direction): another host may not see a
- *   new marker for up to the attribute-cache timeout (~3-60s on default EFS
- *   mounts; `noac` cannot be assumed). The reader acts on a stale token and
- *   keeps a stale snapshot until the cache expires.
- * - (B) Probe throttle: however long the consumer debounces freshness checks.
- * - (C) Self-adoption: after its own mutation a consumer adopts the token it
- *   wrote; if a concurrent foreign bump landed just before ours, we miss that
- *   one notification (window: from our last token observation to our rename).
- * - (E) Fresh-token/stale-scan (malignant direction, cross-host only): NFS
- *   revalidates the marker file on open, but a rebuild's reads may be served
- *   from dentry/attribute caches — a rebuild can record a NEW token against
- *   PRE-mutation data, leaving that consumer confidently stale until the next
- *   bump. Structurally unfixable with a filesystem marker; bounded by
- *   per-request lifetimes and any backstop the consumer implements.
- *
- * ## Guarantee delta for DURABLE snapshot consumers (registry / schema-cache)
- *
- * The in-memory ContentIdIndex tolerates window (E) because a stale index is
- * scoped to one process's memory: it self-heals on the next probe or process
- * recycle, and a wrong-file write is independently guarded by ContentStore's
- * existence check. Consumers that persist a durable snapshot ALONGSIDE this
- * marker — a branch registry list, a resolved-schema cache file — do not get
- * that same containment. If such a consumer's regeneration scan is served
- * from stale NFS dentry/attribute caches, window (E) produces a snapshot that
- * embeds a FRESH token over STALE data, and that snapshot is written to disk.
- * Every other host that reads the marker sees the fresh token, concludes the
- * durable snapshot is current, and serves the stale data too — this is now a
- * durable, SHARED staleness visible to all hosts until the next bump, not a
- * transient one-process condition. A random token cannot distinguish "fresh
- * token over fresh data" from "fresh token over stale data" — the token only
- * proves a bump happened, not that the bumping host's own scan observed it.
- *
- * Durable-snapshot consumers must therefore implement mitigations this module
- * cannot provide on their behalf:
- *
- * - Eager regeneration on the mutating host, performed immediately after its
- *   own bump (in the same request/operation). That host's own scan is
- *   necessarily coherent with the mutation it just made (no NFS round trip
- *   was needed to observe its own writes), so regenerating there rather than
- *   waiting for a lazy pull on some other host avoids handing window (E) a
- *   chance to run at all for the common case.
- * - A get-miss / suspicious-lookup backstop: if a consumer looks up something
- *   that "should" exist per the durable snapshot but is missing (or vice
- *   versa), that mismatch is a signal to force a fresh regeneration rather
- *   than trusting the token match, bounding how long a bad snapshot survives.
+ * A consumer that persists its snapshot (branch registry, schema cache) can
+ * durably record a fresh token over data its scan read from a stale NFS cache,
+ * which every other host then trusts. So the mutating host regenerates eagerly
+ * right after its own bump — that scan is coherent with its own mutation — and
+ * the registry adds a suspicious-miss backstop. Staleness windows (A/B/C/E) and
+ * the rolling-deploy transient: docs/concurrency.md, "Residual staleness windows".
  */
 const log = createDebugLogger({ prefix: 'ResourceGeneration' });
 const META_DIR = '.canopy-meta';
@@ -104,7 +45,7 @@ export function resourceGenerationPath(root, resource) {
  * processes rebuild. Must be called AFTER the filesystem mutation.
  *
  * Returns the token written, or null if the write failed and `mustSucceed`
- * was not set (logged and swallowed).
+ * was not set.
  */
 export async function bumpResourceGeneration(root, resource, options) {
     const token = randomUUID();
@@ -122,12 +63,9 @@ export async function bumpResourceGeneration(root, resource, options) {
     }
 }
 /**
- * Read the current generation token for `resource` under `root`.
- *
- * ENOENT maps to `{ok: true, token: null}` — a valid "never bumped" state,
- * distinct from every real token. Any OTHER read error maps to `{ok: false}`
- * (logged) so callers can force-regenerate instead of trusting a null they
- * cannot actually attribute to "never bumped".
+ * Read the current generation token for `resource` under `root`. ENOENT maps to
+ * `{ok: true, token: null}`, the "never bumped" state; every other read error
+ * maps to `{ok: false}`.
  */
 export async function readResourceGeneration(root, resource) {
     try {
@@ -144,11 +82,10 @@ export async function readResourceGeneration(root, resource) {
     }
 }
 /**
- * True when a previously-captured snapshot token is still current: the read
- * succeeded AND its token matches the snapshot's. A failed read (`ok: false`)
- * is never current, even if the snapshot's token happens to be null — an
- * unreadable marker means we cannot vouch for freshness either way, and the
- * safe default is to treat it as stale.
+ * True when a snapshot's captured token is still current: the read succeeded
+ * AND its token matches. A failed read (`ok: false`) is never current, even
+ * against a null snapshot token — an unreadable marker vouches for nothing, so
+ * the safe default is stale.
  */
 export function isGenerationCurrent(snapshotToken, read) {
     return read.ok && read.token === snapshotToken;

package/dist/schema/meta-loader.d.ts

@@ -1,7 +1,7 @@
 import type { RootCollectionConfig } from '../config/index.js';
 import type { ContentId } from '../paths/types.js';
 import type { EntrySchemaRegistry } from './types.js';
-export type EntryTypeMeta = {
+type EntryTypeMeta = {
     name: string;
     format: 'md' | 'mdx' | 'json' | 'yaml';
     schema: string;
@@ -23,11 +23,6 @@ export type RootCollectionMeta = {
 /**
  * Loads all .collection.json meta files from contentRoot, including root.
  *
- * This function orchestrates the complete discovery process:
- * 1. Attempts to load the root .collection.json (contentRoot/.collection.json) - optional
- * 2. Recursively scans all subdirectories for .collection.json files
- * 3. Returns both root configuration and nested collections
- *
  * Meta File Structure:
  * - Root: contentRoot/.collection.json (optional, defines root-level entry types)
  * - Collections: contentRoot/[path]/.collection.json (defines collection in that directory)
@@ -49,11 +44,6 @@ export declare function loadCollectionMetaFiles(contentRoot: string): Promise<{
  * This function takes the loaded meta files (which contain string references like "postSchema")
  * and resolves them to actual EntrySchema arrays from the entry schema registry.
  *
- * Resolution Process:
- * 1. Root entry types: Resolve "schema" string to entry schema registry lookup
- * 2. Top-level collections: Resolve recursively, building nested tree structure
- * 3. Nested collections: Automatically grouped under their parent collections
- *
  * @param metaFiles - Loaded meta files from loadCollectionMetaFiles()
  * @param entrySchemaRegistry - Map of schema names to EntrySchema arrays
  * @returns Fully resolved root collection config ready for use by CanopyCMS
@@ -66,7 +56,5 @@ export declare function resolveCollectionReferences(metaFiles: {
         contentId?: ContentId;
     }>;
 }, entrySchemaRegistry: EntrySchemaRegistry): RootCollectionConfig;
-/**
- * Watch for changes to .collection.json files
- */
 export declare function watchCollectionMetaFiles(contentRoot: string, onChange: () => void): () => void;
+export {};