@caretcms/caretize 0.1.0

package/dist/usage.js

@@ -0,0 +1,249 @@
+/**
+ * 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 { walkTags, isTagNode } from "./parse.js";
+import { IDENT, identRefRe, referencesIdent } from "./identifiers.js";
+const HTML_DIRECTIVES = new Set(["set:html", "set:text"]);
+/** Concatenated raw JS text of an expression node's direct text children. */
+function exprJs(node) {
+    let s = "";
+    for (const child of node.children ?? []) {
+        if (child.type === "text")
+            s += child.value ?? "";
+    }
+    return s;
+}
+/** The first parameter of an arrow/function param list, respecting brackets. */
+function firstParam(paramSrc) {
+    let depth = 0;
+    let out = "";
+    for (const c of paramSrc) {
+        if (c === "{" || c === "[" || c === "(")
+            depth++;
+        else if (c === "}" || c === "]" || c === ")")
+            depth--;
+        else if (c === "," && depth === 0)
+            break;
+        out += c;
+    }
+    return out.trim();
+}
+/** Identifiers bound by a single callback parameter (plain or destructured). */
+function paramIdents(param) {
+    if (!param)
+        return [];
+    if (param.startsWith("{") || param.startsWith("[")) {
+        // Destructuring: collect every binding identifier. For `{ a: b }` the bound
+        // local is `b`; over-collecting (keeping `a` too) only makes us more
+        // conservative, which is safe. Rest elements (`...rest`) included likewise.
+        const out = [];
+        for (const tok of param.replace(/[[\]{}.]/g, " ").split(/[,\s:=]+/)) {
+            const t = tok.trim();
+            if (IDENT.test(t))
+                out.push(t);
+        }
+        return out;
+    }
+    // Plain param, possibly with a default (`item = {}`): keep the binding name.
+    const name = param.split("=")[0].trim();
+    return IDENT.test(name) ? [name] : [];
+}
+/** Read the callback's first-parameter source starting just after `map(`. */
+function readCallbackFirstParam(js, from) {
+    let i = from;
+    const skipWs = () => {
+        while (i < js.length && /\s/.test(js[i]))
+            i++;
+    };
+    skipWs();
+    if (js.startsWith("async", i) && /[\s(]/.test(js[i + 5] ?? ""))
+        i += 5; // async arrow
+    skipWs();
+    if (js.startsWith("function", i)) {
+        const paren = js.indexOf("(", i);
+        if (paren < 0)
+            return "";
+        i = paren;
+    }
+    if (js[i] === "(") {
+        let depth = 0;
+        let src = "";
+        for (; i < js.length; i++) {
+            const c = js[i];
+            if (c === "(")
+                depth++;
+            else if (c === ")") {
+                depth--;
+                if (depth === 0)
+                    break;
+            }
+            else if (depth >= 1)
+                src += c;
+        }
+        return firstParam(src);
+    }
+    // Parenless arrow: `x => …` — read up to `=>`, `,` or `)`.
+    let src = "";
+    while (i < js.length && !/[=,)\s]/.test(js[i]))
+        src += js[i++];
+    return src;
+}
+/**
+ * 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 function mapParamIdents(js, receiver) {
+    const idents = new Set();
+    const head = receiver
+        ? `${identRefRe(receiver).source}\\s*\\.\\s*(?:map|flatMap)\\s*\\(`
+        : `\\.\\s*(?:map|flatMap)\\s*\\(`;
+    const re = new RegExp(head, "g");
+    let m;
+    while ((m = re.exec(js))) {
+        for (const id of paramIdents(readCallbackFirstParam(js, m.index + m[0].length))) {
+            idents.add(id);
+        }
+    }
+    return [...idents];
+}
+/** Attribute kinds that can carry a JS reference (static `quoted`/`empty` cannot). */
+function attrIsDynamic(kind) {
+    return kind === "expression" || kind === "template-literal" || kind === "shorthand" || kind === "spread";
+}
+/** Does this attribute reference any of `names` (its value, raw, or shorthand/spread name)? */
+function attrReferences(attr, names) {
+    if (attr.kind === "shorthand" || attr.kind === "spread") {
+        // `{name}` / `{...name}` — the identifier is the attribute name.
+        return names.includes(attr.name) || referencesIdent(attr.name, names);
+    }
+    return referencesIdent(`${attr.value} ${attr.raw ?? ""}`, names);
+}
+/**
+ * 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 function classifyConstUsage(root, varName, opts = {}) {
+    const handoffs = [];
+    let unsafe;
+    const varRe = identRefRe(varName);
+    walkTags(root, (node, ancestors) => {
+        const names = [varName];
+        for (const anc of ancestors) {
+            if (anc.type !== "expression")
+                continue;
+            const js = exprJs(anc);
+            if (varRe.test(js))
+                names.push(...mapParamIdents(js));
+        }
+        for (const attr of node.attributes) {
+            if (!attrIsDynamic(attr.kind))
+                continue; // static `quoted`/`empty` are inert
+            if (!attrReferences(attr, names))
+                continue;
+            if (node.type === "element") {
+                // set:html / set:text render the value as CONTENT, not a real attribute;
+                // stega survives there, so (when opted in) it's a safe text sink.
+                if (opts.htmlDirectivesSafe && HTML_DIRECTIVES.has(attr.name))
+                    continue;
+                // Encoded field would land in a real DOM attribute → corrupting.
+                unsafe ??= `field of "${varName}" used in <${node.name}> attribute "${attr.name}"`;
+            }
+            else if (node.type === "component") {
+                handoffs.push({ component: node.name, prop: attr.name });
+                if (opts.componentHandoffUnsafe) {
+                    unsafe ??= `field of "${varName}" handed to <${node.name}> prop "${attr.name}" (child not verified)`;
+                }
+            }
+            else {
+                // custom-element / fragment — unknown rendering; be conservative.
+                unsafe ??= `field of "${varName}" used on <${node.name}> (unverifiable)`;
+            }
+        }
+    });
+    if (unsafe)
+        return { safe: false, reason: unsafe, handoffs };
+    return { safe: true, handoffs };
+}
+/** Elements that live in (or feed) the document `<head>`. A field rendered only
+ *  here is text-safe for stega, but the inline editor's click-to-edit can never
+ *  surface it — so it isn't a real editable sink. */
+const HEAD_ELEMENTS = new Set(["head", "title", "meta", "base", "link"]);
+function inHead(ancestors, node) {
+    if (node && isTagNode(node) && HEAD_ELEMENTS.has(node.name))
+        return true;
+    return ancestors.some((a) => isTagNode(a) && HEAD_ELEMENTS.has(a.name));
+}
+/**
+ * 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 function rendersOutsideHead(root, names) {
+    let found = false;
+    const stack = [];
+    const visit = (node) => {
+        if (found || !node || typeof node !== "object")
+            return;
+        if (node.type === "expression" && referencesIdent(exprJs(node), names) && !inHead(stack)) {
+            found = true;
+            return;
+        }
+        if (isTagNode(node) && !inHead(stack, node)) {
+            for (const attr of node.attributes) {
+                if (HTML_DIRECTIVES.has(attr.name) && attrReferences(attr, names)) {
+                    found = true;
+                    return;
+                }
+            }
+        }
+        const children = node.children;
+        if (Array.isArray(children)) {
+            stack.push(node);
+            for (const child of children)
+                visit(child);
+            stack.pop();
+        }
+    };
+    visit(root);
+    return found;
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

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

package/dist/wrap.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Tier-1 editable() wrapping — PURE INSERTION.
+ *
+ * Wraps a frontmatter `const`/`let`/`var` initializer with
+ * `await editable('key', …)` and inserts the import, WITHOUT moving any code:
+ * the original initializer is preserved verbatim between two inserted spans, so
+ * the transform is provably reversible (strip the inserted text → original
+ * restored) — the same safety contract as caretize's attribute insertion.
+ *
+ *   const services = ['a', 'b'];
+ *     →  const services = await editable("pages::home::services", ['a', 'b']);
+ *   (+ `import { editable } from '@caretcms/core';` at the top of frontmatter)
+ *
+ * Restructuring cases (an inline array literal inside JSX that must be hoisted
+ * to frontmatter) are intentionally NOT handled here — that breaks pure
+ * insertion and belongs to a separate, opt-in migrator.
+ */
+import { type AstroNode } from "./parse.js";
+/** The `editable()` import line + a detector for it, shared with import-wrap.ts. */
+export declare const IMPORT_LINE = "import { editable } from '@caretcms/core';";
+export declare const IMPORT_RE: RegExp;
+/** A literal const the wrapper could target, before its provenance is known. */
+export interface WrapCandidate {
+    /** Frontmatter const/let/var to wrap. */
+    varName: string;
+    /** Binding key, e.g. `pages::home::services`. */
+    key: string;
+}
+/**
+ * How a wrap target was found:
+ *  - `loop`   — a same-file literal const iterated in the template (Tier-1)
+ *  - `prop`   — a literal const passed to a component that renders it as text (Tier-2)
+ *  - `import` — a default JSON/module import iterated in the template (Tier-3)
+ */
+export type WrapOrigin = "loop" | "prop" | "import";
+/** A safety-verified wrap target, tagged with how it was found. */
+export interface WrapTarget extends WrapCandidate {
+    origin: WrapOrigin;
+}
+export interface WrapResult {
+    output: string;
+    ok: boolean;
+    /** Reason when ok === false. */
+    reason?: string;
+    /** True when the source already had the wrap (no-op, idempotent). */
+    alreadyWrapped?: boolean;
+}
+/**
+ * Wrap the initializer of `const <varName> = …` in the frontmatter with
+ * `await editable('<key>', …)` and ensure the import is present. Pure insertion.
+ */
+export declare function wrapConst(source: string, varName: string, key: string): WrapResult;
+/**
+ * Detect Tier-1 wrap targets: frontmatter consts initialized to an array/object
+ * LITERAL that are `.map()`/`.flatMap()`'d in the template. Only literal-inited
+ * consts qualify — loops over fetched data (getCollection/await) or imports
+ * aren't inline content and are left alone. The key is derived from the file's
+ * scope (`collection::id`) plus the variable name as the field.
+ */
+export declare function detectWrapTargets(source: string, relPath: string): WrapCandidate[];
+/**
+ * Safety-checked Tier-1 detection: the literal-const candidates from
+ * `detectWrapTargets`, minus any whose mapped fields flow into a native-element
+ * attribute (where `editable()`'s stega encoding would corrupt an href/src/class
+ * /…). Component prop hand-offs are tolerated here — Tier-1's long-standing
+ * behavior — and verified across files by the Tier-2 prop pass instead.
+ *
+ * Async because the safety check needs the parsed AST; `root` may be passed when
+ * the caller has already parsed `source` (the CLI does, to avoid re-parsing).
+ */
+export declare function detectWrapTargetsSafe(source: string, relPath: string, root?: AstroNode): Promise<WrapTarget[]>;
+//# sourceMappingURL=wrap.d.ts.map

package/dist/wrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../src/wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAKxD,oFAAoF;AACpF,eAAO,MAAM,WAAW,+CAA+C,CAAC;AACxE,eAAO,MAAM,SAAS,QACkD,CAAC;AAEzE,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpD,mEAAmE;AACnE,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAmCD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAiDlF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CA+BlF;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,SAAS,GACf,OAAO,CAAC,UAAU,EAAE,CAAC,CAOvB"}

package/dist/wrap.js

@@ -0,0 +1,170 @@
+/**
+ * Tier-1 editable() wrapping — PURE INSERTION.
+ *
+ * Wraps a frontmatter `const`/`let`/`var` initializer with
+ * `await editable('key', …)` and inserts the import, WITHOUT moving any code:
+ * the original initializer is preserved verbatim between two inserted spans, so
+ * the transform is provably reversible (strip the inserted text → original
+ * restored) — the same safety contract as caretize's attribute insertion.
+ *
+ *   const services = ['a', 'b'];
+ *     →  const services = await editable("pages::home::services", ['a', 'b']);
+ *   (+ `import { editable } from '@caretcms/core';` at the top of frontmatter)
+ *
+ * Restructuring cases (an inline array literal inside JSX that must be hoisted
+ * to frontmatter) are intentionally NOT handled here — that breaks pure
+ * insertion and belongs to a separate, opt-in migrator.
+ */
+import { deriveScope, isValidField, slugifyText } from "./name.js";
+import { parseAstro } from "./parse.js";
+import { classifyConstUsage } from "./usage.js";
+import { frontmatterRange, literalConstNames } from "./frontmatter.js";
+import { isIdentifier } from "./identifiers.js";
+/** The `editable()` import line + a detector for it, shared with import-wrap.ts. */
+export const IMPORT_LINE = `import { editable } from '@caretcms/core';`;
+export const IMPORT_RE = /import\s*\{[^}]*\beditable\b[^}]*\}\s*from\s*['"]@caretcms\/core['"]/;
+/**
+ * Given the offset of `=`, return the offset just past the initializer
+ * expression by balancing brackets and skipping strings. Stops at a `;` or
+ * newline encountered at bracket-depth 0.
+ */
+function initializerEnd(source, eq, limit) {
+    let i = eq + 1;
+    while (i < limit && /\s/.test(source[i]))
+        i++;
+    if (i >= limit)
+        return null;
+    let depth = 0;
+    let quote = null;
+    for (; i < limit; i++) {
+        const c = source[i];
+        if (quote) {
+            if (c === "\\") {
+                i++;
+                continue;
+            }
+            if (c === quote)
+                quote = null;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === "`") {
+            quote = c;
+            continue;
+        }
+        if (c === "[" || c === "(" || c === "{")
+            depth++;
+        else if (c === "]" || c === ")" || c === "}")
+            depth--;
+        else if (depth === 0 && (c === ";" || c === "\n"))
+            return i;
+    }
+    return depth === 0 ? limit : null;
+}
+/**
+ * Wrap the initializer of `const <varName> = …` in the frontmatter with
+ * `await editable('<key>', …)` and ensure the import is present. Pure insertion.
+ */
+export function wrapConst(source, varName, key) {
+    if (!isIdentifier(varName)) {
+        return { output: source, ok: false, reason: `invalid identifier: ${varName}` };
+    }
+    const fm = frontmatterRange(source);
+    if (!fm)
+        return { output: source, ok: false, reason: "no frontmatter block" };
+    const fmText = source.slice(fm.start, fm.end);
+    const declRe = new RegExp(`\\b(?:const|let|var)\\s+${varName}\\b`);
+    const m = declRe.exec(fmText);
+    if (!m) {
+        return { output: source, ok: false, reason: `declaration of ${varName} not found in frontmatter` };
+    }
+    const eqRel = fmText.indexOf("=", m.index + m[0].length);
+    if (eqRel < 0)
+        return { output: source, ok: false, reason: "no initializer" };
+    const eqAbs = fm.start + eqRel;
+    // Idempotent: bail if already wrapped.
+    if (/^\s*await\s+editable\s*\(/.test(source.slice(eqAbs + 1, eqAbs + 48))) {
+        return { output: source, ok: true, alreadyWrapped: true };
+    }
+    let initStart = eqAbs + 1;
+    while (initStart < fm.end && /\s/.test(source[initStart]))
+        initStart++;
+    const initEnd = initializerEnd(source, eqAbs, fm.end);
+    if (initEnd === null || initStart >= fm.end) {
+        return { output: source, ok: false, reason: "could not bound initializer" };
+    }
+    const prefix = `await editable(${JSON.stringify(key)}, `;
+    const suffix = `)`;
+    // Pure insertion: keep every original character, add prefix/suffix around the
+    // untouched initializer.
+    let output = source.slice(0, initStart) +
+        prefix +
+        source.slice(initStart, initEnd) +
+        suffix +
+        source.slice(initEnd);
+    // Add the import at the top of the frontmatter unless it's already there.
+    if (!IMPORT_RE.test(source)) {
+        output = output.slice(0, fm.start) + IMPORT_LINE + "\n" + output.slice(fm.start);
+    }
+    return { output, ok: true };
+}
+/**
+ * Detect Tier-1 wrap targets: frontmatter consts initialized to an array/object
+ * LITERAL that are `.map()`/`.flatMap()`'d in the template. Only literal-inited
+ * consts qualify — loops over fetched data (getCollection/await) or imports
+ * aren't inline content and are left alone. The key is derived from the file's
+ * scope (`collection::id`) plus the variable name as the field.
+ */
+export function detectWrapTargets(source, relPath) {
+    const fm = frontmatterRange(source);
+    if (!fm)
+        return [];
+    const fmText = source.slice(fm.start, fm.end);
+    const template = source.slice(fm.end);
+    // 1. frontmatter consts whose initializer is an array/object literal
+    const literalConsts = literalConstNames(fmText);
+    if (literalConsts.size === 0)
+        return [];
+    // 2. of those, the ones actually iterated in the template
+    const mapped = new Set();
+    const mapRe = /\b([A-Za-z_$][\w$]*)\s*\.\s*(?:map|flatMap)\b/g;
+    let mm;
+    while ((mm = mapRe.exec(template))) {
+        if (literalConsts.has(mm[1]))
+            mapped.add(mm[1]);
+    }
+    if (mapped.size === 0)
+        return [];
+    // 3. derive the scope + a key per target
+    const scoped = deriveScope(relPath);
+    if ("skip" in scoped)
+        return [];
+    const { collection, id } = scoped.scope;
+    const candidates = [];
+    for (const varName of mapped) {
+        const field = isValidField(varName) ? varName : slugifyText(varName);
+        if (!field)
+            continue;
+        candidates.push({ varName, key: `${collection}::${id}::${field}` });
+    }
+    return candidates;
+}
+/**
+ * Safety-checked Tier-1 detection: the literal-const candidates from
+ * `detectWrapTargets`, minus any whose mapped fields flow into a native-element
+ * attribute (where `editable()`'s stega encoding would corrupt an href/src/class
+ * /…). Component prop hand-offs are tolerated here — Tier-1's long-standing
+ * behavior — and verified across files by the Tier-2 prop pass instead.
+ *
+ * Async because the safety check needs the parsed AST; `root` may be passed when
+ * the caller has already parsed `source` (the CLI does, to avoid re-parsing).
+ */
+export async function detectWrapTargetsSafe(source, relPath, root) {
+    const candidates = detectWrapTargets(source, relPath);
+    if (candidates.length === 0)
+        return [];
+    const ast = root ?? (await parseAstro(source));
+    return candidates
+        .filter((t) => classifyConstUsage(ast, t.varName).safe)
+        .map((t) => ({ ...t, origin: "loop" }));
+}
+//# sourceMappingURL=wrap.js.map

package/dist/wrap.js.map

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

package/dist/write.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The multi-tag writer primitive: splice many `data-caret` attributes into one
+ * source. Works on a UTF-8 Buffer (byte offsets) and applies insertions
+ * right-to-left so each splice leaves the not-yet-applied (smaller) offsets
+ * valid. Pure insertion only — never reformats.
+ *
+ * This is the in-memory core; the CLI layer wraps it with backups + atomic
+ * file writes + a re-parse verification gate.
+ */
+export interface TagInsertion {
+    /** Byte offset of the target element's opening `<`. */
+    startOffset: number;
+    /** Attribute text WITHOUT a leading space, e.g. `data-caret="a::b::c"`. */
+    attribute: string;
+}
+export interface ApplyResult {
+    output: string;
+    /** The exact strings inserted (each with its leading space), in source
+     *  order — useful for reversibility checks. */
+    inserted: string[];
+    /** Insertions that could not be placed (their opening tag end wasn't found). */
+    failures: Array<{
+        startOffset: number;
+        reason: string;
+    }>;
+}
+export declare function applyTags(source: string, items: TagInsertion[]): ApplyResult;
+//# sourceMappingURL=write.d.ts.map

package/dist/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf;mDAC+C;IAC/C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gFAAgF;IAChF,QAAQ,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,WAAW,CA8B5E"}

package/dist/write.js

@@ -0,0 +1,37 @@
+/**
+ * The multi-tag writer primitive: splice many `data-caret` attributes into one
+ * source. Works on a UTF-8 Buffer (byte offsets) and applies insertions
+ * right-to-left so each splice leaves the not-yet-applied (smaller) offsets
+ * valid. Pure insertion only — never reformats.
+ *
+ * This is the in-memory core; the CLI layer wraps it with backups + atomic
+ * file writes + a re-parse verification gate.
+ */
+import { findOpenTagEnd } from "./splice.js";
+export function applyTags(source, items) {
+    const buf = Buffer.from(source, "utf8");
+    const resolved = [];
+    const failures = [];
+    for (const item of items) {
+        const found = findOpenTagEnd(buf, item.startOffset);
+        if (!found) {
+            failures.push({ startOffset: item.startOffset, reason: "open tag end not found" });
+            continue;
+        }
+        resolved.push({ insertAt: found.insertAt, text: ` ${item.attribute}` });
+    }
+    // Apply largest-offset-first so earlier splices don't shift later targets.
+    resolved.sort((a, b) => b.insertAt - a.insertAt);
+    let out = buf;
+    for (const r of resolved) {
+        out = Buffer.concat([
+            out.subarray(0, r.insertAt),
+            Buffer.from(r.text, "utf8"),
+            out.subarray(r.insertAt),
+        ]);
+    }
+    // Report inserted strings in source order (resolved is currently desc).
+    const inserted = [...resolved].sort((a, b) => a.insertAt - b.insertAt).map((r) => r.text);
+    return { output: out.toString("utf8"), inserted, failures };
+}
+//# sourceMappingURL=write.js.map

package/dist/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAkB7C,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,KAAqB;IAC7D,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC,MAAM,QAAQ,GAA8C,EAAE,CAAC;IAC/D,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC,CAAC;YACnF,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAEjD,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC;YAClB,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC;YAC3B,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;SACzB,CAAC,CAAC;IACL,CAAC;IAED,wEAAwE;IACxE,MAAM,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAE1F,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAC9D,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@caretcms/caretize",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CLI that scans an Astro project and interactively adds data-caret attributes, turning a static site into a CaretCMS-editable one.",
+  "license": "MIT",
+  "keywords": [
+    "astro",
+    "cms",
+    "caret",
+    "codemod",
+    "cli",
+    "data-caret",
+    "inline-editing"
+  ],
+  "homepage": "https://github.com/web-stacked/caretcms/tree/main/packages/caretize#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/web-stacked/caretcms.git",
+    "directory": "packages/caretize"
+  },
+  "bugs": {
+    "url": "https://github.com/web-stacked/caretcms/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "caretize": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@astrojs/compiler": "2.13.1"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "typescript": "6.0.3"
+  }
+}