canopycms 0.0.64 → 0.0.66-int.81

package/README.md

@@ -316,9 +316,7 @@ This convention is applied consistently across the API:
 | `readByUrlPath`    | Automatically tries `slug: 'index'` as a fallback when the direct entry doesn't match. Works for all paths including `/`. A path whose last segment is an index slug (any case) skips the direct-entry attempt, so an index entry is reachable only at its collapsed path. |
 | `buildContentTree` | Default `buildPath` collapses index entries so tree node paths match the URLs consumers would use.                                                                                                                                                                         |
 
-The round-trip property holds in both directions: for every item from `listEntries`, `readByUrlPath(item.urlPath)` resolves to the same entry, and for an index entry no `.../index` spelling does. (Ordinary entries keep case-insensitive matching on the final slug segment.)
-
-One known exception, still open: an entry-type name is also resolvable as a URL segment, so an index entry additionally answers at `/<collection>/<entryTypeName>` -- e.g. a root index entry at both `/` and `/home`. Nothing advertises that URL (it is absent from `listEntries` and from static-param generation), so it only matters if you serve a catch-all route. See the `readbyurlpath-entry-type-candidate-phantom-url` task in the CanopyCMS repo.
+The round-trip property holds in both directions: for every item from `listEntries`, `readByUrlPath(item.urlPath)` resolves to the same entry, and for an index entry no `.../index` spelling does, nor does an entry-type name -- `readByUrlPath` only accepts a candidate whose collection segment is an actual collection, so `/<collection>/<entryTypeName>` (e.g. a root index entry answering at both `/` and `/home`) is not a second URL for it. (Ordinary entries keep case-insensitive matching on the final slug segment.)
 
 Two different entries can still compute the same `urlPath` — an entry whose slug matches a sibling collection that also has an `index` entry, or two slugs differing only by case. Only one of them can be served, so a production build fails and names them. `findDuplicateUrlPaths` (exported from `canopycms/server`) runs the same scan on demand.
 

package/dist/api/assets.js

@@ -256,6 +256,15 @@ async function serveLazyTransform(assetStore, key) {
     if (meta.kind !== 'raster') {
         return { ok: false, status: 400, error: 'Not a raster asset - svg/pdf are served statically' };
     }
+    // The slug is decorative in the URL but load-bearing in the stored key, so
+    // it must equal the asset's real slug: `[a-z0-9-]+` is all the parser can
+    // enforce, and every other string that passes it aliases the same image into
+    // a new cache key and a new stored object. Canopy's own URLs always carry
+    // `meta.slug` (assets/asset-url.ts). Mirrors the prod transform Lambda's
+    // handler.ts check - the two paths must agree, or dev accepts URLs prod 404s.
+    if (parsed.slug !== meta.slug) {
+        return { ok: false, status: 404, error: 'Not found' };
+    }
     // When the URL omits an explicit `f=` format, the transform preserves the
     // source format, so the URL's `{ext}` must match the source's real ext
     // exactly - the parser alone can't check this (it doesn't know the source

package/dist/auth/file-based-auth-cache.js

@@ -189,10 +189,22 @@ export async function writeAuthCacheSnapshot(cachePath, files) {
         await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
         await fs.rename(tmpPath, finalPath);
     }
-    // Atomic symlink swap: create temp symlink, rename over current
+    // Atomic symlink swap: create temp symlink, rename over current.
+    //
+    // The target MUST be relative (the bare `snapshot-<ts>` basename), because
+    // writer and reader do not always share a mount namespace. In prod the EC2
+    // worker mounts the EFS filesystem root and writes through
+    // CANOPYCMS_WORKSPACE_ROOT=/mnt/efs/workspace (cachePath
+    // /mnt/efs/workspace/.cache), while the CMS Lambda mounts the /workspace
+    // access point at /mnt/efs and reads the SAME directory as /mnt/efs/.cache.
+    // An absolute target recorded by one is a nonexistent path to the other -
+    // `resolveActiveCacheDir`'s escape guard then correctly rejects it and falls
+    // back to the flat layout, where the worker never writes, leaving the Lambda
+    // with a permanently empty cache. A relative target resolves against
+    // whichever cachePath the reader was given, so it is correct from both.
     const currentLink = path.join(cachePath, 'current');
     const tmpLink = path.join(cachePath, `current-${timestamp}`);
-    await fs.symlink(snapshotDir, tmpLink);
+    await fs.symlink(path.basename(snapshotDir), tmpLink);
     await fs.rename(tmpLink, currentLink);
     // Clean up old snapshots (keep the 2 most recent)
     await cleanupOldSnapshots(cachePath, 2);

package/dist/branch-health.d.ts

@@ -34,6 +34,26 @@ export interface BranchHealthEntry {
      * repair-content-duplicates admin action.
      */
     duplicateContentIds?: DuplicateContentId[];
+    /**
+     * healthy only, and only when true: this clone has an interrupted rebase on
+     * disk (`.git/rebase-merge` / `.git/rebase-apply`).
+     *
+     * Deliberately an advisory flag on `healthy` rather than its own
+     * `BranchHealthKind`, for the same reason `duplicateContentIds` is: the
+     * branch's metadata is intact and the state is USUALLY transient -- the
+     * worker's sync loop aborts an interrupted rebase at the top of its next
+     * per-branch pass. What this flag buys is visibility in the window BEFORE
+     * that pass runs, where the branch otherwise scanned as unqualified
+     * `healthy` while being skipped as dirty every cycle.
+     *
+     * NOT self-recovering in every case, so a persisting value is the real
+     * signal and needs an operator. Two ways it sticks: the abort itself keeps
+     * failing, or the branch's status moved off `editing` after it wedged --
+     * the rebase loop filters by status BEFORE reaching the recovery step, so a
+     * clone that crashed mid-rebase and was then submitted or archived is never
+     * revisited, and this flag is the only thing that surfaces it.
+     */
+    rebaseInProgress?: boolean;
     /** corrupt-metadata only: message describing why the file failed to load. */
     parseError?: string;
     /** corrupt-metadata only: branch.json's mtime, ISO. Omitted if branch.json itself couldn't be stat'd. */

package/dist/branch-health.js

@@ -4,6 +4,7 @@ import { BranchMetadataFileManager, BranchMetadataCorruptError } from './branch-
 import { ContentIdIndex } from './content-id-index.js';
 import { sanitizeBranchName } from './paths/branch-name.js';
 import { getErrorMessage, isNodeError, isNotFoundError } from './utils/error.js';
+import { isRebaseInProgress } from './utils/git.js';
 /**
  * The on-disk path of the cross-process provisioning lock marker for a
  * given branch directory, matching `branch-workspace.ts`'s
@@ -139,13 +140,17 @@ export async function scanBranchHealth(baseRoot, opts) {
             continue;
         }
         if (meta) {
-            const duplicateContentIds = await scanDuplicateContentIds(branchRoot, contentRootName);
+            const [duplicateContentIds, rebaseInProgress] = await Promise.all([
+                scanDuplicateContentIds(branchRoot, contentRootName),
+                isRebaseInProgress(branchRoot),
+            ]);
             entries.push({
                 dirName,
                 kind: 'healthy',
                 ...(isBaseBranch ? { isBaseBranch } : {}),
                 branch: meta.branch,
                 ...(duplicateContentIds.length ? { duplicateContentIds } : {}),
+                ...(rebaseInProgress ? { rebaseInProgress } : {}),
             });
             continue;
         }

package/dist/cli/cli.d.ts

@@ -37,6 +37,23 @@ export declare function parseAuthFlag(value: string | boolean | undefined): Auth
 export declare function parseDualBuildFlag(value: unknown): boolean | undefined;
 declare const SYNC_SUBCOMMANDS: readonly ["push", "pull", "both", "abort"];
 type SyncSubcommand = (typeof SYNC_SUBCOMMANDS)[number];
+/** The auth modes `worker run-once` knows how to build a plugin for. */
+export declare const KNOWN_AUTH_MODES: readonly ["clerk", "dev"];
+export type KnownAuthMode = (typeof KNOWN_AUTH_MODES)[number];
+/**
+ * Whether `CANOPY_AUTH_MODE` names a provider the CLI can actually construct.
+ *
+ * Pure and exported so it is testable: the dispatch below branches on 'clerk'
+ * and 'dev' only, and the catch around plugin loading fires solely on an
+ * IMPORT failure -- so before this guard existed, any other value (a typo,
+ * wrong casing like 'Clerk', a stale value from another system) selected no
+ * plugin, skipped the auth refresh entirely, and let the command run to "Done"
+ * with exit code 0. A cron'd `CANOPY_AUTH_MODE=clerk canopycms worker
+ * run-once` that became `Clerk` refreshed nothing for as long as the typo
+ * survived, while the cache aged and a user removed from the Clerk org kept
+ * editor access.
+ */
+export declare function isKnownAuthMode(value: string): value is KnownAuthMode;
 /** Resolve sync subcommand from positional arg. Returns null if missing or invalid. Exported for testing. */
 export declare function resolveSyncSubcommand(sub: string | undefined): SyncSubcommand | null;
 export {};

package/dist/cli/cli.js

@@ -592,7 +592,7 @@ async function recoverOrphanedTasks(taskDir, maxAgeMs = 5 * 6e4, logger = nullLo
 async function cleanupOldTasks(taskDir, maxAgeMs = 30 * 24 * 60 * 6e4, logger = nullLogger) {
   const now = Date.now();
   let cleaned = 0;
-  for (const subdir of ["completed", "failed"]) {
+  for (const subdir of ["completed", "failed", "corrupt"]) {
     const dir = path6.join(taskDir, subdir);
     let files;
     try {
@@ -810,6 +810,13 @@ function configImportPath(appDir, subdirs) {
   const totalDepth = appDepth + subdirs;
   return "../".repeat(totalDepth) + "canopycms.config";
 }
+async function firstExistingPath(projectDir, candidates) {
+  for (const candidate of candidates) {
+    if (await filePathExists2(path7.join(projectDir, candidate)))
+      return candidate;
+  }
+  return null;
+}
 async function init(options) {
   const { projectDir, mode, appDir, ai, force, nonInteractive } = options;
   const writeOpts = { force, nonInteractive };
@@ -864,15 +871,35 @@ async function init(options) {
     await writeFile(path7.join(projectDir, appDir, "ai/config.ts"), await aiConfig2(), writeOpts);
     await writeFile(path7.join(projectDir, appDir, `ai/[...path]/${serverRouteExt}`), await aiRoute2({ configImport: configImportPath(appDir, 2) }), writeOpts);
   }
-  await writeFile(path7.join(projectDir, "next.config.ts"), await nextConfig2({ staticBuild }), writeOpts);
-  await writeFile(path7.join(projectDir, "middleware.ts"), await middleware2({ authProvider }), writeOpts);
+  const existingJsConfig = await firstExistingPath(projectDir, [
+    "next.config.js",
+    "next.config.mjs"
+  ]);
+  if (existingJsConfig) {
+    p.note([
+      `Found ${existingJsConfig}, which Next loads in preference to next.config.ts.`,
+      "Left it untouched rather than writing a second config Next would ignore.",
+      "",
+      "Wrap your existing config by hand:",
+      "",
+      "  import { withCanopy } from 'canopycms-next/config'",
+      "  export default withCanopy(yourConfig)"
+    ].join("\n"), "Manual step");
+  } else {
+    await writeFile(path7.join(projectDir, "next.config.ts"), await nextConfig2({ staticBuild }), writeOpts);
+  }
+  await writeFile(path7.join(projectDir, path7.dirname(appDir), "middleware.ts"), await middleware2({ authProvider }), writeOpts);
   const gitignorePath = path7.join(projectDir, ".gitignore");
+  const CANOPY_GITIGNORE_BLOCK = "# CanopyCMS\n.canopy-dev/\n";
   if (await filePathExists2(gitignorePath)) {
     const content = await fs6.readFile(gitignorePath, "utf-8");
     if (!content.includes(".canopy-dev")) {
-      await fs6.appendFile(gitignorePath, "\n# CanopyCMS\n.canopy-dev/\n");
+      await fs6.appendFile(gitignorePath, `
+${CANOPY_GITIGNORE_BLOCK}`);
       p.log.success("updated: .gitignore");
     }
+  } else {
+    await writeFile(gitignorePath, CANOPY_GITIGNORE_BLOCK, writeOpts);
   }
   const packages = authProvider === "clerk" ? "canopycms canopycms-next canopycms-auth-clerk canopycms-auth-dev" : "canopycms canopycms-next canopycms-auth-dev";
   p.note([
@@ -6237,6 +6264,54 @@ var init_generate_ai_content = __esm({
         }
         return item;
       }
+      /**
+       * Is this path a COLLECTION schema item?
+       *
+       * The non-throwing form of `assertCollection`, reading the same `schemaIndex` -- which is the
+       * point. A caller that gates on this cannot disagree with what `buildPaths` will then do: the
+       * Map is last-wins, so where a subcollection's path collides with a parent's entry-type name
+       * both this and `buildPaths` see the collection. A `find` over the flat schema LIST is
+       * first-wins and would not.
+       *
+       * Type-only, deliberately -- `resolvePath` additionally requires `entries`, but a collection
+       * with subcollections and no entries of its own is legal, and mirroring that stricter test here
+       * would reject something `buildPaths` accepts.
+       *
+       * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
+       * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+       */
+      isCollectionPath(collectionPath) {
+        return this.schemaIndex.get(normalizeFilesystemPath(collectionPath))?.type === "collection";
+      }
+      /**
+       * Does this collection declare `entryTypeName` in its `entries` config?
+       *
+       * Mirrors `parseTypedFilename(filename, collection.entries)`, which is how `listEntries` decides
+       * whether a file on disk is one of the collection's entries at all. `buildPaths`' own directory
+       * scan deliberately does NOT check this -- it matches on slug alone, so that an entry whose type
+       * was renamed out of the schema stays findable and therefore still editable, renameable and
+       * deletable. Only URL resolution consults this, so what enumeration hides is not served.
+       *
+       * Returns FALSE when the collection declares no `entries` at all, which is stricter than
+       * `parseTypedFilename`'s own `if (entryTypes && ...)` guard and deliberately so: the enumerating
+       * surface is not `parseTypedFilename`, it is `listCollectionEntries`, and that returns `[]`
+       * outright for a collection with no `entries`. A collections-only container therefore publishes
+       * nothing, so a URL read that resolved a file sitting in one would be answering where nothing is
+       * advertised -- the exact disagreement this predicate exists to close. Such a file cannot have
+       * been created by the CMS (there is no entry type to create it as); it arrived by hand, by merge
+       * or by retrofit, and it is invisible to the sitemap and to static params either way.
+       *
+       * Returns true for a path that is not a collection at all, because that is rule 1's question,
+       * not this one's -- and under `urlAddressableOnly` rule 1 has already rejected it.
+       */
+      declaresEntryType(collectionPath, entryTypeName) {
+        const item = this.schemaIndex.get(normalizeFilesystemPath(collectionPath));
+        if (item?.type !== "collection")
+          return true;
+        if (!item.entries)
+          return false;
+        return item.entries.some((e) => e.name === entryTypeName);
+      }
       assertCollection(collectionPath) {
         const item = this.assertSchemaItem(collectionPath);
         if (item.type !== "collection") {
@@ -11196,6 +11271,10 @@ async function requireProjectRoot(command) {
   }
   return root;
 }
+var KNOWN_AUTH_MODES = ["clerk", "dev"];
+function isKnownAuthMode(value) {
+  return KNOWN_AUTH_MODES.includes(value);
+}
 function resolveSyncSubcommand(sub) {
   if (sub && SYNC_SUBCOMMANDS.includes(sub))
     return sub;
@@ -11287,6 +11366,10 @@ async function main() {
       process.exit(1);
     }
     const authMode = process.env.CANOPY_AUTH_MODE || "dev";
+    if (!isKnownAuthMode(authMode)) {
+      console.error(`Unknown CANOPY_AUTH_MODE "${authMode}" \u2014 expected one of: ${KNOWN_AUTH_MODES.join(", ")}. No auth plugin was loaded, so the auth cache will NOT be refreshed.`);
+      process.exitCode = 1;
+    }
     let authPlugin;
     try {
       if (authMode === "clerk") {
@@ -11398,6 +11481,8 @@ if (isDirectRun) {
   });
 }
 export {
+  KNOWN_AUTH_MODES,
+  isKnownAuthMode,
   parseArgs,
   parseAuthFlag,
   parseDualBuildFlag,

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

@@ -2926,6 +2926,54 @@ var ContentStore = class {
     }
     return item;
   }
+  /**
+   * Is this path a COLLECTION schema item?
+   *
+   * The non-throwing form of `assertCollection`, reading the same `schemaIndex` -- which is the
+   * point. A caller that gates on this cannot disagree with what `buildPaths` will then do: the
+   * Map is last-wins, so where a subcollection's path collides with a parent's entry-type name
+   * both this and `buildPaths` see the collection. A `find` over the flat schema LIST is
+   * first-wins and would not.
+   *
+   * Type-only, deliberately -- `resolvePath` additionally requires `entries`, but a collection
+   * with subcollections and no entries of its own is legal, and mirroring that stricter test here
+   * would reject something `buildPaths` accepts.
+   *
+   * Exists for `readByUrlPath`'s URL-addressability gate; see `ReadContentInput`'s
+   * `urlAddressableOnly` and the note on `buildPaths`' entry-type branch below.
+   */
+  isCollectionPath(collectionPath) {
+    return this.schemaIndex.get(normalizeFilesystemPath(collectionPath))?.type === "collection";
+  }
+  /**
+   * Does this collection declare `entryTypeName` in its `entries` config?
+   *
+   * Mirrors `parseTypedFilename(filename, collection.entries)`, which is how `listEntries` decides
+   * whether a file on disk is one of the collection's entries at all. `buildPaths`' own directory
+   * scan deliberately does NOT check this -- it matches on slug alone, so that an entry whose type
+   * was renamed out of the schema stays findable and therefore still editable, renameable and
+   * deletable. Only URL resolution consults this, so what enumeration hides is not served.
+   *
+   * Returns FALSE when the collection declares no `entries` at all, which is stricter than
+   * `parseTypedFilename`'s own `if (entryTypes && ...)` guard and deliberately so: the enumerating
+   * surface is not `parseTypedFilename`, it is `listCollectionEntries`, and that returns `[]`
+   * outright for a collection with no `entries`. A collections-only container therefore publishes
+   * nothing, so a URL read that resolved a file sitting in one would be answering where nothing is
+   * advertised -- the exact disagreement this predicate exists to close. Such a file cannot have
+   * been created by the CMS (there is no entry type to create it as); it arrived by hand, by merge
+   * or by retrofit, and it is invisible to the sitemap and to static params either way.
+   *
+   * Returns true for a path that is not a collection at all, because that is rule 1's question,
+   * not this one's -- and under `urlAddressableOnly` rule 1 has already rejected it.
+   */
+  declaresEntryType(collectionPath, entryTypeName) {
+    const item = this.schemaIndex.get(normalizeFilesystemPath(collectionPath));
+    if (item?.type !== "collection")
+      return true;
+    if (!item.entries)
+      return false;
+    return item.entries.some((e) => e.name === entryTypeName);
+  }
   assertCollection(collectionPath) {
     const item = this.assertSchemaItem(collectionPath);
     if (item.type !== "collection") {

package/dist/cli/init.js

@@ -1117,7 +1117,7 @@ async function recoverOrphanedTasks(taskDir, maxAgeMs = 5 * 6e4, logger = nullLo
 async function cleanupOldTasks(taskDir, maxAgeMs = 30 * 24 * 60 * 6e4, logger = nullLogger) {
   const now = Date.now();
   let cleaned = 0;
-  for (const subdir of ["completed", "failed"]) {
+  for (const subdir of ["completed", "failed", "corrupt"]) {
     const dir = path6.join(taskDir, subdir);
     let files;
     try {
@@ -1586,6 +1586,13 @@ function configImportPath(appDir, subdirs) {
   const totalDepth = appDepth + subdirs;
   return "../".repeat(totalDepth) + "canopycms.config";
 }
+async function firstExistingPath(projectDir, candidates) {
+  for (const candidate of candidates) {
+    if (await filePathExists(path7.join(projectDir, candidate)))
+      return candidate;
+  }
+  return null;
+}
 async function init(options) {
   const { projectDir, mode, appDir, ai, force, nonInteractive } = options;
   const writeOpts = { force, nonInteractive };
@@ -1640,15 +1647,35 @@ async function init(options) {
     await writeFile(path7.join(projectDir, appDir, "ai/config.ts"), await aiConfig2(), writeOpts);
     await writeFile(path7.join(projectDir, appDir, `ai/[...path]/${serverRouteExt}`), await aiRoute2({ configImport: configImportPath(appDir, 2) }), writeOpts);
   }
-  await writeFile(path7.join(projectDir, "next.config.ts"), await nextConfig2({ staticBuild }), writeOpts);
-  await writeFile(path7.join(projectDir, "middleware.ts"), await middleware2({ authProvider }), writeOpts);
+  const existingJsConfig = await firstExistingPath(projectDir, [
+    "next.config.js",
+    "next.config.mjs"
+  ]);
+  if (existingJsConfig) {
+    p.note([
+      `Found ${existingJsConfig}, which Next loads in preference to next.config.ts.`,
+      "Left it untouched rather than writing a second config Next would ignore.",
+      "",
+      "Wrap your existing config by hand:",
+      "",
+      "  import { withCanopy } from 'canopycms-next/config'",
+      "  export default withCanopy(yourConfig)"
+    ].join("\n"), "Manual step");
+  } else {
+    await writeFile(path7.join(projectDir, "next.config.ts"), await nextConfig2({ staticBuild }), writeOpts);
+  }
+  await writeFile(path7.join(projectDir, path7.dirname(appDir), "middleware.ts"), await middleware2({ authProvider }), writeOpts);
   const gitignorePath = path7.join(projectDir, ".gitignore");
+  const CANOPY_GITIGNORE_BLOCK = "# CanopyCMS\n.canopy-dev/\n";
   if (await filePathExists(gitignorePath)) {
     const content = await fs6.readFile(gitignorePath, "utf-8");
     if (!content.includes(".canopy-dev")) {
-      await fs6.appendFile(gitignorePath, "\n# CanopyCMS\n.canopy-dev/\n");
+      await fs6.appendFile(gitignorePath, `
+${CANOPY_GITIGNORE_BLOCK}`);
       p.log.success("updated: .gitignore");
     }
+  } else {
+    await writeFile(gitignorePath, CANOPY_GITIGNORE_BLOCK, writeOpts);
   }
   const packages = authProvider === "clerk" ? "canopycms canopycms-next canopycms-auth-clerk canopycms-auth-dev" : "canopycms canopycms-next canopycms-auth-dev";
   p.note([

package/dist/cli/template-files/Dockerfile.cms.template

@@ -1,4 +1,10 @@
-FROM public.ecr.aws/docker/library/node:20-slim AS builder
+# Node 22. Node 20 reached upstream EOL on 2026-04-30, so it receives no
+# further security patches -- and the CMS Lambda runs this image.
+#
+# NOTE: the published canopycms packages declare `engines.node: ">=18"`,
+# so this is not an installability floor -- it is the runtime CanopyCMS is
+# actually built and tested on (.nvmrc is v22, as is the transform Lambda).
+FROM public.ecr.aws/docker/library/node:22-slim AS builder
 WORKDIR /app
 {{DOCKER_COPY}}
 # If your app uses `file:` dependencies (e.g. vendored tarballs under vendor/),
@@ -53,7 +59,7 @@ ARG NEXT_PUBLIC_CANOPY_MODE=dev
 ENV NEXT_PUBLIC_CANOPY_MODE=$NEXT_PUBLIC_CANOPY_MODE
 RUN {{DOCKER_BUILD}}
 
-FROM public.ecr.aws/docker/library/node:20-slim AS runner
+FROM public.ecr.aws/docker/library/node:22-slim AS runner
 # Git is required by CanopyCMS for branch operations
 RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
 # The runtime user's uid differs from the uid that owns EFS workspace files

package/dist/cli/template-files/cms-stack.ts.template

@@ -107,13 +107,35 @@ export class CmsStack extends Stack {
       reservedConcurrency: 10,
     })
 
-    // Media support (uploads, on-demand image transforms). Uncomment to give
-    // the deployed editor an asset backend, pass `assetBucket:
-    // assetSupport.bucket` to CanopyCmsService above, and wire
-    // `assetSupport.cloudFrontBehaviors` into the distribution below. See the
-    // assets section of docs/deploying-to-aws.md.
+    // Media support (uploads, on-demand image transforms). To enable it:
     //
-    // const assetSupport = new AssetSupport(this, 'Assets', {})
+    //   1. add `AssetSupport` to the `canopycms-cdk` import at the top;
+    //   2. uncomment the block below, moving it ABOVE `cmsService` (it has to
+    //      exist before you can pass its bucket);
+    //   3. pass `assetBucket: assetSupport.bucket` to CanopyCmsService;
+    //   4. pass the behaviors to CanopyCmsDistribution, `/assets/t/*` FIRST
+    //      (CloudFront matches in order, so the general pattern would
+    //      otherwise swallow the transform one):
+    //
+    //        additionalBehaviors: {
+    //          '/assets/t/*': assetSupport.assetBehaviors().assetsTransform,
+    //          '/assets/*': assetSupport.assetBehaviors().assets,
+    //        },
+    //
+    // `editorOrigins` is REQUIRED: it is the S3 CORS allowlist for the
+    // editor's presigned uploads, so it must list the origin the editor is
+    // served from. Include http://localhost:3000 only if you upload from a
+    // local dev editor against this bucket.
+    //
+    // Run `pnpm --filter canopycms-cdk run build:lambda` before deploying --
+    // the transform Lambda needs its native sharp binary, and the construct
+    // refuses to synth without it.
+    //
+    // See the assets section of docs/deploying-to-aws.md.
+    //
+    // const assetSupport = new AssetSupport(this, 'Assets', {
+    //   editorOrigins: [`https://${props.domainName}`],
+    // })
 
     // CloudFront + Route53, only when a domain is configured. Skipping this
     // leaves `cmsService.functionUrl` as the entry point, which is enough to
@@ -124,6 +146,11 @@ export class CmsStack extends Stack {
         functionUrl: cmsService.functionUrl,
         domainName: props.domainName,
         hostedZoneDomain: props.hostedZoneDomain,
+        // Keep CloudFront's origin read timeout equal to the Lambda's own.
+        // Both default to 60s, so this line changes nothing today -- it is
+        // here so that raising `timeout` above cannot silently leave
+        // CloudFront answering 504 at the edge on requests that succeed.
+        originReadTimeout: cmsService.timeout,
       })
     }
   }

package/dist/cli/template-files/deploy-cms.yml.template

@@ -39,10 +39,15 @@
 #   3. Install the CDK dependencies the app entry point needs:
 #      `{{ADD_DEV}} canopycms canopycms-cdk aws-cdk-lib constructs tsx aws-cdk`
 #   4. Set these repository secrets (Settings -> Secrets and variables ->
-#      Actions -> Secrets). Every one of them is read by `required()` in
-#      infrastructure/bin/app.ts, so a missing value fails the deploy at synth:
+#      Actions -> Secrets). All but AWS_DEPLOY_ROLE_ARN are read by `required()`
+#      in infrastructure/bin/app.ts, so a missing value fails the deploy at
+#      synth; a missing role ARN fails earlier, at the AWS credentials step:
 #        AWS_DEPLOY_ROLE_ARN            OIDC role ARN from step 2
-#        GITHUB_TOKEN_SECRET_ARN        FULL Secrets Manager ARN (with suffix)
+#        CANOPY_GITHUB_TOKEN_SECRET_ARN  FULL Secrets Manager ARN (with suffix)
+#          NOTE: the CANOPY_ prefix is required, not cosmetic. GitHub rejects any
+#          Actions secret whose name starts with GITHUB_ (a reserved prefix), so
+#          the otherwise-obvious GITHUB_TOKEN_SECRET_ARN cannot be created at all.
+#          The env var handed to CDK below keeps the unprefixed name.
 #        CLERK_SECRET_KEY_SECRET_ARN    FULL Secrets Manager ARN (with suffix)
 #        CLERK_JWT_KEY                  Clerk's public JWKS PEM
 #   5. Set these repository variables (same page -> Variables):
@@ -64,6 +69,14 @@ on:
       - 'src/**'
       - 'content/**'
       - 'canopycms.config.ts'
+      # The Next config is what `init-deploy aws` itself tells you to edit for
+      # the dual build, and `public/**` is copied into the runner image (and is
+      # load-bearing for editor/public preview parity). Omitting them meant an
+      # edit shipped days later, piggybacked on an unrelated content change --
+      # so any breakage was attributed to the wrong commit.
+      - 'next.config.*'
+      - 'middleware.ts'
+      - 'public/**'
       - 'Dockerfile.cms'
       - 'infrastructure/**'
       - 'cdk.json'
@@ -89,11 +102,11 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Install dependencies
         run: {{CI_INSTALL}}
@@ -124,7 +137,7 @@ jobs:
           fi
 
       - name: Configure AWS credentials
-        uses: aws-actions/configure-aws-credentials@v4
+        uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
         with:
           role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
           aws-region: ${{ vars.AWS_REGION }}
@@ -138,7 +151,7 @@ jobs:
       # in one place and not the other fails the deploy at synth.
       - name: Deploy
         env:
-          GITHUB_TOKEN_SECRET_ARN: ${{ secrets.GITHUB_TOKEN_SECRET_ARN }}
+          GITHUB_TOKEN_SECRET_ARN: ${{ secrets.CANOPY_GITHUB_TOKEN_SECRET_ARN }}
           CLERK_SECRET_KEY_SECRET_ARN: ${{ secrets.CLERK_SECRET_KEY_SECRET_ARN }}
           CLERK_JWT_KEY: ${{ secrets.CLERK_JWT_KEY }}
           NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: ${{ vars.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY }}

package/dist/content-reader.d.ts

@@ -11,7 +11,11 @@ export interface ContentReaderOptions {
     getBranchContext?: (branch: string) => Promise<BranchContext | null>;
 }
 export interface ReadContentInput {
-    /** Resolved schema path (e.g., content/posts or content/home). */
+    /**
+     * Resolved schema path (e.g., content/posts or content/home). An entry-TYPE path like
+     * `content/home` is valid and resolves that singleton -- except under `urlAddressableOnly`
+     * below, which rejects it.
+     */
     entryPath: LogicalPath;
     slug?: Slug;
     branch?: string;
@@ -21,6 +25,26 @@ export interface ReadContentInput {
     resolveReferences?: boolean;
     /** Whether to resolve entry:ID links in body/markdown fields. Defaults to true. */
     resolveEntryLinks?: boolean;
+    /**
+     * This read is addressing an entry by its PUBLISHED URL, so accept only what enumeration
+     * publishes. Two rules, both off by default:
+     *
+     * 1. `entryPath` must be a COLLECTION. A published URL is `/<collectionSegments>/<slug>` (or
+     *    the collapsed collection path, for an index entry), so its non-slug segments are always
+     *    collection names. An `entryPath` that resolves to an entry-TYPE item instead would be
+     *    delegated by `ContentStore.buildPaths` to the parent collection -- answering at
+     *    `/<collection>/<typeName>` and `/<collection>/<typeName>/<slug>`, neither of which any
+     *    forward surface emits.
+     * 2. The resolved entry's type must be one its collection declares, matching the
+     *    `parseTypedFilename(filename, collection.entries)` check `listEntries` applies. A legacy
+     *    untyped file has no type token to fail on -- see `declaresEntryType`.
+     *
+     * Set by `readByUrlPath` and nothing else. Note what it does NOT do: `read({ entryPath:
+     * 'content/home' })` and direct `ContentStore` use keep the entry-type delegation, which is a
+     * supported API and the only way to address a singleton structurally. Misusing this flag can
+     * only make a read stricter, never looser.
+     */
+    urlAddressableOnly?: boolean;
 }
 /**
  * Structural metadata surfaced alongside a resolved content read. Shared by

package/dist/content-reader.js

@@ -122,6 +122,13 @@ export const createContentReader = (options) => {
     const readDocument = async (input) => {
         const { entryPath, slug, branchName, user } = resolveTarget(input);
         const { context, branchRoot, store } = await resolveStore(branchName);
+        // Rule 1 of urlAddressableOnly (see ReadContentInput): a published URL's non-slug segments
+        // are collection names, so a candidate landing on an entry-TYPE item can only ever produce a
+        // URL enumeration never emits. NO_SCHEMA_ITEM is what assertCollection raises for exactly
+        // this condition, and readByUrlPath treats it as a miss and tries the next candidate.
+        if (input.urlAddressableOnly && !store.isCollectionPath(entryPath)) {
+            throw new ContentStoreError(`Path is not a collection: ${entryPath}`, 'NO_SCHEMA_ITEM');
+        }
         // Get the path WITHOUT reading the file
         let relativePath;
         // Absolute filesystem path to the entry file. Surfaced on read() / readByUrlPath()
@@ -151,6 +158,14 @@ export const createContentReader = (options) => {
             const code = err instanceof ContentStoreError ? err.code : 'VALIDATION';
             throw new ContentStoreError(message, code);
         }
+        // Rule 2 of urlAddressableOnly (see ReadContentInput): buildPaths' directory scan matches on
+        // slug alone, so it happily returns a file whose type token the collection no longer (or
+        // never did) declare -- a file listEntries skips. Checked here rather than inside the scan so
+        // the write path can still find, edit and rename it; making it unfindable would make the
+        // mistake unrecoverable through the editor.
+        if (input.urlAddressableOnly && !store.declaresEntryType(entryPath, entryType)) {
+            throw new ContentStoreError(`Entry type '${entryType}' is not declared by ${entryPath}`, 'NO_SCHEMA_ITEM');
+        }
         // Check permissions BEFORE reading the file (security)
         const shouldCheckPermissions = !(isDeployedStatic(services.config) || isBuildMode());
         if (shouldCheckPermissions) {