canopycms 0.0.62 → 0.0.64

package/dist/config/types.d.ts

@@ -2,13 +2,13 @@
  * Type definitions for CanopyCMS configuration.
  * These are pure TypeScript types - Zod schemas are in ./schemas/
  */
-import type { CanopyGroupId, CanopyUserId } from '../types';
-import type { OperatingMode } from '../operating-mode';
-import type { AuthPlugin } from '../auth/plugin';
-import type { LogicalPath, ContentId } from '../paths/types';
-import type { PermissionPath } from '../authorization/types';
-import type { EntryLinkUrlResolver } from '../entry-link-resolver';
-import type { CropRect } from '../assets/transform-directives';
+import type { CanopyGroupId, CanopyUserId } from '../types.js';
+import type { OperatingMode } from '../operating-mode/index.js';
+import type { AuthPlugin } from '../auth/plugin.js';
+import type { LogicalPath, ContentId } from '../paths/types.js';
+import type { PermissionPath } from '../authorization/types.js';
+import type { EntryLinkUrlResolver } from '../entry-link-resolver.js';
+import type { CropRect } from '../assets/transform-directives.js';
 export declare const primitiveFieldTypes: readonly ["string", "number", "boolean", "datetime", "markdown", "mdx", "code"];
 export declare const fieldTypes: readonly ["string", "number", "boolean", "datetime", "markdown", "mdx", "code", "image", "select", "reference", "object", "block", "group"];
 export type PrimitiveFieldType = (typeof primitiveFieldTypes)[number];
@@ -68,6 +68,27 @@ export interface ReferenceFieldConfig extends BaseFieldConfig {
     entryTypes?: string[];
     displayField?: string;
     options?: ReferenceOption[];
+    /**
+     * Include the referenced entry's body in the resolved value, under that entry type's own
+     * body field name (`isBody: true`, else `body`). Defaults to `false`.
+     *
+     * This is the embed-vs-link distinction, declared where it is actually known. A reference
+     * that **embeds** its target — a shared call-to-action block rendered inline — needs the
+     * target's prose, and without this a resolved md/mdx target arrives as frontmatter only, so
+     * a search index built over pages with shared blocks silently contains nothing for them. A
+     * reference that merely **links** to its target — related posts, an author byline — wants
+     * `urlPath` and a title, and emphatically not the target's full body inlined into every
+     * page read.
+     *
+     * It lives on the field rather than on `read()`/`listEntries()` because one call routinely
+     * contains both kinds: a page with a shared CTA *and* a related-posts list cannot be served
+     * by a single call-level setting, and a call-level flag would mean the same field resolved
+     * to different shapes in different places.
+     *
+     * Only affects formats that HAVE a separate body — md and mdx. A json/yaml target's whole
+     * document is already its data, so this is a no-op there.
+     */
+    includeBody?: boolean;
 }
 /**
  * Image field config. The value is a structured object (see `ImageFieldValue`
@@ -215,6 +236,15 @@ export interface CanopyEditorConfig {
     title?: string;
     subtitle?: string;
     theme?: unknown;
+    /**
+     * Per-collection overrides for the preview pane's URL, keyed by collection path or name
+     * (e.g. `{ 'content/posts': '/blog' }`) for sites whose routes don't mirror their content tree.
+     *
+     * Values are **site-relative** and must NOT include the deployment `basePath` — that is applied
+     * on top of whatever this yields (see `CanopyConfig.basePath`), so including it here would
+     * prefix it twice. An absolute value (`https://…`) is passed through untouched instead, which
+     * is the escape hatch for previewing against a different origin entirely.
+     */
     previewBase?: Record<string, string>;
     onAccountClick?: () => void;
     onLogoutClick?: () => void;
@@ -315,6 +345,21 @@ export interface CanopyConfig {
     deploymentName?: string;
     contentRoot: ContentRoot;
     sourceRoot?: SourceRoot;
+    /**
+     * The deployment prefix the host Next.js app is served under (e.g. `/preview-123`), matching
+     * that app's `next.config` `basePath`. CanopyCMS cannot read `next.config` at runtime, so this
+     * must be stated here explicitly if the app sets one — without it, editor requests, the preview
+     * iframe `src`, and preview↔editor path matching all target the un-prefixed root and 404 or
+     * silently stop syncing. Normalized (leading slash added, trailing slashes stripped) via
+     * `joinUrlPrefix` at every use site; unset/empty means the app is served at its origin's root.
+     *
+     * NOT the same option as `collectStaticParams`'s `basePath` in
+     * `packages/canopycms-next/src/static.ts` — that one means "the route prefix of a nested
+     * catch-all route" (e.g. `/docs` for `app/docs/[[...slug]]`) and *filters* enumerated entries
+     * down to that prefix. Passing this deployment basePath to `collectStaticParams` instead would
+     * silently filter out every entry (zero static params, a build that goes green with no pages).
+     */
+    basePath?: string;
     editor?: CanopyEditorConfig;
     authPlugin?: AuthPlugin;
     /** Custom URL resolver for entry links. Overrides the default URL computation. */
@@ -362,6 +407,8 @@ export interface CanopyConfigInput {
     deploymentName?: string;
     contentRoot?: string;
     sourceRoot?: string;
+    /** See `CanopyConfig.basePath` — the deployment prefix the host Next.js app is served under. */
+    basePath?: string;
     editor?: CanopyEditorConfig;
     authPlugin?: AuthPlugin;
     /** Custom URL resolver for entry links. Overrides the default URL computation. */
@@ -413,7 +460,7 @@ export type FlatSchemaItem = {
  * Use flatSchema for O(1) cached access to the flattened schema structure.
  * Schema is loaded from .collection.json files on the server and provided as flatSchema.
  */
-export type CanopyClientConfig = Pick<CanopyConfig, 'defaultBaseBranch' | 'defaultActiveBranch' | 'contentRoot' | 'editor' | 'mode' | 'entryLinkUrl'> & {
+export type CanopyClientConfig = Pick<CanopyConfig, 'defaultBaseBranch' | 'defaultActiveBranch' | 'contentRoot' | 'editor' | 'mode' | 'entryLinkUrl' | 'basePath'> & {
     flatSchema: FlatSchemaItem[];
     /**
      * `media.publicBaseUrl`, when configured - the only part of `media` safe/
@@ -431,4 +478,3 @@ export interface ClientOnlyFields {
         AccountComponent?: React.ComponentType;
     };
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/config/types.js

@@ -24,4 +24,3 @@ export const fieldTypes = [
     'block',
     'group',
 ];
-//# sourceMappingURL=types.js.map

package/dist/config/validation.d.ts

@@ -5,7 +5,7 @@
  * from `createEntrySchemaRegistry` so the canonical schema-authoring path runs
  * the same checks. Exported so the test suite can exercise them directly.
  */
-import type { CanopyConfig } from './types';
+import type { CanopyConfig } from './types.js';
 /**
  * Recursively check that all select fields have options defined.
  * Throws an error if a select field is missing options.
@@ -59,4 +59,3 @@ export declare const ensureNoGroupsInsideComplexFields: (fields: unknown) => voi
  * @throws Error if validation fails
  */
 export declare const validateCanopyConfig: (config: unknown) => CanopyConfig;
-//# sourceMappingURL=validation.d.ts.map

package/dist/config/validation.js

@@ -200,4 +200,3 @@ export const validateCanopyConfig = (config) => {
     };
     return normalized;
 };
-//# sourceMappingURL=validation.js.map

package/dist/config.d.ts

@@ -2,9 +2,8 @@
  * CanopyCMS Configuration
  *
  * This file re-exports from the config module for backward compatibility.
- * New code should import directly from './config/index' or './config'.
+ * New code should import directly from './config/index.js' or './config'.
  *
  * @module config
  */
-export * from './config/index';
-//# sourceMappingURL=config.d.ts.map
+export * from './config/index.js';

package/dist/config.js

@@ -8,4 +8,3 @@
  */
 // Re-export everything from the config module
 export * from './config/index.js';
-//# sourceMappingURL=config.js.map

package/dist/content-id-index.d.ts

@@ -1,4 +1,4 @@
-import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths';
+import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths/index.js';
 export interface IdLocation {
     id: ContentId;
     type: 'entry' | 'collection';
@@ -267,4 +267,3 @@ export declare function extractEntryTypeFromFilename(filename: string): string |
  *                        If provided and matches first part, strips it from slug
  */
 export declare function extractSlugFromFilename(filename: string, entryTypeName?: string): Slug;
-//# sourceMappingURL=content-id-index.d.ts.map

package/dist/content-id-index.js

@@ -616,4 +616,3 @@ export function extractSlugFromFilename(filename, entryTypeName) {
     }
     return filename.toLowerCase();
 }
-//# sourceMappingURL=content-id-index.js.map

package/dist/content-index-generation.d.ts

@@ -63,4 +63,3 @@ export declare function invalidateContentIndexesDurable(root: string): Promise<v
  * staleness behavior plus whatever backstop the consumer implements.
  */
 export declare function invalidateBranchContentCaches(root: string): Promise<void>;
-//# sourceMappingURL=content-index-generation.d.ts.map

package/dist/content-index-generation.js

@@ -125,4 +125,3 @@ export async function invalidateBranchContentCaches(root) {
     await bumpResourceGeneration(root, SCHEMA_GENERATION_RESOURCE);
     invalidateContentIndexesForRoot(root);
 }
-//# sourceMappingURL=content-index-generation.js.map

package/dist/content-index-registry.d.ts

@@ -35,4 +35,3 @@ export declare function registerContentIndexForInvalidation(root: string, target
  * index access, so calling this for a root with no live stores is free.
  */
 export declare function invalidateContentIndexesForRoot(root: string): void;
-//# sourceMappingURL=content-index-registry.d.ts.map

package/dist/content-index-registry.js

@@ -50,4 +50,3 @@ export function invalidateContentIndexesForRoot(root) {
             registry.delete(storeRoot);
     }
 }
-//# sourceMappingURL=content-index-registry.js.map

package/dist/content-listing.d.ts

@@ -3,8 +3,9 @@
  *
  * Extracted from api/entries.ts to avoid duplication.
  */
-import type { ContentFormat, FlatSchemaItem, EntryTypeConfig, EntrySchema } from './config';
-import type { LogicalPath, PhysicalPath, Slug, ContentId } from './paths/types';
+import type { ContentFormat, FlatSchemaItem, EntrySchema } from './config/index.js';
+import type { LogicalPath, PhysicalPath, Slug, ContentId } from './paths/types.js';
+import { ContentStore, type ReferenceResolveCache } from './content-store.js';
 /**
  * An entry listing item with raw data from the filesystem.
  * Does not include API-specific fields like canEdit.
@@ -30,15 +31,7 @@ export interface CollectionListItem {
  * Returns an empty object on read/parse failure.
  */
 export declare const readEntryData: (filePath: string, format: ContentFormat, bodyFieldName?: string) => Promise<Record<string, unknown>>;
-/**
- * Parse a filename: {type}.{slug}.{id}.{ext}
- * Returns { type, slug, id } or null if the filename doesn't match the pattern.
- */
-export declare const parseTypedFilename: (filename: string, entryTypes: readonly EntryTypeConfig[]) => {
-    type: string;
-    slug: Slug;
-    id: ContentId;
-} | null;
+export { parseTypedFilename } from './utils/typed-filename.js';
 /**
  * A flat entry item from listEntries.
  * Structural metadata is always present; `data` is controlled by the extract option.
@@ -52,7 +45,12 @@ export interface ListEntriesItem<T = Record<string, unknown>> {
      * For regular entries: '/guides/glossary-of-terms'.
      * For a root index entry: '/'.
      *
-     * Round-trip safe: `readByUrlPath(item.urlPath)` resolves to the same entry.
+     * Round-trip safe: `readByUrlPath(item.urlPath)` resolves to the same entry. That guarantee
+     * depends on `slug` passing `parseSlug` — the filename grammar (`utils/typed-filename.ts`)
+     * allows a slug to contain characters `parseSlug` rejects (a dot, most commonly), and an entry
+     * whose slug does is listed here same as any other but can never be read back by URL.
+     * `static/index.ts`'s `assertRoutableSlugs` is the build-time guard that catches this outside
+     * this doc comment's promise.
      */
     urlPath: string;
     /** Entry slug within its collection */
@@ -76,6 +74,15 @@ export interface ListEntriesItem<T = Record<string, unknown>> {
     data: T;
     /** Field definitions for this entry's type, when resolvable. */
     schema?: EntrySchema;
+    /**
+     * Filesystem mtime (ISO 8601) of the entry file, from an unconditional `fs.stat`
+     * done while listing. Caveat: this is a checkout-time timestamp, not an editorial
+     * one — a fresh CI clone resets every file's mtime to checkout time, so treat this
+     * as "changed since last build" at best, not an authoritative last-edited date for
+     * a public-facing `<lastmod>`. Sourcing mtime from git commit history is a
+     * separate, not-yet-built improvement.
+     */
+    updatedAt?: string;
 }
 export interface ListEntriesOptions<T = Record<string, unknown>> {
     /**
@@ -98,19 +105,118 @@ export interface ListEntriesOptions<T = Record<string, unknown>> {
     rootPath?: string;
     /** Custom sort. */
     sort?: (a: ListEntriesItem<T>, b: ListEntriesItem<T>) => number;
+    /**
+     * Resolve `reference` fields to the referenced entry's data, the way
+     * `read()`/`readByUrlPath()` do — including references nested inside `object` fields,
+     * inline `group`s and block templates (so a shared/referenced block finally carries its
+     * snippet's content here). Off leaves them as the bare id string, or `null`.
+     *
+     * **Defaults to `false`, unlike `read()`, which defaults to `true`.** The asymmetry is
+     * deliberate rather than an oversight. `data` is `T` and `extract` receives an untyped
+     * `Record<string, unknown>`, so turning this on changes a reference from `'a1b2c3d4e5f6'`
+     * to `{ ...data, id, slug, collection, urlPath }` with no compile error anywhere to catch it — an
+     * `/authors/${data.author}` template silently becomes `/authors/[object Object]`. Opting
+     * in is a decision you make per call site, next to the code that reads the field. It also
+     * keeps the common batch uses free: `collectStaticPaths` discards `data` outright, and
+     * `build/generate-ai-content.ts` lists purely to validate entry shapes.
+     *
+     * **Cost, and why it is bounded.** Resolution needs a `ContentStore` and its ContentId
+     * index, so turning it on adds one index scan per call plus one read per DISTINCT
+     * referenced entry — not per referencing entry. A single {@link ReferenceResolveCache}
+     * spans the whole call, so a shared block referenced by 40 pages is read once, not 40
+     * times. Nothing is constructed and nothing is scanned when this is off.
+     *
+     * **Path ACLs are not applied to the resolved targets**, matching `read()` exactly: a
+     * reference can resolve to an entry the user could not `read()` directly. The entries
+     * being LISTED are still ACL-filtered as always, and a filtered-out entry is never
+     * resolved at all.
+     */
+    resolveReferences?: boolean;
 }
+/**
+ * Server-only path-ACL predicate, applied to raw entries before any of their data
+ * reaches a caller.
+ *
+ * Deliberately NOT part of `ListEntriesOptions`/`BuildContentTreeOptions`: those are
+ * adopter-facing, and adopter code must not be able to supply, widen, or override the
+ * access check. `context.ts` is the only intended producer — it builds the predicate
+ * from `services.createContentAccessChecker` for the request-scoped user, and omits it
+ * entirely at build time / on static deployments (synthetic admin, no ACLs).
+ *
+ * Omitting it preserves the pre-existing unfiltered behavior exactly, which is what
+ * build-time callers want.
+ */
+export interface ContentVisibilityOptions {
+    /** Return false to drop an entry. Receives the entry's branch-root-relative physical path. */
+    shouldInclude?: (physicalPath: PhysicalPath) => boolean;
+}
+/** A collection node from the flattened schema. */
+export type CollectionSchemaItem = Extract<FlatSchemaItem, {
+    type: 'collection';
+}>;
+/**
+ * Build the `ContentStore` + shared cache that a batch listing resolves references through.
+ *
+ * Unrelated to the `ReferenceResolver` class in reference-resolver.ts despite the adjacent
+ * name — that one resolves an id to a human-readable *display label* for the editor UI. This
+ * resolves a reference to the referenced entry's *data* for server-side listings.
+ *
+ * Constructed lazily by each listing surface, and ONLY when the caller opted in — a store
+ * builds a ContentId index on first use, which is a full scan of the content tree, and the
+ * default (`resolveReferences` off) must stay a pure filesystem walk with no index at all.
+ *
+ * One store and one cache per listing call, not per collection: the cache is the reason a
+ * shared block referenced from 40 pages costs one read instead of 40, so it has to span the
+ * whole batch. Per-call construction is the established shape here — content-reader.ts's
+ * `resolveStore` builds a store per read, and content-index-registry.ts holds stores through
+ * `WeakRef` + a `FinalizationRegistry` precisely so short-lived instances stay collectable.
+ */
+export declare const createReferenceResolver: (branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string) => {
+    store: ContentStore;
+    cache: ReferenceResolveCache;
+};
+/**
+ * Resolve `reference` fields in a collection's listed entries, in place of their raw data.
+ *
+ * Shared by `listEntries` and `buildContentTree` so both opt into resolution through one
+ * implementation. Each entry resolves against its OWN entry type's field list, since that is
+ * what says which fields are references at all; an entry whose type has no resolvable schema
+ * is returned untouched rather than guessed at.
+ */
+export declare const resolveCollectionItemReferences: (items: CollectionListItem[], collection: CollectionSchemaItem, resolver: {
+    store: ContentStore;
+    cache: ReferenceResolveCache;
+}) => Promise<CollectionListItem[]>;
 /**
  * List all content entries as a flat array.
  *
  * Walks the schema to discover collections, reads entries from each,
  * and returns a flat list suitable for generateStaticParams, search indexing, sitemaps, etc.
  *
+ * Build-time-only failure: a file with a recognized content extension (`.md`/`.mdx`/`.json`/
+ * `.yaml`) sitting in a collection directory that *looks like an attempted entry* (see
+ * `looksLikeMalformedEntry` below) but doesn't match `{type}.{slug}.{id}.{ext}` is, by default,
+ * silently dropped (see `listCollectionEntries`'s debug-gated warning). That is exactly the
+ * silent-page-loss failure mode static generation must not have — a schema rename without a
+ * matching file rename, or an entry type declared in one collection but not another, would
+ * otherwise vanish a page with zero build output. So when `isBuildMode()` is true, any such file
+ * turns the listing into a thrown error instead (see `findInvalidEntries`/`assertBuildEntriesValid`
+ * in `static/index.ts` for the sibling schema-validity guard this mirrors). Outside build mode
+ * (admin UI, content tree, `next dev`) the file is still just skipped, since a fresh scaffold or
+ * mid-rename file legitimately exists there.
+ *
+ * A file that was never entry-shaped to begin with — a `README.md`, or a colocated sibling
+ * artifact named `{contentId}.suffix.ext` per the `entryTransforms`/`readSibling` convention
+ * documented in the README — is not this guard's failure mode and never throws, in or out of
+ * build mode. See `looksLikeMalformedEntry` for the exact shape test.
+ *
  * @param branchRoot - Absolute path to the branch workspace root
  * @param flatSchema - Flattened schema items (from flattenSchema)
  * @param contentRootName - The content root name (e.g. "content")
- * @param options - Listing options (extract, filter, rootPath, sort)
+ * @param options - Listing options (extract, filter, rootPath, sort, resolveReferences)
+ * @param visibility - Internal path-ACL predicate; see `ContentVisibilityOptions`
  */
-export declare function listEntries<T = Record<string, unknown>>(branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string, options?: ListEntriesOptions<T>): Promise<ListEntriesItem<T>[]>;
+export declare function listEntries<T = Record<string, unknown>>(branchRoot: string, flatSchema: FlatSchemaItem[], contentRootName: string, options?: ListEntriesOptions<T>, visibility?: ContentVisibilityOptions): Promise<ListEntriesItem<T>[]>;
 /**
  * Sort items by a content ID order array.
  * Items in the order array come first (in order), items not in the array come at the end
@@ -121,9 +227,24 @@ export declare function listEntries<T = Record<string, unknown>>(branchRoot: str
 export declare const sortByOrder: <T extends {
     contentId?: ContentId;
 }>(items: T[], order: readonly string[] | undefined, fallbackKey: (item: T) => string) => T[];
+/** A content-extension file inside a collection directory whose filename didn't parse. */
+export interface SkippedListingFile {
+    /** The bare filename, e.g. `article.lost-page.4fBqT78gcaLd.md`. */
+    filename: string;
+    /** The collection's logical path. */
+    collectionPath: LogicalPath;
+}
 /**
  * List all entries in a collection directory.
  * Reads each entry's data (frontmatter or JSON).
+ *
+ * @param onSkip - Called for every file that has a recognized content extension, doesn't match
+ *   the `{type}.{slug}.{id}.{ext}` grammar (see `parseTypedFilename`), AND structurally looks
+ *   like an attempted entry (see `looksLikeMalformedEntry`). A file that was never entry-shaped
+ *   (too few dot-separated segments to ever be a valid entry — a `README.md`, a colocated
+ *   sibling artifact) is always silently dropped with a debug-gated `log.warn`, never passed to
+ *   `onSkip`. Optional and purely a diagnostic hook — existing callers that omit it keep the
+ *   exact prior behavior. `listEntries` below uses this to turn the skip into a hard build-time
+ *   failure instead of a silent one.
  */
-export declare const listCollectionEntries: (root: string, collection: FlatSchemaItem) => Promise<CollectionListItem[]>;
-//# sourceMappingURL=content-listing.d.ts.map
+export declare const listCollectionEntries: (root: string, collection: FlatSchemaItem, onSkip?: (file: SkippedListingFile) => void) => Promise<CollectionListItem[]>;