@bettercms-ai/convert 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @bettercms-ai/convert
 
+## 0.20.0
+
+### Minor Changes
+
+- c4bd14b: `--forms` wires an Astro `<form>` by the CMS form's NAME: `data-bcms-form={bcmsFormId("Contact")}`, `action={bcmsFormAction("Contact")}` and `method={bcmsFormMethod("Contact")}`, resolved at build by a committed `src/bcms-forms.ts` from `bcms-content.json` and `BCMS_API_URL`. The source carries no host and no form id, so a repository built by more than one BetterCMS environment wires each build to the environment that built it. An Astro form wired by id is rewired by name once, one wired by name with a static `method="post"` gets `method={bcmsFormMethod(…)}` once, and one already wired by name counts as wired whatever quotes or spacing a formatter gave the calls; a shared name pends `FORM_NAME_AMBIGUOUS`. Form NAMES are the cross-rung contract; rename on both rungs: a wiring by name is never rewritten, so a form this project calls something else pends `FORM_WIRED_TO_OTHER_NAME` with nothing written, and a wiring by a name no form of the brief covers gets one note. At build the helper never fails: a name it cannot resolve among the project's own non-ignored forms, a shared name or a missing `BCMS_API_URL` renders that form unwired (no `action`, no `method`, no `data-bcms-form`) with one warning line naming `BCMS_FORM_NOT_FOUND`, `BCMS_FORM_NAME_AMBIGUOUS` or `BCMS_FORM_API_URL_MISSING` and the form, and a `bcms-content.json` it cannot parse, or one listing a form with no id or name, renders every form unwired with one `FORMS_SNAPSHOT_UNREADABLE` line, because forms are derived only by the release of a successful build. The helper passes a strict site tsconfig (`astro check`). Its first line, `// @bettercms-ai/convert forms-helper v2`, marks it as ours: a copy at that version or older (v1 included) is rewritten to the current bytes, and a `src/bcms-forms.ts` without that line pends `HELPER_CONFLICT`. A matched `<form>` that already carries every attribute no longer gains a stray space.
+
+  Not changed: html and JSX forms stay wired by id (html has no build, and JSX may render in a client bundle that cannot use `node:fs`). The backend's orchestration-validation workflow is left unsuffixed; only the convert, section-validation and component-validation workflows are per rung.
+
 ## 0.19.0
 
 ### Minor Changes

package/README.md

@@ -624,13 +624,43 @@ It writes six things onto a matched `<form>` and nothing else: `action="<submitU
 `method="post"`, `data-bcms-form="<id>"` (plus `data-bcms-form-success` when the CMS form has a
 success message), `data-bcms-form-field="<key>"` on each matched control, a
 `<p class="bcms-form-msg" hidden>` before `</form>` when there is none, and the submit script once
-per file — the same bytes the hosted renderer ships, pinned by a test. No helper, no snapshot, no
-import: a form posts to an absolute URL at runtime, so there is nothing to read at build time.
+per file — the same bytes the hosted renderer ships, pinned by a test.
+
+In an Astro file the form is named, not addressed: `data-bcms-form={bcmsFormId("Contact")}`,
+`action={bcmsFormAction("Contact")}` and `method={bcmsFormMethod("Contact")}`, imported from
+`src/bcms-forms.ts`, which this run adds. At build that helper reads the form's id from
+`bcms-content.json` and the API from `BCMS_API_URL`, so the source holds no host and no id and every
+BetterCMS environment that builds the repository wires it to itself. The built page is unchanged: an
+id, an absolute action and `post`. The helper reads the forms the brief names from: the building
+project's own, ignored ones left out. With no snapshot (a local build) the form renders unwired. The
+helper never fails a build: a name it cannot resolve, a name two forms share, or a build with no
+`BCMS_API_URL` renders that form unwired too (no `action`, no `method`, no `data-bcms-form`, so
+Astro drops all three) and prints one warning line naming the code (`BCMS_FORM_NOT_FOUND`,
+`BCMS_FORM_NAME_AMBIGUOUS`, `BCMS_FORM_API_URL_MISSING`) and the form; a `bcms-content.json` it
+cannot parse, or one listing a form with no id or name, renders every form unwired with one
+`FORMS_SNAPSHOT_UNREADABLE` line. Forms are derived by the release of a successful build and convert
+runs after it, so a helper that threw would leave a first import or a renamed form undeployable for
+good. The helper type-checks under a strict site tsconfig, because `astro check` lints it. Its first
+line, `// @bettercms-ai/convert forms-helper v2`, is what makes the file ours: a copy at that version
+or older is rewritten to the current bytes, a newer one is left alone, and a file without the line is
+`HELPER_CONFLICT`. An Astro form an earlier run wired by id is rewired by name once, a form wired by
+name with v1's static `method="post"` gets `method={bcmsFormMethod(…)}` once, and a form wired by
+name counts as wired whatever quotes or spacing a formatter gave the calls. html and JSX still get
+the literal id and endpoint of the environment that ran the codemod — html has no build, and a JSX
+form may render in a client bundle that cannot read a file.
+
+**Form NAMES are the cross-rung contract; rename on both rungs.** A wiring by name is never
+rewritten, whether or not the name resolves on the environment running the codemod: prod and dev
+share the name and nothing else, so rewriting it for one unwires the form on the other. A form this
+project calls something else is pending `FORM_WIRED_TO_OTHER_NAME` and nothing is written; a wiring by
+a name no form of the brief even covers gets one line in `notes`.
 
 The match is the FIELD KEYS: a `<form>` is a CMS form's only when the names its controls post are a
 superset of that form's field keys and exactly one `<form>` answers. Everything else is pending with
 a reason — `FORM_NOT_IN_SOURCE`, `FORM_AMBIGUOUS`, `FIELD_UNMATCHED`, `ACTION_IS_EXPRESSION`,
-`DIALECT_UNSUPPORTED`, `PARSE_ERROR` — because a form wired to the wrong id sends the customer's
+`DIALECT_UNSUPPORTED`, `PARSE_ERROR`, and for Astro `FORM_NAME_AMBIGUOUS` (two CMS forms share the
+name), `HELPER_CONFLICT` (`src/bcms-forms.ts` is somebody else's file) and
+`FORM_WIRED_TO_OTHER_NAME` (the `<form>` is wired by another name) — because a form wired to the wrong id sends the customer's
 leads into another form's inbox, silently, forever. A `<form>` that already carries
 `data-bcms-form` is `alreadyWired` and is left alone, so a second run is a no-op.
 

package/dist/cli.js

@@ -6434,6 +6434,114 @@ function readPlan(value) {
 // src/forms.ts
 import MagicString4 from "magic-string";
 var WIRABLE = ["html", "astro", "jsx"];
+var BY_NAME = ["astro"];
+var FORMS_HELPER_PATH = "src/bcms-forms.ts";
+var FORMS_HELPER_VERSION = 2;
+var FORMS_HELPER_HEADER = /^\/\/ @bettercms-ai\/convert forms-helper v(\d+)\r?\n/;
+var formsHelperVersion = (content) => {
+  const m = FORMS_HELPER_HEADER.exec(content);
+  return m ? Number(m[1]) : null;
+};
+var FORMS_HELPER_SOURCE = `// @bettercms-ai/convert forms-helper v${FORMS_HELPER_VERSION}
+// Written by @bettercms-ai/convert; a re-run rewrites it, so do not edit it.
+// Resolves a BetterCMS form by NAME at build, for the environment that is building this site: the id
+// from bcms-content.json (written into the tree before the build) and the endpoint from BCMS_API_URL.
+// The source names no host and no id, so every BetterCMS environment builds its own wiring.
+// A form it cannot resolve renders unwired (no action, no method, no id) with one warning line, and
+// the build goes on. Form NAMES are the contract between environments: rename a form on every one.
+import { existsSync, readFileSync } from "node:fs";
+
+type SnapshotForm = { id: string; name: string; projectId?: string | null; ignoredAt?: string | null };
+type Snapshot = { projectId: string | null; forms: SnapshotForm[] };
+type Wiring = { id: string; action: string };
+
+let snapshot: Snapshot | null | undefined;
+const resolved = new Map<string, Wiring | undefined>();
+
+const env = (key: string): string | undefined => process.env[key] || process.env[\`PUBLIC_\${key}\`] || undefined;
+
+const isForm = (value: unknown): value is SnapshotForm =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof (value as { id?: unknown }).id === "string" &&
+  typeof (value as { name?: unknown }).name === "string";
+
+function readSnapshot(): Snapshot | null {
+  for (const file of ["bcms-content.json", "bcms-content/forms.json"]) {
+    if (!existsSync(file)) continue;
+    try {
+      const data: unknown = JSON.parse(readFileSync(file, "utf8"));
+      const record = (Array.isArray(data) ? { forms: data } : (data ?? {})) as { forms?: unknown; projectId?: unknown };
+      const forms: unknown[] = Array.isArray(record.forms) ? record.forms : [];
+      if (!forms.every(isForm)) throw new Error("a form entry has no id or name");
+      return { projectId: typeof record.projectId === "string" ? record.projectId : null, forms };
+    } catch (error) {
+      // Read once per build, so this is the one line however many forms the site has.
+      console.warn(\`[bcms-forms] FORMS_SNAPSHOT_UNREADABLE: \${file} could not be read (\${error instanceof Error ? error.message : String(error)}); every form renders unwired.\`);
+      return null;
+    }
+  }
+  return null;
+}
+
+function unwired(code: string, name: string, why: string): undefined {
+  console.warn(\`[bcms-forms] \${code}: form "\${name}" renders unwired; \${why}.\`);
+  return undefined;
+}
+
+function resolve(name: string): Wiring | undefined {
+  if (snapshot === undefined) snapshot = readSnapshot();
+  // No snapshot (a local dev build), or one it could not read: the form renders unwired, as before.
+  if (snapshot === null) return undefined;
+  const project = env("BCMS_PROJECT_ID") ?? snapshot.projectId;
+  // The forms the conversion brief names from: this project's own, ignored ones left out.
+  const own = snapshot.forms.filter((f) => !f.ignoredAt && (!project || f.projectId === project));
+  const hits = own.filter((f) => f.name === name);
+  const form = hits.length === 1 ? hits[0] : undefined;
+  if (!form && hits.length > 1) {
+    return unwired("BCMS_FORM_NAME_AMBIGUOUS", name, \`\${hits.length} forms in this project share that name; rename one in the Forms tab\`);
+  }
+  if (!form) {
+    return unwired(
+      "BCMS_FORM_NOT_FOUND",
+      name,
+      own.length === 0
+        ? "this project has no forms yet; the release of this build derives them"
+        : "no form in this project has that name; a name is shared by every environment, so rename the form on each one",
+    );
+  }
+  const api = env("BCMS_API_URL");
+  if (!api) return unwired("BCMS_FORM_API_URL_MISSING", name, "BCMS_API_URL is not set, so it has nowhere to post");
+  return { id: form.id, action: \`\${api.replace(/\\/$/, "")}/api/v1/forms/public/\${form.id}/submissions\` };
+}
+
+/** Resolved once per name, so a form's three attributes print one warning, not three. */
+function wiring(name: string): Wiring | undefined {
+  if (!resolved.has(name)) resolved.set(name, resolve(name));
+  return resolved.get(name);
+}
+
+export const bcmsFormId = (name: string): string | undefined => wiring(name)?.id;
+
+export const bcmsFormAction = (name: string): string | undefined => wiring(name)?.action;
+
+/** "post" only for a form that resolved: an unwired form keeps no method, like its action and id. */
+export const bcmsFormMethod = (name: string): "post" | undefined => (wiring(name) ? "post" : undefined);
+`;
+var idCall = (form) => `bcmsFormId(${JSON.stringify(form.name)})`;
+var actionCall = (form) => `bcmsFormAction(${JSON.stringify(form.name)})`;
+var methodCall = (form) => `bcmsFormMethod(${JSON.stringify(form.name)})`;
+function calledName(code, fn) {
+  const m = code === null ? null : new RegExp(`^${fn}\\s*\\(\\s*(["'\`])((?:\\\\.|(?!\\1)[^\\\\])*)\\1\\s*,?\\s*\\)$`).exec(code);
+  if (!m) return null;
+  const [, quote, raw] = m;
+  if (quote === "`" && raw.includes("${")) return null;
+  try {
+    return JSON.parse(`"${raw.replace(/\\(['`])/g, "$1").replace(/(?<!\\)"/g, '\\"')}"`);
+  } catch {
+    return null;
+  }
+}
 var CONTROLS = /* @__PURE__ */ new Set(["input", "select", "textarea"]);
 var FORM_SCRIPT = `<script>
 function bcmsPhone(cc,raw,trunk){var d=String(raw||'').trim();if(!d)return '';if(d.charAt(0)==='+'){var i=d.replace(/D/g,'');return i?'+'+i:'';}if(!cc)return d;var n=d.replace(/D/g,'');if(trunk&&n.charAt(0)==='0')n=n.slice(1);return n?'+'+cc+n:'';}
@@ -6495,6 +6603,10 @@ function* elementsIn(nodes) {
 var childElements = (node) => node.children.flatMap(
   (child) => child.type === "element" ? [child] : child.type === "expr" ? childElements(child) : []
 );
+function exprOf(c, name) {
+  const range = attrOf(c.el, name)?.expressionRange;
+  return range ? c.content.slice(range.start + 1, range.end - 1).trim() : null;
+}
 var LANDMARK_TAGS = /* @__PURE__ */ new Set(["footer", "header", "nav", "main", "aside", "dialog"]);
 function landmarkOf(chain) {
   for (let i = chain.length - 1; i >= 0; i--) {
@@ -6516,7 +6628,7 @@ function* formsIn(nodes, chain = []) {
   }
 }
 var isComponentTag = (dialect, tag) => dialect !== "html" && /^[A-Z]/.test(tag);
-function candidateOf(file, dialect, form, imported, landmark, content) {
+function candidateOf(file, dialect, form, imported, landmark, content, importAt) {
   const controls = /* @__PURE__ */ new Map();
   const wrapper = /* @__PURE__ */ new Map();
   const foreign = /* @__PURE__ */ new Set();
@@ -6557,7 +6669,7 @@ function candidateOf(file, dialect, form, imported, landmark, content) {
     content.slice(attr.expressionRange.start, attr.expressionRange.end).replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*|"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\$]|\\.|\$(?!\{))*`/g, "")
   );
   const dynamic = all.some((control) => !foreign.has(control) && computed(attrOf(control, "name")));
-  return { file, dialect, el: form, controls, wrapper, foreign, landmark, dynamic };
+  return { file, dialect, el: form, controls, wrapper, foreign, landmark, dynamic, content, importAt };
 }
 async function importedControls(source, parsed, dialect, project, cache) {
   const out = /* @__PURE__ */ new Map();
@@ -6590,11 +6702,20 @@ function wire(source, candidate, form) {
     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");
-  set("data-bcms-form", form.id);
+  const setExpr = (name, code) => {
+    const attr = attrOf(el, name);
+    if (!attr) inserts.push(`${name}={${code}}`);
+    else source.overwrite(attr.range.start, attr.range.end, `${name}={${code}}`);
+  };
+  const byName = BY_NAME.includes(dialect);
+  if (byName) setExpr("action", actionCall(form));
+  else set("action", form.submitUrl);
+  if (byName) setExpr("method", methodCall(form));
+  else set("method", "post");
+  if (byName) setExpr("data-bcms-form", idCall(form));
+  else set("data-bcms-form", form.id);
   if (form.successMessage) set("data-bcms-form-success", form.successMessage);
-  source.appendLeft(el.attrInsertAt, ` ${inserts.join(" ")}`);
+  if (inserts.length > 0) source.appendLeft(el.attrInsertAt, ` ${inserts.join(" ")}`);
   for (const inner of elementsIn(el.children)) {
     for (const attr of inner.attrs) {
       if (!DECLARED_BINDING_ATTR.test(attr.name)) continue;
@@ -6651,12 +6772,20 @@ async function wireForms(briefIn, sources, options_ = {}) {
     }
     const imported = dialect === "html" ? /* @__PURE__ */ new Map() : await importedControls(source, parsed, dialect, project, componentFiles);
     for (const { el, landmark } of formsIn(parsed.roots)) {
-      candidates.push(candidateOf(source.path, dialect, el, imported, landmark, source.content));
+      candidates.push(candidateOf(source.path, dialect, el, imported, landmark, source.content, parsed.importAt));
     }
   }
   const holds = (c, f) => f.fields.filter((field) => c.controls.has(field.key)).length;
-  const wiredTo = (c, f) => attrOf(c.el, "data-bcms-form")?.value === f.id;
-  const covers2 = (c, f) => c.dynamic && wiredTo(c, f) || f.fields.length > 0 && holds(c, f) === f.fields.length;
+  const byId = (c, f) => !attrOf(c.el, "data-bcms-form")?.expression && attrOf(c.el, "data-bcms-form")?.value === f.id;
+  const programAction = (c) => !!attrOf(c.el, "action")?.expression && calledName(exprOf(c, "action"), "bcmsFormAction") === null;
+  const wiredTo = (c, f) => BY_NAME.includes(c.dialect) ? calledName(exprOf(c, "data-bcms-form"), "bcmsFormId") === f.name || byId(c, f) && programAction(c) : byId(c, f);
+  const wiredName = (c) => BY_NAME.includes(c.dialect) ? calledName(exprOf(c, "data-bcms-form"), "bcmsFormId") : null;
+  const staticPost = (c) => {
+    const method = attrOf(c.el, "method");
+    return !!method && !method.expression && method.value.toLowerCase() === "post";
+  };
+  const claims = (c, f) => wiredTo(c, f) || byId(c, f);
+  const covers2 = (c, f) => c.dynamic && claims(c, f) || f.fields.length > 0 && holds(c, f) === f.fields.length;
   const samePath = (a, b) => a.replace(/\\/g, "/").replace(/^\.\//, "") === b.replace(/\\/g, "/").replace(/^\.\//, "");
   const options = new Map(forms.map((f) => [f.id, candidates.filter((c) => covers2(c, f))]));
   const pinned = /* @__PURE__ */ new Map();
@@ -6700,7 +6829,14 @@ async function wireForms(briefIn, sources, options_ = {}) {
   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 methodUpgrades = [];
+  const pendedByName = /* @__PURE__ */ new Set();
   const pending = [];
+  const existingHelper = sources.find((s) => samePath(s.path, FORMS_HELPER_PATH))?.content;
+  const helperVersion = existingHelper === void 0 ? null : formsHelperVersion(existingHelper);
+  const helperOk = existingHelper === void 0 || helperVersion !== null;
+  const helperStale = existingHelper !== void 0 && helperVersion !== null && helperVersion <= FORMS_HELPER_VERSION && existingHelper !== FORMS_HELPER_SOURCE;
+  let byNameOnSite = false;
   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 } : {} });
@@ -6739,12 +6875,25 @@ async function wireForms(briefIn, sources, options_ = {}) {
       continue;
     }
     const candidate = list[0];
+    const byName = BY_NAME.includes(candidate.dialect);
+    if (byName && forms.filter((f) => f.name === form.name).length > 1) {
+      pend2(form, "FORM_NAME_AMBIGUOUS", candidate.file, `more than one CMS form is named "${form.name}"; rename one in the Forms tab.`);
+      continue;
+    }
     if (wiredTo(candidate, form)) {
       alreadyWired++;
       onSite.push({ form, file: candidate.file });
+      if (byName) byNameOnSite = true;
+      if (wiredName(candidate) === form.name && staticPost(candidate) && helperOk) methodUpgrades.push({ form, candidate });
       continue;
     }
-    if (attrOf(candidate.el, "action")?.expression) {
+    const other = wiredName(candidate);
+    if (other !== null) {
+      pendedByName.add(candidate);
+      pend2(form, "FORM_WIRED_TO_OTHER_NAME", candidate.file, `its <form> is wired by name to "${other}", and a wiring by name is never rewritten: form names are shared by every environment, so give this form the same name on each one.`);
+      continue;
+    }
+    if (programAction(candidate)) {
       pend2(form, "ACTION_IS_EXPRESSION", candidate.file, "its action is an expression, so this run will not replace it.");
       continue;
     }
@@ -6756,18 +6905,46 @@ async function wireForms(briefIn, sources, options_ = {}) {
       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 (byName && !helperOk) {
+      pend2(form, "HELPER_CONFLICT", FORMS_HELPER_PATH, `${FORMS_HELPER_PATH} exists and is not the file @bettercms-ai/convert writes, so nothing may import it. Move it and re-run.`);
+      continue;
+    }
     matched.push({ form, candidate });
     onSite.push({ form, file: candidate.file });
+    if (byName) byNameOnSite = true;
   }
   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 editsOf = (path) => {
+    if (!byFile.has(path)) byFile.set(path, { wire: [], upgrade: [] });
+    return byFile.get(path);
+  };
+  for (const m of matched) editsOf(m.candidate.file).wire.push(m);
+  for (const m of methodUpgrades) editsOf(m.candidate.file).upgrade.push(m);
   const files = [];
-  for (const [path, list] of [...byFile].sort(([a], [b]) => a.localeCompare(b))) {
+  for (const [path, { wire: list, upgrade }] 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]")) {
+    for (const { form, candidate } of upgrade) {
+      const method = attrOf(candidate.el, "method");
+      source.overwrite(method.range.start, method.range.end, `method={${methodCall(form)}}`);
+    }
+    const first = (list[0] ?? upgrade[0]).candidate;
+    if (BY_NAME.includes(first.dialect) && first.importAt) {
+      const at = first.importAt;
+      const helper = relativeImport(path, FORMS_HELPER_PATH.replace(/\.ts$/, ""));
+      const names = !/\bbcmsFormId\b/.test(content) ? "bcmsFormAction, bcmsFormId, bcmsFormMethod" : !/\bbcmsFormMethod\b/.test(content) ? "bcmsFormMethod" : null;
+      if (names) {
+        const line = `import { ${names} } from "${helper}";`;
+        if (at.wrap) source.appendLeft(at.at, `${at.wrap.before}${line}${at.wrap.after}`);
+        else if (at.at === 0) source.appendLeft(0, `${line}
+`);
+        else source.appendLeft(at.at, `
+${line}`);
+      }
+    }
+    if (list.length > 0 && !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, `
@@ -6775,6 +6952,10 @@ ${indent}${scriptFor(last.candidate.dialect)}`);
     }
     files.push({ path, operation: "modify", content: source.toString() });
   }
+  const helperAdded = existingHelper === void 0 && (matched.some((m) => BY_NAME.includes(m.candidate.dialect)) || methodUpgrades.length > 0);
+  if (helperAdded) files.push({ path: FORMS_HELPER_PATH, operation: "add", content: FORMS_HELPER_SOURCE });
+  const helperUpgraded = helperStale && byNameOnSite;
+  if (helperUpgraded) files.push({ path: FORMS_HELPER_PATH, operation: "modify", content: FORMS_HELPER_SOURCE });
   const notes = onSite.filter(({ form }) => form.status === "draft").map(({ form }) => `publish form ${form.name} in the Forms tab \u2014 a draft form rejects every submission with 403.`);
   for (const { form, candidate } of matched) {
     const tie = beat.get(candidate);
@@ -6790,6 +6971,13 @@ ${indent}${scriptFor(last.candidate.dialect)}`);
       );
     }
   }
+  for (const c of candidates) {
+    const name = wiredName(c);
+    if (name === null || pendedByName.has(c) || forms.some((f) => f.name === name)) continue;
+    notes.push(
+      `${c.file}: its <form> is wired by name to "${name}", which no form of this project has, so this environment's build renders it unwired; it was not rewritten \u2014 form names are shared by every environment, so give the form that name here too.`
+    );
+  }
   for (const { form, candidate } of matched) {
     const keys = form.fields.filter((field) => candidate.foreign.has(candidate.controls.get(field.key))).map((field) => field.key);
     if (keys.length > 0) {
@@ -6807,8 +6995,8 @@ ${indent}${scriptFor(last.candidate.dialect)}`);
       paths: { declared: 0, rewritten: 0, alreadyDeclared: 0, pending: [] },
       occurrences: { located: 0, rewritten: 0 },
       files: [],
-      helpers: [],
-      helperUpgraded: false,
+      helpers: helperAdded || helperUpgraded ? [FORMS_HELPER_PATH] : [],
+      helperUpgraded,
       dynamicBindings: [],
       forms: assertForms(forms.length, {
         wired: matched.length,
@@ -9988,7 +10176,7 @@ function styleEdits(before, after) {
 // package.json
 var package_default = {
   name: "@bettercms-ai/convert",
-  version: "0.19.0",
+  version: "0.20.0",
   type: "module",
   description: "Deterministic codemod that turns an imported site's text-matched bindings into declared ones \u2014 parser offsets in, one magic-string pass out, plus a receipt of everything it could not do.",
   bin: {