@bettercms-ai/convert 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @bettercms-ai/convert
 
+## 0.10.0
+
+### Minor Changes
+
+- ac3a9ff: Declare the shapes the derive lane mints for every visible body tag: a heading whose styled run is
+  part of its value (`richtext inline`, bound whole rather than wrapped around its text node), a
+  standalone `span`/`time`/`small`/`label`/`option` leaf, a `<pre>` code block (the `<pre>` is the
+  field, not the `<code>` inside it), and a group row whose optional leaf is empty (covered by its
+  own route's templated declaration instead of reported `NO_ORIGINAL`). A heading split by a `<br />`
+  is found again: its value carries no space, because no text node holds one.
+
+  An inline heading the lane cannot own whole — its element holds a component, a `<slot>` or an
+  expression, which no stored string can re-emit — is refused by name (`SUBTREE_NOT_HTML`) instead of
+  being bound over the top of it.
+
+  New `--xray <dist-dir>` mode: how much of each built page's visible copy no binding owns, and the
+  biggest buckets of it, so the loop is build -> measure -> fix -> build with no deploy in it.
+
+## 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

package/README.md

@@ -38,6 +38,27 @@ Exit codes: `0` done — the pending list is printed, not hidden; `1` something
 | `--strict` | exit 2 when any path is pending. |
 | `--overwrite-helper` | replace a `bcms-content` helper whose bytes this tool did not write — including one of ours that has since been edited. |
 | `--verbose` | stack traces, and every file considered. |
+| `--xray <dist-dir>` | a mode of its own: measure a LOCAL build instead of converting one. |
+
+### `--xray` — what is not editable
+
+A receipt says what the codemod bound. It cannot say what it was never asked to bind, so a site can
+report full coverage while a quarter of its visible text is unreachable from the editor. `--xray`
+walks a build and counts that, per page, with no deploy in the loop:
+
+```bash
+npm run build && npx @bettercms-ai/convert --xray dist
+```
+
+```
+docs/index.html  visible=3512 unaddressable=701 (20.0%)
+     379ch    4n  code @ main  e.g. "const site = { direction: 'rtl', language: 'ar'," | "npm install"
+     188ch   12n  span @ main>ul  e.g. "Performance" | "100"
+```
+
+Glyphs, ordinals, the platform badge and skip links are excluded from BOTH halves of the ratio —
+counting them would put a floor under every route that no amount of binding could lift. `--strict`
+exits 2 while any page is above 2 %. It takes no `--brief`: it measures, it does not convert.
 
 ## What it actually does
 
@@ -152,6 +173,8 @@ rendering that binding — `<img>`, `<source>`, `<video poster>`, or `<Image>`/`
 different paths share a sentence and position cannot separate them (both are skipped; the rest of
 the file still converts), `SUBSTRING_ONLY`, `IN_SCRIPT_OR_COMMENT`, `KIND_MISMATCH`,
 `REPEATER_AMBIGUOUS` (one array declaration, two loops over it — the row has two homes),
+`SUBTREE_NOT_HTML` (an INLINE richtext heading whose element holds a component, a `<slot>` or an
+expression: its whole subtree is the value and no stored string can re-emit that),
 `IMAGE_ASSET_UNRESOLVED`, `PARSE_ERROR`. `NOT_IN_SOURCE` is reserved for what it says: a path
 `locate` found in a file is `IN_EXPRESSION` when it sits in the module region or an expression
 node, and where `NOT_IN_SOURCE` is still the answer the row names the file it was found in. And
@@ -520,6 +543,48 @@ 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
 
 GROWABLE lists. An array of primitives or tuples is bound (above) but renders the number of rows