@bettercms-ai/convert 0.18.2 → 0.20.0

package/dist/index.d.ts

@@ -428,8 +428,12 @@ interface ConversionReceipt {
  * `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.
+ * `FORM_NAME_AMBIGUOUS`     an Astro form is wired by name, and two CMS forms share this one's.
+ * `HELPER_CONFLICT`         `src/bcms-forms.ts` exists with bytes this package did not write.
+ * `FORM_WIRED_TO_OTHER_NAME` an Astro `<form>` is already wired by another name. Never rewritten:
+ *                           the name is what every environment building the repo shares.
  */
-type FormPendingReason = "FORM_NOT_IN_SOURCE" | "FORM_AMBIGUOUS" | "FIELD_UNMATCHED" | "ACTION_IS_EXPRESSION" | "DIALECT_UNSUPPORTED" | "PARSE_ERROR";
+type FormPendingReason = "FORM_NOT_IN_SOURCE" | "FORM_AMBIGUOUS" | "FIELD_UNMATCHED" | "ACTION_IS_EXPRESSION" | "DIALECT_UNSUPPORTED" | "PARSE_ERROR" | "FORM_NAME_AMBIGUOUS" | "HELPER_CONFLICT" | "FORM_WIRED_TO_OTHER_NAME";
 interface PendingForm {
     id: string;
     name: string;
@@ -951,7 +955,7 @@ declare function attrsFor(path: string, kind: string, props?: AttrBinding[], sco
 declare function propsAttribute(props: AttrBinding[]): string;
 
 /** Bumped whenever the emitted source changes. `isKnownHelper` upgrades anything older. */
-declare const HELPER_VERSION = 8;
+declare const HELPER_VERSION = 9;
 /** Where each dialect's helper lives. Null = this dialect reads nothing at build time. */
 declare const HELPER_PATH: Record<Dialect, string | null>;
 /** The directory the snapshots live in, at the repository root. */

package/dist/index.js

@@ -4187,7 +4187,7 @@ async function bindImages(ctx, targets) {
 
 // src/helper.ts
 import { createHash as createHash2 } from "crypto";
-var HELPER_VERSION = 8;
+var HELPER_VERSION = 9;
 var HEADER = "// @bettercms-ai/convert helper v";
 var HELPER_PATH = Object.fromEntries(
   Object.keys(DIALECT_RULES).map((d) => [d, DIALECT_RULES[d].helper])
@@ -4352,9 +4352,19 @@ export function bcmsImage<T>(page: unknown, path: string, fallback: T, slug?: st
  * the fallback the template shipped with \u2014 which is why a section renders correctly against the
  * committed \`{}\` stub.
  */
-export function bcmsSection(page: unknown, bind?: string, overrides?: unknown): Record<string, unknown> {
+export function bcmsSection(
+  page: unknown,
+  bind?: string,
+  overrides?: unknown,
+  bindPaths?: Record<string, string>,
+): Record<string, unknown> {
   const group = bind ? readPath(page, bind) : undefined;
   const base: Record<string, unknown> = isRecord(group) ? { ...group } : {};
+  // A locale copy on its twin's component spells its fields its own way: each prop's copy is
+  // read from the path the placement names for it.
+  if (bind && isRecord(bindPaths)) {
+    for (const [key, path] of Object.entries(bindPaths)) base[key] = readPath(page, path);
+  }
   if (!isRecord(overrides)) return base;
   for (const key of Object.keys(overrides)) {
     const value = overrides[key];
@@ -4417,21 +4427,25 @@ export function bcmsSectionPaths(
   overrides: unknown,
   prefix: string,
   map: BcmsPathMap,
+  bindPaths?: Record<string, string>,
 ): Record<string, unknown> {
   const out: Record<string, unknown> = isRecord(page) ? { ...page } : {};
   const own = isRecord(overrides) ? overrides : {};
   const separator = prefix.slice(-1);
-  const fromPage = (path: string): unknown =>
-    bind ? readPath(page, bind + separator + path.slice(prefix.length)) : undefined;
+  // A re-keyed locale copy names each prop's path on its own page; any other placement re-bases.
+  const fromPage = (path: string, key: string): unknown =>
+    !bind ? undefined
+    : isRecord(bindPaths) && typeof bindPaths[key] === "string" ? readPath(page, bindPaths[key])
+    : readPath(page, bind + separator + path.slice(prefix.length));
   for (const [path, key] of Object.entries(map.scalars ?? {})) {
     const value = own[key];
-    out[path] = value !== undefined && value !== null ? value : fromPage(path);
+    out[path] = value !== undefined && value !== null ? value : fromPage(path, key);
   }
   for (const [path, table] of Object.entries(map.tables ?? {})) {
     const held = own[table.key];
     const rows = isRecord(held) && Array.isArray(held.rows) ? held.rows : held;
     if (!Array.isArray(rows)) {
-      out[path] = fromPage(path);
+      out[path] = fromPage(path, table.key);
       continue;
     }
     const pageColumn = new Map(Object.entries(table.columns).map(([column, key]) => [key, column]));
@@ -4446,12 +4460,17 @@ export function bcmsSectionPaths(
 }
 
 export function bcmsFields(
-  placement: { blockId?: string; bind?: string; overrides?: unknown },
+  placement: { blockId?: string; bind?: string; overrides?: unknown; bindPaths?: Record<string, string> },
   pathPrefix: string,
   map?: BcmsPathMap,
 ): (path: string) => string {
   const id = placement.blockId;
   const own = typeof id === "string" && id !== "" && !placement.bind && isRecord(placement.overrides);
+  /** A re-keyed locale copy's own path for a prop, with whatever follows the prop kept. */
+  const moved = (key: string | undefined, rest: string): string | undefined => {
+    const paths = placement.bind && isRecord(placement.bindPaths) ? placement.bindPaths : undefined;
+    return key !== undefined && paths && typeof paths[key] === "string" ? paths[key] + rest : undefined;
+  };
   /**
    * What replaces the prefix the markup was cut with, or null for "leave every path alone".
    *
@@ -4470,11 +4489,14 @@ export function bcmsFields(
     const separator = pathPrefix.slice(-1);
     return (path: string): string => {
       if (!path.startsWith(pathPrefix) || !(own || placement.bind)) return path;
-      if (!own) return placement.bind + separator + path.slice(pathPrefix.length);
       const scalar = map.scalars?.[path];
-      if (scalar !== undefined) return id + "__overrides." + scalar;
       const row = /^([^[]+)\\[(\\d+)\\]\\.(.+)$/.exec(path);
       const table = row ? map.tables?.[row[1]] : undefined;
+      if (!own) {
+        return moved(scalar, "") ?? moved(table?.key, row ? "[" + row[2] + "]." + row[3] : "")
+          ?? placement.bind + separator + path.slice(pathPrefix.length);
+      }
+      if (scalar !== undefined) return id + "__overrides." + scalar;
       const column = row && table ? table.columns[row[3]] : undefined;
       return table && column !== undefined ? id + "__overrides." + table.key + "[" + row![2] + "]." + column : path;
     };
@@ -4484,7 +4506,9 @@ export function bcmsFields(
     // it names a key the instance does not hold and a group this placement is not bound to.
     // (An EMPTY prefix is a plan saying the prop key IS the page path, and matches everything.)
     if (lane === null || !path.startsWith(pathPrefix)) return path;
-    return lane + path.slice(pathPrefix.length);
+    const rest = path.slice(pathPrefix.length);
+    const key = /^[^.[]+/.exec(rest)?.[0];
+    return (own ? undefined : moved(key, rest.slice(key?.length ?? 0))) ?? lane + rest;
   };
 }
 `;
@@ -4497,7 +4521,8 @@ var HISTORICAL = {
     4: "a5742f64dacb1b26ee6dd5e1469a54871487934c71bc8267df19e3a80e417595",
     5: "0472fe3ffdcfa49e719c7b9da9cb63b6eba637cc22783bb00c3c2cadd3d800da",
     6: "c907e7245578d947c6541b1ab2c5c6659ea7789a1519e895b4a4aed122c6f649",
-    7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93"
+    7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
+    8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9"
   },
   "src/lib/bcms-content.ts": {
     1: "ae72ae14d706943d481c880d70da5789b4816ba1ba319a10fbc63ded4d0b42f2",
@@ -4506,7 +4531,8 @@ var HISTORICAL = {
     4: "0146d027a727ecd3c9e3fc336fcf1299b59ddf75b04091c05703f3f983ec28af",
     5: "c8c93655320fa65664611ba84541f3fa7bfa292cc9a2fd655373440b99049fba",
     6: "63f1fa29e47e70c5193b81ee24addb238ba100247124d55bc17713102d587df5",
-    7: "ed92fb88de953d9951abbe6a1edae1d048f4050eaf6fb607ac08167f94d8bcc7"
+    7: "ed92fb88de953d9951abbe6a1edae1d048f4050eaf6fb607ac08167f94d8bcc7",
+    8: "1a6f669d76d42effe77f082436e9d21c0efa6fc499e919e3d116bc3a27a7f3d5"
   },
   "composables/bcms-content.ts": {
     1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407",
@@ -4515,7 +4541,8 @@ var HISTORICAL = {
     4: "a5742f64dacb1b26ee6dd5e1469a54871487934c71bc8267df19e3a80e417595",
     5: "0472fe3ffdcfa49e719c7b9da9cb63b6eba637cc22783bb00c3c2cadd3d800da",
     6: "c907e7245578d947c6541b1ab2c5c6659ea7789a1519e895b4a4aed122c6f649",
-    7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93"
+    7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
+    8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9"
   }
 };
 var sha256 = (value) => createHash2("sha256").update(value, "utf8").digest("hex");
@@ -6416,6 +6443,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:'';}
@@ -6477,6 +6612,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--) {
@@ -6498,7 +6637,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();
@@ -6539,7 +6678,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();
@@ -6572,11 +6711,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;
@@ -6633,12 +6781,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();
@@ -6682,7 +6838,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 } : {} });
@@ -6721,12 +6884,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;
+    }
+    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 (attrOf(candidate.el, "action")?.expression) {
+    if (programAction(candidate)) {
       pend2(form, "ACTION_IS_EXPRESSION", candidate.file, "its action is an expression, so this run will not replace it.");
       continue;
     }
@@ -6738,18 +6914,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, `
@@ -6757,6 +6961,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);
@@ -6772,6 +6980,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) {
@@ -6789,8 +7004,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,
@@ -8131,6 +8346,7 @@ function componentFile(dialect, path, fromFile, content, parsed, resolved, pathP
     provided: [
       "blockId",
       "bind",
+      "bindPaths",
       "overrides",
       "page",
       fieldName,
@@ -8145,8 +8361,8 @@ function componentFile(dialect, path, fromFile, content, parsed, resolved, pathP
   const key = /^[A-Za-z_$][\w$]*$/.test(groupKey) ? groupKey : JSON.stringify(groupKey);
   const carriedDeclarations = carry.declarations.length > 0 ? `${carry.declarations.join("\n")}
 ` : "";
-  const copy = !snapshot ? "" : flat3 ? `const ${snapshot} = bcmsSectionPaths(page, bind, overrides, ${JSON.stringify(pathPrefix)}, ${JSON.stringify(pathMap)});` : `const ${snapshot} = { ${key}: bcmsSection(page, bind, overrides) };`;
-  const field = bound > 0 ? `const ${fieldName} = ${fieldsName}({ blockId, bind, overrides }, ${JSON.stringify(pathPrefix)}${flat3 ? `, ${JSON.stringify(pathMap)}` : ""});` : "";
+  const copy = !snapshot ? "" : flat3 ? `const ${snapshot} = bcmsSectionPaths(page, bind, overrides, ${JSON.stringify(pathPrefix)}, ${JSON.stringify(pathMap)}, bindPaths);` : `const ${snapshot} = { ${key}: bcmsSection(page, bind, overrides, bindPaths) };`;
+  const field = bound > 0 ? `const ${fieldName} = ${fieldsName}({ blockId, bind, bindPaths, overrides }, ${JSON.stringify(pathPrefix)}${flat3 ? `, ${JSON.stringify(pathMap)}` : ""});` : "";
   const declared = [copy, field].filter(Boolean).join("\n");
   const styles = dialect === "astro" ? carriedStyles(content) : "";
   if (dialect === "astro") {
@@ -8159,12 +8375,14 @@ interface Props {
   blockId?: string;
   /** The page field group this placement renders \u2014 Phase A keeps the copy where P2 put it. */
   bind?: string;
+  /** A locale copy's own field path for each prop, when its keys differ from this component's. */
+  bindPaths?: Record<string, string>;
   /** The instance's own copy, when an editor gave it any. Wins over the bound group. */
   overrides?: Record<string, unknown>;
   /** The page snapshot, so one component can serve every page whose group has this shape. */
   page?: unknown;
 }
-const { blockId, bind, overrides, page } = Astro.props;
+const { blockId, bind, bindPaths, overrides, page } = Astro.props;
 ${carriedDeclarations}${declared}
 ---
 ${markup}
@@ -8176,7 +8394,7 @@ ${styles}
 ${[...carried, `import { ${helpers.join(", ")} } from "${helperSpecifier}";`, `import type { BcmsSectionProps } from "${relativeImport(path, SECTIONS_LIB).replace(/\.tsx?$/, "")}";`].join("\n")}
 ${carriedDeclarations === "" ? "" : `
 ${carriedDeclarations}`}
-export default function ${resolved.name}({ blockId, bind, overrides, page }: BcmsSectionProps) {
+export default function ${resolved.name}({ blockId, bind, bindPaths, overrides, page }: BcmsSectionProps) {
   ${declared.split("\n").join("\n  ")}
   return (
     ${markup}
@@ -8538,6 +8756,7 @@ const isRecord = (v: unknown): v is Record<string, unknown> =>
 export interface BcmsSectionProps {
   blockId?: string;
   bind?: string;
+  bindPaths?: Record<string, string>;
   overrides?: Record<string, unknown>;
   page?: unknown;
 }
@@ -8547,6 +8766,8 @@ export interface BcmsPlacement {
   blockId?: string;
   slug: string;
   bind?: string;
+  /** A locale copy's own field path for each prop, when its keys differ from the component's. */
+  bindPaths?: Record<string, string>;
   overrides?: Record<string, unknown>;
 }
 
@@ -8607,6 +8828,7 @@ export function pageSections(pageSlug: string): BcmsPlacement[] {
       blockId: typeof block.id === "string" ? block.id : undefined,
       slug,
       bind: typeof props.bind === "string" ? props.bind : undefined,
+      bindPaths: isRecord(props.bindPaths) ? (props.bindPaths as Record<string, string>) : undefined,
       overrides: isRecord(props.overrides) ? props.overrides : undefined,
     });
   }
@@ -8672,6 +8894,7 @@ const snapshot = pageSnapshot(page);
     <Component
       blockId={placement.blockId}
       bind={placement.bind}
+      bindPaths={placement.bindPaths}
       overrides={placement.overrides}
       page={snapshot}
     />
@@ -8694,6 +8917,7 @@ export default function Sections({ page }: { page: string }) {
             key={placement.blockId ?? \`\${placement.slug}-\${i}\`}
             blockId={placement.blockId}
             bind={placement.bind}
+            bindPaths={placement.bindPaths}
             overrides={placement.overrides}
             page={snapshot}
           />