@bettercms-ai/mcp 0.25.2 → 0.27.0

package/dist/index.js

@@ -3183,6 +3183,16 @@ function buildToolDefs(deps) {
         z.object({ declaredBindings: z.boolean().describe("true = trust the template's declared bindings; false = text-match (the default)") }).shape,
         async (c, a) => ok("Recorded the binding mode.", await data(c, "PATCH", `/management/projects/current/binding-mode`, { declaredBindings: a.declaredBindings }))
       ),
+      def(
+        "submit_conversion_receipt",
+        "Record what the conversion codemod could and could not do",
+        "Hand BetterCMS the codemod's own account of a conversion run, so the coverage meter can say WHY a path is not declared instead of only that it is not. Submit the receipt `npx @bettercms-ai/convert` wrote (`--receipt out.json`) for the SAME `briefDigest` get_conversion_brief { complete: true } returned: `{ briefDigest, receipt }`, where the receipt carries `paths: { declared, rewritten, alreadyDeclared, pending[{ route, scope, path, kind, file, reason, message }] }`. `paths.declared` must equal rewritten + alreadyDeclared + pending.length, and each pending `reason` is one of the converter's own (IN_EXPRESSION, AMBIGUOUS_LITERAL, REPEATER_FIXED_LENGTH, PARSE_ERROR, \u2026) \u2014 a path with no receipt row simply reads `not-declared`. It is a RECORD, not a release: it changes nothing about the site, and the meter picks it up on the next get_binding_report after the next deploy. A 404 `unknown-brief` means that digest was never issued here, so convert against a brief this project actually returned. Requires a project-scoped connection carrying artifact:write, the same authority as set_binding_mode.",
+        z.object({
+          briefDigest: z.string().min(1).describe("The `briefDigest` get_conversion_brief { complete: true } returned. Must match the receipt's own."),
+          receipt: z.record(z.string(), z.unknown()).describe("The receipt `npx @bettercms-ai/convert --receipt out.json` wrote, verbatim.")
+        }).shape,
+        async (c, a) => ok("Recorded the conversion receipt.", await data(c, "POST", `/management/projects/current/conversion-receipt`, { briefDigest: a.briefDigest, receipt: a.receipt }))
+      ),
       def(
         "clone_project",
         "Clone a project",
@@ -3302,9 +3312,19 @@ function buildToolDefs(deps) {
       def(
         "get_conversion_brief",
         "Get the brief for making this site's bindings durable",
-        "The per-project brief for making this site's bindings DURABLE \u2014 read it before you touch the templates. Returns what already exists in the CMS: every live page with its route, and every bindable field path with its `label`, `kind`, the value the CMS holds now (`current`) and the copy the repo renders today (`original`, the field's defaultValue) \u2014 plus the exact attributes to declare, and the ordered steps. Call it for any site whose pages were DERIVED at import, and whenever get_next_steps reports `bindings-not-declared`. It REPLACES re-registering a schema: these pages, fields and values exist already, so create_page / add_page_field / create_content_model would build a second schema over the first \u2014 edit values with set_page_content instead. `lane` says how to get the source ('git-connected' = pull_project_source returns a repo; 'archive' = a tarball). The full recipe is section 13 of the bettercms://playbook/schema resource; get_binding_report is the receipt that says you finished.",
+        "The per-project brief for making this site's bindings DURABLE \u2014 read it before you touch the templates. Returns what already exists in the CMS: every live page with its route, and every bindable field path with its `label`, `kind`, the value the CMS holds now (`current`) and the copy the repo renders today (`original`, the field's defaultValue) \u2014 plus the exact attributes to declare, and the ordered steps. Call it for any site whose pages were DERIVED at import, and whenever get_next_steps reports `bindings-not-declared`. It REPLACES re-registering a schema: these pages, fields and values exist already, so create_page / add_page_field / create_content_model would build a second schema over the first \u2014 edit values with set_page_content instead. `lane` says how to get the source ('git-connected' = pull_project_source returns a repo; 'archive' = a tarball). The full recipe is section 13 of the bettercms://playbook/schema resource; get_binding_report is the receipt that says you finished. Pass `complete: true` when you are about to run the CODEMOD (`npx @bettercms-ai/convert`): that returns the brief UNCAPPED and paged \u2014 nothing truncated, no page omitted \u2014 and pins the full path list under a `briefDigest`, which is the list the coverage meter in get_binding_report measures the build against. Follow `cursor` until it stops coming back; a 409 `BRIEF_CHANGED` means the brief was re-derived while you paged, so start again.",
+        z.object({
+          complete: z.boolean().optional().describe("true = the COMPLETE brief for a codemod: nothing truncated, no page omitted, paged 50 pages at a time. Page 1 pins the path list the coverage meter measures against."),
+          cursor: z.string().optional().describe("The `cursor` from the previous page. Implies complete. A 409 BRIEF_CHANGED means the brief was re-derived mid-pagination \u2014 start again with no cursor.")
+        }).shape,
+        async (c, a) => ok("Conversion brief.", await data(c, "GET", `/management/projects/current/conversion-brief${q({ complete: a.complete, cursor: a.cursor })}`))
+      ),
+      def(
+        "get_conversion_plan",
+        "Get the approved conversion to apply",
+        "The APPROVED conversion a human reviewed in the BetterCMS dashboard: the exact new contents of each template file, already checked against this project's real field paths. Apply it instead of writing the bindings by hand. Check out `baseHeadOid` (the exact commit it was written against \u2014 a plan applied to a different base is a different change), branch from there, write each file's `content` verbatim (whole file, no merge, no reformatting), then push or deploy however this project ships. `stale.head` / `stale.brief` say the repository or the CMS moved since it was approved: stop and ask for a fresh proposal rather than applying it anyway. `receipt.paths.pending` lists every field the codemod could NOT bind, each with a reason (`DIALECT_UNSUPPORTED`, `PROP_TARGET_NOT_FOUND`, `REPEATER_FIXED_LENGTH`, \u2026) \u2014 apply the plan first, then bind those by hand. Finish the loop the same way as a hand conversion \u2014 get_binding_report until `unmatched` is empty, then set_binding_mode { declaredBindings: true } and release once more. 404 with `code: \"no-approved-plan\"` means nobody has approved one: use get_conversion_brief and do the conversion yourself. Requires a project-scoped connection carrying artifact:write.",
         z.object({}).shape,
-        async (c) => ok("Conversion brief.", await data(c, "GET", `/management/projects/current/conversion-brief`))
+        async (c) => ok("Approved conversion plan.", await data(c, "GET", `/management/projects/current/conversion-plan`))
       ),
       def(
         "get_analytics_overview",
@@ -4314,6 +4334,41 @@ first: it lists those pages, their routes, every bindable path with its current
 value, and the attributes to declare. SKIP steps 3 and 4 below and bind the keys it names \u2014
 registering the schema again builds a second one over the first.
 
+**Run the CODEMOD rather than editing by hand.** For a derived site the whole of step 5 is
+mechanical, and there is a tool that does it. THE ORDER, and every step of it matters:
+
+1. \`get_conversion_brief { complete: true }\` \u2014 the COMPLETE brief, not the capped one. It comes
+   back uncapped and paged (50 pages at a time): follow \`cursor\` until it stops coming back and
+   keep every page. The capped read truncates values and omits pages, and a codemod fed a
+   truncated \`original\` searches the source for a string that is not there. Page 1 PINS the
+   path list under a \`briefDigest\`; that pinned list is what the coverage meter measures the
+   build against, so nothing later can move the denominator. A 409 \`BRIEF_CHANGED\` mid-pagination
+   means the brief was re-derived under you \u2014 start again with no cursor.
+2. Write the pages you collected to \`brief.json\` and run
+   \`npx @bettercms-ai/convert --brief brief.json --root . --receipt receipt.json\`, then read
+   \`git diff\`. It rewrites the templates to read from BetterCMS, keeps the in-code copy as the
+   fallback, and declares each binding.
+3. REVIEW THE PENDING LIST. Every path the codemod could not do is in \`paths.pending\` with a
+   reason (\`IN_EXPRESSION\`, \`AMBIGUOUS_LITERAL\`, \`REPEATER_FIXED_LENGTH\`, \`PARSE_ERROR\`, \u2026).
+   Do those by hand, or decide they are genuinely not convertible \u2014 do not skip past them.
+4. \`submit_conversion_receipt { briefDigest, receipt }\` with the receipt file, verbatim. This is
+   what lets the coverage meter say WHY a path is undeclared instead of only that it is; without
+   it every one of them reads \`not-declared\`, which looks like a broken site rather than work
+   with a reason. It records and releases nothing.
+5. Push, or \`deploy_project\`, and wait for the release to be live (step 6 below).
+6. \`get_binding_report\`. Alongside \`unmatched\` it now carries \`coverage\` \u2014 \`declared\` (what the
+   brief listed), \`bound\` (what the build declares) and \`pending\` with the reasons. Fix what it
+   names and release again until \`coverage.pending\` is empty.
+7. \`set_binding_mode { declaredBindings: true }\` and release ONE MORE TIME \u2014 the mode applies to
+   the next release, not to the one already out.
+
+**Or let BetterCMS propose the edit.** \`get_conversion_plan\` returns an APPROVED conversion \u2014 the
+exact new contents of each template file, reviewed by a human in the dashboard and already checked
+against this project's real field paths. When there is one, apply it instead of doing step 5 by
+hand: check out its \`baseHeadOid\`, branch from there, write each file's \`content\` verbatim, and
+carry on from step 6. A 404 with \`code: "no-approved-plan"\` means nobody approved one, so the
+conversion is yours to write.
+
 **The steps.**
 
 1. \`pull_project_source\` (or clone the \`github\` remote it returns). Read the SOURCE. Never
@@ -4342,9 +4397,20 @@ registering the schema again builds a second one over the first.
    Prefer schema-derived bindings \u2014 the TypeGen analogue:
    \`npx @bettercms-ai/codegen --bindings-out src/bettercms.bindings.generated.ts\`, then spread
    \`{...bcms.home.hero.title}\` / \`{...bcms.blog.features.$(i)}\`. The hand form is
-   \`data-bcms-field="<path>"\` (plus \`data-bcms-kind="richtext"|"image"\`), \`data-bcms-props\`
-   for an \`href\` / \`alt\` / \`src\`, the \xA711 layout markers for nav and footer, and
-   \`<div data-bcms-field="body" data-bcms-kind="document">\` around a Portable Text render.
+   \`data-bcms-field="<path>"\` (plus \`data-bcms-kind="richtext"|"image"\`), the \xA711 layout markers
+   for nav and footer, and \`<div data-bcms-field="body" data-bcms-kind="document">\` around a
+   Portable Text render.
+   **A value that lives in an ATTRIBUTE \u2014 an \`href\`, an \`alt\`, an \`src\` \u2014 rides
+   \`data-bcms-props\`, and its grammar is PIPES, NOT JSON:**
+   \`data-bcms-props="<path>|<kind>|<domAttribute>"\`, semicolon-separated for several on one
+   element, where \`kind\` is \`text | richtext | image | url | number | array\`. A link is
+   \`data-bcms-props="cta.url|url|href"\`; an image's alt text is
+   \`data-bcms-props="hero.image.alt|text|alt"\`; an \`<a>\` wrapping an \`<img>\` carries both as
+   \`data-bcms-props="cta.url|url|href;hero.image.alt|text|alt"\`. A JSON object there parses to
+   NOTHING \u2014 the reader splits on \`;\` and \`|\` and drops what does not match \u2014 so the value stays
+   uneditable and the binding report never mentions it. The SDK helpers
+   (\`@bettercms-ai/astro\`, \`@bettercms-ai/next\`) and \`@bettercms-ai/codegen\` emit this form
+   for you; write it by hand only when you are not using them.
    Bind CONDITIONALLY (\`fromCms ? path : undefined\`) so a fallback row is never bound. A value
    rendered in N places carries the binding on ALL N \u2014 the editor keeps the copies in sync.
    **Read the LIVE SCHEMA before you bind \u2014 \`get_page\` / \`get_content_model\`, never the
@@ -4368,11 +4434,13 @@ registering the schema again builds a second one over the first.
       one the site renders its fallbacks and the report says \`no-element\` for every path.
 6. Push, or \`deploy_project\`; poll \`get_deploy_status\` until it is live. Then
    \`get_binding_report\` \u2014 still \`text-match\`, and \`unmatched\` should be EMPTY because the
-   values are byte-equal to what the build renders. Now \`set_binding_mode
+   values are byte-equal to what the build renders. On a converted site read \`coverage\` too: it
+   counts the PINNED brief's paths, which \`unmatched\` cannot, because \`unmatched\` only ever
+   speaks about fields that already hold a value. Now \`set_binding_mode
    {declaredBindings: true}\` and release again (an empty commit is enough). Do not flip before
    the report is clean: in declared mode an undeclared field simply stops being editable.
-7. **Receipts.** \`get_binding_report\` reads \`mode: "declared"\`, \`unmatched: []\`, and
-   \`bound > 0\`. That certifies one thing only \u2014 that every non-empty field has SOME element
+7. **Receipts.** \`get_binding_report\` reads \`mode: "declared"\`, \`unmatched: []\`,
+   \`bound > 0\`, and \u2014 for a site converted against a pinned brief \u2014 \`coverage.pending: []\`. That certifies one thing only \u2014 that every non-empty field has SOME element
    carrying its path. It CANNOT see copy that was never modelled, so diff each route's visible
    text against its entry values yourself before you call the page done. Then publish, and
    fetch the live URL cache-busted (\xA712: publish and deploy are separate claims).