canopycms 0.0.67-int.90 → 0.0.67

package/dist/url-path-resolver.js

@@ -1,25 +1,17 @@
 import { trimSlashes } from './paths/normalize.js';
 import { isIndexSlug } from './utils/entry-url.js';
 /**
- * Resolves a URL path to candidate entryPath/slug pairs for content lookup.
+ * Resolve a URL path to the candidate entryPath/slug pairs a lookup should try, in order:
  *
- * Returns an ordered list of attempts:
- * 1. Direct entry: last segment is slug, rest is collection path — SKIPPED when that slug is
- *    literally 'index' (see below)
- * 2. Index fallback: full path is collection, slug is 'index'
+ * 1. Direct entry: last segment is the slug, the rest is the collection path — SKIPPED when that
+ *    slug is an index slug (see below).
+ * 2. Index fallback: the whole path is a collection and the slug is 'index'.
  *
- * This is the REVERSE of the forward collection+slug -> url rule, and the two must agree on how
- * many URLs an entry answers at. The forward rule (`computeEntryUrl` in utils/entry-url.ts, which
+ * This is the REVERSE of the forward collection+slug -> url rule and must agree with it about how
+ * many URLs an entry answers at. The forward rule — `computeEntryUrl` (utils/entry-url.ts), which
  * `listEntries` publishes as `item.urlPath` and reference resolution stamps on every resolved
- * reference; and `defaultBuildPath` in content-tree.ts for tree nodes) collapses an `index` slug
- * onto its collection's path and never emits a trailing `/index`. Candidate 1 used to match it
- * anyway, so an index entry ALSO answered at a `.../index` URL that no forward surface publishes
- * — enumeration and resolution disagreeing about how many URLs exist. Adopters paid for that with
- * per-route entryType gates whose only job was to reject the phantom.
- *
- * @param urlPath - URL path like '/docs/guides/getting-started' or 'docs/guides'
- * @param contentRoot - Content root directory name (default: 'content')
- * @returns Array of { entryPath, slug } candidates to try in order
+ * reference, plus `defaultBuildPath` (content-tree.ts) for tree nodes — collapses an `index` slug
+ * onto its collection's path and never emits a trailing `/index`.
  */
 export function resolveUrlPathCandidates(urlPath, contentRoot) {
     const normalized = trimSlashes(urlPath);
@@ -29,24 +21,23 @@ export function resolveUrlPathCandidates(urlPath, contentRoot) {
     const candidates = [];
     // Try 1: last segment is the entry slug, rest is the collection path.
     //
-    // Skipped when that slug is an index slug. An index entry's ADVERTISED URL is its collapsed
+    // Skipped when that slug is an index slug: an index entry's ADVERTISED URL is its collapsed
     // collection path, so matching it here would answer at a second URL enumeration never emits.
-    // `index` is not a contrived segment either — it is the slug the index convention requires on
-    // disk, so the collision was structural rather than accidental.
+    // `index` is the slug the index convention requires on disk, so the collision is structural
+    // rather than contrived.
     //
-    // This closes the `.../index` spelling only. The other extra URLs an entry answered at —
+    // This closes the `.../index` spelling only. The other extra URLs an entry can answer at —
     // `/<collection>/<entryTypeName>` via candidate 2, and `/<collection>/<entryTypeName>/<slug>`
     // via candidate 1 — are closed DOWNSTREAM instead, by `readByUrlPath` requiring every
     // candidate's `entryPath` to be a collection (`ReadContentInput.urlAddressableOnly`). They have
-    // to be: telling those apart needs the branch's schema, and this module is deliberately pure
-    // and schema-free so that the candidate shapes stay a fact about URLs rather than about
-    // content. The consequence to keep in mind when reading this file: the candidates below are
-    // what is ATTEMPTED, not what can resolve.
+    // to be: telling those apart needs the branch's schema, and this module is deliberately pure and
+    // schema-free so the candidate shapes stay a fact about URLs rather than about content. So the
+    // candidates below are what is ATTEMPTED, not what can resolve.
     //
-    // Compared case-INSENSITIVELY, through the shared `isIndexSlug`. This function is the one
-    // consumer that sees a raw, un-normalized URL segment — everything downstream lowercases
-    // (`parseSlug`, and ContentStore's directory scan) — so a strict compare here closed
-    // `/x/index` while leaving `/x/Index` and `/x/INDEX` resolving the very entry it exists to hide.
+    // Compared case-INSENSITIVELY through the shared `isIndexSlug`: this function is the one consumer
+    // that sees a raw, un-normalized URL segment (`parseSlug` and ContentStore's directory scan
+    // lowercase downstream), so a strict compare would close `/x/index` while leaving `/x/Index` and
+    // `/x/INDEX` resolving the very entry the skip exists to hide.
     const slug = segments[segments.length - 1];
     const collectionSegments = segments.slice(0, -1);
     const entryPath = collectionSegments.length > 0 ? `${contentRoot}/${collectionSegments.join('/')}` : contentRoot;
@@ -58,7 +49,6 @@ export function resolveUrlPathCandidates(urlPath, contentRoot) {
     // Kept unconditionally, which is what makes the skip above a skip rather than a removal: a
     // collection literally NAMED `index` is handed the path `/x/index` by
     // `defaultBuildPath(kind: 'collection')`, and this candidate is the only one that can answer it.
-    // (Candidate 1 used to shadow that collection entirely, returning the parent's own index entry.)
     candidates.push({
         entryPath: `${contentRoot}/${segments.join('/')}`,
         slug: 'index',

package/dist/user.d.ts

@@ -1,17 +1,13 @@
 import type { CanopyUserId, CanopyGroupId } from './types.js';
 import type { AuthenticationResult } from './auth/types.js';
 import type { InternalGroup } from './authorization/groups/schema.js';
-/**
- * Anonymous user - explicitly marked for public/unauthenticated access
- */
+/** Anonymous user — explicit public/unauthenticated access. */
 export interface AnonymousUser {
     type: 'anonymous';
     userId: 'anonymous';
     groups: readonly [];
 }
-/**
- * Authenticated user - verified identity from auth provider
- */
+/** Authenticated user — verified identity from the auth provider. */
 export interface AuthenticatedUser {
     type: 'authenticated';
     userId: CanopyUserId;
@@ -20,24 +16,15 @@ export interface AuthenticatedUser {
     name?: string;
     avatarUrl?: string;
 }
-/**
- * Unified user type for all CanopyCMS operations
- */
+/** Unified user type for all CanopyCMS operations. */
 export type CanopyUser = AnonymousUser | AuthenticatedUser;
-/**
- * Branded ANONYMOUS_USER constant - use this for intentional anonymous access.
- * Callers must explicitly pass this to indicate anonymous access is intended.
- */
+/** Pass this constant explicitly wherever anonymous access is intended. */
 export declare const ANONYMOUS_USER: AnonymousUser;
 /**
- * Convert authentication result to CanopyUser.
- * Applies bootstrap admin groups, merges internal groups, and returns ANONYMOUS_USER if not authenticated.
- *
- * This is the SINGLE source of truth for converting external auth to CanopyUser.
+ * Convert an authentication result to a CanopyUser: applies bootstrap admin groups, merges
+ * internal groups, returns ANONYMOUS_USER when not authenticated. The SINGLE source of truth
+ * for turning external auth into a CanopyUser.
  *
- * @param authResult - Result from auth plugin's authenticate() method
- * @param bootstrapAdminIds - Set of user IDs that should always be admins
- * @param internalGroups - Optional internal groups from .canopycms/groups.json (loaded by caller)
- * @returns CanopyUser (either authenticated with groups or ANONYMOUS_USER)
+ * @param internalGroups - Internal groups from .canopycms/groups.json, loaded by the caller.
  */
 export declare function authResultToCanopyUser(authResult: AuthenticationResult, bootstrapAdminIds: Set<string>, internalGroups?: InternalGroup[]): CanopyUser;

package/dist/user.js

@@ -1,40 +1,31 @@
 // Import from client-safe subpaths to avoid pulling in server-only loader code
 import { RESERVED_GROUPS, stripReservedGroups } from './authorization/helpers.js';
-/**
- * Branded ANONYMOUS_USER constant - use this for intentional anonymous access.
- * Callers must explicitly pass this to indicate anonymous access is intended.
- */
+/** Pass this constant explicitly wherever anonymous access is intended. */
 export const ANONYMOUS_USER = Object.freeze({
     type: 'anonymous',
     userId: 'anonymous',
     groups: [],
 });
 /**
- * Convert authentication result to CanopyUser.
- * Applies bootstrap admin groups, merges internal groups, and returns ANONYMOUS_USER if not authenticated.
- *
- * This is the SINGLE source of truth for converting external auth to CanopyUser.
+ * Convert an authentication result to a CanopyUser: applies bootstrap admin groups, merges
+ * internal groups, returns ANONYMOUS_USER when not authenticated. The SINGLE source of truth
+ * for turning external auth into a CanopyUser.
  *
- * @param authResult - Result from auth plugin's authenticate() method
- * @param bootstrapAdminIds - Set of user IDs that should always be admins
- * @param internalGroups - Optional internal groups from .canopycms/groups.json (loaded by caller)
- * @returns CanopyUser (either authenticated with groups or ANONYMOUS_USER)
+ * @param internalGroups - Internal groups from .canopycms/groups.json, loaded by the caller.
  */
 export function authResultToCanopyUser(authResult, bootstrapAdminIds, internalGroups) {
     if (!authResult.success || !authResult.user) {
         return ANONYMOUS_USER;
     }
-    // Step 1: Start with external groups from the auth provider.
-    // SECURITY (SEC-H1): reserved privileged group IDs (Admins/Reviewers) are
-    // stripped here so a provider-controlled group name can never grant
-    // CanopyCMS privilege. Reserved membership is only added below, from
-    // bootstrapAdminIds and Canopy-managed internal groups.
+    // SECURITY (SEC-H1): the privileged group IDs held in `RESERVED_GROUPS` are stripped from the
+    // provider's list here, so a provider-controlled group name can never grant CanopyCMS
+    // privilege. Reserved membership is added only below, from bootstrapAdminIds and
+    // Canopy-managed internal groups.
     const groups = stripReservedGroups(authResult.user.externalGroups ?? []);
-    // Step 2: Add Admins group if user is in bootstrap admin list
     if (bootstrapAdminIds.has(authResult.user.userId) && !groups.includes(RESERVED_GROUPS.ADMINS)) {
         groups.push(RESERVED_GROUPS.ADMINS);
     }
-    // Step 3: Merge internal groups from .canopycms/groups.json
+    // Internal groups from .canopycms/groups.json.
     if (internalGroups) {
         for (const group of internalGroups) {
             if (group.members.includes(authResult.user.userId) && !groups.includes(group.id)) {

package/dist/utils/async-mutex.js

@@ -1,11 +1,9 @@
 /**
- * FIFO per-key async mutex.
+ * FIFO per-key async mutex, keyed by any string that uniquely identifies the resource (usually
+ * an absolute file path). Module-level, so it serializes only within one process.
  *
- * Module-level map so all callers within the same process share the same set of locks.
- * Lock key = absolute file path (or any string that uniquely identifies the resource).
- *
- * Each caller atomically enqueues itself behind the current tail and only ever wakes
- * once — guaranteeing strict FIFO order with no thundering-herd on release.
+ * Each caller atomically enqueues itself behind the current tail and wakes exactly once: strict
+ * FIFO order, no thundering herd on release.
  */
 const locks = new Map();
 export async function withLock(key, fn) {

package/dist/utils/atomic-write.d.ts

@@ -1,14 +1,5 @@
 /**
- * Atomic file write utility.
- *
- * Writes to a temp file first, then renames over the target.
- * Prevents partial/interleaved writes that corrupt files on NFS/EFS.
- */
-/**
- * Atomically write content to a file via temp-file + rename.
- * Ensures the target file is never partially written.
- *
- * @param filePath - Absolute path to the target file
- * @param content - String or binary content to write
+ * Atomic file write: temp file first, then rename over the target, so the file is never
+ * partially written. Prevents the interleaved writes that corrupt files on NFS/EFS.
  */
 export declare function atomicWriteFile(filePath: string, content: string | Buffer | Uint8Array): Promise<void>;

package/dist/utils/atomic-write.js

@@ -1,18 +1,9 @@
 /**
- * Atomic file write utility.
- *
- * Writes to a temp file first, then renames over the target.
- * Prevents partial/interleaved writes that corrupt files on NFS/EFS.
+ * Atomic file write: temp file first, then rename over the target, so the file is never
+ * partially written. Prevents the interleaved writes that corrupt files on NFS/EFS.
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-/**
- * Atomically write content to a file via temp-file + rename.
- * Ensures the target file is never partially written.
- *
- * @param filePath - Absolute path to the target file
- * @param content - String or binary content to write
- */
 export async function atomicWriteFile(filePath, content) {
     const dir = path.dirname(filePath);
     await fs.mkdir(dir, { recursive: true });

package/dist/utils/body-field.d.ts

@@ -1,28 +1,21 @@
 import type { FieldConfig } from '../config/index.js';
 /**
- * Count the number of top-level fields marked `isBody: true` in a schema.
- * Does NOT recurse into objects — isBody only makes sense at the top level
- * because it maps to the file's markdown content.
+ * Count top-level fields marked `isBody: true`. Does NOT recurse into objects — `isBody` maps
+ * to the file's markdown content, which exists only at the top level.
  */
 export declare function countBodyFields(fields: readonly FieldConfig[]): number;
-/**
- * Find the name of the field marked `isBody: true`, or `'body'` as the default.
- * Used at read time to map the markdown file's content to the correct data field.
- */
+/** Name of the `isBody: true` field, or `'body'`; maps the file's markdown onto a data field. */
 export declare function findBodyFieldName(fields: readonly FieldConfig[]): string;
 /**
  * Find an isBody field whose NAME is reserved by reference resolution.
  *
  * A resolved reference reserves `id`/`slug`/`collection`/`urlPath` by applying them after the
  * target's data. The body is the one value assigned by key rather than spread, so a body field
- * named e.g. `id` would be the single way to get around that — and since the write boundary
- * recovers a reference's id from `value.id`, re-saving would then persist the prose as the
- * reference. Rejected at registry-validation time instead, so the schema fails loudly rather
- * than the body being silently dropped at resolution.
+ * named e.g. `id` is the one way around that — and the write boundary recovers a reference's id
+ * from `value.id`, so re-saving would persist the prose as the reference. Rejected at
+ * registry-validation time, so the schema fails loudly instead of the body being silently
+ * dropped at resolution.
  */
 export declare function findReservedBodyFieldName(fields: readonly FieldConfig[], reserved: readonly string[]): string | undefined;
-/**
- * Find isBody fields that have an invalid type (not 'markdown' or 'mdx').
- * Returns field names that fail validation.
- */
+/** Names of isBody fields whose type is neither 'markdown' nor 'mdx'. */
 export declare function findInvalidBodyFields(fields: readonly FieldConfig[]): string[];

package/dist/utils/body-field.js

@@ -1,9 +1,8 @@
 import { flattenGroupFields } from './flatten-group-fields.js';
 const BODY_FIELD_TYPES = new Set(['markdown', 'mdx']);
 /**
- * Count the number of top-level fields marked `isBody: true` in a schema.
- * Does NOT recurse into objects — isBody only makes sense at the top level
- * because it maps to the file's markdown content.
+ * Count top-level fields marked `isBody: true`. Does NOT recurse into objects — `isBody` maps
+ * to the file's markdown content, which exists only at the top level.
  */
 export function countBodyFields(fields) {
     let count = 0;
@@ -13,10 +12,7 @@ export function countBodyFields(fields) {
     }
     return count;
 }
-/**
- * Find the name of the field marked `isBody: true`, or `'body'` as the default.
- * Used at read time to map the markdown file's content to the correct data field.
- */
+/** Name of the `isBody: true` field, or `'body'`; maps the file's markdown onto a data field. */
 export function findBodyFieldName(fields) {
     for (const field of flattenGroupFields(fields)) {
         if ('isBody' in field && field.isBody)
@@ -29,10 +25,10 @@ export function findBodyFieldName(fields) {
  *
  * A resolved reference reserves `id`/`slug`/`collection`/`urlPath` by applying them after the
  * target's data. The body is the one value assigned by key rather than spread, so a body field
- * named e.g. `id` would be the single way to get around that — and since the write boundary
- * recovers a reference's id from `value.id`, re-saving would then persist the prose as the
- * reference. Rejected at registry-validation time instead, so the schema fails loudly rather
- * than the body being silently dropped at resolution.
+ * named e.g. `id` is the one way around that — and the write boundary recovers a reference's id
+ * from `value.id`, so re-saving would persist the prose as the reference. Rejected at
+ * registry-validation time, so the schema fails loudly instead of the body being silently
+ * dropped at resolution.
  */
 export function findReservedBodyFieldName(fields, reserved) {
     for (const field of flattenGroupFields(fields)) {
@@ -41,10 +37,7 @@ export function findReservedBodyFieldName(fields, reserved) {
     }
     return undefined;
 }
-/**
- * Find isBody fields that have an invalid type (not 'markdown' or 'mdx').
- * Returns field names that fail validation.
- */
+/** Names of isBody fields whose type is neither 'markdown' nor 'mdx'. */
 export function findInvalidBodyFields(fields) {
     const invalid = [];
     for (const field of flattenGroupFields(fields)) {

package/dist/utils/content-serialize.d.ts

@@ -1,37 +1,31 @@
 /**
  * Comment-preserving serialisation for YAML content files and md/mdx frontmatter.
  *
- * ContentStore used to write a content file by stringifying a fresh plain object
- * (`yamlStringify(data)` / `matter.stringify(body, data)`). Comments live in neither the object
- * nor that round trip, so **every editor save silently deleted every comment in the file** —
- * invisible to a dev team (`canopycms sync` copies files byte-for-byte) and certain for an
- * editorial team. See `.claude/future-tasks/resolved/content-comment-loss-on-editor-save.md`.
+ * Stringifying a fresh plain object (`yamlStringify(data)` / `matter.stringify(body, data)`)
+ * deletes every comment in the file, because comments live in neither the object nor that round
+ * trip. So these functions re-serialise onto the file's OWN parsed document: a node whose value
+ * did not change is left untouched, and an untouched node keeps its attached comments and its
+ * original quoting/block style. Only what actually changed is rewritten.
  *
- * The fix re-serialises onto the file's OWN parsed document instead of a fresh one: nodes whose
- * value did not change are left untouched, and an untouched node keeps its attached comments
- * (and its original quoting/block style). Only what actually changed is rewritten.
- *
- * What this module does NOT do is give the file any authority over its own content. The
- * reconciler makes the document's key set match `data` exactly — a key the caller dropped
- * disappears, a key the caller kept survives whether or not the schema still knows about it.
- * Data authority stays with the payload; comments are the only thing inherited from disk. That
- * separation is deliberate: whether a surviving key SHOULD still be there is a schema question,
- * answered one layer up by `findUnknownKeys` (validation/entry-validator.ts) at the API
- * boundary, not by a serialiser that has no schema.
+ * The file gets no authority over its own content. The reconciler makes the document's key set
+ * match `data` exactly — a key the caller dropped disappears, a key the caller kept survives
+ * whether or not the schema still knows about it. Data authority stays with the payload;
+ * comments are the only thing inherited from disk. Whether a surviving key SHOULD still be there
+ * is a schema question, answered one layer up by `findUnknownKeys`
+ * (validation/entry-validator.ts) at the API boundary, not by a schema-blind serialiser.
  */
 /**
  * Serialise entry data as a YAML file, carrying the comments of `existingRaw` through.
  *
- * Falls back to a plain stringify — byte-identical to the pre-fix behaviour — when there is
- * nothing to preserve (a new file) or nothing trustworthy to preserve (the bytes on disk do not
- * parse). A save must not fail because the previous content was malformed.
+ * Falls back to a plain stringify — byte-identical to serialising without preservation — when
+ * there is nothing to preserve (a new file) or nothing trustworthy to preserve (the bytes on disk
+ * do not parse). A save must not fail because the previous content was malformed.
  */
 export declare function serializeYaml(data: Record<string, unknown>, existingRaw?: string): string;
 /**
- * Serialise an md/mdx entry, carrying the comments of `existingRaw`'s frontmatter through.
- *
- * The reconciled YAML goes back through `matter.stringify` via a custom stringify engine rather
- * than being spliced between hand-written `---` lines, so the delimiters, blank lines and
- * trailing newline stay exactly what gray-matter would have produced.
+ * Serialise an md/mdx entry, carrying the comments of `existingRaw`'s frontmatter through. The
+ * reconciled YAML goes back through `matter.stringify` via a custom stringify engine rather than
+ * being spliced between hand-written `---` lines, so delimiters, blank lines and the trailing
+ * newline stay exactly what gray-matter would have produced.
  */
 export declare function serializeFrontmatter(body: string, data: Record<string, unknown>, existingRaw?: string): string;