@caretcms/caretize 0.1.0

package/dist/run.js

@@ -0,0 +1,213 @@
+/**
+ * Run orchestration. The atomicity model is "validate everything in memory,
+ * then write": every file's tagged output is computed and verified (re-parses +
+ * is pure-insertion-reversible) BEFORE a single byte hits disk. If any file
+ * fails verification, the run aborts having written nothing. During the write
+ * phase, backups are taken per file; if a write throws, everything written so
+ * far is restored from those backups.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseAstro } from "./parse.js";
+import { applyTags } from "./write.js";
+import { wrapConst } from "./wrap.js";
+import { wrapImport } from "./import-wrap.js";
+import { hoistPropLiterals, verifyHoistResult } from "./prop-hoist.js";
+import { writeBackup, restoreBackups } from "./backup.js";
+/** Apply the right editable() wrap for a target's origin. */
+function applyWrap(source, t) {
+    return t.origin === "import"
+        ? wrapImport(source, t.varName, t.key)
+        : wrapConst(source, t.varName, t.key);
+}
+/** Compute and verify a single file's tagged output. No disk access. */
+export async function prepareFile(relPath, source, items) {
+    const base = {
+        relPath, source, output: source, inserted: [], tagCount: 0, ok: true,
+    };
+    if (items.length === 0)
+        return base;
+    const { output, inserted, failures } = applyTags(source, items);
+    if (failures.length > 0) {
+        return { ...base, ok: false, reason: `could not place ${failures.length} tag(s)` };
+    }
+    // Gate 1: the result must still be valid Astro.
+    try {
+        await parseAstro(output);
+    }
+    catch (err) {
+        return { ...base, ok: false, reason: `output failed to re-parse: ${err.message}` };
+    }
+    // Gate 2: pure-insertion — stripping the inserted attrs restores the original.
+    let restored = output;
+    for (const attr of inserted) {
+        const idx = restored.indexOf(attr);
+        if (idx < 0)
+            return { ...base, ok: false, reason: "inserted attribute not found on verify" };
+        restored = restored.slice(0, idx) + restored.slice(idx + attr.length);
+    }
+    if (restored !== source) {
+        return { ...base, ok: false, reason: "output is not a pure insertion of the original" };
+    }
+    return { relPath, source, output, inserted, tagCount: items.length, ok: true };
+}
+/** True when every character of `needle` appears in `haystack` in order. */
+function isSubsequence(needle, haystack) {
+    let i = 0;
+    for (let j = 0; j < haystack.length && i < needle.length; j++) {
+        if (haystack[j] === needle[i])
+            i++;
+    }
+    return i === needle.length;
+}
+/**
+ * Compute and verify a single file's editable()-wrapped output (Tier-1). Same
+ * atomicity contract as prepareFile, so the result feeds commitRun unchanged.
+ *
+ * Gate 2 here is a SUBSEQUENCE check rather than strip-by-string: the inserted
+ * `await editable(…, ` / `)` spans contain characters (`)`, commas) that also
+ * occur elsewhere, so verifying "original is a subsequence of output" is the
+ * robust way to prove pure insertion (no original char deleted or reordered).
+ */
+export async function prepareWrapFile(relPath, source, targets) {
+    const base = {
+        relPath, source, output: source, inserted: [], tagCount: 0, ok: true,
+    };
+    if (targets.length === 0)
+        return base;
+    let output = source;
+    const inserted = [];
+    for (const t of targets) {
+        const result = applyWrap(output, t);
+        if (!result.ok)
+            return { ...base, ok: false, reason: `${t.varName}: ${result.reason}` };
+        if (result.alreadyWrapped)
+            continue;
+        inserted.push(`editable(${JSON.stringify(t.key)}) around ${t.varName}`);
+        output = result.output;
+    }
+    if (inserted.length === 0)
+        return base; // nothing applicable (already wrapped)
+    // Gate 1: the result must still be valid Astro.
+    try {
+        await parseAstro(output);
+    }
+    catch (err) {
+        return { ...base, ok: false, reason: `output failed to re-parse: ${err.message}` };
+    }
+    // Gate 2: pure insertion — every original character survives, in order.
+    if (!isSubsequence(source, output)) {
+        return { ...base, ok: false, reason: "output is not a pure insertion of the original" };
+    }
+    return { relPath, source, output, inserted, tagCount: inserted.length, ok: true };
+}
+/**
+ * Compute and verify a file's output with BOTH passes: attribute tags and
+ * editable() wraps. Tags are applied first (offset-based, in the template), then
+ * wraps (content-scan, in the frontmatter) — so the frontmatter insertions never
+ * shift the template tag offsets. Same atomicity gates; one PreparedFile out.
+ */
+export async function prepareFileFull(relPath, source, items, targets, hoistTargets = []) {
+    const base = {
+        relPath, source, output: source, inserted: [], tagCount: 0, ok: true,
+    };
+    if (items.length === 0 && targets.length === 0 && hoistTargets.length === 0)
+        return base;
+    let output = source;
+    const inserted = [];
+    // Pass 1: attribute tags (template).
+    if (items.length > 0) {
+        const tagged = applyTags(source, items);
+        if (tagged.failures.length > 0) {
+            return { ...base, ok: false, reason: `could not place ${tagged.failures.length} tag(s)` };
+        }
+        output = tagged.output;
+        inserted.push(...tagged.inserted);
+    }
+    // Pass 2: editable() wraps (frontmatter) — wrapConst for consts, wrapImport
+    // for default data imports. Both are pure insertion.
+    let wrapCount = 0;
+    for (const t of targets) {
+        const wrapped = applyWrap(output, t);
+        if (!wrapped.ok)
+            return { ...base, ok: false, reason: `${t.varName}: ${wrapped.reason}` };
+        if (wrapped.alreadyWrapped)
+            continue;
+        inserted.push(`editable(${JSON.stringify(t.key)}) around ${t.varName}`);
+        output = wrapped.output;
+        wrapCount++;
+    }
+    if (output === source && hoistTargets.length === 0)
+        return base; // nothing changed
+    // Passes 1+2 are pure insertion: verify the running output is a subsequence of
+    // the original BEFORE the (deletion-bearing) hoist pass runs.
+    const afterWraps = output;
+    if (!isSubsequence(source, afterWraps)) {
+        return { ...base, ok: false, reason: "output is not a pure insertion of the original" };
+    }
+    // Pass 3 (LAST): prop-hoist rewrite. Self-locating, so it runs after the
+    // offset-based tag pass. Verified by an inverse gate against `afterWraps`.
+    let hoistCount = 0;
+    if (hoistTargets.length > 0) {
+        const h = hoistPropLiterals(afterWraps, hoistTargets);
+        if (!h.ok)
+            return { ...base, ok: false, reason: `hoist: ${h.reason}` };
+        if (h.propsRewritten > 0) {
+            if (!verifyHoistResult(afterWraps, h.output, hoistTargets, h.addedImport)) {
+                return { ...base, ok: false, reason: "hoist not reversible to pre-hoist source" };
+            }
+            output = h.output;
+            hoistCount = h.propsRewritten;
+            inserted.push(...h.constsDeclared.map((c) => `editable() hoist → const ${c}`));
+        }
+    }
+    if (output === source)
+        return base; // nothing actually changed
+    // Gate 1: still valid Astro.
+    try {
+        await parseAstro(output);
+    }
+    catch (err) {
+        return { ...base, ok: false, reason: `output failed to re-parse: ${err.message}` };
+    }
+    return {
+        relPath, source, output, inserted,
+        tagCount: items.length + wrapCount + hoistCount, ok: true,
+    };
+}
+/**
+ * Write verified files to disk with backups. Throws (after rolling back) if any
+ * prepared file failed verification or any write fails.
+ */
+export function commitRun(rootDir, prepared, stamp) {
+    const toWrite = prepared.filter((p) => p.tagCount > 0);
+    const bad = toWrite.find((p) => !p.ok);
+    if (bad) {
+        throw new Error(`refusing to write: ${bad.relPath} failed verification (${bad.reason})`);
+    }
+    const written = [];
+    const backups = [];
+    const thisRun = [];
+    try {
+        for (const file of toWrite) {
+            const backupAbs = writeBackup(rootDir, file.relPath, stamp);
+            backups.push(backupAbs);
+            thisRun.push({ relPath: file.relPath, backupAbs });
+            writeFileSync(resolve(rootDir, file.relPath), file.output, "utf8");
+            written.push(file.relPath);
+        }
+    }
+    catch (err) {
+        // Roll back exactly the files THIS run backed up — never "the latest
+        // stamp", which could be a previous run's backups if we died before
+        // writing our first one.
+        restoreBackups(rootDir, thisRun);
+        throw new Error(`write failed, rolled back: ${err.message}`);
+    }
+    return { written, backups };
+}
+/** Convenience: read a file from disk for preparation. */
+export function readSource(rootDir, relPath) {
+    return readFileSync(resolve(rootDir, relPath), "utf8");
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,SAAS,EAAqB,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAmB,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAwB,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE1D,6DAA6D;AAC7D,SAAS,SAAS,CAAC,MAAc,EAAE,CAAa;IAC9C,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;QAC1B,CAAC,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC;QACtC,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;AAC1C,CAAC;AAYD,wEAAwE;AACxE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAe,EACf,MAAc,EACd,KAAqB;IAErB,MAAM,IAAI,GAAiB;QACzB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI;KACrE,CAAC;IACF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAChE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,QAAQ,CAAC,MAAM,SAAS,EAAE,CAAC;IACrF,CAAC;IAED,gDAAgD;IAChD,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA+B,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC;IAChG,CAAC;IAED,+EAA+E;IAC/E,IAAI,QAAQ,GAAG,MAAM,CAAC;IACtB,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wCAAwC,EAAE,CAAC;QAC7F,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gDAAgD,EAAE,CAAC;IAC1F,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACjF,CAAC;AAID,4EAA4E;AAC5E,SAAS,aAAa,CAAC,MAAc,EAAE,QAAgB;IACrD,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9D,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC;YAAE,CAAC,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC;AAC7B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAe,EACf,MAAc,EACd,OAAqB;IAErB,MAAM,IAAI,GAAiB;QACzB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI;KACrE,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,IAAI,MAAM,GAAG,MAAM,CAAC;IACpB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QACxF,IAAI,MAAM,CAAC,cAAc;YAAE,SAAS;QACpC,QAAQ,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IACzB,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,uCAAuC;IAE/E,gDAAgD;IAChD,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA+B,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC;IAChG,CAAC;IAED,wEAAwE;IACxE,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;QACnC,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gDAAgD,EAAE,CAAC;IAC1F,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACpF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAe,EACf,MAAc,EACd,KAAqB,EACrB,OAAqB,EACrB,eAAkC,EAAE;IAEpC,MAAM,IAAI,GAAiB;QACzB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI;KACrE,CAAC;IACF,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzF,IAAI,MAAM,GAAG,MAAM,CAAC;IACpB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,qCAAqC;IACrC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACxC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,MAAM,CAAC,QAAQ,CAAC,MAAM,SAAS,EAAE,CAAC;QAC5F,CAAC;QACD,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QACvB,QAAQ,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAED,4EAA4E;IAC5E,qDAAqD;IACrD,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC1F,IAAI,OAAO,CAAC,cAAc;YAAE,SAAS;QACrC,QAAQ,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACxE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QACxB,SAAS,EAAE,CAAC;IACd,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAC,kBAAkB;IAEnF,+EAA+E;IAC/E,8DAA8D;IAC9D,MAAM,UAAU,GAAG,MAAM,CAAC;IAC1B,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAAC;QACvC,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gDAAgD,EAAE,CAAC;IAC1F,CAAC;IAED,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,iBAAiB,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QACtD,IAAI,CAAC,CAAC,CAAC,EAAE;YAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACvE,IAAI,CAAC,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,iBAAiB,CAAC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC1E,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;YACpF,CAAC;YACD,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;YAClB,UAAU,GAAG,CAAC,CAAC,cAAc,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IAED,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC,CAAC,2BAA2B;IAE/D,6BAA6B;IAC7B,IAAI,CAAC;QACH,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,8BAA+B,GAAa,CAAC,OAAO,EAAE,EAAE,CAAC;IAChG,CAAC;IAED,OAAO;QACL,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ;QACjC,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,SAAS,GAAG,UAAU,EAAE,EAAE,EAAE,IAAI;KAC1D,CAAC;AACJ,CAAC;AAOD;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,OAAe,EACf,QAAwB,EACxB,KAAa;IAEb,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;IAEvD,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACvC,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAkD,EAAE,CAAC;IAClE,IAAI,CAAC;QACH,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YAC5D,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;YACnD,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACnE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,qEAAqE;QACrE,oEAAoE;QACpE,yBAAyB;QACzB,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,8BAA+B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,OAAe;IACzD,OAAO,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC"}

package/dist/splice.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The byte-correct splice core for caretize.
+ *
+ * Why this file exists at all: `@astrojs/compiler` reports node positions as
+ * **0-based UTF-8 byte offsets** (see `Point.offset` in its AST types), but
+ * JavaScript string indexing counts UTF-16 code units. The two diverge the
+ * moment a file contains a multibyte character (em-dash, curly quote,
+ * box-drawing glyph, emoji) before an element. Splicing at a byte offset into a
+ * JS string therefore lands in the wrong place and silently corrupts the tag.
+ *
+ * The rule, proven by spike against the example corpus: do ALL offset
+ * arithmetic and splicing on a UTF-8 `Buffer`, never on a string. Everything in
+ * this module takes and returns `Buffer`s for that reason.
+ *
+ * We use the compiler AST for DETECTION only. Writing is pure insertion of an
+ * attribute just before the `>` of an opening tag — never AST reprinting — so
+ * the user's formatting, comments, and whitespace are preserved byte-for-byte.
+ */
+export interface OpenTagEnd {
+    /** Byte offset at which to insert an attribute (just before `>` or `/>`). */
+    insertAt: number;
+    /** Byte offset of the closing `>` itself. */
+    gtOffset: number;
+    /** Whether the tag is self-closing (`<img ... />`). */
+    selfClosing: boolean;
+}
+/**
+ * Given the byte offset of an opening tag's `<`, find where its opening tag
+ * ends. Scans forward to the `>` that is not inside a quoted attribute value or
+ * a `{...}` expression (Astro attributes can hold JS expressions and template
+ * literals that legitimately contain `>`), so we don't stop early.
+ *
+ * Returns null if `startOffset` isn't a `<` or no closing `>` is found.
+ */
+export declare function findOpenTagEnd(buf: Buffer, startOffset: number): OpenTagEnd | null;
+/**
+ * Insert `attribute` (e.g. ` data-caret="pages::home::headline"`, including its
+ * leading space) at the given byte offset, returning a new buffer. Pure
+ * insertion: removing the inserted bytes yields the original exactly, which is
+ * the reversibility invariant the writer relies on for backups/undo.
+ */
+export declare function spliceAttribute(buf: Buffer, insertAt: number, attribute: string): Buffer;
+//# sourceMappingURL=splice.d.ts.map

package/dist/splice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splice.d.ts","sourceRoot":"","sources":["../src/splice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAaH,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GAClB,UAAU,GAAG,IAAI,CA0CnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,MAAM,CAOR"}

package/dist/splice.js

@@ -0,0 +1,90 @@
+/**
+ * The byte-correct splice core for caretize.
+ *
+ * Why this file exists at all: `@astrojs/compiler` reports node positions as
+ * **0-based UTF-8 byte offsets** (see `Point.offset` in its AST types), but
+ * JavaScript string indexing counts UTF-16 code units. The two diverge the
+ * moment a file contains a multibyte character (em-dash, curly quote,
+ * box-drawing glyph, emoji) before an element. Splicing at a byte offset into a
+ * JS string therefore lands in the wrong place and silently corrupts the tag.
+ *
+ * The rule, proven by spike against the example corpus: do ALL offset
+ * arithmetic and splicing on a UTF-8 `Buffer`, never on a string. Everything in
+ * this module takes and returns `Buffer`s for that reason.
+ *
+ * We use the compiler AST for DETECTION only. Writing is pure insertion of an
+ * attribute just before the `>` of an opening tag — never AST reprinting — so
+ * the user's formatting, comments, and whitespace are preserved byte-for-byte.
+ */
+// ASCII byte constants (all the structural characters we scan for are ASCII,
+// so single-byte comparisons on the UTF-8 buffer are safe).
+const LT = 0x3c; // <
+const GT = 0x3e; // >
+const SLASH = 0x2f; // /
+const LBRACE = 0x7b; // {
+const RBRACE = 0x7d; // }
+const DQUOTE = 0x22; // "
+const SQUOTE = 0x27; // '
+const BACKTICK = 0x60; // `
+/**
+ * Given the byte offset of an opening tag's `<`, find where its opening tag
+ * ends. Scans forward to the `>` that is not inside a quoted attribute value or
+ * a `{...}` expression (Astro attributes can hold JS expressions and template
+ * literals that legitimately contain `>`), so we don't stop early.
+ *
+ * Returns null if `startOffset` isn't a `<` or no closing `>` is found.
+ */
+export function findOpenTagEnd(buf, startOffset) {
+    let i = startOffset;
+    if (buf[i] !== LT)
+        return null;
+    i++;
+    let braceDepth = 0;
+    while (i < buf.length) {
+        const b = buf[i];
+        // Skip quoted attribute values (only when not inside an expression).
+        if (braceDepth === 0 && (b === DQUOTE || b === SQUOTE || b === BACKTICK)) {
+            const quote = b;
+            i++;
+            while (i < buf.length && buf[i] !== quote)
+                i++;
+            i++; // step past the closing quote
+            continue;
+        }
+        if (b === LBRACE) {
+            braceDepth++;
+            i++;
+            continue;
+        }
+        if (b === RBRACE) {
+            braceDepth = Math.max(0, braceDepth - 1);
+            i++;
+            continue;
+        }
+        if (braceDepth === 0 && b === GT) {
+            const selfClosing = buf[i - 1] === SLASH;
+            return {
+                insertAt: selfClosing ? i - 1 : i,
+                gtOffset: i,
+                selfClosing,
+            };
+        }
+        i++;
+    }
+    return null;
+}
+/**
+ * Insert `attribute` (e.g. ` data-caret="pages::home::headline"`, including its
+ * leading space) at the given byte offset, returning a new buffer. Pure
+ * insertion: removing the inserted bytes yields the original exactly, which is
+ * the reversibility invariant the writer relies on for backups/undo.
+ */
+export function spliceAttribute(buf, insertAt, attribute) {
+    const attrBuf = Buffer.from(attribute, "utf8");
+    return Buffer.concat([
+        buf.subarray(0, insertAt),
+        attrBuf,
+        buf.subarray(insertAt),
+    ]);
+}
+//# sourceMappingURL=splice.js.map

package/dist/splice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"splice.js","sourceRoot":"","sources":["../src/splice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,6EAA6E;AAC7E,4DAA4D;AAC5D,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI;AACrB,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI;AACrB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,IAAI;AACxB,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,IAAI;AACzB,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,IAAI;AACzB,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,IAAI;AACzB,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,IAAI;AACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,IAAI;AAW3B;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,WAAmB;IAEnB,IAAI,CAAC,GAAG,WAAW,CAAC;IACpB,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC/B,CAAC,EAAE,CAAC;IAEJ,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAEjB,qEAAqE;QACrE,IAAI,UAAU,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;YACzE,MAAM,KAAK,GAAG,CAAC,CAAC;YAChB,CAAC,EAAE,CAAC;YACJ,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK;gBAAE,CAAC,EAAE,CAAC;YAC/C,CAAC,EAAE,CAAC,CAAC,8BAA8B;YACnC,SAAS;QACX,CAAC;QAED,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC;YACjB,UAAU,EAAE,CAAC;YACb,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,MAAM,EAAE,CAAC;YACjB,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,CAAC,CAAC;YACzC,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QAED,IAAI,UAAU,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;YACjC,MAAM,WAAW,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC;YACzC,OAAO;gBACL,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;gBACjC,QAAQ,EAAE,CAAC;gBACX,WAAW;aACZ,CAAC;QACJ,CAAC;QAED,CAAC,EAAE,CAAC;IACN,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAW,EACX,QAAgB,EAChB,SAAiB;IAEjB,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC/C,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC;QACzB,OAAO;QACP,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;KACvB,CAAC,CAAC;AACL,CAAC"}

package/dist/usage.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Usage safety classifier — the single safety primitive both wrap tiers depend on.
+ *
+ * `editable()` stega-encodes EVERY string leaf of the value it wraps (see
+ * `@caretcms/core`'s encodeLeaves). An encoded string is invisible and harmless
+ * when it renders as visible TEXT, but it CORRUPTS anything it lands in as an
+ * attribute — a broken href/src/class/id/datetime. So a literal const is only
+ * safe to wrap when every field that flows out of it reaches the DOM as text and
+ * never as a native-element attribute.
+ *
+ * This module answers exactly that, from the `@astrojs/compiler` AST:
+ *   - native element (`type:"element"`) + a DYNAMIC attribute that references a
+ *     field of the value  →  UNSAFE.
+ *   - native element text position (`{item.title}`)                →  safe.
+ *   - component (`type:"component"`) attribute that references a field → a prop
+ *     hand-off; reported so a cross-file pass can verify the child (Tier-2),
+ *     and — depending on `componentHandoffUnsafe` — either tolerated (Tier-1,
+ *     preserving prior behavior) or treated as unprovable/UNSAFE (Tier-2 child).
+ *
+ * The bias is conservative throughout: anything we cannot positively prove is
+ * text-only is reported UNSAFE. False negatives (a safe const left unwrapped)
+ * are acceptable; a false positive (encoding into an attribute) is not. In line
+ * with that, the loop-variable scan over-approximates — within an expression
+ * that mentions the const, EVERY `.map()`/`.flatMap()` binding is treated as
+ * carrying a field of it, so nested and chained loops can never smuggle a field
+ * into an attribute unnoticed.
+ */
+import type { AstroNode } from "./parse.js";
+export interface Handoff {
+    /** Component the value (or a field of it) is passed to. */
+    component: string;
+    /** Prop name it is passed as. */
+    prop: string;
+}
+export interface UsageVerdict {
+    safe: boolean;
+    /** Populated when `safe` is false. */
+    reason?: string;
+    /** Component prop hand-offs of this const, for an optional cross-file check. */
+    handoffs: Handoff[];
+}
+export interface ClassifyOptions {
+    /**
+     * When true, a field flowing into a component prop counts as UNSAFE (we can't
+     * prove how the component renders it). Tier-2's child analysis sets this so a
+     * re-pass to a grandchild is conservatively skipped. Tier-1 leaves it false to
+     * preserve its established "component prop ≈ text" behavior.
+     */
+    componentHandoffUnsafe?: boolean;
+    /**
+     * When true, the `set:html` / `set:text` directives count as TEXT sinks, not
+     * native attributes. They render the value as element CONTENT, where stega
+     * survives harmlessly — so a field reaching them is safe to encode. Off by
+     * default (the wrap tiers stay conservative); the prop-hoist child check sets
+     * it so a `<p set:html={prop} />` rich field can be hoisted.
+     */
+    htmlDirectivesSafe?: boolean;
+}
+/**
+ * Loop-binding identifiers introduced by `.map()`/`.flatMap()` callbacks in a JS
+ * fragment. With `receiver`, only loops over that exact variable are read; with
+ * no receiver, EVERY map/flatMap is read (the conservative scan used during
+ * classification, so chained/nested loops can't hide a field).
+ */
+export declare function mapParamIdents(js: string, receiver?: string): string[];
+/**
+ * Classify how a literal const `varName` is consumed in a parsed template.
+ *
+ * For every tag node, the field-carrying identifiers in scope are `varName`
+ * itself plus the binding variables of any ancestor expression that mentions
+ * `varName` and loops. A dynamic attribute referencing one of those names is the
+ * encoded value escaping into a sink: a native element → UNSAFE; a component → a
+ * recorded prop hand-off (and UNSAFE too under `componentHandoffUnsafe`). Text
+ * positions (`{item.x}` as an element's child) are never attributes, so they
+ * never trip this — exactly the leaves `editable()` can safely encode.
+ */
+export declare function classifyConstUsage(root: AstroNode, varName: string, opts?: ClassifyOptions): UsageVerdict;
+/**
+ * Does the template render any of `names` in a BODY-reachable position — a text
+ * expression (`{title}`) or a `set:html`/`set:text` content sink — that is NOT
+ * inside the document `<head>`?
+ *
+ * `classifyConstUsage` proves a field never lands in a corrupting attribute, but
+ * a field that renders ONLY into `<head>` (a layout's `<title>{title}</title>`)
+ * is text-safe yet has no click-to-edit target. The prop-hoist tier requires a
+ * positive body sink so it doesn't mint `editable()` bindings the editor can't
+ * surface (and, incidentally, won't hoist a prop the child never renders at all).
+ */
+export declare function rendersOutsideHead(root: AstroNode, names: string[]): boolean;
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,YAAY,CAAC;AAGrD,MAAM,WAAW,OAAO;IACtB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AA8ED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAatE;AAgBD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,eAAoB,GACzB,YAAY,CAqCd;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CA4B5E"}