canopycms 0.0.63 → 0.0.64

package/dist/content-reader.js

@@ -2,6 +2,7 @@ import { loadBranchContext, loadOrCreateBranchContext } from './branch-workspace
 import { ContentStore, ContentStoreError } from './content-store.js';
 import { resolveBranchPaths, } from './paths/index.js';
 import { trimSlashes } from './paths/normalize.js';
+import { isIndexSlug } from './utils/entry-url.js';
 import { isDeployedStatic, isBuildMode } from './build-mode.js';
 import { isNotFoundError } from './utils/error.js';
 import { resolveEntryLinksInData } from './entry-link-resolver.js';
@@ -86,7 +87,20 @@ export const createContentReader = (options) => {
         .join('/');
     // Build preview paths using simple path construction
     const contentRoot = trimSlashes(services.config.contentRoot ?? 'content');
-    const stripRoot = (val) => contentRoot && val.startsWith(`${contentRoot}/`) ? val.slice(contentRoot.length + 1) : val;
+    // The `val === contentRoot` branch matters as much as the prefix one: a root-level entry's
+    // collectionPath IS the content root, which does not start with `${contentRoot}/`, so without
+    // it the root index reported `path: '/content'` (and a root entry `/content/about`) -- paths
+    // that resolve to nothing. `computeEntryUrl` has always had both branches; this had one.
+    //
+    // Both branches stay guarded on `contentRoot` so an empty one passes the value through
+    // unchanged, exactly as `computeEntryUrl` does. Unreachable today (`contentRootSchema` is
+    // `relativePathSchema.default('content')` with `.min(1)`), but a blanket short-circuit would
+    // be the WRONG answer if it ever were reachable -- it would flatten every entry to root.
+    const stripRoot = (val) => contentRoot && val === contentRoot
+        ? ''
+        : contentRoot && val.startsWith(`${contentRoot}/`)
+            ? val.slice(contentRoot.length + 1)
+            : val;
     const buildEntryPath = (opts) => {
         // Construct preview path from collectionPath
         const stripped = stripRoot(opts.collectionPath);
@@ -95,7 +109,13 @@ export const createContentReader = (options) => {
             ? `${url}${url.includes('?') ? '&' : '?'}branch=${encodeURIComponent(opts.branch)}`
             : url;
         const trimmed = base.endsWith('/') ? base.slice(0, -1) : base;
-        const encodedSlug = encodeSlug(opts.slug);
+        // An index entry's URL is its COLLECTION's path. Without this collapse `path` handed back
+        // `/docs/index` for an entry advertised at `/docs` -- `resolveUrlPathCandidates`
+        // deliberately does not resolve the former, so a caller linking `path` linked to a 404.
+        // Same index decision as computeEntryUrl/listEntries/buildPreviewSrc, through the same
+        // predicate. NOTE this builder still keeps its own content-root strip and its own encoding
+        // rather than delegating wholesale -- see .claude/future-tasks/default-build-path-url-rule-copy.md.
+        const encodedSlug = isIndexSlug(opts.slug) ? '' : encodeSlug(opts.slug);
         const url = encodedSlug ? `${trimmed}/${encodedSlug}` : trimmed || '/';
         return appendBranch(url);
     };
@@ -196,4 +216,3 @@ export const createContentReader = (options) => {
     };
     return { read };
 };
-//# sourceMappingURL=content-reader.js.map

package/dist/content-store.d.ts

@@ -1,6 +1,6 @@
-import type { FlatSchemaItem, EntryTypeConfig } from './config';
-import { ContentIdIndex } from './content-id-index';
-import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths';
+import type { EntrySchema, FlatSchemaItem, EntryTypeConfig } from './config/index.js';
+import { ContentIdIndex } from './content-id-index.js';
+import { type LogicalPath, type PhysicalPath, type Slug, type ContentId } from './paths/index.js';
 export type MarkdownDocument = {
     format: 'md' | 'mdx';
     data: Record<string, unknown>;
@@ -92,6 +92,25 @@ export declare class DuplicateContentIdError extends ContentConflictError {
     readonly paths: readonly string[];
     constructor(contentId: string, paths: readonly string[]);
 }
+/**
+ * Thrown when a create or rename would give a SECOND entry a `urlPath` another entry already
+ * holds -- the write-boundary half of the invariant `assertNoDuplicateUrlPaths` enforces at build
+ * time (see url-collision.ts for which shapes count and, just as importantly, which do not).
+ *
+ * Why refuse rather than write: only one of the two entries can be served at that URL, so the
+ * other silently has no route anywhere. Allowing the write trades a clear error now for a page
+ * that quietly does not exist later -- and, because the loser is picked by resolver precedence
+ * rather than by the author, not necessarily the page they were editing.
+ *
+ * A `ContentConflictError` subclass so every existing 409 mapping keeps working; the distinct
+ * type exists so the API can surface THIS message rather than the generic "modified by another
+ * editor", which would send the editor into a reload-and-retry loop that cannot succeed.
+ */
+export declare class UrlPathConflictError extends ContentConflictError {
+    /** Absolute path of the entry already holding the contested URL. */
+    readonly conflictingPath: string;
+    constructor(message: string, conflictingPath: string);
+}
 /**
  * Get the default entry type from a collection's entries array.
  * Returns the entry marked as default, or the first one, or undefined if no entries.
@@ -122,6 +141,46 @@ export interface ContentStoreOptions {
      */
     contentWriteLockWaitMs?: number;
 }
+/**
+ * Per-batch memo for reference resolution, keyed by content ID.
+ *
+ * Exists because a batch surface resolves the SAME reference over and over: a shared
+ * block ("call to action", "promo card") referenced by 40 pages costs 40 separate
+ * `read()`s of one small file in a single `listEntries()` pass, and a search-index build
+ * over thousands of entries multiplies that. Pass one cache through a whole batch and
+ * each distinct target is read once.
+ *
+ * Values are the in-flight **promise**, not the settled value, so concurrent lookups
+ * inside a `Promise.all` collapse onto one read rather than each starting their own —
+ * the same in-flight dedup `ContentStore.indexBuild` uses for index rebuilds.
+ *
+ * What is cached is the READ, not the object handed out: every occurrence receives its own
+ * deep copy, so a caller mutating one resolved reference cannot rewrite it for the other 39
+ * entries pointing at the same target. See `resolveSingleReference` for why that matters and
+ * why it does not undo the saving.
+ *
+ * ## Lifetime and invalidation
+ *
+ * There is no invalidation, and that is the design: a cache lives inside a single
+ * `listEntries()` / `buildContentTree()` call and is dropped when it returns. That is
+ * strictly shorter than the lifetime of the `ContentStore` whose memoized `idIndex()` it
+ * sits on top of, so it introduces no staleness window that store did not already have,
+ * and it is out of scope for the generation-marker protocol in
+ * `docs/concurrency.md` (which governs caches rebuilt by scanning that OUTLIVE the
+ * mutations they can miss). Never make one module-global, never persist one, and never
+ * reuse one across requests.
+ *
+ * Misses are memoized alongside hits, deliberately: one batch should be internally
+ * coherent, and a shared block resolving to data on page 1 and to `null` on page 40 of
+ * the same sitemap is worse than either consistent answer. The accepted cost is that a
+ * later occurrence in the same batch can no longer get incidentally lucky after a
+ * sibling lookup wins the stale-index refresh throttle. Each DISTINCT id still gets its
+ * full self-healing retry, because that retry happens inside the memoized promise (see
+ * `resolveSingleReference`).
+ */
+export type ReferenceResolveCache = Map<string, Promise<Record<string, unknown> | null>>;
+/** Create a cache for one batch of reference resolution. See {@link ReferenceResolveCache}. */
+export declare const createReferenceResolveCache: () => ReferenceResolveCache;
 export declare class ContentStore {
     private readonly root;
     /** See ContentStoreOptions.contentRootName — the ID index scan root. */
@@ -274,6 +333,15 @@ export declare class ContentStore {
      * existing entries lock on a per-slug create-key (createLockKey()).
      */
     private entryLockKey;
+    /**
+     * Refuse a create/rename that would give a second entry a `urlPath` another entry already
+     * holds. See url-collision.ts for the two shapes that count, and the legitimate
+     * landing-page-beside-a-collection shape that deliberately does not.
+     *
+     * @param collectionDir Absolute physical directory the entry will live in.
+     * @param slug The entry's slug, as it will be written.
+     */
+    private assertUrlPathAvailable;
     /**
      * Build absolute and relative paths with security validation.
      * All entries use the unified filename pattern: {type}.{slug}.{id}.{ext}
@@ -426,13 +494,72 @@ export declare class ContentStore {
         collection: LogicalPath;
         slug: Slug;
     }>>;
+    /**
+     * Resolve every `reference` field in `data` against `fields`, returning a copy.
+     *
+     * This is what `read()` applies automatically (unless `resolveReferences: false`), exposed
+     * so BATCH surfaces can opt into the same resolution without duplicating the walk: the
+     * listing primitives in content-listing.ts and content-tree.ts read entry files straight
+     * off disk and never touch this store, so before this existed a `reference` field reached
+     * `listEntries()`/`buildContentTree()` callers as a bare id string or `null`.
+     *
+     * Pass one {@link ReferenceResolveCache} across a whole batch so a target referenced by
+     * many entries is read once rather than once per referencing entry. Omit `cache` and the
+     * behavior is exactly what `read()` has always done, unmemoized.
+     *
+     * **Path ACLs are not consulted for the targets.** Resolution goes through this store's
+     * own `read()`, below the per-entry permission check in content-reader.ts — so a resolved
+     * target may be an entry the caller could not `read()` directly. That is pre-existing
+     * `read()` behavior, matched here on purpose so one rule covers both; see the
+     * `resolveReferences` option in content-listing.ts for the note adopters see.
+     */
+    resolveReferences(data: Record<string, unknown>, fields: EntrySchema, cache?: ReferenceResolveCache): Promise<Record<string, unknown>>;
     /**
      * Recursively resolve reference fields in data.
      * This traverses objects, arrays, and blocks to find and resolve all reference fields.
      */
     private resolveReferencesInData;
     /**
-     * Resolve a single reference ID to full entry data.
+     * Resolve a single reference ID to full entry data, memoized when a batch cache is
+     * supplied. Without a cache this is a straight pass-through to the uncached path, so
+     * `read()` behaves exactly as it always has.
+     *
+     * Every occurrence gets its OWN deep copy, even on a cache hit. Without that, the memo
+     * would hand one shared object to all 40 entries referencing the same block — a mutation
+     * in one caller's `extract` (truncating a body for a search index, deleting a field) would
+     * silently rewrite it for every sibling, and both `list: true` elements of `[id, id]` would
+     * be the same instance. The copy is what keeps the cache a pure performance optimization
+     * instead of a semantic change.
+     *
+     * Note the uncached path is NOT the clean baseline it looks like. For a json/yaml target it
+     * genuinely reparses fresh per occurrence, but for md/mdx gray-matter serves `data` from a
+     * process-global content-keyed cache, so `resolveSingleReferenceOnce`'s top-level spread
+     * severs exactly one level and NESTED frontmatter objects alias across occurrences, calls and
+     * requests. That is pre-existing `read()` behavior and out of scope here — deliberately, since
+     * touching it would change `read()` — but it means the cached path is the safer of the two,
+     * not a relaxation of a guarantee the uncached one provides. See
+     * `.claude/future-tasks/graymatter-cache-shared-frontmatter.md`.
+     *
+     * What the copy costs, measured rather than assumed (2000 occurrences of one target, local
+     * disk, so every read hits the page cache — the friendliest possible case for NOT caching):
+     * a snippet-sized target is ~63x cheaper to clone than to re-read-and-parse, while a 265KB
+     * JSON target is ~0.8x, i.e. cloning is marginally SLOWER than reparsing it. So the win is
+     * large in the case this exists for and roughly a wash at the pathological end, never a
+     * blow-up. Two things keep the bad end narrow: an md/mdx target resolves to its FRONTMATTER
+     * only *unless the field sets `includeBody`* (`read()` puts the body on `doc.body`, which
+     * `resolveSingleReferenceOnce` spreads in only for an embedding field), so by default body
+     * size is irrelevant no matter how long the document and only a genuinely huge JSON/YAML
+     * target reaches the wash. **`includeBody: true` is the case that CAN reach it on markdown**:
+     * the body then sits inside the memoized object and is cloned once per referencing entry, so
+     * a long document embedded by many pages pays that repeatedly — the reason `includeBody`
+     * exists as an opt-in per field rather than as resolution's default. And in the deployment this
+     * targets, content lives on EFS/NFS where the syscall the memo removes dominates parse and
+     * clone alike, which the local-disk numbers above understate badly. Correctness is the
+     * reason for the copy regardless; the numbers are here so nobody has to re-derive them
+     * before touching this.
+     */
+    private resolveSingleReference;
+    /**
      * Returns null if the reference is invalid or missing.
      * Includes id, slug, and collection fields for debugging.
      *
@@ -446,8 +573,12 @@ export declare class ContentStore {
      * idIndex() dedupes concurrent builds — so a sibling call that wins the
      * throttle and rebuilds heals every other miss in the same batch, not just
      * the first.
+     *
+     * A {@link ReferenceResolveCache} sits ABOVE this, never inside it, so every
+     * distinct id still runs the full refresh-and-retry above. What a cache changes
+     * is only that repeats of the SAME id in one batch share that one attempt's
+     * outcome instead of each getting an independent throw of the dice.
      */
-    private resolveSingleReference;
+    private resolveSingleReferenceUncached;
     private resolveSingleReferenceOnce;
 }
-//# sourceMappingURL=content-store.d.ts.map