canopycms 0.0.67 → 0.0.68-int.101

package/dist/utils/provisioning-lock.js

@@ -3,6 +3,12 @@ import path from 'node:path';
 import lockfile from 'proper-lockfile';
 import { getErrorMessage, isNodeError } from './error.js';
 import { canopyLogWarn } from './logger.js';
+/**
+ * When an acquirer may take a provisioning marker over. Staleness is read from the marker's mtime,
+ * which EFS serves from the NFS attribute cache for up to 60s, so a live holder's 15s refreshes
+ * can look 60s late; one threshold above that for every acquirer means none reaps a live hold.
+ */
+export const PROVISIONING_LOCK_STALE_MS = 90_000;
 /**
  * Shared option set for both provisioning-lock variants.
  *
@@ -16,12 +22,14 @@ import { canopyLogWarn } from './logger.js';
  * share one. `realpath: false` because that anchor path does not exist before we create it
  * (realpath would ENOENT). See docs/concurrency.md ("Anchor path matters").
  */
-function provisioningLockOptions(lockPath, retries, onCompromised) {
+function provisioningLockOptions(lockPath, retries, onCompromised, staleMs) {
     return {
         lockfilePath: lockPath,
         realpath: false,
         retries,
-        stale: 30_000,
+        stale: staleMs,
+        // Fixed, not stale/2: every holder refreshes at 15s whatever threshold it judges others by.
+        update: 15_000,
         // proper-lockfile invokes this from inside its refresh timer, so ANY throw escaping here is
         // an uncaught exception that kills the process. Call sites are told not to throw (see
         // OnLockCompromised); this makes it structural rather than a convention, and also covers the
@@ -76,6 +84,15 @@ function releaseIgnoringAlreadyReleased(release, lockPath) {
         }
     };
 }
+/**
+ * The provisioning lock's name for the branch workspace directory `dirName`, held in that
+ * directory's parent. Every party to a branch workspace's provisioning names it through this:
+ * the Lambda while it clones, the admin purge, branch-health's freshness rail, and the worker
+ * while it refreshes or rebases.
+ */
+export function branchProvisioningLockName(dirName) {
+    return `.${dirName}.init.lock`;
+}
 /**
  * Acquire a cross-process filesystem lock for content provisioning. Returns a release function —
  * always call it in a `finally`.
@@ -94,9 +111,9 @@ export async function acquireProvisioningLock(lockTargetDir, lockName, onComprom
     // Generous, jittered retries: several processes may contend for one workspace (Lambda
     // containers cold-starting together against one EFS root), and the holder can take seconds to
     // init plus clone/push. `randomize` de-syncs the herd so a waiter is not perpetually colliding
-    // on the same tick. `stale` stays modest because proper-lockfile auto-refreshes a live holder's
-    // lock, so it expires only when a process actually dies.
-    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised));
+    // on the same tick. A live holder's lock never goes stale, because proper-lockfile refreshes it;
+    // it expires only when a process actually dies.
+    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, { retries: 600, factor: 1, minTimeout: 300, maxTimeout: 800, randomize: true }, onCompromised, PROVISIONING_LOCK_STALE_MS));
     return releaseIgnoringAlreadyReleased(release, lockPath);
 }
 /**
@@ -104,17 +121,61 @@ export async function acquireProvisioningLock(lockTargetDir, lockName, onComprom
  * request/response cycle (a Lambda-backed API handler). `acquireProvisioningLock`'s ~600-retry
  * budget waits minutes for a live provisioner; an admin request must fail fast instead.
  *
- * `stale: 30_000` is unchanged from the patient variant: a genuinely stale lock (holder crashed
- * more than 30s ago) is still taken over normally. Only the RETRY loop for live contention is
- * removed, not the staleness recovery a caller depends on -- see branch-health.ts's [H1]
- * freshness rail, which reads this lock's mtime before an admin purge/repair proceeds.
+ * Staleness recovery is unchanged from the patient variant: a genuinely stale lock is still taken
+ * over normally. Only the RETRY loop for live contention is removed, not the staleness recovery a
+ * caller depends on -- see branch-health.ts's [H1] freshness rail, which reads this lock's mtime
+ * before an admin purge/repair proceeds.
  *
  * Throws with `err.code === 'ELOCKED'` on contention (a live, non-stale holder) -- callers
  * translate that into a 409.
+ *
+ * @param staleMs how old the marker must look before this caller takes it over; defaults to
+ *   {@link PROVISIONING_LOCK_STALE_MS}
+ * @param createParents whether a missing parent of `lockTargetDir` is created. A lock inside a
+ *   branch passes false: a waiter must never recreate a branch root a delete removed, so a missing
+ *   parent fails with ENOENT instead.
  */
-export async function tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised) {
-    await fs.mkdir(lockTargetDir, { recursive: true });
+export async function tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised, staleMs = PROVISIONING_LOCK_STALE_MS, createParents = true) {
+    if (createParents) {
+        await fs.mkdir(lockTargetDir, { recursive: true });
+    }
+    else {
+        await fs.mkdir(lockTargetDir).catch((err) => {
+            if (!isNodeError(err) || err.code !== 'EEXIST')
+                throw err;
+        });
+    }
     const lockPath = path.join(lockTargetDir, lockName);
-    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised));
+    const release = await lockfile.lock(lockPath, provisioningLockOptions(lockPath, 0, onCompromised, staleMs));
     return releaseIgnoringAlreadyReleased(release, lockPath);
 }
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * {@link tryAcquireProvisioningLock} retried for at most `waitMs`, for a caller whose own hold is
+ * milliseconds long (publishing a staged branch workspace). A dead holder's marker stays live for
+ * {@link PROVISIONING_LOCK_STALE_MS}, so waiting it out from a request would spend the request's
+ * whole timeout; this gives up instead.
+ *
+ * Retries only on `ELOCKED`, like the content-write lock's bounded wait.
+ *
+ * @throws the last `ELOCKED` error once the budget is spent
+ */
+export async function acquireProvisioningLockWithin(lockTargetDir, lockName, waitMs, onCompromised) {
+    const startedAt = Date.now();
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await tryAcquireProvisioningLock(lockTargetDir, lockName, onCompromised);
+        }
+        catch (err) {
+            if (!isNodeError(err) || err.code !== 'ELOCKED')
+                throw err;
+            const remaining = waitMs - (Date.now() - startedAt);
+            if (remaining <= 0)
+                throw err;
+            const base = Math.min(50 * 2 ** attempt, 500);
+            await sleep(Math.min(base * (0.5 + Math.random()), remaining));
+        }
+    }
+}

package/dist/utils/request-timing.d.ts

@@ -0,0 +1,25 @@
+interface PhaseTotal {
+    count: number;
+    ms: number;
+}
+/** Record `fn` as `phase` in the active request scope; outside one, just run it. */
+export declare function timeRequestPhase<T>(phase: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Whether a request scope is open here.
+ * @internal Exported for tests.
+ */
+export declare function isRequestTimingScopeActive(): boolean;
+/** Name the matched route (a pattern, never raw path segments) for the summary line. */
+export declare function setRequestTimingRoute(route: string): void;
+/**
+ * The summary line's message, after the logger's timestamp/category prefix:
+ * `GET :branch/entries 200 1172ms | context=0 auth=12 route=1110 route>settingsRoot=1080(x2) untimed=50`.
+ * @internal Exported for tests.
+ */
+export declare function formatRequestTimingSummary(method: string, route: string, status: number | 'error', totalMs: number, phases: ReadonlyMap<string, PhaseTotal>): string;
+/**
+ * Run one API request inside a timing scope and log its summary line when it settles,
+ * thrown or not. `statusOf` reads the status from the result.
+ */
+export declare function runWithRequestTiming<T>(method: string, fn: () => Promise<T>, statusOf: (result: T) => number): Promise<T>;
+export {};

package/dist/utils/request-timing.js

@@ -0,0 +1,101 @@
+/**
+ * Per-request phase timing for the API handler, enabled by `CANOPYCMS_DEBUG=true`.
+ *
+ * `runWithRequestTiming` opens a request scope in AsyncLocalStorage and, when the request
+ * finishes, emits ONE summary line: method, route pattern, status, total, and every phase
+ * recorded inside the scope. `timeRequestPhase` records a phase into whichever scope is
+ * active. Scopes are per async context, so concurrent requests in one process never share
+ * or overwrite a span, and a phase reached outside any request (the worker, a build, a
+ * page render) just runs its function.
+ *
+ * Disabled, `runWithRequestTiming` calls straight through without opening a scope, so each
+ * `timeRequestPhase` costs one `getStore()` that returns undefined.
+ *
+ * A phase started inside another records under the joined name (`route>settingsRoot`), so
+ * nesting stays visible and nested time is never added to its parent's siblings. A phase
+ * run several times in one request accumulates, and the line shows the count. `untimed` is
+ * the total minus the top-level phases, which run sequentially in the handler.
+ *
+ * Server-only: `node:async_hooks`.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createDebugLogger } from './debug.js';
+const storage = new AsyncLocalStorage();
+const log = createDebugLogger({ prefix: 'CanopyCMS' });
+/** Read per call, like DebugLogger, so toggling the env var needs no restart. */
+function isRequestTimingEnabled() {
+    return process.env.CANOPYCMS_DEBUG === 'true';
+}
+/** Record `fn` as `phase` in the active request scope; outside one, just run it. */
+export async function timeRequestPhase(phase, fn) {
+    const parent = storage.getStore();
+    if (!parent)
+        return fn();
+    const key = parent.path ? `${parent.path}>${phase}` : phase;
+    // Created at START so the summary lists phases in the order they began.
+    let total = parent.phases.get(key);
+    if (!total) {
+        total = { count: 0, ms: 0 };
+        parent.phases.set(key, total);
+    }
+    const start = performance.now();
+    try {
+        return await storage.run({ ...parent, path: key }, fn);
+    }
+    finally {
+        total.count += 1;
+        total.ms += performance.now() - start;
+    }
+}
+/**
+ * Whether a request scope is open here.
+ * @internal Exported for tests.
+ */
+export function isRequestTimingScopeActive() {
+    return storage.getStore() !== undefined;
+}
+/** Name the matched route (a pattern, never raw path segments) for the summary line. */
+export function setRequestTimingRoute(route) {
+    const scope = storage.getStore();
+    if (scope)
+        scope.request.route = route;
+}
+/**
+ * The summary line's message, after the logger's timestamp/category prefix:
+ * `GET :branch/entries 200 1172ms | context=0 auth=12 route=1110 route>settingsRoot=1080(x2) untimed=50`.
+ * @internal Exported for tests.
+ */
+export function formatRequestTimingSummary(method, route, status, totalMs, phases) {
+    let topLevelMs = 0;
+    const parts = [];
+    for (const [name, { count, ms }] of phases) {
+        if (!name.includes('>'))
+            topLevelMs += ms;
+        parts.push(`${name}=${Math.round(ms)}${count > 1 ? `(x${count})` : ''}`);
+    }
+    parts.push(`untimed=${Math.max(0, Math.round(totalMs - topLevelMs))}`);
+    return `${method} ${route} ${status} ${Math.round(totalMs)}ms | ${parts.join(' ')}`;
+}
+/**
+ * Run one API request inside a timing scope and log its summary line when it settles,
+ * thrown or not. `statusOf` reads the status from the result.
+ */
+export async function runWithRequestTiming(method, fn, statusOf) {
+    if (!isRequestTimingEnabled())
+        return fn();
+    const scope = {
+        phases: new Map(),
+        path: '',
+        request: { route: '(unmatched)' },
+    };
+    const start = performance.now();
+    let status = 'error';
+    try {
+        const result = await storage.run(scope, fn);
+        status = statusOf(result);
+        return result;
+    }
+    finally {
+        log.debug('timing', formatRequestTimingSummary(method, scope.request.route, status, performance.now() - start, scope.phases));
+    }
+}

package/dist/utils/sanitize-href.d.ts

@@ -55,36 +55,22 @@ export declare function neutralizeImplicitOffOrigin(url: string): string;
  * this file either way, so the two surfaces cannot drift into disagreeing about which schemes
  * are acceptable (that drift is exactly why `utils/url-prefix.ts` exists — see its header).
  *
- * `allowProtocolRelative` exists because the two callers genuinely differ, and the difference
- * is blast radius rather than taste:
- *
- * - A READ-side prefix (`media.publicBaseUrl`, joined onto `/assets/…`) may legitimately be
- *   `//cdn.example.com`. `utils/url-prefix.ts`'s `isAbsoluteUrl` documents that literal
- *   spelling as an intentionally-supported off-site pointer, so rejecting it here would break
- *   a working configuration. A bad value costs a broken `<img>`.
- * - A WRITE-side endpoint (`media.uploadUrl`, where the browser POSTs a presigned upload) must
- *   not be protocol-relative even when spelled literally, because such a URL is AMBIGUOUS: it
- *   resolves to http or https depending on the scheme of whichever editor page happens to
- *   issue the upload, so the stored config does not determine where a live presigned credential
- *   and the user's file bytes are sent. That is the same principle every other rule here
- *   enforces — a config value must describe what actually happens.
- *
- *   Note this is NOT an argument that http is forbidden on the write side; bare `http://` is
- *   accepted, because a loopback or in-cluster S3-compatible endpoint is a real need and a
- *   browser on an https editor blocks the mixed-content request anyway, so it fails closed. The
- *   objection to `//host` is that it is undetermined, not that it might be insecure.
+ * A protocol-relative `//host` is refused even when spelled literally, because it is AMBIGUOUS:
+ * it resolves to http or https depending on the page issuing the request, so the stored config
+ * does not determine where, for `media.uploadUrl`, a live presigned credential and the user's
+ * file bytes are sent. Bare `http://` is accepted: a loopback or in-cluster S3-compatible
+ * endpoint is a real need, and a browser on an https editor blocks the mixed-content request
+ * anyway, so it fails closed.
  *
  * Every spelling that READS as site-relative while redefining the authority — `/\host`,
- * `\\host`, `\/host`, `///host` — is rejected for both, in both modes. Those look site-relative
+ * `\\host`, `\/host`, `///host` — is rejected too. Those look site-relative
  * to a human and to a naive `startsWith('/')` check, but WHATWG URL resolves each to a
  * different authority (measured: `///x` resolves to host `x`, not to pathname `/x`), so they
  * are never what an adopter meant. A scheme-qualified absolute URL is a separate case and is
  * accepted — `https:///cdn.example.com/` is unusual but unambiguous, resolving identically
  * standalone and against any base.
  */
-export declare function isHttpUrlOrSameOriginPath(value: string, opts?: {
-    allowProtocolRelative?: boolean;
-}): boolean;
+export declare function isHttpUrlOrSameOriginPath(value: string): boolean;
 /**
  * Sanitize an untrusted URL for use in `href` attributes.
  *

package/dist/utils/sanitize-href.js

@@ -90,34 +90,22 @@ export function neutralizeImplicitOffOrigin(url) {
  * this file either way, so the two surfaces cannot drift into disagreeing about which schemes
  * are acceptable (that drift is exactly why `utils/url-prefix.ts` exists — see its header).
  *
- * `allowProtocolRelative` exists because the two callers genuinely differ, and the difference
- * is blast radius rather than taste:
- *
- * - A READ-side prefix (`media.publicBaseUrl`, joined onto `/assets/…`) may legitimately be
- *   `//cdn.example.com`. `utils/url-prefix.ts`'s `isAbsoluteUrl` documents that literal
- *   spelling as an intentionally-supported off-site pointer, so rejecting it here would break
- *   a working configuration. A bad value costs a broken `<img>`.
- * - A WRITE-side endpoint (`media.uploadUrl`, where the browser POSTs a presigned upload) must
- *   not be protocol-relative even when spelled literally, because such a URL is AMBIGUOUS: it
- *   resolves to http or https depending on the scheme of whichever editor page happens to
- *   issue the upload, so the stored config does not determine where a live presigned credential
- *   and the user's file bytes are sent. That is the same principle every other rule here
- *   enforces — a config value must describe what actually happens.
- *
- *   Note this is NOT an argument that http is forbidden on the write side; bare `http://` is
- *   accepted, because a loopback or in-cluster S3-compatible endpoint is a real need and a
- *   browser on an https editor blocks the mixed-content request anyway, so it fails closed. The
- *   objection to `//host` is that it is undetermined, not that it might be insecure.
+ * A protocol-relative `//host` is refused even when spelled literally, because it is AMBIGUOUS:
+ * it resolves to http or https depending on the page issuing the request, so the stored config
+ * does not determine where, for `media.uploadUrl`, a live presigned credential and the user's
+ * file bytes are sent. Bare `http://` is accepted: a loopback or in-cluster S3-compatible
+ * endpoint is a real need, and a browser on an https editor blocks the mixed-content request
+ * anyway, so it fails closed.
  *
  * Every spelling that READS as site-relative while redefining the authority — `/\host`,
- * `\\host`, `\/host`, `///host` — is rejected for both, in both modes. Those look site-relative
+ * `\\host`, `\/host`, `///host` — is rejected too. Those look site-relative
  * to a human and to a naive `startsWith('/')` check, but WHATWG URL resolves each to a
  * different authority (measured: `///x` resolves to host `x`, not to pathname `/x`), so they
  * are never what an adopter meant. A scheme-qualified absolute URL is a separate case and is
  * accepted — `https:///cdn.example.com/` is unusual but unambiguous, resolving identically
  * standalone and against any base.
  */
-export function isHttpUrlOrSameOriginPath(value, opts = {}) {
+export function isHttpUrlOrSameOriginPath(value) {
     if (value === '')
         return false;
     // Reject ASCII control characters and spaces ANYWHERE in the value, not only at the edges.
@@ -132,7 +120,7 @@ export function isHttpUrlOrSameOriginPath(value, opts = {}) {
     }
     // A query or fragment is meaningless on both sides this predicate serves. S3's POST Object
     // takes no query parameters and a browser never transmits a fragment; and on the read side a
-    // prefix carrying either produces `https://cdn.example.com/?x=1/assets/…` once joined.
+    // prefix carrying either produces `https://cdn.example.com/?x=1/…` once joined.
     if (value.includes('?') || value.includes('#'))
         return false;
     // A backslash is never legitimate in a configured URL, and it is not merely cosmetic: WHATWG
@@ -169,13 +157,8 @@ export function isHttpUrlOrSameOriginPath(value, opts = {}) {
             return false;
         }
     }
-    // A LITERAL `//host` is the only off-origin spelling that can be intentional, and only for
-    // callers that opt in. `value[2] !== '/'` matters: `///x` and `////x` are also "implicitly
-    // off-origin" and also start with `//`, but resolve to a host named `x` rather than to a
-    // path — so they must not ride in on the opt-in.
-    if (isImplicitlyOffOrigin(value)) {
-        return opts.allowProtocolRelative === true && value.startsWith('//') && value[2] !== '/';
-    }
+    if (isImplicitlyOffOrigin(value))
+        return false;
     // Site-relative, with exactly one leading slash. The second clause also covers `//`, which
     // `isImplicitlyOffOrigin` reports as false only because `new URL('//', base)` throws.
     return value.startsWith('/') && value[1] !== '/';

package/dist/utils/url-prefix.d.ts

@@ -119,3 +119,33 @@ export declare function sanitizeUnprefixedPath(url: string): string;
  * neutralizing it would silently rewrite a legitimate protocol-relative CDN base into a path.
  */
 export declare function joinUrlPrefix(prefix: string | undefined, path: string): string;
+/**
+ * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
+ *
+ * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
+ * `/blog/rss.xml`) alone, and never doubles an existing slash. So it never produces a URL that
+ * Next's `trailingSlash: true` redirects (`next/dist/lib/load-custom-routes.js:489,502` in
+ * 15.5.21): Next adds a slash only to a last segment with no dot, and strips one from a segment
+ * ending `.ext`.
+ *
+ * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
+ * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
+ * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
+ * with a trailing slash" means and breaks the URL).
+ */
+export declare function withTrailingSlash(path: string): string;
+/**
+ * Give a URL's path the trailing-slash form a Next host serves, so loading it draws no 308:
+ * `withTrailingSlash`'s rule when `trailingSlash` is true, else no trailing slash on any path
+ * but the root (Next also redirects `<basePath>/` to `<basePath>`, `load-custom-routes.js:528`). An
+ * absolute URL's origin, and any query or fragment, are kept as they are.
+ */
+export declare function matchTrailingSlash(url: string, trailingSlash: boolean): string;
+/**
+ * Whether the host is built with Next's `trailingSlash: true`. `withCanopy` sets
+ * `CANOPY_TRAILING_SLASH` in Next's `env` config, which Next substitutes for this literal member
+ * expression in server and browser bundles (`getNextConfigEnv`, `next/dist/build/define-env.js:54`).
+ * The try/catch covers a host whose bundler neither substitutes it nor shims `process` in the
+ * browser.
+ */
+export declare function readTrailingSlashEnv(): boolean;

package/dist/utils/url-prefix.js

@@ -156,3 +156,64 @@ export function joinUrlPrefix(prefix, path) {
         : `/${trimmedPrefix}`;
     return `${normalizedPrefix}${normalizedPath}`;
 }
+/**
+ * Append a trailing slash to a site-relative path, matching a site that serves `/contact/`.
+ *
+ * Leaves the root (`/`) and file-like paths (a last segment containing a dot, e.g.
+ * `/blog/rss.xml`) alone, and never doubles an existing slash. So it never produces a URL that
+ * Next's `trailingSlash: true` redirects (`next/dist/lib/load-custom-routes.js:489,502` in
+ * 15.5.21): Next adds a slash only to a last segment with no dot, and strips one from a segment
+ * ending `.ext`.
+ *
+ * A query string and/or fragment (`?page=2`, `#section`) is split off BEFORE the slash decision
+ * and placement, then reattached after — so `/blog?page=2` becomes `/blog/?page=2`, never
+ * `/blog?page=2/` (a literal trailing slash inside the query string, which is not what "serve
+ * with a trailing slash" means and breaks the URL).
+ */
+export function withTrailingSlash(path) {
+    const splitIndex = path.search(/[?#]/);
+    const base = splitIndex === -1 ? path : path.slice(0, splitIndex);
+    const suffix = splitIndex === -1 ? '' : path.slice(splitIndex);
+    const withLeading = base.startsWith('/') ? base : `/${base}`;
+    if (withLeading === '/' || withLeading.endsWith('/'))
+        return withLeading + suffix;
+    const lastSegment = withLeading.slice(withLeading.lastIndexOf('/') + 1);
+    if (lastSegment.includes('.'))
+        return withLeading + suffix;
+    return `${withLeading}/${suffix}`;
+}
+// Linear: `[^/?#]*` cannot overlap the literal `//` before it, so there is one way to match.
+// eslint-disable-next-line security/detect-unsafe-regex
+const URL_ORIGIN = /^(?:[a-z][a-z0-9+.-]*:)?\/\/[^/?#]*/i;
+/**
+ * Give a URL's path the trailing-slash form a Next host serves, so loading it draws no 308:
+ * `withTrailingSlash`'s rule when `trailingSlash` is true, else no trailing slash on any path
+ * but the root (Next also redirects `<basePath>/` to `<basePath>`, `load-custom-routes.js:528`). An
+ * absolute URL's origin, and any query or fragment, are kept as they are.
+ */
+export function matchTrailingSlash(url, trailingSlash) {
+    const origin = isAbsoluteUrl(url) ? (URL_ORIGIN.exec(url)?.[0] ?? '') : '';
+    const rest = url.slice(origin.length);
+    if (trailingSlash)
+        return origin + withTrailingSlash(rest);
+    const splitIndex = rest.search(/[?#]/);
+    const base = splitIndex === -1 ? rest : rest.slice(0, splitIndex);
+    const suffix = splitIndex === -1 ? '' : rest.slice(splitIndex);
+    const trimmed = stripTrailingSlashes(base);
+    return origin + (trimmed || (origin ? '' : '/')) + suffix;
+}
+/**
+ * Whether the host is built with Next's `trailingSlash: true`. `withCanopy` sets
+ * `CANOPY_TRAILING_SLASH` in Next's `env` config, which Next substitutes for this literal member
+ * expression in server and browser bundles (`getNextConfigEnv`, `next/dist/build/define-env.js:54`).
+ * The try/catch covers a host whose bundler neither substitutes it nor shims `process` in the
+ * browser.
+ */
+export function readTrailingSlashEnv() {
+    try {
+        return process.env.CANOPY_TRAILING_SLASH === 'true';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/yaml-source-splice.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Print a reconciled YAML document by editing the source text it was parsed from, so the bytes
+ * the reconciler did not change stay as the author wrote them.
+ *
+ * `Document.toString()` re-emits every scalar from its VALUE: folded and long plain scalars are
+ * re-wrapped at the library's line width, so the first CMS save of a hand-written file rewrites
+ * lines nobody edited. Here a clean subtree is copied verbatim from the source, and only a slot
+ * the reconciler touched is re-rendered, at the column it already occupies:
+ *
+ * - **Map**: the reconciler keeps retained pairs in source order and appends new ones, so a map
+ *   becomes a list of local edits — delete a dropped pair's lines, re-render a pair whose value
+ *   was replaced, recurse into a value edited in place, insert new pairs after the last item.
+ * - **Sequence**: items can be reordered, so the item region is rebuilt as a concatenation of
+ *   per-item chunks, each one either an original item's source (recursively patched) or a freshly
+ *   rendered item.
+ *
+ * A chunk is an item's lines plus the comment and blank lines above it, which is where `yaml`
+ * attaches those comments (the item's `commentBefore`), so a chunk moves and dies with exactly
+ * the comments the reconciler moves and drops. Above a nested collection's FIRST item they
+ * belong to the collection instead, and stay put; above the root map's first key they are the
+ * key's (`ownLeadingLines`).
+ *
+ * Anything this does not handle returns `undefined` from that collection, and the parent
+ * re-renders the whole slot instead; only at the root does that reach the caller, which falls
+ * back to the reconciled document as `yaml` prints it. Every splice is also re-parsed and
+ * checked ({@link printsAs}) before it is returned, so a wrong splice costs formatting, never
+ * data.
+ */
+import { Document, YAMLMap, YAMLSeq } from 'yaml';
+type Collection = YAMLMap<unknown, unknown> | YAMLSeq<unknown>;
+/** One parsed item: a pair for a map, the item node for a sequence. */
+interface SnapshotItem {
+    readonly item: unknown;
+    /** A map pair's value as parsed; the reconciler reassigns `pair.value`. */
+    readonly value: unknown;
+}
+/** The parsed document's shape, taken before the reconciler runs. */
+export interface SourceSnapshot {
+    /** Every collection's items exactly as parsed. */
+    readonly items: ReadonlyMap<Collection, readonly SnapshotItem[]>;
+    /** The source uses anchors or aliases; an edit through an alias is not local to one slot. */
+    readonly anchored: boolean;
+}
+export declare function snapshotDocument(doc: Document): SourceSnapshot;
+/**
+ * `printed` (a `toString()`) written with `raw`'s line endings: CRLF when `raw` is consistently
+ * CRLF, else LF. Either way without the stray `\r` that comments parsed from CRLF keep, so a
+ * whole-file re-print does not leave the file with mixed line endings.
+ */
+export declare function withSourceLineEndings(printed: string, raw: string): string;
+/**
+ * The source text of `raw` with only the reconciler's changes applied, or undefined when the
+ * document holds a construct this does not splice or the splice fails its self-check.
+ * `replaced` maps each node the reconciler created for an existing slot back to the node it
+ * replaced; `printed` is the reconciled document's `toString()`.
+ */
+export declare function spliceSource(raw: string, doc: Document, snapshot: SourceSnapshot, replaced: WeakMap<object, unknown>, printed: string): string | undefined;
+export {};