@bettercms-ai/convert 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -56,6 +56,11 @@ interface BriefPage {
 /** Only what the codemod reads. A backend `ConversionBrief` satisfies it. */
 interface Brief {
     pages: BriefPage[];
+    /**
+     * The project's forms, for the `--forms` lane. OPTIONAL: a brief issued before that lane
+     * existed carries none, and a run over one simply has no form to wire. @see BriefForm
+     */
+    forms?: BriefForm[];
 }
 /**
  * The name of one brief — `(route, path, kind, original)` for every page, hashed.
@@ -72,6 +77,29 @@ interface Brief {
  * coverage meter read zero forever. `brief-digest.test.ts` pins both against one literal hash.
  */
 declare function briefDigest(brief: Brief): string;
+/**
+ * One CMS form, as the brief lists it — the half the codemod cannot derive from the repository.
+ *
+ * The `<form>` in the source and the row in the Forms tab are two halves of one thing, and only
+ * the platform knows the id that joins them. `submitUrl` is the absolute endpoint a browser posts
+ * to (`packages/sdk/src/forms.ts`), so a wired form needs no helper, no import and no snapshot:
+ * it posts to a URL. `status` is carried because a DRAFT form 403s that endpoint — wiring one is
+ * correct and incomplete, and the receipt says so rather than leaving a live form that silently
+ * rejects every visitor.
+ */
+interface BriefForm {
+    id: string;
+    name: string;
+    status: "draft" | "published";
+    /** `/api/v1/forms/public/<id>/submissions`, absolute or origin-relative as the brief states it. */
+    submitUrl: string;
+    successMessage?: string;
+    /** The control this form expects, by `name`. `type` is informative; the key is the match. */
+    fields: {
+        key: string;
+        type: string;
+    }[];
+}
 
 /**
  * Where in the source does each of the brief's paths actually appear?
@@ -255,7 +283,59 @@ interface ConversionReceipt {
         lane: "bridge" | "pending";
         files?: string[];
     };
+    /**
+     * What `--forms` wired, and what it could not. OPTIONAL, and ADDITIVE ON PURPOSE: the server's
+     * `receiptInvariantHolds` reads `paths` only, so a receipt carrying this is accepted verbatim by
+     * a server that has never heard of the lane. @see FormsReceipt
+     */
+    forms?: FormsReceipt;
+}
+/**
+ * Why one CMS form could not be wired to a `<form>` in the repository.
+ *
+ * `FORM_NOT_IN_SOURCE`      no `<form>` in any file this run read holds any of its fields.
+ * `FORM_AMBIGUOUS`          two `<form>`s hold its fields, or two CMS forms want the same one.
+ * `FIELD_UNMATCHED`         a `<form>` is plainly the one, but a field's key names no control in it.
+ * `ACTION_IS_EXPRESSION`    the `<form>`'s `action` is code; replacing it would rewrite a program.
+ * `DIALECT_UNSUPPORTED`     the `<form>` is in a svelte/vue file, which this lane does not write.
+ * `PARSE_ERROR`             the file holding it did not parse.
+ */
+type FormPendingReason = "FORM_NOT_IN_SOURCE" | "FORM_AMBIGUOUS" | "FIELD_UNMATCHED" | "ACTION_IS_EXPRESSION" | "DIALECT_UNSUPPORTED" | "PARSE_ERROR";
+interface PendingForm {
+    id: string;
+    name: string;
+    reason: FormPendingReason;
+    /** The file the reason is about, when the reason is about one. */
+    file?: string;
+    /** What exactly could not be done. Informative; the reason is the contract. */
+    message?: string;
 }
+interface FormsReceipt {
+    /** A `<form>` this run pointed at the CMS: action, method, id, field markers and the script. */
+    wired: number;
+    /**
+     * Already ours, from a previous run — the `<form>` carries `data-bcms-form`.
+     *
+     * Its own bucket for the same reason componentize keeps one: a second run over a wired tree has
+     * to report `wired: 0, pending: []` AND still account for every form of the brief.
+     */
+    alreadyWired: number;
+    pending: PendingForm[];
+    /** Prose a human has to act on — a draft form still 403s every submission. */
+    notes?: string[];
+}
+/** Raised when the receipt does not account for every form. Never caught inside this package. */
+declare class FormInvariantError extends Error {
+    readonly code = "FORM_INVARIANT";
+    constructor(message: string);
+}
+/**
+ * The invariant, checked where the receipt is built — the same shape as `assertSections`.
+ *
+ * A form in none of the buckets is a form the codemod forgot, and a forgotten form is a live site
+ * whose submit button does nothing at all.
+ */
+declare function assertForms(total: number, forms: FormsReceipt): FormsReceipt;
 /**
  * One binding whose `data-bcms-field` is an expression, and where its value is written literally.
  *
@@ -749,6 +829,32 @@ declare function helperSource(dialect: Dialect): string;
  */
 declare function isKnownHelper(content: string, dialect: Dialect): number | null;
 
+/**
+ * The submit runtime, LIFTED VERBATIM from `src/lib/sites/render-page.ts` `FORM_SCRIPT`.
+ *
+ * 🔴 THE SAME BYTES, AND A TEST THAT SAYS SO. The hosted renderer and this codemod ship the same
+ * form contract to two different kinds of site, and the `cf-turnstile-response` hoist in the
+ * middle is the part that cannot drift: the token must travel as a TOP-LEVEL key and never inside
+ * `data`, or the ingest route reads `token === undefined` and — once any Turnstile secret resolves
+ * — answers 403 to every single submission. A copy that fell behind would turn enabling Turnstile
+ * into a kill switch for the customer's live form, on their own repository, where nothing here can
+ * see it. `src/__tests__/content/form-script-pin.test.ts` reads THIS FILE as text and asserts the
+ * renderer's constant occurs in it byte for byte, which is the only thing that keeps the copy a
+ * copy. Change it there first, then paste it here.
+ */
+declare const FORM_SCRIPT = "<script>\ndocument.querySelectorAll('form[data-bcms-form]').forEach(function(f){\n  f.addEventListener('submit',function(e){\n    e.preventDefault();\n    var msg=f.querySelector('.bcms-form-msg');\n    var data={};\n    // A checkboxes group posts one entry per checked box under the SAME name; the old\n    // one-at-a-time assignment kept only the last, so \"pick many\" delivered one answer.\n    // One checked box still arrives as a scalar \u2014 FormData cannot tell a group from a\n    // lone field \u2014 which is exactly why lib/forms/validate.ts's chosenValues() accepts\n    // both an array and a comma string.\n    new FormData(f).forEach(function(v,k){\n      if(k==='cf-turnstile-response')return;\n      if(Object.prototype.hasOwnProperty.call(data,k))data[k]=(Array.isArray(data[k])?data[k]:[data[k]]).concat(v);\n      else data[k]=v;\n    });\n    var body={data:data};\n    var tok=f.querySelector('[name=\"cf-turnstile-response\"]');\n    if(tok&&tok.value)body['cf-turnstile-response']=tok.value;\n    fetch(f.action,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(body)})\n      .then(function(r){return r.ok;})\n      .then(function(ok){if(msg){msg.hidden=false;msg.textContent=ok?(f.getAttribute('data-bcms-form-success')||'Thanks! Your submission was received.'):'Sorry, something went wrong.';}if(ok)f.reset();})\n      .catch(function(){if(msg){msg.hidden=false;msg.textContent='Sorry, something went wrong.';}});\n  });\n});\n</script>";
+/**
+ * Wire every form the brief lists, and say what could not be.
+ *
+ * PURE, like the rest of this package: files in as values, files out as values. The receipt is a
+ * `ConversionReceipt` with an empty path arithmetic and the lane's own account under `forms`, so
+ * `submit_conversion_receipt` takes it unchanged — the server's invariant reads `paths` only.
+ */
+declare function wireForms(briefIn: Brief, sources: SourceFile[]): Promise<{
+    files: PlanFile[];
+    receipt: ConversionReceipt;
+}>;
+
 /**
  * Copy that lives in a DATA LITERAL beside the markup, rendered through `.map`.
  *
@@ -1538,4 +1644,4 @@ declare function convertSources(briefIn: Brief, sources: SourceFile[], options?:
     receipt: ConversionReceipt;
 }>;
 
-export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type Brief, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type CanvasResult, type CanvasSource, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type DataMember, type DataResult, type DeclaredPath, type Dialect, type DynamicBinding, type FileDeclaration, type FindSitesResult, HELPER_PATH, HELPER_VERSION, type ImageResult, type ImageTarget, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type ReceiptNote, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, SSR_DRAFT_RECIPE, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionsReceipt, type Site, type SiteWhere, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, type ValidationCode, ValidationError, aliasesFrom, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findSites, findSitesTolerant, flat, helperSource, importsIn, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeOfFile, stripTags, unreadableConfigs, walkAst };
+export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type Brief, type BriefForm, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type CanvasResult, type CanvasSource, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type DataMember, type DataResult, type DeclaredPath, type Dialect, type DynamicBinding, FORM_SCRIPT, type FileDeclaration, type FindSitesResult, FormInvariantError, type FormPendingReason, type FormsReceipt, HELPER_PATH, HELPER_VERSION, type ImageResult, type ImageTarget, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingForm, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type ReceiptNote, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, SSR_DRAFT_RECIPE, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionsReceipt, type Site, type SiteWhere, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, type ValidationCode, ValidationError, aliasesFrom, assertForms, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findSites, findSitesTolerant, flat, helperSource, importsIn, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeOfFile, stripTags, unreadableConfigs, walkAst, wireForms };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import MagicString5 from "magic-string";
+import MagicString6 from "magic-string";
 
 // src/brief.ts
 import { createHash } from "crypto";
@@ -2561,7 +2561,16 @@ var IMAGE_SOURCES = {
 };
 var isImageSource = (site) => site.where === "attr" && (IMAGE_SOURCES[site.tag.toLowerCase()] ?? []).includes(site.attr ?? "");
 var norm = (value) => decodeEntities(value.normalize("NFC")).replace(/\s+/g, " ").trim();
-var BCMS_ATTRS = ["data-bcms-field", "data-bcms-kind", "data-bcms-props", "data-bcms-layout-field"];
+var BCMS_ATTRS = [
+  "data-bcms-field",
+  "data-bcms-kind",
+  "data-bcms-props",
+  "data-bcms-layout-field",
+  // The forms lane's two. Listed here so `collectSites` never matches a brief literal against a
+  // marker this package itself wrote — a form id or a field key is not the page's copy.
+  "data-bcms-form",
+  "data-bcms-form-field"
+];
 var attrInsertAfter = (attrs, start, tag) => attrs.length > 0 ? Math.max(...attrs.map((a) => a.range.end)) : start + 1 + tag.length;
 function openTagEnd(content, start) {
   let quote = null;
@@ -5160,6 +5169,22 @@ function importLines(imports) {
 
 // src/receipt.ts
 var CANVAS_REASONS = /* @__PURE__ */ new Set(["CANVAS_BRIDGE_MANUAL", "SSR_DRAFT_ROUTE"]);
+var FormInvariantError = class extends Error {
+  code = "FORM_INVARIANT";
+  constructor(message) {
+    super(message);
+    this.name = "FormInvariantError";
+  }
+};
+function assertForms(total, forms) {
+  const sum = forms.wired + forms.alreadyWired + forms.pending.length;
+  if (sum !== total) {
+    throw new FormInvariantError(
+      `The receipt does not account for every form: ${total} listed but ${forms.wired} wired + ${forms.alreadyWired} already wired + ${forms.pending.length} pending = ${sum}.`
+    );
+  }
+  return forms;
+}
 var ReceiptInvariantError = class extends Error {
   code = "RECEIPT_INVARIANT";
   constructor(message) {
@@ -6011,6 +6036,17 @@ function readBrief(value) {
       }
     }
   }
+  for (const [at, entry] of check.array(brief.forms ?? [], `the brief's "forms"`).entries()) {
+    const where = `brief.forms[${at}]`;
+    const form = check.record(entry, where);
+    check.segment(form.id, `${where}.id`);
+    check.string(form.name, `${where}.name`);
+    check.string(form.submitUrl, `${where}.submitUrl`);
+    check.optionalString(form.successMessage, `${where}.successMessage`);
+    for (const [n, held] of check.array(form.fields, `${where}.fields`).entries()) {
+      check.segment(check.record(held, `${where}.fields[${n}]`).key, `${where}.fields[${n}].key`);
+    }
+  }
   return brief;
 }
 function readPlan(value) {
@@ -6057,6 +6093,236 @@ function readPlan(value) {
   return plan2;
 }
 
+// src/forms.ts
+import MagicString4 from "magic-string";
+var WIRABLE = ["html", "astro", "jsx"];
+var CONTROLS = /* @__PURE__ */ new Set(["input", "select", "textarea"]);
+var FORM_SCRIPT = `<script>
+document.querySelectorAll('form[data-bcms-form]').forEach(function(f){
+  f.addEventListener('submit',function(e){
+    e.preventDefault();
+    var msg=f.querySelector('.bcms-form-msg');
+    var data={};
+    // A checkboxes group posts one entry per checked box under the SAME name; the old
+    // one-at-a-time assignment kept only the last, so "pick many" delivered one answer.
+    // One checked box still arrives as a scalar \u2014 FormData cannot tell a group from a
+    // lone field \u2014 which is exactly why lib/forms/validate.ts's chosenValues() accepts
+    // both an array and a comma string.
+    new FormData(f).forEach(function(v,k){
+      if(k==='cf-turnstile-response')return;
+      if(Object.prototype.hasOwnProperty.call(data,k))data[k]=(Array.isArray(data[k])?data[k]:[data[k]]).concat(v);
+      else data[k]=v;
+    });
+    var body={data:data};
+    var tok=f.querySelector('[name="cf-turnstile-response"]');
+    if(tok&&tok.value)body['cf-turnstile-response']=tok.value;
+    fetch(f.action,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(body)})
+      .then(function(r){return r.ok;})
+      .then(function(ok){if(msg){msg.hidden=false;msg.textContent=ok?(f.getAttribute('data-bcms-form-success')||'Thanks! Your submission was received.'):'Sorry, something went wrong.';}if(ok)f.reset();})
+      .catch(function(){if(msg){msg.hidden=false;msg.textContent='Sorry, something went wrong.';}});
+  });
+});
+</script>`;
+var SCRIPT_BODY = FORM_SCRIPT.slice("<script>".length, -"</script>".length);
+function scriptFor(dialect) {
+  if (dialect === "jsx") return `<script dangerouslySetInnerHTML={{ __html: \`${SCRIPT_BODY}\` }} />`;
+  if (dialect === "astro") return `<script is:inline>${SCRIPT_BODY}</script>`;
+  return FORM_SCRIPT;
+}
+var messageFor = (dialect) => dialect === "jsx" ? `<p className="bcms-form-msg" hidden></p>` : `<p class="bcms-form-msg" hidden></p>`;
+var escapeAttr = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
+var attrOf = (el, name) => el.attrs.find((a) => a.name.toLowerCase() === name);
+function* elementsIn(nodes) {
+  for (const node of nodes) {
+    if (node.type === "expr") {
+      yield* elementsIn(node.children);
+      continue;
+    }
+    if (node.type !== "element") continue;
+    yield node;
+    yield* elementsIn(node.children);
+  }
+}
+var childElements = (node) => node.children.flatMap(
+  (child) => child.type === "element" ? [child] : child.type === "expr" ? childElements(child) : []
+);
+function candidateOf(file, dialect, form) {
+  const controls = /* @__PURE__ */ new Map();
+  const wrapper = /* @__PURE__ */ new Map();
+  const all = [];
+  const walk = (parent) => {
+    const own = [];
+    for (const child of childElements(parent)) {
+      if (CONTROLS.has(child.tag.toLowerCase())) {
+        own.push(child);
+        all.push(child);
+      }
+      walk(child);
+    }
+    if (own.length === 1 && parent !== form) wrapper.set(own[0], parent);
+  };
+  walk(form);
+  for (const control of all) {
+    const name = attrOf(control, "name")?.value;
+    if (name && !controls.has(name)) controls.set(name, control);
+  }
+  for (const control of all) {
+    const id = attrOf(control, "id")?.value;
+    if (id && !controls.has(id)) controls.set(id, control);
+  }
+  return { file, dialect, el: form, controls, wrapper };
+}
+var hasMessage = (form) => [...elementsIn([form])].some((el) => (attrOf(el, "class") ?? attrOf(el, "classname"))?.value.includes("bcms-form-msg") ?? false);
+function wire(source, candidate, form) {
+  const { el, dialect } = candidate;
+  const inserts = [];
+  const set = (name, value) => {
+    const attr = attrOf(el, name);
+    if (!attr) inserts.push(`${name}="${escapeAttr(value)}"`);
+    else if (attr.valueRange) source.overwrite(attr.valueRange.start, attr.valueRange.end, escapeAttr(value));
+    else source.overwrite(attr.range.start, attr.range.end, `${name}="${escapeAttr(value)}"`);
+  };
+  set("action", form.submitUrl);
+  set("method", "post");
+  inserts.push(`data-bcms-form="${escapeAttr(form.id)}"`);
+  if (form.successMessage) inserts.push(`data-bcms-form-success="${escapeAttr(form.successMessage)}"`);
+  source.appendLeft(el.attrInsertAt, ` ${inserts.join(" ")}`);
+  for (const field of form.fields) {
+    const control = candidate.controls.get(field.key);
+    const host = candidate.wrapper.get(control) ?? control;
+    source.appendLeft(host.attrInsertAt, ` data-bcms-form-field="${escapeAttr(field.key)}"`);
+    const name = attrOf(control, "name");
+    if (!name) source.appendLeft(control.attrInsertAt, ` name="${escapeAttr(field.key)}"`);
+    else if (!name.expression && name.value !== field.key && name.valueRange) {
+      source.overwrite(name.valueRange.start, name.valueRange.end, escapeAttr(field.key));
+    }
+  }
+  if (el.inner && !hasMessage(el)) {
+    const tail = /\s*$/.exec(source.original.slice(el.inner.start, el.inner.end))[0];
+    source.appendLeft(el.inner.end - tail.length, `${tail || "\n"}${messageFor(dialect)}`);
+  }
+}
+async function wireForms(briefIn, sources) {
+  const brief = readBrief(briefIn);
+  const forms = brief.forms ?? [];
+  const candidates = [];
+  const unreadable = [];
+  for (const source of sources) {
+    if (!/<form[\s/>]/i.test(source.content)) continue;
+    const dialect = dialectOf(source.path, source.content);
+    if (!dialect || !WIRABLE.includes(dialect)) {
+      unreadable.push({
+        file: source.path,
+        reason: "DIALECT_UNSUPPORTED",
+        message: `${source.path} is ${dialect ?? "not a template"}.`
+      });
+      continue;
+    }
+    const parsed = await parseFile4(dialect, source.content);
+    if (parsed.error) {
+      unreadable.push({
+        file: source.path,
+        reason: parsed.error.code === "DIALECT_UNSUPPORTED" ? "DIALECT_UNSUPPORTED" : "PARSE_ERROR",
+        message: parsed.error.message
+      });
+      continue;
+    }
+    for (const el of elementsIn(parsed.roots)) {
+      if (el.tag.toLowerCase() === "form") candidates.push(candidateOf(source.path, dialect, el));
+    }
+  }
+  const holds = (c, f) => f.fields.filter((field) => c.controls.has(field.key)).length;
+  const covers2 = (c, f) => f.fields.length > 0 && holds(c, f) === f.fields.length;
+  const options = new Map(forms.map((f) => [f.id, candidates.filter((c) => covers2(c, f))]));
+  const wanted = /* @__PURE__ */ new Map();
+  for (const list of options.values()) for (const c of list) wanted.set(c, (wanted.get(c) ?? 0) + 1);
+  const matched = [];
+  const pending = [];
+  const onSite = [];
+  let alreadyWired = 0;
+  const pend2 = (f, reason, file, message) => void pending.push({ id: f.id, name: f.name, reason, ...file ? { file } : {}, ...message ? { message } : {} });
+  for (const form of forms) {
+    const list = options.get(form.id) ?? [];
+    if (list.length > 1) {
+      pend2(form, "FORM_AMBIGUOUS", void 0, `${list.length} forms post every field of "${form.name}": ${list.map((c) => c.file).join(", ")}.`);
+      continue;
+    }
+    if (list.length === 1 && (wanted.get(list[0]) ?? 0) > 1) {
+      pend2(form, "FORM_AMBIGUOUS", list[0].file, "more than one CMS form's fields are posted by this <form>.");
+      continue;
+    }
+    if (list.length === 0) {
+      const [best] = candidates.map((c) => ({ c, n: holds(c, form) })).filter((x) => x.n > 0).sort((a, b) => b.n - a.n);
+      if (best) {
+        const missing = form.fields.filter((f) => !best.c.controls.has(f.key)).map((f) => f.key);
+        pend2(form, "FIELD_UNMATCHED", best.c.file, `no control posts ${missing.join(", ")} in the <form> that posts its other fields.`);
+      } else if (unreadable[0]) {
+        pend2(form, unreadable[0].reason, unreadable[0].file, unreadable[0].message);
+      } else {
+        pend2(form, "FORM_NOT_IN_SOURCE", void 0, `no <form> posts ${form.fields.map((f) => f.key).join(", ") || "any field of this form"}.`);
+      }
+      continue;
+    }
+    const candidate = list[0];
+    if (attrOf(candidate.el, "action")?.expression) {
+      pend2(form, "ACTION_IS_EXPRESSION", candidate.file, "its action is an expression, so this run will not replace it.");
+      continue;
+    }
+    const misnamed = form.fields.find((field) => {
+      const attr = attrOf(candidate.controls.get(field.key), "name");
+      return !!attr && attr.value !== field.key && (attr.expression || !attr.valueRange);
+    });
+    if (misnamed) {
+      pend2(form, "FIELD_UNMATCHED", candidate.file, `the control for ${misnamed.key} posts under an expression, so its name cannot be set to the CMS key.`);
+      continue;
+    }
+    if (attrOf(candidate.el, "data-bcms-form")) {
+      alreadyWired++;
+      onSite.push(form);
+      continue;
+    }
+    matched.push({ form, candidate });
+    onSite.push(form);
+  }
+  const contents = new Map(sources.map((s) => [s.path, s.content]));
+  const byFile = /* @__PURE__ */ new Map();
+  for (const m of matched) byFile.set(m.candidate.file, [...byFile.get(m.candidate.file) ?? [], m]);
+  const files = [];
+  for (const [path, list] of [...byFile].sort(([a], [b]) => a.localeCompare(b))) {
+    const content = contents.get(path);
+    const source = new MagicString4(content);
+    for (const { form, candidate } of list) wire(source, candidate, form);
+    if (!content.includes("form[data-bcms-form]")) {
+      const last = list.reduce((a, b) => b.candidate.el.end > a.candidate.el.end ? b : a);
+      const indent = /[^\S\n]*$/.exec(content.slice(0, last.candidate.el.start))[0];
+      source.appendRight(last.candidate.el.end, `
+${indent}${scriptFor(last.candidate.dialect)}`);
+    }
+    files.push({ path, operation: "modify", content: source.toString() });
+  }
+  const notes = onSite.filter((f) => f.status === "draft").map((f) => `publish form ${f.name} in the Forms tab \u2014 a draft form rejects every submission with 403.`);
+  return {
+    files,
+    receipt: {
+      briefDigest: briefDigest(brief),
+      // This lane binds no brief PATH, and says so rather than leaving the arithmetic to a reader:
+      // a receipt claiming zero of zero paths is exactly what a forms-only run did.
+      paths: { declared: 0, rewritten: 0, alreadyDeclared: 0, pending: [] },
+      occurrences: { located: 0, rewritten: 0 },
+      files: [],
+      helpers: [],
+      helperUpgraded: false,
+      dynamicBindings: [],
+      forms: assertForms(forms.length, {
+        wired: matched.length,
+        alreadyWired,
+        pending,
+        ...notes.length > 0 ? { notes } : {}
+      })
+    }
+  };
+}
+
 // src/scan.ts
 var SKIP_DIRS = [
   "node_modules/",
@@ -6425,7 +6691,7 @@ function moduleScope(parsed, content) {
 }
 
 // src/componentize.ts
-import MagicString4 from "magic-string";
+import MagicString5 from "magic-string";
 var SectionInvariantError = class extends Error {
   code = "SECTION_INVARIANT";
   constructor(message) {
@@ -7351,7 +7617,7 @@ export default function ${resolved.name}({ blockId, bind, overrides, page }: Bcm
 ` };
 }
 function sectionMarkup(content, root, fieldName) {
-  const slice = new MagicString4(content.slice(root.start, root.end));
+  const slice = new MagicString5(content.slice(root.start, root.end));
   const at = (offset) => offset - root.start;
   const stamps = root.attrs.filter((attr) => attr.name === "data-bcms-block");
   if (stamps.length === 0) slice.appendLeft(at(root.attrInsertAt), " data-bcms-block={blockId}");
@@ -7550,7 +7816,7 @@ async function migrateSections(plan2, contents, written, fileSet, aliases) {
         );
         continue;
       }
-      const source = new MagicString4(content);
+      const source = new MagicString5(content);
       const { bound, duplicates } = wrapFieldAttrs(source, content, elements, (at) => at, "bcmsField");
       if (duplicates.length > 0) {
         refused.set(refusalKey(dialect, slug), `${entry.path} has ${duplicates.join(", ")} carrying more than one data-bcms-field, so there is no single address to rewrite.`);
@@ -7827,7 +8093,7 @@ export default function Sections({ page }: { page: string }) {
 function splicePageRun(file, content, dialect, parsed, placeable, pageSlug) {
   const names = allocateNames(topLevelBindings(dialect, parsed, content), [{ key: "Sections", name: "Sections" }]);
   const local = names.get("Sections");
-  const source = new MagicString4(content);
+  const source = new MagicString5(content);
   const first = placeable[0].root;
   const last = placeable[placeable.length - 1].root;
   source.overwrite(first.start, last.end, `<${local} page="${pageSlug}" />`);
@@ -7847,7 +8113,7 @@ function splicePageInline(file, content, dialect, parsed, placeable, pageSlug, w
     { key: "pageSnapshot", name: "pageSnapshot" }
   ]);
   const snapshot = names.get("pageSnapshot");
-  const source = new MagicString4(content);
+  const source = new MagicString5(content);
   for (const resolved of placeable) {
     const component = written.get(resolved.slug);
     const tag = component.member ? `${names.get(resolved.slug)}.${component.member}` : names.get(resolved.slug);
@@ -8234,7 +8500,7 @@ async function convertSources(briefIn, sources, options) {
     } else rewritten++;
   }
   for (const [file, splices] of [...componentEdits].sort(([a], [b]) => a.localeCompare(b))) {
-    const source = new MagicString5(contents.get(file));
+    const source = new MagicString6(contents.get(file));
     const seen = /* @__PURE__ */ new Set();
     for (const splice of splices) {
       const id = `${splice.start}:${splice.end}:${splice.text}`;
@@ -8942,6 +9208,8 @@ export {
   CONTENT_DIR,
   ConvertError,
   DIALECT_RULES,
+  FORM_SCRIPT,
+  FormInvariantError,
   HELPER_PATH,
   HELPER_VERSION,
   PARSE_FILE,
@@ -8957,6 +9225,7 @@ export {
   SectionInvariantError,
   ValidationError,
   aliasesFrom,
+  assertForms,
   assertReceipt,
   assertSections,
   assetCandidates,
@@ -8999,6 +9268,7 @@ export {
   routeOfFile,
   stripTags,
   unreadableConfigs,
-  walkAst
+  walkAst,
+  wireForms
 };
 //# sourceMappingURL=index.js.map