canopycms 0.0.67 → 0.0.68-int.101

package/dist/utils/yaml-source-splice.js

@@ -0,0 +1,515 @@
+/**
+ * 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 { isDeepStrictEqual } from 'node:util';
+import { Document, parseDocument, isAlias, isCollection, isMap, isNode, isPair, isScalar, isSeq, YAMLMap, visit, YAMLSeq, } from 'yaml';
+/** Successor markers: the end of a collection, and an item with no source counterpart. */
+const END = Symbol('end');
+const FRESH = Symbol('fresh');
+/** `yaml`'s default `lineWidth`, which `Document.toString()` folds at. */
+const LINE_WIDTH = 80;
+/** Narrowest fold width a deeply indented fragment is rendered at. */
+const MIN_LINE_WIDTH = 40;
+export function snapshotDocument(doc) {
+    const items = new Map();
+    const visitNode = (node) => {
+        if (isMap(node)) {
+            items.set(node, node.items.map((pair) => ({ item: pair, value: pair.value })));
+            for (const pair of node.items)
+                visitNode(pair.value);
+        }
+        else if (isSeq(node)) {
+            items.set(node, node.items.map((item) => ({ item, value: item })));
+            for (const item of node.items)
+                visitNode(item);
+        }
+    };
+    visitNode(doc.contents);
+    let anchored = false;
+    visit(doc, (_key, node) => {
+        if (isAlias(node) || (isNode(node) && node.anchor !== undefined)) {
+            anchored = true;
+            return visit.BREAK;
+        }
+        return undefined;
+    });
+    return { items, anchored };
+}
+class SourceSplicer {
+    constructor(raw, eol, doc, snapshot, replaced) {
+        this.raw = raw;
+        this.eol = eol;
+        this.doc = doc;
+        this.snapshot = snapshot;
+        this.replaced = replaced;
+        this.dirtyMemo = new Map();
+    }
+    print() {
+        const root = this.doc.contents;
+        if (!isCollection(root) || !this.snapshot.items.has(root))
+            return undefined;
+        if (!this.isDirty(root))
+            return this.raw;
+        if (this.snapshot.anchored)
+            return undefined;
+        const edits = this.collectionEdits(root);
+        return edits === undefined ? undefined : this.applyEdits(0, this.raw.length, edits);
+    }
+    /**
+     * Did the reconciler change anything under this node? An original scalar is never mutated in
+     * place (a changed value gets a fresh node), so only collections can be dirty.
+     */
+    isDirty(node) {
+        if (!isCollection(node))
+            return false;
+        const memo = this.dirtyMemo.get(node);
+        if (memo !== undefined)
+            return memo;
+        const snap = this.snapshot.items.get(node);
+        let dirty = snap === undefined || snap.length !== node.items.length;
+        for (let i = 0; !dirty && snap !== undefined && i < snap.length; i++) {
+            const now = node.items[i];
+            const before = snap[i];
+            if (now !== before.item)
+                dirty = true;
+            else if (isPair(now))
+                dirty = now.value !== before.value || this.isDirty(now.value);
+            else
+                dirty = this.isDirty(now);
+        }
+        this.dirtyMemo.set(node, dirty);
+        return dirty;
+    }
+    collectionEdits(node) {
+        if (node.flow)
+            return undefined;
+        const snap = this.snapshot.items.get(node);
+        // An emptied block collection has no block spelling (`key:` alone reads back as null).
+        if (snap === undefined || snap.length === 0 || node.items.length === 0)
+            return undefined;
+        const geometry = [];
+        for (const { item, value } of snap) {
+            const g = isPair(item) ? this.pairGeometry(item, value) : this.seqItemGeometry(item);
+            if (g === undefined)
+                return undefined;
+            geometry.push(g);
+        }
+        if (!this.isBlockLayout(geometry))
+            return undefined;
+        return isMap(node) ? this.mapEdits(node, snap, geometry) : this.seqEdits(node, snap, geometry);
+    }
+    mapEdits(map, snap, geometry) {
+        const col = this.column(geometry[0].content);
+        const original = new Set(snap.map((s) => s.item));
+        const kept = new Set(map.items);
+        const edits = [];
+        // Retained pairs must still be in source order, followed only by new pairs.
+        const retainedOrder = map.items.filter((pair) => original.has(pair));
+        const expectedOrder = snap.map((s) => s.item).filter((pair) => kept.has(pair));
+        if (retainedOrder.some((pair, i) => pair !== expectedOrder[i]))
+            return undefined;
+        const added = map.items.slice(retainedOrder.length);
+        if (added.some((pair) => original.has(pair)))
+            return undefined;
+        const layout = [...geometry];
+        for (let i = 0; i < snap.length; i++) {
+            const { item, value: before } = snap[i];
+            const g = layout[i];
+            if (!isPair(item))
+                return undefined;
+            if (!kept.has(item)) {
+                if (g.inline) {
+                    const next = this.promoteToInline(snap, layout, kept);
+                    if (next === undefined)
+                        return undefined;
+                    edits.push({ start: g.content, end: layout[next].content, text: '' });
+                    i = next - 1;
+                }
+                else {
+                    const start = i === 0 ? this.ownLeadingLines(map, item, g.lineStart) : this.chunkStart(layout, i);
+                    edits.push({ start, end: g.end, text: '' });
+                }
+                continue;
+            }
+            const now = item.value;
+            const clean = now === before && !this.isDirty(now);
+            const inner = clean
+                ? []
+                : now === before && isCollection(now)
+                    ? this.collectionEdits(now)
+                    : undefined;
+            if (inner !== undefined) {
+                const next = map.items[map.items.indexOf(item) + 1] ?? END;
+                if ((i + 1 < snap.length ? snap[i + 1].item : END) !== next) {
+                    edits.push(...uncovered(this.outdentedCommentEdits(g, col), inner));
+                }
+                edits.push(...inner);
+                continue;
+            }
+            // The key is never replaced, so the comment lines above it stay in the source.
+            const text = withoutLeadingComment(item.key, () => this.render(mapOf([item]), col, g.inline));
+            edits.push({ start: g.lineStart, end: g.end, text: this.matchFinalNewline(g.end, text) });
+        }
+        if (added.length > 0) {
+            const at = layout[layout.length - 1].end;
+            const text = this.render(mapOf(added), col, false);
+            edits.push({ start: at, end: at, text: this.raw[at - 1] === '\n' ? text : this.eol + text });
+        }
+        return edits;
+    }
+    seqEdits(seq, snap, geometry) {
+        if (geometry[0].inline)
+            return undefined;
+        const col = this.column(geometry[0].content);
+        const oldIndex = new Map(snap.map((s, i) => [s.item, i]));
+        const parts = [];
+        const sourceOf = (item) => oldIndex.has(item) ? item : isNode(item) ? this.replaced.get(item) : undefined;
+        for (const [k, item] of seq.items.entries()) {
+            const j = oldIndex.get(item);
+            let part;
+            if (j !== undefined) {
+                const start = this.chunkStart(geometry, j);
+                const inner = isCollection(item) && this.isDirty(item) ? this.collectionEdits(item) : [];
+                const next = k + 1 < seq.items.length ? sourceOf(seq.items[k + 1]) : END;
+                const moved = (j + 1 < snap.length ? snap[j + 1].item : END) !== (next ?? FRESH);
+                part =
+                    inner !== undefined
+                        ? this.applyEdits(start, geometry[j].end, [
+                            ...inner,
+                            ...(moved ? uncovered(this.outdentedCommentEdits(geometry[j], col), inner) : []),
+                        ])
+                        : this.raw.slice(start, geometry[j].lineStart) +
+                            withoutLeadingComment(item, () => this.render(seqOf(item), col, false));
+            }
+            else {
+                // A fresh node keeps the comment lines above its slot only if the reconciler carried
+                // them across; it does not off a replaced collection.
+                const old = isNode(item) ? this.replaced.get(item) : undefined;
+                const k = old === undefined ? undefined : oldIndex.get(old);
+                part =
+                    k !== undefined && sameLeadingComment(old, item)
+                        ? this.raw.slice(this.chunkStart(geometry, k), geometry[k].lineStart) +
+                            withoutLeadingComment(item, () => this.render(seqOf(item), col, false))
+                        : this.render(seqOf(item), col, false);
+            }
+            parts.push(part.endsWith('\n') ? part : part + this.eol);
+        }
+        const start = geometry[0].lineStart;
+        const end = geometry[geometry.length - 1].end;
+        return [{ start, end, text: this.matchFinalNewline(end, parts.join('')) }];
+    }
+    /** Rendered text always ends in a line break; drop it where the source it replaces had none. */
+    matchFinalNewline(end, text) {
+        return this.raw[end - 1] !== '\n' && text.endsWith(this.eol)
+            ? text.slice(0, -this.eol.length)
+            : text;
+    }
+    /**
+     * The first pair shares the parent's `- ` line and was dropped: move the first retained pair up
+     * onto that line, so the pairs before it go and the rest of the map stays as written. Returns
+     * that pair's index, or undefined when no pair is retained or comment lines above it would have
+     * to go with the lines being removed.
+     */
+    promoteToInline(snap, layout, kept) {
+        const next = snap.findIndex((s) => kept.has(s.item));
+        if (next <= 0)
+            return undefined;
+        if (this.raw.slice(this.chunkStart(layout, next), layout[next].lineStart).includes('#')) {
+            return undefined;
+        }
+        const g = layout[next];
+        layout[next] = { ...g, inline: true, lineStart: g.content };
+        return next;
+    }
+    /**
+     * Where a dropped FIRST pair's lines begin. The comment lines above a nested collection's first
+     * item are the collection's and stay, but above the root map's first key `yaml` gives them to
+     * the key, so the reconciler drops them with it and so must the splice.
+     */
+    ownLeadingLines(map, pair, start) {
+        const key = pair.key;
+        if (map !== this.doc.contents || !key.commentBefore || this.doc.commentBefore)
+            return start;
+        let at = start;
+        while (at > 0) {
+            const previous = this.lineStart(at - 1);
+            if (previous >= at)
+                break;
+            if (!/^[ \t]*(#.*)?\r?\n?$/.test(this.raw.slice(previous, at)))
+                break;
+            at = previous;
+        }
+        return at;
+    }
+    /**
+     * The run of comment lines that ends an item's region reads to a person as being about what
+     * comes next, but it is the item's: `yaml`'s parser (`pop()`) keeps a trailing run with the
+     * nested collection it ends when that collection is not at column 0 and any line of the run is
+     * at or right of its indent. While the neighbour below is unchanged that is harmless; once it
+     * changes, indent the run's shallower lines to its deepest comment, so they read as the item's
+     * and do not head content they were never about. Where that lands a line in a deeper scalar's comment or content
+     * instead, {@link printsAs} refuses the splice. A run at or left of the item's own column is a
+     * zero-indented list's tail, and is left alone.
+     */
+    outdentedCommentEdits(g, col) {
+        let run = [];
+        let at = this.raw.indexOf('\n', g.content) + 1;
+        while (at > 0 && at < g.end) {
+            const lineEnd = this.raw.indexOf('\n', at);
+            const line = this.raw.slice(at, lineEnd === -1 ? g.end : lineEnd);
+            const indent = line.length - line.trimStart().length;
+            if (line.trimStart().startsWith('#'))
+                run.push({ start: at, indent });
+            else if (line.trim() !== '')
+                run = [];
+            at = lineEnd === -1 ? g.end : lineEnd + 1;
+        }
+        const pin = Math.max(-1, ...run.map((line) => line.indent));
+        if (pin <= col)
+            return [];
+        return run
+            .filter((line) => line.indent < pin)
+            .map((line) => ({ start: line.start, end: line.start + line.indent, text: ' '.repeat(pin) }));
+    }
+    /** Where item `i`'s chunk begins: its own line for the first item, else the previous item's end. */
+    chunkStart(geometry, i) {
+        return i === 0 ? geometry[0].lineStart : geometry[i - 1].end;
+    }
+    /**
+     * Every item starts at the same column, in order, and only the first may share its line with
+     * the parent's `- ` (a compact `- key: value`). Anything else — an explicit `? key`, a
+     * multi-line key, a node property on its own line — is not a layout this splices.
+     */
+    isBlockLayout(geometry) {
+        const col = this.column(geometry[0].content);
+        let previousEnd = -1;
+        for (const [i, g] of geometry.entries()) {
+            if (this.column(g.content) !== col)
+                return false;
+            if (i > 0 && g.inline)
+                return false;
+            if (g.lineStart < previousEnd || g.end <= g.content)
+                return false;
+            previousEnd = g.end;
+        }
+        return true;
+    }
+    /** `value` is the pair's value as parsed: the reconciler may already have replaced it. */
+    pairGeometry(pair, value) {
+        const key = pair.key;
+        if (!isScalar(key) || key.range == null)
+            return undefined;
+        const content = key.range[0];
+        const range = isNode(value) && value.range != null ? value.range : key.range;
+        return this.geometry(content, range[1], range[2]);
+    }
+    seqItemGeometry(item) {
+        if (!isNode(item) || item.range == null)
+            return undefined;
+        let dash = item.range[0] - 1;
+        while (dash >= 0 && ' \t\r\n'.includes(this.raw[dash]))
+            dash--;
+        if (dash < 0 || this.raw[dash] !== '-')
+            return undefined;
+        return this.geometry(dash, item.range[1], item.range[2]);
+    }
+    /**
+     * Trailing blank lines are not the item's — `yaml` gives them to whatever follows — unless they
+     * are inside the value itself, as a keep-chomped (`|+`) block scalar's are. A node that ends in
+     * a comment can end inside the NEXT line's indentation; that line is not the item's either.
+     */
+    geometry(content, valueEnd, nodeEnd) {
+        const nodeEndLine = this.lineStart(nodeEnd);
+        if (nodeEndLine > content && /^[ \t]*$/.test(this.raw.slice(nodeEndLine, nodeEnd))) {
+            nodeEnd = nodeEndLine;
+            valueEnd = Math.min(valueEnd, nodeEnd);
+        }
+        let last = Math.max(content, nodeEnd - 1);
+        while (last > content && last >= valueEnd && ' \t\r\n'.includes(this.raw[last]))
+            last--;
+        const newline = this.raw.indexOf('\n', last);
+        const lineStart = this.lineStart(content);
+        const onOwnLine = /^ *$/.test(this.raw.slice(lineStart, content));
+        return {
+            content,
+            inline: !onOwnLine,
+            lineStart: onOwnLine ? lineStart : content,
+            end: newline === -1 ? this.raw.length : newline + 1,
+        };
+    }
+    lineStart(offset) {
+        // `lastIndexOf` clamps a negative index to 0, which would find a newline AT offset 0.
+        return offset <= 0 ? 0 : this.raw.lastIndexOf('\n', offset - 1) + 1;
+    }
+    column(offset) {
+        return offset - this.lineStart(offset);
+    }
+    applyEdits(start, end, edits) {
+        const sorted = [...edits].sort((a, b) => a.start - b.start || a.end - b.end);
+        let out = '';
+        let cursor = start;
+        for (const edit of sorted) {
+            if (edit.start < cursor || edit.end > end)
+                throw new Error('overlapping source edits');
+            out += this.raw.slice(cursor, edit.start) + edit.text;
+            cursor = edit.end;
+        }
+        return out + this.raw.slice(cursor, end);
+    }
+    /**
+     * Render `items` as a block collection whose items sit at column `col`. `inline` leaves the
+     * first line unindented, for a slot that continues the parent's `- ` line. The fold width is
+     * reduced by the indent so the lines come out as wide as `toString()` would make them there.
+     */
+    render(container, col, inline) {
+        const fragment = new Document();
+        fragment.schema = this.doc.schema;
+        fragment.contents = container;
+        // A comment parsed from a CRLF file keeps a `\r` on every line but its last; the line ending
+        // is this.eol's to write.
+        const text = fragment
+            .toString({ lineWidth: Math.max(MIN_LINE_WIDTH, LINE_WIDTH - col) })
+            .replace(/\r\n?/g, '\n');
+        const indent = ' '.repeat(col);
+        const lines = text.split('\n');
+        if (lines[lines.length - 1] === '')
+            lines.pop();
+        return lines
+            .map((line, i) => (line === '' || (i === 0 && inline) ? line : indent + line))
+            .map((line) => line + this.eol)
+            .join('');
+    }
+}
+/**
+ * The edits in `extra` that no edit in `edits` already rewrites. A run of comment lines inside
+ * a value that is being deleted or re-rendered goes, or is re-drawn, with that value.
+ */
+function uncovered(extra, edits) {
+    return extra.filter((e) => !edits.some((x) => x.end > x.start && x.start <= e.start && e.end <= x.end));
+}
+function mapOf(pairs) {
+    const map = new YAMLMap();
+    map.items = [...pairs];
+    return map;
+}
+function seqOf(item) {
+    const seq = new YAMLSeq();
+    seq.items = [item];
+    return seq;
+}
+function sameLeadingComment(a, b) {
+    if (!isNode(a) || !isNode(b))
+        return false;
+    const x = a;
+    const y = b;
+    return ((x.commentBefore ?? undefined) === (y.commentBefore ?? undefined) &&
+        !!x.spaceBefore === !!y.spaceBefore);
+}
+/** Run `fn` with `node`'s leading comment and blank line hidden, because the source keeps them. */
+function withoutLeadingComment(node, fn) {
+    if (!isNode(node))
+        return fn();
+    const target = node;
+    const { commentBefore, spaceBefore } = target;
+    target.commentBefore = undefined;
+    target.spaceBefore = false;
+    try {
+        return fn();
+    }
+    finally {
+        target.commentBefore = commentBefore;
+        target.spaceBefore = spaceBefore;
+    }
+}
+/**
+ * The line ending a splice must write, or undefined for a file mixing them (or using bare `\r`),
+ * which no single choice would reproduce.
+ */
+function lineEndingOf(raw) {
+    const crlf = (raw.match(/\r\n/g) ?? []).length;
+    const lf = (raw.match(/\n/g) ?? []).length;
+    const cr = (raw.match(/\r/g) ?? []).length;
+    if (crlf === 0)
+        return cr === 0 ? '\n' : undefined;
+    return crlf === lf && crlf === cr ? '\r\n' : undefined;
+}
+/**
+ * `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 function withSourceLineEndings(printed, raw) {
+    const text = printed.replace(/\r\n?/g, '\n');
+    return lineEndingOf(raw) === '\r\n' ? text.replace(/\n/g, '\r\n') : text;
+}
+/**
+ * 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 function spliceSource(raw, doc, snapshot, replaced, printed) {
+    const eol = lineEndingOf(raw);
+    if (eol === undefined)
+        return undefined;
+    const spliced = new SourceSplicer(raw, eol, doc, snapshot, replaced).print();
+    return spliced !== undefined && printsAs(spliced, doc, printed) ? spliced : undefined;
+}
+/**
+ * Does `candidate` read back as the text it replaces, `printed`, would? It must parse cleanly,
+ * hold the reconciled document's data, and print as `printed` re-parsed prints — the same keys
+ * in the same order, the same comments where `yaml` draws them, which is by the node it gives
+ * each to.
+ *
+ * Re-parsed, not `printed` itself: where `yaml` cannot write the reconciled document so that it
+ * reads back as itself — a comment following an outdented trailing comment is read as the
+ * previous item's, whoever it belonged to — the splice need only be no worse than `printed`.
+ * Wherever it can, the two are the same comparison.
+ *
+ * Blank lines and trailing whitespace are left out: they are formatting the splice copies from
+ * the source, and `yaml` prints them inconsistently (a blank line inside an indented block as the
+ * indent alone; a blank line before a list's first item doubled; a stray `\r` kept in some
+ * comments parsed from a CRLF file).
+ */
+function printsAs(candidate, reconciled, printed) {
+    if (candidate === printed)
+        return true;
+    const reparsed = parseDocument(candidate);
+    if (reparsed.errors.length > 0)
+        return false;
+    if (!isDeepStrictEqual(reparsed.toJS(), reconciled.toJS()))
+        return false;
+    return layoutFree(reparsed.toString()) === layoutFree(parseDocument(printed).toString());
+}
+function layoutFree(text) {
+    return text
+        .split('\n')
+        .map((line) => line.replace(/[ \t\r]+$/, ''))
+        .filter((line) => line !== '')
+        .join('\n');
+}

package/dist/validation/entry-validator.js

@@ -12,7 +12,7 @@
  * `ReferenceValidator` at the write boundary.
  */
 import { fieldTypes } from '../config/index.js';
-import { isValidCropRect } from '../assets/transform-directives.js';
+import { isValidCropRect, roundCropRect } from '../assets/transform-directives.js';
 import { BLOCK_STRUCTURAL_KEYS } from './block-structural-keys.js';
 import { resolveBlockItem, traverseFields } from './field-traversal.js';
 import { findBodyFieldName } from '../utils/body-field.js';
@@ -27,7 +27,10 @@ function isPlainRecord(value) {
 function isPositiveInt(value) {
     return typeof value === 'number' && Number.isInteger(value) && value > 0;
 }
-/** True when `value` is a well-formed `{ x, y, w, h }` normalized crop rect. */
+/**
+ * True when `value` is a well-formed `{ x, y, w, h }` normalized crop rect that is still valid
+ * after `roundCropRect`, the rounding its transform URL applies.
+ */
 function isValidImageCropValue(value) {
     if (!isPlainRecord(value))
         return false;
@@ -38,7 +41,10 @@ function isValidImageCropValue(value) {
         typeof h !== 'number') {
         return false;
     }
-    return isValidCropRect(x, y, w, h);
+    if (!isValidCropRect(x, y, w, h))
+        return false;
+    const rounded = roundCropRect({ x, y, w, h });
+    return isValidCropRect(rounded.x, rounded.y, rounded.w, rounded.h);
 }
 /**
  * Validate a structured `image` field value: `{ src, alt, width?, height?, crop? }`

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const CANOPYCMS_VERSION = "0.0.68-int.101";

package/dist/version.js

@@ -0,0 +1,3 @@
+// Generated by scripts/bump-version.mjs, its only writer. The package builds with plain
+// tsc (rootDir: src), so src/ cannot import ../package.json; version.test.ts keeps the two equal.
+export const CANOPYCMS_VERSION = '0.0.68-int.101';

package/dist/worker/canopy-state.d.ts

@@ -0,0 +1,45 @@
+import type { FileStatusResult, SimpleGit, StatusResult } from 'simple-git';
+/**
+ * How the sync loop treats canopycms's own state (`.canopy-meta/`) in a branch clone. It is
+ * never content, so untracked state never makes a clone "dirty" for sync, but git refuses some
+ * operations over it while the adopter's repo tracks it. Only the adopter can stop that; once
+ * they have, the base clone follows on its next fast-forward ({@link untrackInIndex}), and a
+ * branch clone with modified tracked state needs an operator.
+ */
+/** The fix an operator applies when an adopter repo tracks `.canopy-meta/`. */
+export declare const TRACKED_CANOPY_STATE_FIX = "run `git rm -r --cached .canopy-meta` in the site repo, add `.canopy-meta/` to its .gitignore, and commit";
+/** Paths listed in worker-status.json per category; the admin panel shows them in a tooltip. */
+export declare const MAX_REPORTED_PATHS = 10;
+export declare function isUntracked(file: FileStatusResult): boolean;
+/** Files under `.canopy-meta/` that the clone's index tracks. */
+export declare function listTrackedCanopyState(git: SimpleGit): Promise<string[]>;
+/**
+ * Discard local changes to the schema cache's retired in-tree copy, so a clone of a repo that
+ * committed it can sync again. Nothing reads or writes that path in a clone any more, so its
+ * content is dead; but while it differs from HEAD, `git rebase` refuses to start and a
+ * fast-forward that touches it (including the adopter's own commit untracking it) refuses too.
+ * An untracked copy blocks neither and a newly staged one has nothing in HEAD to restore, so
+ * both are left alone. Returns whether it restored anything; the caller re-reads status if so.
+ */
+export declare function restoreRetiredSchemaCache(git: SimpleGit, status: StatusResult): Promise<boolean>;
+/**
+ * The changed tracked `.canopy-meta/` files in `status`: what git refuses to rebase over, and
+ * what a fast-forward refuses to overwrite where it touches them.
+ */
+export declare function trackedCanopyStateChanges(status: StatusResult): string[];
+/**
+ * Split `paths` by whether the commit `tip` still tracks them. Those it no longer tracks, the
+ * adopter has untracked upstream, so a fast-forward onto `tip` would delete them from disk unless
+ * {@link untrackInIndex} takes them out of the index first.
+ */
+export declare function splitByUpstreamTracking(git: SimpleGit, paths: string[], tip: string): Promise<{
+    droppedUpstream: string[];
+    stillTracked: string[];
+}>;
+/**
+ * Remove `paths` from this clone's index, leaving them on disk as untracked, excluded state.
+ * Index-only, so a concurrent write to them (branch metadata, comments) is not lost. Only for a
+ * clone with no commits of its own: a rebase that replays a commit touching these paths writes
+ * that commit's bytes over them. Paths already out of the index are ignored.
+ */
+export declare function untrackInIndex(git: SimpleGit, paths: string[]): Promise<void>;

package/dist/worker/canopy-state.js

@@ -0,0 +1,75 @@
+import { SCHEMA_CACHE_FILE } from '../branch-schema-cache.js';
+import { CANOPY_META_DIR, isCanopyInternalPath } from '../utils/git.js';
+/**
+ * How the sync loop treats canopycms's own state (`.canopy-meta/`) in a branch clone. It is
+ * never content, so untracked state never makes a clone "dirty" for sync, but git refuses some
+ * operations over it while the adopter's repo tracks it. Only the adopter can stop that; once
+ * they have, the base clone follows on its next fast-forward ({@link untrackInIndex}), and a
+ * branch clone with modified tracked state needs an operator.
+ */
+/** The fix an operator applies when an adopter repo tracks `.canopy-meta/`. */
+export const TRACKED_CANOPY_STATE_FIX = 'run `git rm -r --cached .canopy-meta` in the site repo, add `.canopy-meta/` to its .gitignore, and commit';
+/** Paths listed in worker-status.json per category; the admin panel shows them in a tooltip. */
+export const MAX_REPORTED_PATHS = 10;
+/** The schema cache's location in a clone before it moved under `.git/` (branch-schema-cache.ts). */
+const RETIRED_SCHEMA_CACHE_PATH = `${CANOPY_META_DIR}/${SCHEMA_CACHE_FILE}`;
+export function isUntracked(file) {
+    return file.index === '?' && file.working_dir === '?';
+}
+/** NUL-separated git output, which is never quoted, unlike `core.quotePath` line output. */
+function splitNul(out) {
+    return out.split('\0').filter((entry) => entry.length > 0);
+}
+/** Files under `.canopy-meta/` that the clone's index tracks. */
+export async function listTrackedCanopyState(git) {
+    return splitNul(await git.raw(['ls-files', '-z', '--', CANOPY_META_DIR]));
+}
+/**
+ * Discard local changes to the schema cache's retired in-tree copy, so a clone of a repo that
+ * committed it can sync again. Nothing reads or writes that path in a clone any more, so its
+ * content is dead; but while it differs from HEAD, `git rebase` refuses to start and a
+ * fast-forward that touches it (including the adopter's own commit untracking it) refuses too.
+ * An untracked copy blocks neither and a newly staged one has nothing in HEAD to restore, so
+ * both are left alone. Returns whether it restored anything; the caller re-reads status if so.
+ */
+export async function restoreRetiredSchemaCache(git, status) {
+    const entry = status.files.find((f) => f.path === RETIRED_SCHEMA_CACHE_PATH);
+    if (!entry || entry.index === '?' || entry.index === 'A')
+        return false;
+    await git.raw(['checkout', 'HEAD', '--', RETIRED_SCHEMA_CACHE_PATH]);
+    return true;
+}
+/**
+ * The changed tracked `.canopy-meta/` files in `status`: what git refuses to rebase over, and
+ * what a fast-forward refuses to overwrite where it touches them.
+ */
+export function trackedCanopyStateChanges(status) {
+    return status.files
+        .filter((f) => isCanopyInternalPath(f.path) && !isUntracked(f))
+        .map((f) => f.path);
+}
+/**
+ * Split `paths` by whether the commit `tip` still tracks them. Those it no longer tracks, the
+ * adopter has untracked upstream, so a fast-forward onto `tip` would delete them from disk unless
+ * {@link untrackInIndex} takes them out of the index first.
+ */
+export async function splitByUpstreamTracking(git, paths, tip) {
+    if (paths.length === 0)
+        return { droppedUpstream: [], stillTracked: [] };
+    const tracked = new Set(splitNul(await git.raw(['ls-tree', '-r', '-z', '--name-only', tip, '--', CANOPY_META_DIR])));
+    return {
+        droppedUpstream: paths.filter((p) => !tracked.has(p)),
+        stillTracked: paths.filter((p) => tracked.has(p)),
+    };
+}
+/**
+ * Remove `paths` from this clone's index, leaving them on disk as untracked, excluded state.
+ * Index-only, so a concurrent write to them (branch metadata, comments) is not lost. Only for a
+ * clone with no commits of its own: a rebase that replays a commit touching these paths writes
+ * that commit's bytes over them. Paths already out of the index are ignored.
+ */
+export async function untrackInIndex(git, paths) {
+    if (paths.length === 0)
+        return;
+    await git.raw(['rm', '--cached', '--ignore-unmatch', '-q', '--', ...paths]);
+}