@bettercms-ai/mcp 0.41.1 → 0.43.0

package/dist/index.js

@@ -2273,6 +2273,11 @@ function toField(f) {
     ...f.config ? { config: f.config } : {}
   };
 }
+var STRUCTURE_NOTE = 'ORGANISATION ONLY: folders never change a URL, slug, content or publish state, and nothing is rebuilt or delivered. Folders nest at most 4 levels deep (a page or collection may sit in a level-4 folder). Icons are lucide icon names, e.g. "folder", "file-text", "rows-3", "house" (a-z, 0-9 and dashes); null clears one.';
+function structureResult(d) {
+  const message = d?.message;
+  return ok(typeof message === "string" ? message : "Updated the Content structure.", d);
+}
 function ok(summary, data) {
   return {
     content: [
@@ -2927,6 +2932,94 @@ function buildToolDefs(deps) {
         z.object({ formId: z.string().min(1), submissionId: z.string().min(1) }).shape,
         async (c, a) => ok("Deleted submission.", await data(c, "DELETE", `/management/forms/${s(a.formId)}/submissions/${s(a.submissionId)}`))
       ),
+      // ── Content structure: the Content sidebar's folders and icons (CPO-127 f) ──
+      def(
+        "get_content_structure",
+        "Get the Content sidebar structure",
+        `Read the Content sidebar's structure for the connected project: its folders, which pages and collections sit in each, and their icons. Returns { doc, version, summary }: \`doc\` is the raw document ({ schema: 1, folders: [{ id, parentId, name, icon, sort }], items: [{ kind: 'page'|'collection', id, folderId, sort, icon }] }), \`version\` is what set_content_structure needs, and \`summary\` is the resolved tree with page and collection TITLES (\`outline\` is a readable version), ids that no longer resolve (\`missing\`), and the pages and collections not in any folder yet. Call it before changing the structure. ${STRUCTURE_NOTE}`,
+        z.object({}).shape,
+        async (c) => {
+          const d = await data(c, "GET", `/management/content-structure`);
+          return ok(d?.summary?.outline ? `Content structure:
+${d.summary.outline}` : "Content structure.", d);
+        }
+      ),
+      def(
+        "set_content_structure",
+        "Replace the Content sidebar structure",
+        `Replace the whole Content sidebar document in one write. Prefer the single-action tools (create_folder, rename_folder, move_to_folder, set_icon, delete_folder) for small changes; use this to lay out a full structure at once. Send the complete \`doc\` and the \`version\` get_content_structure returned (0 when the project has none yet). Validated exactly like the dashboard: unique folder ids, every parentId/folderId must be a folder in the doc, no cycles, depth at most 4, names 1-80 chars, lucide icon names. A 412 VERSION_CONFLICT means someone changed it since you read it: call get_content_structure again and re-apply your change. Returns the new version and a diff (folders added, removed, renamed or moved; items moved; icons changed). ${STRUCTURE_NOTE}`,
+        z.object({
+          doc: z.object({
+            schema: z.literal(1),
+            folders: z.array(z.object({
+              id: z.string().min(1).describe("your own stable id, up to 64 chars"),
+              parentId: z.string().nullable().describe("parent folder id; null = top level"),
+              name: z.string(),
+              icon: z.string().nullable().describe("lucide icon name or null"),
+              sort: z.number()
+            })),
+            items: z.array(z.object({
+              kind: z.enum(["page", "collection"]),
+              id: z.string().min(1).describe("page id or collection (content model) id"),
+              folderId: z.string().nullable().describe("folder id; null = its home (Static pages for a page, the Collections list for a collection)"),
+              sort: z.number(),
+              icon: z.string().nullable()
+            }))
+          }).describe("the complete document"),
+          version: z.number().int().min(0).describe("the version get_content_structure returned")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "PUT", `/management/content-structure`, { doc: a.doc, version: a.version }))
+      ),
+      def(
+        "create_folder",
+        "Create a Content sidebar folder",
+        `Create a folder in the Content sidebar, at the top level or inside \`parentId\`, placed after what is already there. Returns the new \`folderId\`. Reads, applies and writes with the version check, retrying once on a conflict. ${STRUCTURE_NOTE}`,
+        z.object({
+          name: z.string().min(1).describe("the folder's label, 1-80 chars"),
+          parentId: z.string().min(1).optional().describe("optional parent folder id (from get_content_structure); omit for the top level"),
+          icon: z.string().min(1).optional().describe("optional lucide icon name, e.g. 'folder'")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "POST", `/management/content-structure/folders`, { name: a.name, parentId: a.parentId, icon: a.icon }))
+      ),
+      def(
+        "rename_folder",
+        "Rename a Content sidebar folder",
+        `Rename a Content sidebar folder. ${STRUCTURE_NOTE}`,
+        z.object({
+          folderId: z.string().min(1).describe("folder id (from get_content_structure)"),
+          name: z.string().min(1).describe("the new label, 1-80 chars")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "PATCH", `/management/content-structure/folders/${encodeURIComponent(s(a.folderId))}`, { name: a.name }))
+      ),
+      def(
+        "move_to_folder",
+        "Move into a Content sidebar folder",
+        `Move a page, a collection or a folder into a folder. folderId null moves it back to its home: Static pages for a page, the Collections list for a collection, the top level for a folder. It lands after what is already there. Moving a folder takes its contents with it and is refused if the result would nest deeper than 4 levels or put a folder inside itself. ${STRUCTURE_NOTE}`,
+        z.object({
+          kind: z.enum(["page", "collection", "folder"]),
+          id: z.string().min(1).describe("the page id, collection (content model) id, or folder id"),
+          folderId: z.string().min(1).nullable().describe("target folder id, or null to move it back to its home (Static pages, the Collections list, or the top level for a folder)")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "POST", `/management/content-structure/move`, { kind: a.kind, id: a.id, folderId: a.folderId }))
+      ),
+      def(
+        "set_icon",
+        "Set a Content sidebar icon",
+        `Set or clear the sidebar icon of a page, a collection or a folder. ${STRUCTURE_NOTE}`,
+        z.object({
+          kind: z.enum(["page", "collection", "folder"]),
+          id: z.string().min(1).describe("the page id, collection (content model) id, or folder id"),
+          icon: z.string().min(1).nullable().describe("lucide icon name, e.g. 'file-text'; null clears it")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "POST", `/management/content-structure/icon`, { kind: a.kind, id: a.id, icon: a.icon }))
+      ),
+      def(
+        "delete_folder",
+        "Delete a folder (its contents move up; nothing is deleted)",
+        `Delete a folder (its contents move up; nothing is deleted). NOTHING ELSE IS DELETED: its pages, collections and sub-folders move up to the folder's parent, in the same order. ${STRUCTURE_NOTE}`,
+        z.object({ folderId: z.string().min(1).describe("folder id (from get_content_structure)") }).shape,
+        async (c, a) => structureResult(await data(c, "DELETE", `/management/content-structure/folders/${encodeURIComponent(s(a.folderId))}`))
+      ),
       def(
         "list_redirects",
         "List redirects",
@@ -3107,7 +3200,7 @@ function buildToolDefs(deps) {
       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. \u{1F534} SUBMIT THE BINDING RECEIPT, NOT THE `--forms` ONE. A run of `npx @bettercms-ai/convert --forms` writes a receipt whose `paths` are all zero and whose account is in a `forms` block (`{ wired, alreadyWired, pending[{ id, name, reason }], notes }`); it passes this endpoint's arithmetic and would overwrite the real coverage with zeros. Write it to its own file (`--receipt forms-receipt.json`), read `forms.pending` and publish every form `forms.notes` names in the Forms tab, and submit the binding run's receipt here. Requires artifact:write, the same authority as set_binding_mode; on a workspace-wide connection pass `projectId`.",
+        "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, fix }] }`. `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`. \u{1F534} A RECEIPT WITH PENDING PATHS IS A PROGRESS REPORT, NOT A FINISH LINE. The response answers `complete` and `pendingTotal`, and echoes the first 40 pending rows WITH their `fix` \u2014 `{ action, file, line, col?, snippet, why? }`, where `action` is one of `wrap-span` (wrap the literal in a `<span data-bcms-field=\u2026>`), `declare-attr` (add `data-bcms-field=\u2026` to the element at file:line), `bind-expression` (replace the expression with the framework's bcmsField helper), `declare-richtext` (bind the container with the richtext helper), `bind-data` (the literal comes from the data file at file:line \u2014 bind that field) or `manual` (with a one-sentence `why`). Apply every fix in the source, rerun the codemod, resubmit. `complete: true` is the only receipt that ends a conversion \u2014 do not report a site converted on anything less. 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. \u{1F534} SUBMIT THE BINDING RECEIPT, NOT THE `--forms` ONE. A run of `npx @bettercms-ai/convert --forms` writes a receipt whose `paths` are all zero and whose account is in a `forms` block (`{ wired, alreadyWired, pending[{ id, name, reason }], notes }`); it passes this endpoint's arithmetic and would overwrite the real coverage with zeros. Write it to its own file (`--receipt forms-receipt.json`), read `forms.pending` and publish every form `forms.notes` names in the Forms tab, and submit the binding run's receipt here. Requires artifact:write, the same authority as set_binding_mode; on a workspace-wide connection pass `projectId`.",
         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.")
@@ -4803,8 +4896,14 @@ an empty string on the live site.
 
 ## 13. Convert an imported repo into a CMS-backed, editable site
 
-\xA711 says a deploy does not make a site editable. This is the recipe that does, and it ends in a
-receipt you can read: \`get_binding_report\` says \`mode: "declared"\` with zero unmatched paths.
+\xA711 says a deploy does not make a site editable. This is the recipe that does.
+
+\u{1F534} **A CONVERSION ENDS ONLY WHEN NOTHING IS PENDING.** The codemod's first pass never
+declares every path \u2014 measured on a real site, one pass declared 282 of 767 \u2014 and every path it
+leaves in \`paths.pending\` carries a \`fix\` naming the file, the line and the one edit. Apply
+them, rerun, resubmit, and repeat until \`submit_conversion_receipt\` answers \`complete: true\`.
+That boolean is the finish line; a receipt with pending paths is a progress report. The
+\`convert_site\` MCP prompt walks exactly this loop.
 
 **Scope, before you start.**
 
@@ -4878,21 +4977,30 @@ hand. THE ORDER, and every step of it matters:
    could not match are in \`forms.pending\` with a reason (\`FORM_NOT_IN_SOURCE\`,
    \`FIELD_UNMATCHED\`, \`FORM_AMBIGUOUS\`, \u2026) \u2014 it refuses rather than guessing, because a form
    wired to the wrong id delivers the customer's leads into another form's inbox.
-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.
+3. APPLY EVERY PENDING FIX, THEN RERUN. Each entry of \`paths.pending\` carries its reason
+   (\`IN_EXPRESSION\`, \`AMBIGUOUS_LITERAL\`, \`REPEATER_FIXED_LENGTH\`, \`PARSE_ERROR\`, \u2026) and,
+   where the codemod could work one out, a \`fix\`: \`{ action, file, line, col?, snippet, why? }\`.
+   Go to \`file\`:\`line\` and do what \`action\` says \u2014 \`wrap-span\` (wrap the literal in
+   \`<span data-bcms-field="\u2026">\`), \`declare-attr\` (add \`data-bcms-field="\u2026"\` to that element),
+   \`bind-expression\` (replace the expression with the framework's bcmsField helper),
+   \`declare-richtext\` (bind the container with the richtext helper), \`bind-data\` (bind the field
+   in the data file or collection entry it names) or \`manual\` (do what its \`why\` says). A row
+   with no \`fix\` is still yours. Then RERUN step 2 and repeat until \`paths.pending\` is empty \u2014
+   the codemod is idempotent, so a second run over converted source rewrites nothing.
+4. \`submit_conversion_receipt { briefDigest, receipt }\` with the receipt file, verbatim. It
+   answers \`complete\`, \`pendingTotal\` and the first 40 pending rows with their \`fix\`. \`complete: true\` \u2014 nothing
+   pending \u2014 is the ONLY receipt that ends a conversion; on anything less go back to step 3. It
+   is also what lets the coverage meter say WHY a path is undeclared instead of only that it is.
+   It records and releases nothing.
 5. Push, or \`deploy_project\`. A PLAIN HTML repo \u2014 no \`package.json\` \u2014 deploys by PUSH ONLY:
    \`deploy_project\` refuses such an archive by design, so pushing is the whole lane. Either way,
    poll \`get_deploy_status\` until \`slot\` is \`current\` (or \`awaitingPromote\` is false) before you
    read the report in step 6 \u2014 a report read against the previous release is the previous
    release's verdict.
 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.
+   brief listed), \`bound\` (what the build declares) and \`pending\` with the reasons. It must read
+   \`unmatched\` 0 and \`unaddressable\` under 2% of each route's visible text (\xA711). Fix what it
+   names IN THE SOURCE 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.
 
@@ -5121,6 +5229,31 @@ disagrees with the array the moment anyone drags a row in the builder.
 // src/prompts.ts
 var STRUCTURE_RULE = `### Page structure (non-negotiable)
 ${SECTION_DOCTRINE}`;
+var CONVERT_SITE_TEXT = (projectId) => `Convert my site so every visible element is editable in BetterCMS${projectId ? `, project ${projectId}` : ""}.
+Do not stop at the plan or at a partial receipt \u2014 finish the whole site.
+
+1. \`list_projects\`; pass \`projectId\`${projectId ? ` (${projectId})` : ""} on every project tool from here on. If the project
+   is not listed the grant is on another workspace \u2014 stop and say so.
+2. \`get_conversion_plan\`. On a 404 \`no-approved-plan\`, call
+   \`get_conversion_brief { complete: true }\` and follow \`cursor\` to the LAST page, keeping every
+   page \u2014 a codemod fed the capped brief converts a truncated site. Write them to \`brief.json\`.
+3. \`pull_project_source\` (or clone the \`github\` remote it names) and work from the SOURCE, never
+   from the deployed HTML.
+4. \`npx @bettercms-ai/convert --brief brief.json --root . --receipt receipt.json\`; read \`git diff\`.
+5. For EVERY entry of \`paths.pending\`, go to its \`fix.file\`:\`fix.line\` and do what \`fix.action\`
+   says: \`wrap-span\` wrap the literal in \`<span data-bcms-field="\u2026">\`; \`declare-attr\` add
+   \`data-bcms-field="\u2026"\` to that element; \`bind-expression\` replace the expression with the
+   framework's bcmsField helper; \`declare-richtext\` bind the container with the richtext helper;
+   \`bind-data\` bind the field in the data file it names; \`manual\` do what its \`why\` says. A row
+   with no \`fix\` is still yours. Then rerun step 4 until \`paths.pending\` is EMPTY.
+6. \`submit_conversion_receipt { briefDigest, receipt }\`. It must answer \`complete: true\`; if it
+   does not, go back to step 5 \u2014 that is the only receipt that ends a conversion.
+7. Deploy (push, or \`deploy_project\`) and poll \`get_deploy_status\` until the release is live.
+8. \`get_binding_report\` must read \`unmatched\` 0 and \`unaddressable\` under 2% of each route's
+   visible text. Fix what it names in the SOURCE, deploy, re-read (playbook section 11).
+9. \`set_binding_mode { declaredBindings: true }\`, deploy AGAIN and poll \u2014 the mode applies to the
+   NEXT release \u2014 then confirm \`get_binding_report\` reads mode "declared", unmatched 0, bound
+   above 0, \`coverage.pending\` empty. That report is your final answer to me.`;
 var SCHEMA_PROPOSAL_FLOW = `### Whole-project design (confirm-first) \u2192 \`create_component\` / \`create_page\` / \`create_content_model\`
 Design the WHOLE project from its brief or its code, and **confirm the shape with the user
 BEFORE creating anything**. Never silently guess.
@@ -5500,6 +5633,19 @@ in the dashboard \u2014 those render as an empty string until they are published
       ]
     })
   );
+  server.registerPrompt(
+    "convert_site",
+    {
+      title: "Convert a site so nothing is left pending (guided)",
+      description: "Run the conversion end to end: pull the source, run @bettercms-ai/convert, apply every fix it lists as pending, rerun until nothing is pending, and finish only when submit_conversion_receipt returns complete and get_binding_report reads unmatched 0.",
+      argsSchema: {
+        projectId: z2.string().optional().describe("the project to convert; omit if this connection is scoped to one")
+      }
+    },
+    ({ projectId }) => ({
+      messages: [{ role: "user", content: { type: "text", text: CONVERT_SITE_TEXT(projectId) } }]
+    })
+  );
   server.registerPrompt(
     "build_site",
     {