canopycms 0.0.61 → 0.0.63

package/dist/static/seo.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Framework-agnostic SEO field extraction and URL shaping.
+ *
+ * This module is pure: it maps an entry's raw data onto a neutral `SeoFields` shape and
+ * resolves URLs. Framework adapters (e.g. canopycms-next's `entryToMetadata`) turn that shape
+ * into their own metadata objects; nothing here imports a framework or a node built-in.
+ *
+ * The field names default to the recommended SEO field group — see `defineSeoFieldGroup` in
+ * entry-schema.ts, which builds a schema group from these same names so the schema side and
+ * the read side cannot drift.
+ */
+/** og:type values covered by the recommended group. */
+export type SeoOgType = 'website' | 'article' | 'profile';
+/** twitter:card values covered by the recommended group. */
+export type SeoTwitterCard = 'summary' | 'summary_large_image';
+/** The neutral, framework-agnostic SEO shape. */
+export interface SeoFields {
+    title?: string;
+    description?: string;
+    ogImage?: string;
+    ogType?: SeoOgType;
+    canonical?: string;
+    noindex?: boolean;
+    twitterCard?: SeoTwitterCard;
+}
+/** Entry field names backing each neutral field. */
+export type SeoFieldNames = Record<keyof SeoFields, string>;
+/**
+ * The recommended SEO field names. `defineSeoFieldGroup()` emits a schema group using exactly
+ * these names, so an adopter who uses both ends needs no configuration at all.
+ */
+export declare const DEFAULT_SEO_FIELD_NAMES: {
+    readonly title: "metaTitle";
+    readonly description: "metaDescription";
+    readonly ogImage: "ogImage";
+    readonly ogType: "ogType";
+    readonly canonical: "canonical";
+    readonly noindex: "noindex";
+    readonly twitterCard: "twitterCard";
+};
+export interface ExtractSeoFieldsOptions {
+    /** Per-field name overrides (e.g. `{ title: 'seoTitle' }`). */
+    fields?: Partial<SeoFieldNames>;
+    /**
+     * Read the fields from a nested object under this key instead of from flat entry fields.
+     * Pair with `defineSeoFieldGroup({ group: 'seo' })`, which nests the same fields under that
+     * key in the content file. Omit for the flat (inline-group) convention, which is the default
+     * on both ends.
+     */
+    group?: string;
+    /** Used when the entry has no meta title (typically the entry's own title/heading). */
+    fallbackTitle?: string;
+    /** Used when the entry has no meta description. */
+    fallbackDescription?: string;
+}
+/** Just the parts of `ExtractSeoFieldsOptions` that locate the fields, with no fallbacks. */
+export type SeoFieldLocation = Pick<ExtractSeoFieldsOptions, 'fields' | 'group'>;
+/**
+ * Map an entry's SEO fields onto the neutral shape.
+ *
+ * Entry data is `unknown` — every read is guarded, unknown enum values are dropped rather than
+ * passed through, and non-object data (null, a string, an array) yields an all-undefined result
+ * rather than throwing.
+ */
+export declare function extractSeoFields(entryData: unknown, opts?: ExtractSeoFieldsOptions): SeoFields;
+/**
+ * THE `noindex` predicate. Every surface that suppresses an entry must route through this one
+ * function rather than re-deriving the flag:
+ *
+ * - the page's own `robots: { index: false }` (canopycms-next's `entryToMetadata`), and
+ * - exclusion from the sitemap (canopycms-next's `generateContentSitemap`).
+ *
+ * Those two shipping from one predicate is the point of shipping them together. Where they were
+ * derived separately, a `noindex` entry stayed advertised in one surface while correctly absent
+ * from the other, and nothing warned.
+ *
+ * NOT applied to enumeration: `noindex` means "don't advertise this", not "don't build this".
+ * `collectRoutableEntries` and `generateStaticParams` must still emit the entry, so its URL
+ * resolves for anyone holding the link.
+ */
+export declare function isNoindexEntry(entryData: unknown, opts?: SeoFieldLocation): boolean;
+/**
+ * An off-site URL: either scheme-qualified (`https://…`) or LITERAL protocol-relative
+ * (`//cdn…`). Both name a host we don't control, so neither may be rewritten against the site
+ * origin — `resolveSeoUrl` passes a `true` result through verbatim.
+ *
+ * Deliberately narrower than "resolves off-origin": a WHATWG-backslash-equivalent spelling
+ * (`/\evil.com`, `\\evil.com`, `\/evil.com` — see `utils/sanitize-href.ts`'s
+ * `isImplicitlyOffOrigin`) also resolves off-origin in a browser, but is NOT recognized here as
+ * an intentional off-site pointer the way a literal `//cdn…` is. `resolveSeoUrl` handles that
+ * case separately, by neutralizing (`neutralizeImplicitOffOrigin`) rather than passing through: a
+ * `false` result here isn't a guarantee the value is a safe site-relative path on its own, only
+ * that it isn't a *declared* off-site one.
+ */
+export declare function isAbsoluteUrl(url: string): boolean;
+/**
+ * Strip trailing slashes without a regex.
+ *
+ * The obvious `replace(/\/+$/, '')` is a polynomial-ReDoS shape (CodeQL
+ * `js/polynomial-redos`, flagged high): on a value that is mostly slashes but does not end in
+ * one, the engine retries `\/+` from every position and the match cost is quadratic in the
+ * input length. `siteUrl` is adopter-supplied and can reach here from config or an env var, so
+ * it counts as uncontrolled. A character scan is linear and needs no reasoning about
+ * backtracking.
+ *
+ * Exported (from `canopycms/server`) so adopter code normalizing its own site-origin env var —
+ * e.g. a `SITE_URL` constant built from `NEXT_PUBLIC_SITE_URL` — has a package-provided linear
+ * way to do it instead of reaching for the same regex this function replaced.
+ */
+export declare function stripTrailingSlashes(value: 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.
+ *
+ * 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;
+export interface ResolveSeoUrlOptions {
+    /** Site origin (e.g. `https://example.com`). Trailing slashes are stripped. */
+    siteUrl?: string;
+    /**
+     * Emit site-relative paths with a trailing slash. CanopyCMS has no knowledge of your
+     * framework's routing config, so this must be stated explicitly — see the note on
+     * `generateContentSitemap`.
+     */
+    trailingSlash?: boolean;
+}
+/**
+ * Resolve a possibly-relative URL for public emission (canonical tag, sitemap URL, OG image).
+ *
+ * ORDER MATTERS — the absolute check runs FIRST. An absolute or protocol-relative value is a
+ * deliberate off-site pointer (syndication, a partner-hosted copy, a CDN image) and passes
+ * through verbatim; only a site-relative path gets trailing-slash normalization and the site
+ * origin. Normalizing first turns `https://other.org/page` into
+ * `<siteUrl>/https://other.org/page/`.
+ *
+ * With no `siteUrl`, a site-relative path is returned still relative (normalized), which is
+ * what you want when the framework resolves relative metadata URLs itself.
+ *
+ * A NOT-absolute value is also run through `neutralizeImplicitOffOrigin` before normalization,
+ * so a WHATWG-backslash-equivalent spelling that `isAbsoluteUrl` correctly declines to call
+ * "absolute" (see its doc) can't still be read by a browser as protocol-relative once emitted.
+ */
+export declare function resolveSeoUrl(pathOrUrl: string, opts?: ResolveSeoUrlOptions): string;
+//# sourceMappingURL=seo.d.ts.map

package/dist/static/seo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.d.ts","sourceRoot":"","sources":["../../src/static/seo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,uDAAuD;AACvD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;AAEzD,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,qBAAqB,CAAA;AAE9D,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,WAAW,CAAC,EAAE,cAAc,CAAA;CAC7B;AAED,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,SAAS,EAAE,MAAM,CAAC,CAAA;AAE3D;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;CAQF,CAAA;AAElC,MAAM,WAAW,uBAAuB;IACtC,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;IAC/B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mDAAmD;IACnD,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,6FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,uBAAuB,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAA;AA6ChF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,OAAO,EAClB,IAAI,GAAE,uBAA4B,GACjC,SAAS,CAcX;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAEvF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUtD;AAED,MAAM,WAAW,oBAAoB;IACnC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,CAUxF"}

package/dist/static/seo.js

@@ -0,0 +1,189 @@
+/**
+ * Framework-agnostic SEO field extraction and URL shaping.
+ *
+ * This module is pure: it maps an entry's raw data onto a neutral `SeoFields` shape and
+ * resolves URLs. Framework adapters (e.g. canopycms-next's `entryToMetadata`) turn that shape
+ * into their own metadata objects; nothing here imports a framework or a node built-in.
+ *
+ * The field names default to the recommended SEO field group — see `defineSeoFieldGroup` in
+ * entry-schema.ts, which builds a schema group from these same names so the schema side and
+ * the read side cannot drift.
+ */
+import { neutralizeImplicitOffOrigin } from '../utils/sanitize-href.js';
+/**
+ * The recommended SEO field names. `defineSeoFieldGroup()` emits a schema group using exactly
+ * these names, so an adopter who uses both ends needs no configuration at all.
+ */
+export const DEFAULT_SEO_FIELD_NAMES = {
+    title: 'metaTitle',
+    description: 'metaDescription',
+    ogImage: 'ogImage',
+    ogType: 'ogType',
+    canonical: 'canonical',
+    noindex: 'noindex',
+    twitterCard: 'twitterCard',
+};
+const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : undefined;
+/**
+ * A non-empty trimmed string, or undefined.
+ *
+ * Empty is treated as UNSET, deliberately: CanopyCMS writes optional fields present-but-empty
+ * rather than omitting them, so `metaTitle: ''` is what an untouched SEO group looks like on
+ * disk. Treating it as a value would let a blank field beat the fallback title on every entry
+ * whose author never opened the SEO section.
+ */
+const asText = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+};
+const asFlag = (value) => typeof value === 'boolean' ? value : undefined;
+/**
+ * An image URL from either convention: a plain string field, or an `image` field, whose value
+ * is a structured `{ src, alt, ... }` object. Supporting both means switching the recommended
+ * `ogImage` field to `type: 'image'` doesn't silently drop every OG image.
+ */
+const asImageUrl = (value) => {
+    const text = asText(value);
+    if (text)
+        return text;
+    return asText(asRecord(value)?.src);
+};
+const asOgType = (value) => {
+    const text = asText(value);
+    return text === 'website' || text === 'article' || text === 'profile' ? text : undefined;
+};
+const asTwitterCard = (value) => {
+    const text = asText(value);
+    return text === 'summary' || text === 'summary_large_image' ? text : undefined;
+};
+/**
+ * Map an entry's SEO fields onto the neutral shape.
+ *
+ * Entry data is `unknown` — every read is guarded, unknown enum values are dropped rather than
+ * passed through, and non-object data (null, a string, an array) yields an all-undefined result
+ * rather than throwing.
+ */
+export function extractSeoFields(entryData, opts = {}) {
+    const names = { ...DEFAULT_SEO_FIELD_NAMES, ...opts.fields };
+    const entry = asRecord(entryData);
+    const source = opts.group ? asRecord(entry?.[opts.group]) : entry;
+    return {
+        title: asText(source?.[names.title]) ?? asText(opts.fallbackTitle),
+        description: asText(source?.[names.description]) ?? asText(opts.fallbackDescription),
+        ogImage: asImageUrl(source?.[names.ogImage]),
+        ogType: asOgType(source?.[names.ogType]),
+        canonical: asText(source?.[names.canonical]),
+        noindex: asFlag(source?.[names.noindex]),
+        twitterCard: asTwitterCard(source?.[names.twitterCard]),
+    };
+}
+/**
+ * THE `noindex` predicate. Every surface that suppresses an entry must route through this one
+ * function rather than re-deriving the flag:
+ *
+ * - the page's own `robots: { index: false }` (canopycms-next's `entryToMetadata`), and
+ * - exclusion from the sitemap (canopycms-next's `generateContentSitemap`).
+ *
+ * Those two shipping from one predicate is the point of shipping them together. Where they were
+ * derived separately, a `noindex` entry stayed advertised in one surface while correctly absent
+ * from the other, and nothing warned.
+ *
+ * NOT applied to enumeration: `noindex` means "don't advertise this", not "don't build this".
+ * `collectRoutableEntries` and `generateStaticParams` must still emit the entry, so its URL
+ * resolves for anyone holding the link.
+ */
+export function isNoindexEntry(entryData, opts = {}) {
+    return extractSeoFields(entryData, opts).noindex === true;
+}
+/**
+ * An off-site URL: either scheme-qualified (`https://…`) or LITERAL protocol-relative
+ * (`//cdn…`). Both name a host we don't control, so neither may be rewritten against the site
+ * origin — `resolveSeoUrl` passes a `true` result through verbatim.
+ *
+ * Deliberately narrower than "resolves off-origin": a WHATWG-backslash-equivalent spelling
+ * (`/\evil.com`, `\\evil.com`, `\/evil.com` — see `utils/sanitize-href.ts`'s
+ * `isImplicitlyOffOrigin`) also resolves off-origin in a browser, but is NOT recognized here as
+ * an intentional off-site pointer the way a literal `//cdn…` is. `resolveSeoUrl` handles that
+ * case separately, by neutralizing (`neutralizeImplicitOffOrigin`) rather than passing through: a
+ * `false` result here isn't a guarantee the value is a safe site-relative path on its own, only
+ * that it isn't a *declared* off-site one.
+ */
+export function isAbsoluteUrl(url) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('//');
+}
+/**
+ * Strip trailing slashes without a regex.
+ *
+ * The obvious `replace(/\/+$/, '')` is a polynomial-ReDoS shape (CodeQL
+ * `js/polynomial-redos`, flagged high): on a value that is mostly slashes but does not end in
+ * one, the engine retries `\/+` from every position and the match cost is quadratic in the
+ * input length. `siteUrl` is adopter-supplied and can reach here from config or an env var, so
+ * it counts as uncontrolled. A character scan is linear and needs no reasoning about
+ * backtracking.
+ *
+ * Exported (from `canopycms/server`) so adopter code normalizing its own site-origin env var —
+ * e.g. a `SITE_URL` constant built from `NEXT_PUBLIC_SITE_URL` — has a package-provided linear
+ * way to do it instead of reaching for the same regex this function replaced.
+ */
+export function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47 /* '/' */)
+        end--;
+    return value.slice(0, end);
+}
+/**
+ * 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.
+ *
+ * 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}`;
+}
+/**
+ * Resolve a possibly-relative URL for public emission (canonical tag, sitemap URL, OG image).
+ *
+ * ORDER MATTERS — the absolute check runs FIRST. An absolute or protocol-relative value is a
+ * deliberate off-site pointer (syndication, a partner-hosted copy, a CDN image) and passes
+ * through verbatim; only a site-relative path gets trailing-slash normalization and the site
+ * origin. Normalizing first turns `https://other.org/page` into
+ * `<siteUrl>/https://other.org/page/`.
+ *
+ * With no `siteUrl`, a site-relative path is returned still relative (normalized), which is
+ * what you want when the framework resolves relative metadata URLs itself.
+ *
+ * A NOT-absolute value is also run through `neutralizeImplicitOffOrigin` before normalization,
+ * so a WHATWG-backslash-equivalent spelling that `isAbsoluteUrl` correctly declines to call
+ * "absolute" (see its doc) can't still be read by a browser as protocol-relative once emitted.
+ */
+export function resolveSeoUrl(pathOrUrl, opts = {}) {
+    if (isAbsoluteUrl(pathOrUrl))
+        return pathOrUrl;
+    const safePathOrUrl = neutralizeImplicitOffOrigin(pathOrUrl);
+    const normalized = opts.trailingSlash
+        ? withTrailingSlash(safePathOrUrl)
+        : safePathOrUrl.startsWith('/')
+            ? safePathOrUrl
+            : `/${safePathOrUrl}`;
+    const origin = opts.siteUrl === undefined ? undefined : stripTrailingSlashes(opts.siteUrl);
+    return origin ? origin + normalized : normalized;
+}
+//# sourceMappingURL=seo.js.map

package/dist/static/seo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.js","sourceRoot":"","sources":["../../src/static/seo.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -124,6 +124,16 @@ export interface WorkerStatusReport {
         durationMs: number;
         rebased: string[];
         skippedDirty: string[];
+        /**
+         * [SYNC-C1] Branches skipped because a content write held the branch's
+         * cross-host content-write lock (utils/content-write-lock.ts) -- the
+         * worker yields and retries next cycle.
+         *
+         * Optional for the same reason as `tracked` below: absent from a
+         * worker-status.json written by a worker predating that lock. Readers must
+         * tolerate its absence.
+         */
+        skippedLocked?: string[];
         failed: {
             branch: string;
             error: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,YAAY,GAAG,MAAM,CAAA;AACjC,MAAM,MAAM,aAAa,GAAG,MAAM,CAAA;AAElC;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,CAAA;AAC5E,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,cAAc,GAAG,aAAa,CAAA;AAClE,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,oBAAoB,CAAA;AAC3D,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE3D,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,YAAY,EAAE,CAAA;IAC7B,aAAa,CAAC,EAAE,aAAa,EAAE,CAAA;IAC/B,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,EAAE,mBAAmB,CAAA;IAC3B,SAAS,EAAE,YAAY,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,iFAAiF;IACjF,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,8FAA8F;IAC9F,aAAa,CAAC,EAAE,SAAS,EAAE,CAAA;IAC3B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IACpE;;;;;;;;;;;;;;;OAeG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAA;IAEhB,4FAA4F;IAC5F,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,MAAM,EAAE,cAAc,CAAA;IAEtB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,OAAO,UAAU,EAAE,cAAc,EAAE,CAAA;CACjD;AAED,6FAA6F;AAC7F,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,UAAU,EAAE,OAAO,UAAU,EAAE,cAAc,EAAE,CAAA;CAChD;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,CAAA;IACV,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gBAAgB,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IAClD,WAAW,CAAC,EAAE;QACZ,UAAU,EAAE,MAAM,CAAA;QAClB,OAAO,EAAE,MAAM,EAAE,CAAA;QACjB,YAAY,EAAE,MAAM,EAAE,CAAA;QACtB,MAAM,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;QAC3C;;;;;WAKG;QACH;;;;WAIG;QACH,OAAO,CAAC,EAAE;YACR,OAAO,EAAE,MAAM,EAAE,CAAA;YACjB,aAAa,EAAE,MAAM,EAAE,CAAA;YACvB,KAAK,EAAE,MAAM,EAAE,CAAA;YACf,QAAQ,EAAE,MAAM,EAAE,CAAA;YAClB;;;;;;eAMG;YACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;SACrB,CAAA;KACF,CAAA;IACD,cAAc,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,GAAG,KAAK,CAAA;KAAE,CAAA;CAC3E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/utils/content-write-lock.d.ts

@@ -0,0 +1,127 @@
+/**
+ * [SYNC-C1] Cross-host mutual exclusion between the worker's rebase loop and
+ * content writes against the same branch working tree.
+ *
+ * Production runs a Lambda (API) and an EC2 worker over one EFS filesystem.
+ * `ContentStore`'s write/delete/rename critical sections were guarded only by
+ * the in-process mutex (`utils/async-mutex`), which does not cross that
+ * boundary, while `CmsWorker.rebaseActiveBranches()` rewrites the very same
+ * working tree. A write landing after `git rebase` started is destroyed two
+ * ways -- `git checkout --theirs <file>` overwrites it with the branch's
+ * committed version (and the rebase then SUCCEEDS, logging nothing), and
+ * `git rebase --abort` hard-resets the tree. Either way the editor already got
+ * its 200. This lock is what serializes the two.
+ *
+ * **Asymmetric by design.** The worker retries every branch on its next sync
+ * cycle (~5 minutes) while the editor is a person waiting on a save, so the
+ * worker yields and the writer waits:
+ *
+ * - Worker: {@link tryAcquireContentWriteLock} -- zero retries. On contention
+ *   it skips that branch this cycle (an extension of the existing
+ *   skip-dirty-branches behavior) and picks it up next cycle.
+ * - Writers: {@link withContentWriteLock} -- a short bounded wait, then a
+ *   retriable failure the API surfaces as a 409.
+ *
+ * **Reads never take this lock.** An extra EFS round-trip on every read is not
+ * an acceptable price, and a read racing a rebase gets a consistent-enough
+ * older or newer file, never a destroyed one.
+ *
+ * ## Why the lock is anchored on `{branchRoot}/.canopy-meta`
+ *
+ * proper-lockfile keys its module-level `locks{}` bookkeeping (refresh timer,
+ * release function) by the **target path** passed to `lock()`, NOT by
+ * `lockfilePath`. The provisioning lock targets `path.dirname(branchRoot)` --
+ * the shared content-branches directory -- so anchoring here on that same
+ * directory with a different lock NAME would land on the same registry key:
+ * one process holding both (a Lambda container provisioning a workspace and
+ * writing content) would have the second acquisition clobber the first's
+ * bookkeeping. Targeting `{branchRoot}/.canopy-meta` instead gives:
+ *
+ * - a distinct in-process registry key from the provisioning lock (and from
+ *   every other branch's content lock -- the provisioning locks already share
+ *   one key across branches);
+ * - a distinct on-disk lock directory, so the server-enforced mkdir cannot
+ *   collide either; and
+ * - no deadlock potential: the two locks are never both required, and the only
+ *   possible acquisition order (provision, then write) is consistent.
+ *
+ * `.canopy-meta/` is git-excluded in every branch clone (`ensureGitExclude`),
+ * so the lock directory can never dirty the working tree or be swept into
+ * `git add .` at publish time.
+ *
+ * ## Honest caveat (do not oversell this)
+ *
+ * `proper-lockfile` decides a holder is dead by reading the lock directory's
+ * mtime with `fs.stat`, which on EFS is served through the NFS attribute
+ * cache. A live holder refreshes every `stale/2`, but a waiter can read a
+ * cached mtime and conclude the lock is stale when it is not, taking it over.
+ * The failure mode of a bad takeover is exactly today's behavior (two
+ * unsynchronized writers), so this is a strict improvement -- not a proof of
+ * mutual exclusion. See docs/concurrency.md.
+ */
+/** On-disk name of the lock marker (a directory, created by mkdir). */
+export declare const CONTENT_WRITE_LOCK_NAME = "content-write.lock";
+/**
+ * Default bounded wait for a content write.
+ *
+ * Deliberately short. A rebase holds this lock for a fetch plus a replay plus
+ * N conflict rounds of git subprocesses on EFS -- far longer than any wait an
+ * interactive save can absorb, and longer than the API's own latency budget.
+ * So the wait is not sized to outlast a rebase (nothing reasonable could); it
+ * is sized to absorb lock handoff and the short holds of other writers, and to
+ * turn everything longer into a fast, explicit "retry" the editor can act on
+ * rather than a request that hangs toward the Lambda timeout. The worker
+ * revisits the branch next cycle, so the blocked state is transient.
+ *
+ * This is ALSO the writer-vs-writer budget, not only the rebase one. The lock
+ * is per-branch-root, so every write to one branch now serializes behind it
+ * where in-process serialization used to be per-entry -- bounded on Lambda
+ * (one invocation per container), but real under `next dev` and build-time
+ * provisioning across worker processes. The case to watch is a write whose
+ * in-lock path triggers a full `idIndex()` rescan of a large tree over EFS:
+ * that can plausibly exceed this budget and start 409ing unrelated saves.
+ * Making it configurable for prod tuning is tracked in
+ * .claude/future-tasks/content-write-lock-tuning-and-granularity.md.
+ */
+export declare const DEFAULT_CONTENT_WRITE_LOCK_WAIT_MS = 2000;
+/**
+ * Thrown when the bounded wait expires with the branch's content lock still
+ * held. Retriable -- callers translate this into a 409 with a message that
+ * says so.
+ *
+ * The message says "syncing OR another save" because BOTH produce it. The
+ * lock is taken by `write`/`delete`/`renameEntry` and by the admin
+ * repair-content-duplicates action as well as by the worker's rebase, so a
+ * message naming only the rebase was a confident claim about something that
+ * may not be happening. `api/content.ts` routes this error ahead of the
+ * generic conflict specifically so the editor sees this wording, which makes
+ * the wording load-bearing rather than cosmetic.
+ */
+export declare class ContentWriteLockBusyError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Acquire the branch's content-write lock WITHOUT waiting.
+ *
+ * Throws an error with `code === 'ELOCKED'` when a live holder has it. Used by
+ * the worker's rebase loop (which skips the branch and retries next cycle) and
+ * by tests standing in for a writer.
+ */
+export declare function tryAcquireContentWriteLock(branchRoot: string): Promise<() => Promise<void>>;
+/**
+ * Acquire the branch's content-write lock with a short bounded wait.
+ *
+ * Retries ONLY on genuine contention (`ELOCKED`), the same discipline
+ * `withOccFileLock` uses: proper-lockfile's own retry loop retries blindly on
+ * any error, which would burn the whole budget re-hitting e.g. ENOENT after
+ * the branch directory was deleted out from under the caller.
+ *
+ * @throws ContentWriteLockBusyError when the budget expires under contention.
+ */
+export declare function acquireContentWriteLock(branchRoot: string, waitMs?: number): Promise<() => Promise<void>>;
+/**
+ * Run `fn` holding the branch's content-write lock, releasing it in a
+ * `finally` so a throw can never strand it.
+ */
+export declare function withContentWriteLock<T>(branchRoot: string, fn: () => Promise<T>, waitMs?: number): Promise<T>;
+//# sourceMappingURL=content-write-lock.d.ts.map

package/dist/utils/content-write-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-write-lock.d.ts","sourceRoot":"","sources":["../../src/utils/content-write-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAUH,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,uBAAuB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kCAAkC,OAAO,CAAA;AAEtD;;;;;;;;;;;;GAYG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBAEhD,OAAO,SAAuI;CAKjJ;AAYD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAE3F;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAA2C,GAClD,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAe9B;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,GAAE,MAA2C,GAClD,OAAO,CAAC,CAAC,CAAC,CAOZ"}