@bettercms-ai/convert 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @bettercms-ai/convert
+
+Turn an imported site's text-matched bindings into **declared** ones — deterministically, and with
+a receipt of everything it could not do.
+
+BetterCMS can already make an imported site editable by matching text: a release reads the built
+HTML, finds the element whose text equals a field's value, and binds it. That works until someone
+edits the copy, at which point the match is gone and the field quietly stops reflecting. The fix is
+for the template itself to say which element holds which field — `data-bcms-field` — and to read the
+value from the CMS with the current copy as its in-code fallback. This package does that edit.
+
+## Use it
+
+```bash
+# In your site repo, with the brief from get_conversion_brief
+npx @bettercms-ai/convert --brief brief.json --root .
+git diff
+```
+
+```
+modify src/pages/index.astro
+add    src/bcms-content.ts
+add    bcms-content/home.json
+
+10 of 11 paths bound (0 already declared, 1 pending)
+  pending /about p-founded-in-2019-in — DIALECT_UNSUPPORTED (src/data/facts.js)
+```
+
+Exit codes: `0` done — the pending list is printed, not hidden; `1` something was refused;
+`2` only with `--strict`, when any path is left pending. That last one is for CI.
+
+| flag | |
+|---|---|
+| `--brief <file>` | the brief, as `get_conversion_brief` returns it. Required. |
+| `--root <dir>` | the repository to convert. Nothing outside it is ever read or written. |
+| `--dry-run` | print what would change; write nothing. |
+| `--receipt <file>` | write the receipt as JSON. |
+| `--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. |
+
+## What it actually does
+
+**Parser offsets in, one `magic-string` splice out.** The tree is never re-serialised, so your
+formatting, comments and directives survive and the diff is one a human can read. `parse5` reads
+html, `@astrojs/compiler` reads astro, `@babel/parser` reads jsx/tsx, `svelte/compiler` reads
+svelte and `@vue/compiler-sfc` reads vue — five dialects, one neutral tree, one matcher.
+
+**Values are read at BUILD time, page-scoped.** A converted page statically imports
+`bcms-content/<page>.json` and calls a ~30-line helper this package commits. Every bundler resolves
+that at build time — no `fs`, no fetch, no key, and only that page's content can reach its bundle.
+The committed stubs are `{}`, so a build with them renders every fallback and still succeeds; the
+platform overwrites them before a real build. The consequence is worth stating plainly: outside the
+visual editor, seeing an edit means a rebuild.
+
+**Three tiers per file, and a file is exactly one of them.** The dialect's parser; failing that, a
+tolerant pass that will only place a literal occurring exactly once between a `>` and a `<`; failing
+that, an injected `llmFallback` whose output is accepted only if it re-parses and declares exactly
+the paths that were asked for. The CLI injects none — the agent running it is tier 3.
+
+**Everything it will not do has a name.** `AMBIGUOUS_LITERAL` when two 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`, `NOT_IN_SOURCE`, `PARSE_ERROR` — and the
+receipt's arithmetic is checked, not hoped for:
+
+```
+paths.declared === paths.rewritten + paths.alreadyDeclared + paths.pending.length
+```
+
+A path counts as rewritten only when EVERY located occurrence of it was. A value rendered by both
+the home page and a shared header is two places a reader sees it, and converting one of them reads
+as a finished job.
+
+## As a library
+
+```ts
+import { convertSources } from "@bettercms-ai/convert";
+
+const { files, receipt } = await convertSources(brief, sources);
+```
+
+Pure: no filesystem, no network, no credential, no clock. `cli.ts` is the only module that touches a
+disk. That is what lets the interesting half — which element holds which path, and why one could not
+be found — be tested without a repository.
+
+**A repeater becomes a loop, not three stamps.** Three identical siblings the derive lane called
+`cards[i].*` are rewritten as one row inside the dialect's loop, reading
+`bcmsRows(page, "cards", [ …every row's copy… ])` — so a card added in the dashboard renders, and a
+build against the committed stub still renders the three the repository has. The bindings there are
+template literals (`` data-bcms-field={`cards[${i}].title`} ``), the receipt lists each one, and the
+proposer re-derives them from its own scan rather than believing the receipt. A group that cannot
+become a loop — non-consecutive siblings, one row shaped differently, the html dialect — is still
+declared and read per index and reported `REPEATER_FIXED_LENGTH`.
+
+**A prop-drilled literal is converted in two hops, in one proposal.** `<Hero title="…" />` becomes
+`title={bcms(…)}` plus `bcmsBindings={{ title: "hero.title" }}`, and the `<h1>{title}</h1>` inside
+`Hero` — resolved through the file's own imports, relative or through the project's tsconfig
+`paths` — gets `data-bcms-field={bcmsBindings?.title}`, the prop added to its destructuring, and
+`bcmsBindings?: Record<string, string>` added to its `Props` type when it has one. A chain through
+intermediate components is followed for four components — including a `{...props}` spread, which is
+how most of them forward — with the object handed over explicitly at each call site; deeper is
+`PROP_DRILLED_DEEP`. Which component is analysed comes from the IMPORT, so a module exporting a
+`Hero` and a `HeroSkeleton` gets the declaration on the one the page renders. If the component cannot be resolved or nothing in it renders the prop, hop
+1 still reads from the CMS, the bindings prop is DROPPED, and the path is `PROP_TARGET_NOT_FOUND`.
+
+**The shared chrome is one field, not one per route.** A path the brief marks `scope: "layout"` is
+read with `bcmsLayout("<address>", "…")` and declared on `data-bcms-layout-field` — the chrome
+lane's own attribute, so the block lane's `[data-bcms-field]` query cannot reach it — and it is
+counted once however many pages list it.
+
+**A dynamic route reads its own entry.** `[slug].astro` appends `Astro.params.slug`, SvelteKit
+`$page.params.slug` (importing the store), Nuxt `useRoute().params.slug`. A Next `[slug]/page.tsx`
+gets a TYPED `{ params }: { params: Promise<{ slug: string }> }` on its page component, is made
+`async` if it is not already, and reads `(await params).slug` — because `params` is a promise, and
+reading `.slug` off one is `undefined` on every request. A `"use client"` page cannot be made async
+and a signature this cannot edit is not guessed at: both are `DYNAMIC_PARAMS_UNAVAILABLE` and are
+left alone. A repeater on a dynamic route passes the same parameter to `bcmsRows`.
+
+## Not here yet
+
+`promoteSharedChrome`, and prop drilling through a svelte or vue component (both parse, and both
+bind their own copy; only `findPropTargets` is jsx/astro-only, so a drilled prop there is
+`PROP_TARGET_NOT_FOUND` rather than a wrong edit).