@bettercms-ai/convert 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # @bettercms-ai/convert
 
+## 0.9.0
+
+### Minor Changes
+
+- 94a00c3: `--forms`: point an imported site's own `<form>` at the CMS form behind it.
+
+  After an import the release hook derives a draft form row per `<form>` in the built site, so the
+  Forms tab fills up while the repository's markup still posts wherever it always did — to nothing,
+  or to somebody else's endpoint. Nothing joined the two halves, because the id that does is the
+  platform's and lives in the brief.
+
+  `npx @bettercms-ai/convert --forms --brief brief.json --root . --receipt receipt.json` reads the
+  brief's new `forms` array and writes, in one `magic-string` pass: `action`, `method`,
+  `data-bcms-form`, `data-bcms-form-success`, a `data-bcms-form-field` per field (on the control's
+  wrapper where it has one), the CMS key as each control's `name`, the `<p class="bcms-form-msg">`
+  the runtime writes into, and the submit script — the same bytes the hosted renderer ships, held
+  byte-for-byte by a test, because the `cf-turnstile-response` hoist in the middle of it is what
+  keeps enabling Turnstile from 403ing every submission.
+
+  The match is strict: a `<form>` is the CMS form's only when the names its controls post cover
+  every field key, and exactly one `<form>` answers. Everything else is receipted by name —
+  `FORM_NOT_IN_SOURCE`, `FORM_AMBIGUOUS`, `FIELD_UNMATCHED`, `ACTION_IS_EXPRESSION`,
+  `DIALECT_UNSUPPORTED`, `PARSE_ERROR` — because a form wired to the wrong id sends a customer's
+  leads into another form's inbox, silently, forever. A form already carrying `data-bcms-form` is
+  `alreadyWired`, so a second run writes nothing.
+
+  The receipt rides on `ConversionReceipt.forms` and claims no brief path, so
+  `submit_conversion_receipt` takes it unchanged. A form the brief lists as a DRAFT is wired AND
+  noted: it rejects every submission with a 403 until somebody publishes it in the Forms tab.
+
+  Also: `--version` now reports the package's real version. The constant had been stale at `0.4.0`
+  for four releases.
+
+## 0.8.0
+
+### Minor Changes
+
+- 8a4e961: Bind array literals written inline in the markup, and drill a repeater row's leaf into the
+  component that renders it.
+
+  `{['Offer', 'Structure', 'RTL'].map((item) => <li>…</li>)}` had no lane at all — the list lane
+  searches the module for a NAMED array, and an inline literal has no name — so every one of its
+  items came back `IN_EXPRESSION` with the copy in plain sight. The `]` immediately before the
+  `.map(` is the literal's close, which is what makes it safe without a name: there is exactly one
+  loop over it and nothing else in the file can hold a second reference. A value rendered beside an
+  icon (`<li><span>✓</span>{item}</li>`) gets a `<span>` of its own instead of declaring on the
+  parent, because a publish writing the value over the parent deletes the icon.
+
+  `demos.map((demo) => <DemoCard title={demo.title} />)` refused the whole group with
+  `PROP_TARGET_NOT_FOUND`: the value is rendered in the component's file, not the page's. It now
+  follows the same drill the scalar lane has always used — a row's leaf is that journey with an index
+  in the path. The call site declares one `bcmsBindings={{ title: `cards[${i}].title` }}` per element
+  and the component gets `data-bcms-field={bcmsBindings?.title}`. `{...row}` counts as passing the
+  prop. Every leaf placed or none, as before: a drill that misses refuses the group by its own reason.
+
+  Also: `tsconfig.json` / `jsconfig.json` are now opened by the scan gate. `aliasesFrom` reads them
+  and nothing ever handed it one, so every `paths` alias resolved to nothing and every prop drilled
+  through an `@components/*` import refused with the component sitting right there.
+
+  `bindDataLiterals` is async for this; it is exported, and a caller outside this package has to
+  await it.
+
+- 07f6648: Bind arrays of primitives and tuples rendered through `.map`.
+
+  `const promise = [['Once', 'One message'], …]` iterated as `promise.map(([title, text], i) => …)`
+  is the same shape as a row of objects one rung simpler, and the derive lane describes it as a
+  repeater group all the same. The declaration becomes `bcmsTuples(page, [[…paths…], …], [ …the
+original array, verbatim… ])` — `bcmsList` for a list one wide — and each rendered element carries
+  the same templated `data-bcms-field` a repeater writes, so a second run reads it back and changes
+  nothing. The committed helper is v6; an existing v5 helper upgrades in place.
+
+  The read maps over the path list rather than over the CMS array, so every row's text is editable
+  and the number of rows is still the template's: the receipt adds one `PRIMITIVE_LIST` note per
+  array saying a row added in the CMS does not appear and a deleted one falls back to the template's
+  own copy. A list whose paths are unrelated scalars, one used anywhere but that single `.map` or
+  `export`ed, one rendered inside a larger expression, one whose tuple position changes kind between
+  rows, and one the brief covers only part of are all refused by name.
+
+  On the Shatter acceptance repository this moves 16 paths from `IN_EXPRESSION` to `rewritten`
+  (219 → 235 of 735).
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -88,6 +88,58 @@ inherits row 0's styling). Each row element then declares
 `` data-bcms-field={`cards[${i}].<leaf>`} ``, and the callback gains an index parameter if it had
 none. An imported data module stays `IN_DATA_FILE`.
 
+**An array of PRIMITIVES or TUPLES is converted through its paths, not through its name.** The
+same shape one rung simpler: `const deliverables = ["…", "…", "…"]`, or
+`const faqs = [["q", "a"], …]`, iterated by `.map` with the callback rendering the item (or its
+destructured positions) on one element each. There is no row object to key, so every element's
+path is passed to the read:
+
+```js
+const faqs = bcmsTuples(bcmsLanding, [["faqs[0].dt-field", "faqs[0].dd-field"], …],
+                        [ …the original array, verbatim… ]);
+```
+
+`bcmsList` is the same for a list one wide. Each rendered element declares
+`` data-bcms-field={`faqs[${i}].<leaf>`} `` — the same templated path a repeater writes, so a
+second run reads it back and changes nothing — and the callback gains an index parameter, and a
+jsx row its `key`, if it had none.
+
+These arrays render exactly the paths this run wrote. Unlike `bcmsRows`, which reads the array
+itself, `bcmsList`/`bcmsTuples` map over that fixed path list — so every row's TEXT is editable and
+the NUMBER of rows is still the template's: a row added in the CMS has no path and never appears,
+and a row deleted falls back to the copy the template shipped with. The receipt says so out loud,
+once per array, as a `PRIMITIVE_LIST` note. Reading the array itself is the derive lane's job, not a
+fourth shape here.
+
+The lane refuses, by name: `IN_EXPRESSION` when the identifier is used anywhere but that one `.map`
+or is `export`ed (the read replaces the value everywhere, including in files this run cannot see),
+when the callback renders the item inside a larger expression, when an element is not a string
+literal, when one tuple position is text in one row and richtext in the next (one element has one
+sink), when the brief's paths do not cover EVERY element of the array, and when the paths are
+unrelated scalars rather than one group's rows — that last one could only be declared as an
+expression nothing downstream can verify; `REPEATER_AMBIGUOUS` when two loops iterate the array.
+
+**An array literal written INLINE in the markup is the same lane, with no name between the two
+halves.** `{['Offer', 'Structure', 'RTL'].map((item) => <li>…</li>)}` is what a template reaches
+for whenever the list is four words long — nobody lifts four bullet points into a `const` — and the
+copy then sits inside an expression the matcher is blind to by construction. The `]` immediately
+before the `.map(` IS the literal's close, so there is exactly one loop over it and nothing else in
+the file can hold a second reference to it: no "used anywhere but that one `.map`" test is needed,
+and everything else — the paths, the templated declaration, the index parameter, the refusals — is
+the named lane's. A value rendered BESIDE something else (`<li><span>✓</span>{item}</li>`) gets a
+`<span>` of its own rather than declaring on the parent, because a publish writing the value over
+the parent deletes the icon; the same wrap the scalar lane writes for a mixed element.
+
+**A row's leaf handed to a component is drilled, exactly as a scalar prop is.**
+`demos.map((demo) => <DemoCard title={demo.title} />)` renders the value in the COMPONENT's file,
+so the page's call site declares `` bcmsBindings={{ title: `cards[${i}].title` }} `` — one object
+per element, merged when a row hands two leaves to one component — and the component's element gets
+`data-bcms-field={bcmsBindings?.title}` with the prop added to its destructuring and its props
+type. `{...row}` counts as passing the prop: it is how most templates hand a row over. The group
+still binds whole or not at all, so a drill that misses (the component cannot be resolved, nothing
+in it renders the prop, this conversion already rewrites that file, or the call site already
+carries a `bcmsBindings`) refuses the WHOLE group by the drill's own reason.
+
 **An image is bound through its import, not through its url.** An image's `original` is the name
 the bundler minted (`/_astro/hero.do77EGgx_ZNfVA8.jpg`) — it exists in no file, and the asset
 itself is not a source candidate, so a text search can never find it. What survives the build is
@@ -468,14 +520,59 @@ the now-unused `bcms`/snapshot imports P2 added, and a page whose registered cal
 `<Sections>` keeps the imports of the components it used to call. They are harmless at build time
 and removing them would mean editing statements no section asked about.
 
+## Forms
+
+The third mode, and the shortest. The release-time derive lane reads every `<form>` in the built
+site and creates a DRAFT form per distinct shape, so the Forms tab fills on import while the
+repository's own markup goes on posting wherever it always did. `--forms` joins the two halves.
+
+```bash
+# after the import; the brief carries the project's forms
+npx @bettercms-ai/convert --forms --brief brief.json --root . --receipt forms-receipt.json
+git diff
+```
+
+```
+modify src/pages/contact.astro
+
+1 forms wired (0 already wired, 0 pending)
+  todo publish form Contact in the Forms tab — a draft form rejects every submission with 403.
+```
+
+It writes six things onto a matched `<form>` and nothing else: `action="<submitUrl>"`,
+`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.
+
+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
+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.
+
+`--receipt <file>` writes this run's own receipt (`forms-receipt.json` — a separate file from the
+P2 run's, since the two runs describe different work), and `--strict` exits 2 on any pending form.
+`--forms` and `--componentize` are separate runs; doing both in one command is refused.
+
+**Publish the drafts afterwards.** The lane creates forms as drafts and the public submit route
+403s a draft, so a wired draft form is an inviting form on a live site that rejects every
+submission. The receipt carries one `notes` line per draft naming the form to publish in the Forms
+tab; that is the step no codemod can do for you.
+
 ## Not here yet
 
-An array of PRIMITIVES — `const items = ["a", "b", "c"]`, or of tuples — whose elements the brief
-gave a separate NON-indexed path each (`li-field`, `li-rtl`, …) rather than one repeater group.
-There is no group to key and no constant to rewrite, so those stay `IN_EXPRESSION`; what would fix
-them is the derive lane minting the group, not a third shape here. Svelte and vue data literals are
-not converted either — both lanes are written against the two dialects that keep their module and
-their markup in one file with an AST this package already holds.
+GROWABLE lists. An array of primitives or tuples is bound (above) but renders the number of rows
+the template shipped with, because the read maps over a fixed path list rather than over the CMS
+array — and when the brief gave its elements unrelated scalar paths (`li-field`, `li-rtl`, …)
+rather than one group's rows, it is not bound at all: the only declaration that could carry a
+different path per row is an expression, and one nothing downstream can verify is worse than the
+honest `IN_EXPRESSION`. Both are the same fix on the derive side — minting the group — not a
+further shape here. Svelte and vue data literals are not converted
+either; all three lanes are written against the two dialects that keep their module and their
+markup in one file with an AST this package already holds.
 
 SHARED CHROME the brief still calls page copy. A header rendered by one component that nine routes
 each declare a `nav[0].label` for is nine targets on one element, and there is no honest binding: a