canopycms 0.0.68-int.98 → 0.1.0

package/dist/utils/provisioning-lock.js

@@ -3,12 +3,40 @@ import path from 'node:path';
 import lockfile from 'proper-lockfile';
 import { getErrorMessage, isNodeError } from './error.js';
 import { canopyLogWarn } from './logger.js';
+/**
+ * Wrap a compromise handler for proper-lockfile's `onCompromised`, which it invokes from inside
+ * its refresh timer: ANY throw escaping there is an uncaught exception that kills the process.
+ * Call sites are told not to throw (see {@link OnLockCompromised}); this makes it structural
+ * rather than a convention, and also covers the LOGGER throwing -- under `CI=true`, vitest's
+ * `onConsoleLog` turns a console write into a throw.
+ *
+ * Handlers report through an always-on logger (`canopyLogWarn`), never the debug logger: "two
+ * holders may now be live" must be visible without CANOPYCMS_DEBUG.
+ */
+export function guardOnCompromised(handler, lockPath) {
+    return (err) => {
+        try {
+            handler(err);
+        }
+        catch {
+            // Last resort: a raw stderr write goes around both a replaced logger and vitest's console
+            // interception, so the compromise still leaves a trace. Guarded in turn, because nothing
+            // here is allowed to throw out of a refresh timer.
+            try {
+                process.stderr.write(`[canopy] lock compromised for ${lockPath}; its handler or logger threw\n`);
+            }
+            catch {
+                // Nothing further is safe to attempt.
+            }
+        }
+    };
+}
 /**
  * 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.
  */
-const PROVISIONING_LOCK_STALE_MS = 90_000;
+export const PROVISIONING_LOCK_STALE_MS = 90_000;
 /**
  * Shared option set for both provisioning-lock variants.
  *
@@ -30,35 +58,12 @@ function provisioningLockOptions(lockPath, retries, onCompromised, staleMs) {
         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
-        // LOGGER throwing -- under `CI=true`, vitest's `onConsoleLog` turns a console write into a
-        // throw.
-        onCompromised: (err) => {
-            try {
-                if (onCompromised) {
-                    onCompromised(err);
-                    return;
-                }
-                // Default: log and let the holder finish. proper-lockfile's own default rethrows from
-                // the refresh timer, which protects nothing -- by the time a compromise is reported the
-                // mutual exclusion is already gone. `canopyLogWarn`, not the debug logger, because "two
-                // holders may now be live" must be visible without CANOPYCMS_DEBUG.
-                canopyLogWarn(`[canopy] Provisioning lock compromised mid-hold for ${lockPath}:`, getErrorMessage(err));
-            }
-            catch {
-                // Last resort: a raw stderr write goes around both a replaced logger and vitest's console
-                // interception, so the compromise still leaves a trace. Guarded in turn, because nothing
-                // here is allowed to throw out of a refresh timer.
-                try {
-                    process.stderr.write(`[canopy] lock compromised for ${lockPath}; its handler or logger threw\n`);
-                }
-                catch {
-                    // Nothing further is safe to attempt.
-                }
-            }
-        },
+        onCompromised: guardOnCompromised(onCompromised ??
+            ((err) => 
+            // Default: log and let the holder finish. proper-lockfile's own default rethrows from
+            // the refresh timer, which protects nothing -- by the time a compromise is reported the
+            // mutual exclusion is already gone.
+            canopyLogWarn(`[canopy] Provisioning lock compromised mid-hold for ${lockPath}:`, getErrorMessage(err))), lockPath),
     };
 }
 /**
@@ -131,10 +136,51 @@ export async function acquireProvisioningLock(lockTargetDir, lockName, onComprom
  *
  * @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, staleMs = PROVISIONING_LOCK_STALE_MS) {
-    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, 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/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.
  *
@@ -122,4 +108,4 @@ export declare function isHttpUrlOrSameOriginPath(value: string, opts?: {
  * <a href={sanitizeHref(cta.link)}>{cta.text}</a>
  * ```
  */
-export declare function sanitizeHref(url: string, fallback?: string): string;
+export declare function sanitizeHref(url: string | null | undefined, fallback?: string): string;

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] !== '/';
@@ -218,6 +201,9 @@ export function isHttpUrlOrSameOriginPath(value, opts = {}) {
  * ```
  */
 export function sanitizeHref(url, fallback = '#') {
+    // A live preview's draft can lack the field, as after a Clear and a partial refill.
+    if (typeof url !== 'string')
+        return fallback;
     const trimmed = url.trim();
     if (trimmed === '')
         return fallback;

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

@@ -5,6 +5,16 @@ import type { FieldConfig } from '../config/index.js';
  * @internal Exported for tests.
  */
 export declare function extractTitleFromSchema(fields: readonly FieldConfig[], data: Record<string, unknown>): string | undefined;
+/**
+ * The data path `resolveEntryTitle` reads the title from for these fields: the `isTitle` field
+ * (found by the walk `extractTitleFromSchema` uses, so inline groups are transparent and
+ * non-list objects are entered), else a top-level plain-string field named `title`, then `name`
+ * (fields of an inline group count as top level, as they do in the data).
+ * Undefined when the schema has no such field, so a create form has nothing to ask a title for.
+ */
+export declare function titleFieldPath(fields: readonly FieldConfig[]): readonly string[] | undefined;
+/** Data holding `title` at `path`: `['hero', 'title']` gives `{ hero: { title } }`. */
+export declare function withTitleAtPath(path: readonly string[], title: string): Record<string, unknown>;
 /**
  * Convert a slug like "my-cool-page" to "My Cool Page".
  * @internal Exported for tests.

package/dist/utils/title-field.js

@@ -33,6 +33,53 @@ function findTitleValue(fields, data) {
     }
     return undefined;
 }
+/**
+ * The data path `resolveEntryTitle` reads the title from for these fields: the `isTitle` field
+ * (found by the walk `extractTitleFromSchema` uses, so inline groups are transparent and
+ * non-list objects are entered), else a top-level plain-string field named `title`, then `name`
+ * (fields of an inline group count as top level, as they do in the data).
+ * Undefined when the schema has no such field, so a create form has nothing to ask a title for.
+ */
+export function titleFieldPath(fields) {
+    return (findTitlePath(fields) ??
+        findNamedStringField(fields, 'title') ??
+        findNamedStringField(fields, 'name'));
+}
+function findTitlePath(fields) {
+    for (const field of fields) {
+        if (isGroupField(field)) {
+            const result = findTitlePath(field.fields);
+            if (result)
+                return result;
+        }
+        else if ('isTitle' in field && field.isTitle) {
+            return [field.name];
+        }
+        else if (field.type === 'object' && 'fields' in field && field.fields && !field.list) {
+            const nested = findTitlePath(field.fields);
+            if (nested)
+                return [field.name, ...nested];
+        }
+    }
+    return undefined;
+}
+function findNamedStringField(fields, name) {
+    for (const field of fields) {
+        if (isGroupField(field)) {
+            const result = findNamedStringField(field.fields, name);
+            if (result)
+                return result;
+        }
+        else if (field.name === name && field.type === 'string' && !field.list) {
+            return [field.name];
+        }
+    }
+    return undefined;
+}
+/** Data holding `title` at `path`: `['hero', 'title']` gives `{ hero: { title } }`. */
+export function withTitleAtPath(path, title) {
+    return path.reduceRight((value, key) => ({ [key]: value }), title);
+}
 /**
  * Convert a slug like "my-cool-page" to "My Cool Page".
  * @internal Exported for tests.

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 {};