@bettercms-ai/mcp 0.31.0 → 0.32.0

package/dist/index.js

@@ -2965,7 +2965,7 @@ function buildToolDefs(deps) {
       def(
         "deploy_project",
         "Deploy new source/build",
-        "Deploy new source/build for the connected project and make it live at its <handle>.bettercms.site. Pass a .tgz or .zip of the project as a base64 string in `data`: SOURCE (has package.json) is built server-side in an isolated sandbox; a prebuilt static site is served as-is. Returns the release id + sha \u2014 then poll get_deploy_status until it is live. IMPORTANT \u2014 you MUST exclude node_modules, .git, and build output/caches (dist, build, .next, .astro, .cache) BEFORE creating the archive: a source deploy is reinstalled and built server-side, so those are never needed, and the upload has a hard size ceiling (~100 MB) enforced before the request reaches the server \u2014 an archive that includes node_modules is rejected in transit (a 413/502 with no server-side detail). Keep the archive to your own source files. Server-side stripping exists as a safety net, but it runs AFTER the upload and cannot rescue an over-limit body. For a LARGE archive (or if this returns a 413/502), use create_deploy_upload + deploy_from_upload instead \u2014 that path uploads straight to storage with no size ceiling.",
+        "Deploy new source/build for the connected project and make it live at its <handle>.bettercms.site. Pass a .tgz or .zip of the project as a base64 string in `data`: SOURCE (has package.json) is built server-side in an isolated sandbox; a prebuilt static site is served as-is. Returns the release id + sha \u2014 then poll get_deploy_status until it is live. IMPORTANT \u2014 you MUST exclude node_modules, .git, and build output/caches (dist, build, .next, .astro, .cache) BEFORE creating the archive: a source deploy is reinstalled and built server-side, so those are never needed, and the upload has a hard size ceiling (~100 MB) enforced before the request reaches the server \u2014 an archive that includes node_modules is rejected in transit (a 413/502 with no server-side detail). Keep the archive to your own source files. Server-side stripping exists as a safety net, but it runs AFTER the upload and cannot rescue an over-limit body. For a LARGE archive (or if this returns a 413/502), use create_deploy_upload + deploy_from_upload instead \u2014 that path uploads straight to storage with no size ceiling. Returns `canvas.lane` \u2014 which live-preview lane the last release gave the editor (`bridge` / `draft-route` / `none`; see the playbook's section 11) \u2014 and `editorUrl`, the visual editor to hand the user.",
         z.object({ data: z.string().min(1).describe("base64 .tgz/.zip of the project"), mimeType: z.string().optional() }).shape,
         async (c, a) => ok("Deploy queued.", await raw(c, `/management/projects/deploy`, s(a.data), a.mimeType))
       ),
@@ -3008,7 +3008,7 @@ function buildToolDefs(deps) {
       def(
         "get_binding_report",
         "Check what on the live site is editable",
-        "The receipt for 'is this site actually EDITABLE?'. Every release scans the built HTML for the element that renders each CMS field value; this returns what that scan found, per slot: `mode` ('text-match' = bindings guessed from rendered text, 'declared' = the template declares them), `pagesInspected`, `bound` (elements carrying a binding), and `unmatched` \u2014 per page, each path with its kind and the reason it failed (not-declared / ambiguous-text / no-element). DEPLOY FIRST: before any release there is no report and this answers pages 0, mode null, refreshRequired true. It certifies exactly one thing \u2014 that every non-empty field of every page 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 calling a page done. Pass `slot` ('current' or 'staging') to read the other tree; the default is the slot this project's releases land in.",
+        "The receipt for 'is this site actually EDITABLE?'. Every release scans the built HTML for the element that renders each CMS field value; this returns what that scan found, per slot: `mode` ('text-match' = bindings guessed from rendered text, 'declared' = the template declares them), `pagesInspected`, `bound` (elements carrying a binding), and `unmatched` \u2014 per page, each path with its kind and the reason it failed (not-declared / ambiguous-text / no-element). DEPLOY FIRST: before any release there is no report and this answers pages 0, mode null, refreshRequired true. It certifies exactly one thing \u2014 that every non-empty field of every page 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 calling a page done. `builtRoutes` lists the routes the live build has HTML for (null when unknown: runtime release, >500 routes, or a report older than this field). `canvas.lane` names the live-preview lane this build gives the editor \u2014 `bridge` (the build ships BcmsDraftBridge), `draft-route` (a node runtime rendering drafts server-side) or `none`, in which case get_next_steps carries the recipe (playbook section 11); null means the report predates the field. `unaddressable` counts visible text on the live site that no field owns, as the editor's x-ray measured it against the sha now serving \u2014 the one thing `unmatched` structurally cannot see; absent means nobody has turned that control on for this build. `unaddressable` is measured PER SLOT by the editor, which frames `current`; on a promote-gated project pass slot:'current' to read it. Pass `slot` ('current' or 'staging') to read the other tree; the default is the slot this project's releases land in.",
         z.object({ slot: z.enum(["current", "staging"]).optional().describe("which release tree to read; defaults to the one this project deploys to") }).shape,
         async (c, a) => ok("Binding report.", await data(c, "GET", `/management/projects/current/binding-report${q({ slot: a.slot })}`))
       ),
@@ -3218,7 +3218,7 @@ function buildToolDefs(deps) {
       def(
         "get_deploy_status",
         "Get deploy/build status",
-        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. Poll this after deploy_project until state is idle with your sha live.",
+        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. Poll this after deploy_project until state is idle with your sha live. Also returns `canvas.lane` (the editor's live-preview lane for this site: `bridge` / `draft-route` / `none`) and `editorUrl`, the visual editor to hand the user.",
         z.object({}).shape,
         async (c) => ok("Deploy status.", await data(c, "GET", `/management/projects/deploy-status`))
       )
@@ -3984,6 +3984,10 @@ in this order:
     4. list_extraction_candidates / extract_component
                              now that blocks exist, fold any section repeated 3+ times
 
+Step 2 is not a formality: \`componentize_sections\` and \`create_component\` both land components
+as DRAFTS, so \`publish_component\` each one and publish the page \u2014 otherwise the canvas keeps
+painting the PUBLISHED copy and the editor reports N components unpublished.
+
 **Answering \`fields\` is a real answer, not a deferral.** A blog, a catalogue or a directory
 is schema-first by design (\xA71) and should stay that way. Say so and move on.
 
@@ -3996,16 +4000,38 @@ the user rather than describing the choice in the abstract.
 A deploy makes a site LIVE. It does not make it editable \u2014 those are different states, and the
 gap between them is the single most common disappointment after an import.
 
-**The canvas is the real site when it can be.** When a page's draft matches its published copy
-structurally, the visual editor frames the project's OWN deployed build and paints unpublished
-text over it. Structural drafts (new sections, unpublished pages, changed components) render on
-the platform's own renderer instead \u2014 and that renderer previews in a GENERIC theme unless the
-deploy artifact declares \`bcms-presentation.json\` at its root. Put the file in \`public/\`
+**The canvas is the real site.** A PUBLISHED page of a DEPLOYED site with DECLARED bindings
+frames the project's OWN build, with unpublished text painted over it, whether or not the draft
+has drifted from the published copy. STRUCTURAL drafts (new
+sections, reordering, a changed component definition) are the one thing that build cannot show,
+and there are four ways to see them: publish and redeploy; the editor's **Draft render** toggle,
+which swaps in the platform renderer on demand (approximate theme, one click back); live, through
+the draft bridge below (Next); or \u2014 for server-rendered sites \u2014 the node lane, coming.
+
+Only FOUR states use the platform renderer by default: an UNPUBLISHED page, a page whose route
+the last build does not carry (\`get_binding_report.builtRoutes\`), a project with NO build at
+all, and a \`mode: "text-match"\` site whose draft has drifted (its elements are found by matching
+page text to stored values, so drifted text may be unclickable \u2014 declare the bindings, \xA713).
+Those are exactly where \`bcms-presentation.json\` matters \u2014 the renderer previews in a
+GENERIC theme unless the deploy artifact declares one at its root. Put the file in \`public/\`
 (the build lands it at the artifact root) declaring the site's presentation \u2014 container width,
 type scale, nav position and background, footer surface \u2014 as DTCG \`{"$type": ..., "$value": ...}\`
 entries. Redeclare it on every deploy; absent means "declared nothing" and previews fall back
 to platform defaults that will not look like this site.
 
+**Which live-preview lane THIS site has, and what it costs not to have one.**
+\`get_binding_report.canvas.lane\` names it: \`bridge\` (the build ships \`BcmsDraftBridge\` from
+\`@bettercms-ai/next/draft-bridge\`, so a structural draft re-renders inside the site's own
+build), \`draft-route\` (a node runtime whose app renders drafts server-side), or \`none\` \u2014 no
+lane, so every structural draft falls back to the platform renderer and its generic theme.
+\`null\` means the report predates the field; redeploy to learn. When it is \`none\`,
+\`get_next_steps\` names the recipe for this project's framework (\`canvas-lane-missing\`), and
+\xA713 step 5c has both. The same report carries \`unaddressable\`: how much VISIBLE text on the
+live site no field owns, counted against the sha now serving when an author turns the visual
+editor's **"Unbound text"** control on \u2014 \`unmatched\` cannot see it, because it only ever speaks
+about fields that already exist. Absent means nobody has turned that control on for this build,
+not that the site is clean.
+
 **A site built in the CMS with NO deployed build has only that renderer** \u2014 live and in the
 editor \u2014 so the generic theme IS the site until you theme it. Theme it without a deploy:
 \`update_project { presentation: { "page.maxWidth": { "$type": "dimension", "$value": 1200 },
@@ -4059,13 +4085,14 @@ renders. Three consequences, each load-bearing:
        content. Div-built chrome outside \`<main>\` is still excluded; div-built chrome with no
        \`<main>\` anywhere loses that protection.
 
-**Structural drafts can render on the real site too \u2014 the draft bridge.** Wrap your page's
+**Structural drafts can render on the real site too, LIVE \u2014 the draft bridge.** Wrap your page's
 blocks in \`BcmsDraftBridge\` (\`@bettercms-ai/next/draft-bridge\`) instead of calling
 \`BcmsBlocks\` directly: standalone it renders identically, and inside the visual editor it
 receives the DRAFT block tree over a same-origin postMessage handshake and re-renders it with
 the site's own components \u2014 so adding, removing or reordering sections previews in the site's
-real design instead of the platform's approximate renderer. Sites without the bridge keep the
-approximate fallback; unpublished ROUTES always fall back (a static build has no file to frame).
+real design, with no publish and no Draft render detour. A bridge that answers wins over the
+toggle. Sites without one keep Draft render's approximate fallback, and a route the build does
+not carry falls back always (a static build has no file to frame).
 
 **Hosting decides whether a canvas exists at all.** A site deployed here is framed through a
 same-origin proxy \u2014 that is what the canvas requires. A site hosted elsewhere (your own Vercel,
@@ -4226,6 +4253,17 @@ conversion is yours to write.
       and no network content step, by design. So the archive MUST SHIP its own
       \`bcms-content.json\` \u2014 generate it locally with a delivery key and commit it. Without
       one the site renders its fallbacks and the report says \`no-element\` for every path.
+5c. **Live preview lane.** Static HTML makes a page click-to-edit; it cannot show a STRUCTURAL
+    draft \u2014 a new section, a reorder, a changed component \u2014 so those fall back to the platform
+    renderer's generic theme unless the build can render drafts itself. Give it a lane:
+    - NEXT: wrap the page's \`BcmsBlocks\` in \`BcmsDraftBridge\` from
+      \`@bettercms-ai/next/draft-bridge\` and redeploy. The bridge marks its output
+      \`data-bcms-canvas="bridge"\`, which is what the release scan records.
+    - ASTRO: switch the pages to \`output: 'server'\` with the node adapter, mount
+      \`@bettercms-ai/astro\`'s draft routes under \`src/pages/api/bcms/draft/\`, set
+      \`BCMS_DRAFT_SECRET\`, redeploy, then switch the project to "Run as a server app" on the
+      Hosting page. Never migrate a static site to SSR without asking the human first.
+    Then \`get_binding_report.canvas.lane\` reads \`bridge\` or \`draft-route\` instead of \`none\`.
 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. On a converted site read \`coverage\` too: it