From 0a95ff79b124ad01539800622c355e53ef24f392 Mon Sep 17 00:00:00 2001 From: Shevchik Igor Date: Fri, 18 Sep 2026 09:39:23 +0000 Subject: [PATCH] docs: flatten the migration guide and its MCP tool (nuxt/ui@a3c3ff3, nuxt/ui@60db60e) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two contiguous upstream commits in one PR, per §6 step 4b: after the flattening the tool's `LIKE %/migration/v2` matches nothing, so it would answer 404 for the only guide this library has. `3.migration/1.v2.md` becomes `3.migration.md`; the directory and its `.navigation.yml` go. Upstream's reasoning holds for a fork whose major is 2 — the version lives in the package, not in the URL. Five places here against upstream's four, and none of the URL lines could be taken verbatim. This site uses trailing slashes, so every route is `/docs/getting-started/migration/`; copying upstream's targets would have 301'd to a path this site does not serve. The redirect had to reverse rather than be edited — ours pointed `/migration/` at `/migration/v2/`, and after flattening `/migration/` *is* the page, so that rule would have shadowed it with a redirect to a route that no longer exists. It now points the other way, with a 301 for the `/raw/**.md` twin beside it. The fifth place has no counterpart in the upstream diff and is the one a faithful-looking port would have missed: `docs/nuxt.config.ts:12` holds a fork-only `pages` array that line 401 maps into `/raw/.md` prerender routes. Leaving `/migration/v2/` there would have kept generating the twin for a page that no longer exists and stopped generating the one that does. `.navigation.yml` held only `shadow: true` (upstream's also had an `icon`), asserted before deleting so nothing else went with it; it marks a directory whose index defers to a child and has no meaning without one. The page keeps its own `navigation.title: 'Migration'`, so the sidebar entry is unchanged. In the MCP tool, two fork-only lines are deliberately kept: `path` and `url` are built from `baseUrl` + `withTrailingSlash`, which upstream does not do. The asymmetry that leaves is correct rather than sloppy — the query matches `/docs/getting-started/migration` without a slash, because that is the path nuxt/content stores, while the response adds one, because that is what the site serves. Also reconciles the `ee37a5b4` entry with #607 / ecd9e83a. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01JS8ypVfQSFzYVZzkTHhURb --- .sync/dep-parity.json | 2 +- ...0db60e05f2c605b9b96883218629754babc73e6.md | 43 ++++++++++++++ ...3c3ff34b187b6447f9c5082fdd2bd3671f442a2.md | 56 +++++++++++++++++++ .sync/nuxt-ui.json | 18 +++++- .../content/docs/1.getting-started/1.index.md | 2 +- .../{3.migration/1.v2.md => 3.migration.md} | 0 .../3.migration/.navigation.yml | 1 - docs/nuxt.config.ts | 6 +- .../mcp/tools/b24-ui-get-migration-guide.ts | 16 ++---- 9 files changed, 124 insertions(+), 20 deletions(-) create mode 100644 .sync/log/60db60e05f2c605b9b96883218629754babc73e6.md create mode 100644 .sync/log/a3c3ff34b187b6447f9c5082fdd2bd3671f442a2.md rename docs/content/docs/1.getting-started/{3.migration/1.v2.md => 3.migration.md} (100%) delete mode 100644 docs/content/docs/1.getting-started/3.migration/.navigation.yml diff --git a/.sync/dep-parity.json b/.sync/dep-parity.json index 8de457e0c..277a431cb 100644 --- a/.sync/dep-parity.json +++ b/.sync/dep-parity.json @@ -1,6 +1,6 @@ { "$note": "Upstream's pinned versions for every dependency both trees declare in the SAME section, snapshotted at `cursor`. The sync ports deltas, which is correct per commit and lets a one-time divergence become permanent: once a version is off upstream's line, every later `chore(deps)` batch skips it, because those ports bump only where this fork already matched upstream's pre-image. `prettier` sat at ^3.8.4 against upstream's ^3.9.6 for that reason, through four ported batches, until this file was written. Section-aware on purpose: 18 packages are declared on both sides but in different sections — the whole `@tiptap/*` family is a peer `^3` upstream and a dependency `^3.29.2` here, and `ai` is a peer there and a devDependency here. Those are structural divergences, not drift, and comparing a peer range against a dependency range says nothing. They are absent from this file by construction rather than by omission. Guarded by `test/utils/dep-parity.spec.ts`. Refresh with `node .sync/dep-parity.mjs [cursor]`, which preserves `exceptions`.", - "cursor": "ee37a5b4a8af2c8fa651288dcfbb263710f6d907", + "cursor": "60db60e05f2c605b9b96883218629754babc73e6", "manifests": { "package.json": { "dependencies": { diff --git a/.sync/log/60db60e05f2c605b9b96883218629754babc73e6.md b/.sync/log/60db60e05f2c605b9b96883218629754babc73e6.md new file mode 100644 index 000000000..a45d2ce1c --- /dev/null +++ b/.sync/log/60db60e05f2c605b9b96883218629754babc73e6.md @@ -0,0 +1,43 @@ +# port — nuxt/ui@60db60e05f2c605b9b96883218629754babc73e6 + +**Upstream:** docs(mcp): resolve flattened page in `get-migration-guide` (#6963) + +**Decision:** port — the companion to `a3c3ff34`; without it the MCP tool queries +a path that no longer exists. + +## Upstream change + +The tool loses its `version` input. `z.enum(['v4'])`, the `inputExamples` and the +`version` key in the response all go, the description stops promising +"version-specific" guides, and the lookup changes from a `LIKE %/migration/${version}` +pattern to an exact match on the flattened path. + +## What changed here + +The same five edits to `docs/server/mcp/tools/b24-ui-get-migration-guide.ts`, with +`v2` in place of `v4`: + +- `import { z } from 'zod'` dropped — it had no other use in the file +- `inputSchema` / `inputExamples` removed +- `async handler({ version })` → `async handler()` +- `.where('path', 'LIKE', `%/migration/${version}`)` → `.where('path', '=', '/docs/getting-started/migration')` +- the 404 message and the `version` response key + +**Two fork-only lines were deliberately left alone.** The response's `path` and +`url` are built as +`${config.public.baseUrl}${withTrailingSlash(page.path)}` — this site is served +under a base path and with trailing slashes, which upstream's tool does not do. +Taking upstream's `path: page.path` would have returned a URL that 301s at best. + +Note the asymmetry that results, and that it is correct: the **query** matches +`'/docs/getting-started/migration'` without a trailing slash, because that is the +`path` nuxt/content stores for the collection entry; the **returned** URL adds one, +because that is what the site serves. The two are different things and only look +inconsistent. + +## Why it ships with `a3c3ff34` + +The two are adjacent upstream and inseparable in effect: after the flattening the +old `LIKE %/migration/v2` matches nothing, so the tool would answer 404 for the +only guide this library has. §6 step 4b permits one PR for a contiguous run, and +this is one. diff --git a/.sync/log/a3c3ff34b187b6447f9c5082fdd2bd3671f442a2.md b/.sync/log/a3c3ff34b187b6447f9c5082fdd2bd3671f442a2.md new file mode 100644 index 000000000..b6f51718b --- /dev/null +++ b/.sync/log/a3c3ff34b187b6447f9c5082fdd2bd3671f442a2.md @@ -0,0 +1,56 @@ +# port — nuxt/ui@a3c3ff34b187b6447f9c5082fdd2bd3671f442a2 + +**Upstream:** docs: flatten migration guide to a single page + +**Decision:** port — the same one-page-in-a-directory shape is here, and the +reasoning (the major lives in the package, not in the URL) holds for a fork whose +major is 2. + +## Upstream change + +`3.migration/1.v4.md` → `3.migration.md`; the directory and its `.navigation.yml` +go; the prose link loses its `/v4`; and the redirect reverses — `/migration` used +to send readers to `/migration/v4`, now `/migration/v4` sends them to +`/migration`, 301, with the `/raw/**.md` twin redirected alongside. Their comment +gives the reason: *the version lives in the domain, +ui4.nuxt.com/docs/getting-started/migration*. + +## Ported, not copied + +Five places here against upstream's four, and none of the URL lines could be +taken verbatim. + +**This site uses trailing slashes.** Every route in `docs/nuxt.config.ts` is +written `/docs/getting-started/migration/`, not `/docs/getting-started/migration`. +Copying upstream's redirect targets would have produced a 301 to a path this site +does not serve. + +**The redirect had to reverse, not be edited.** Ours read + +```ts +'/docs/getting-started/migration/': { redirect: '/docs/getting-started/migration/v2/', … } +``` + +and after flattening `/migration/` *is* the page, so a rule pointing away from it +would shadow the page with a redirect to a route that no longer exists. It now +points the other way, plus a 301 for the raw twin. + +**There is a fork-only prerender list.** `docs/nuxt.config.ts:12` holds a `pages` +array that line 401 maps into `/raw/.md` prerender routes — the mechanism +that publishes every page's Markdown twin. Upstream has no such list. Leaving +`/docs/getting-started/migration/v2/` in it would have kept generating +`/raw/.../migration/v2.md` for a page that no longer exists and stopped generating +the one that does. This is the edit with no counterpart in the upstream diff, and +the one a faithful-looking port would have missed. + +**`.navigation.yml` held only `shadow: true`** — upstream's also had an `icon`. +Asserted before deleting, so nothing else went with it. `shadow` marks a directory +whose index defers to a child; with no directory it has no meaning. The page keeps +its own `navigation.title: 'Migration'` in frontmatter, so the sidebar entry is +unchanged. + +## Note + +The page is still titled *Migration to v2* and still describes v1 → v2. Only its +location changed. A fork on major 2 with one guide is exactly the shape upstream +just moved to, so this is convergence rather than divergence. diff --git a/.sync/nuxt-ui.json b/.sync/nuxt-ui.json index c712814b7..88a4ed56a 100644 --- a/.sync/nuxt-ui.json +++ b/.sync/nuxt-ui.json @@ -1,7 +1,7 @@ { "upstream": "nuxt/ui", "branch": "v4", - "cursor": "ee37a5b4a8af2c8fa651288dcfbb263710f6d907", + "cursor": "60db60e05f2c605b9b96883218629754babc73e6", "_cursor_note": "cursor = last upstream commit ported into b24ui. The sync is manual by decision: one commit at a time, oldest-first, each with a `.sync/log/.md` journal and an entry in `processed`. There is no dispatcher, no porter workflow and no kill-switch — `.sync/PORTING.md` is the whole procedure. `processed` is maintained per port (backfilled #68-#72 on 2026-06-09).", "processed": { "2799fa6f2b25ce3eb15e050f3ef7c57d0d9a2fdb": { @@ -1981,10 +1981,22 @@ "summary": "refactor(unplugin): resolve vue runtime paths from a file url — second half of b0e1d715; an absolute Windows path like `D:/...` parses as a `d:` url scheme, so the four sites take a relative id against a new `runtimeUrl` (pathToFileURL of runtimeDir WITH a trailing slash, which is load-bearing). Drops the now-unused `join` import from bitrix24-environment.ts, as upstream does" }, "ee37a5b4a8af2c8fa651288dcfbb263710f6d907": { - "pr": "pending-merge", - "b24ui_sha": "pending-merge", + "pr": 607, + "b24ui_sha": "ecd9e83a", "decision": "n/a", "summary": "chore(github): drop `@nuxt/ui` placeholder from consumer fixtures — n/a: module.yml and test/fixtures/ do not exist here (recorded with b2cb53f8 / #598). Worth noting the reason: the placeholder made the job resolve the released package, so the build under test was never the one whose optional peers were checked" + }, + "a3c3ff34b187b6447f9c5082fdd2bd3671f442a2": { + "pr": "pending-merge", + "b24ui_sha": "pending-merge", + "decision": "port", + "summary": "docs: flatten migration guide to a single page — 3.migration/1.v2.md -> 3.migration.md, directory + .navigation.yml (shadow only) removed, prose link updated, redirect REVERSED (/migration/ is the page now) + a 301 for the raw twin. Five places against upstream’s four: our routes carry trailing slashes and we have a fork-only `pages` prerender list that generates /raw/**.md, which upstream has no counterpart for" + }, + "60db60e05f2c605b9b96883218629754babc73e6": { + "pr": "pending-merge", + "b24ui_sha": "pending-merge", + "decision": "port", + "summary": "docs(mcp): resolve flattened page in `get-migration-guide` (#6963) — drops the `version` input and queries the flattened path exactly. Kept the fork-only baseUrl/withTrailingSlash construction of the returned path and url; the query matches without a trailing slash (nuxt/content’s stored path) while the response adds one (what the site serves)" } } } diff --git a/docs/content/docs/1.getting-started/1.index.md b/docs/content/docs/1.getting-started/1.index.md index ce26628f8..4e2e3a9a3 100644 --- a/docs/content/docs/1.getting-started/1.index.md +++ b/docs/content/docs/1.getting-started/1.index.md @@ -45,7 +45,7 @@ title: Production Ready We support almost all components of Nuxt UI v4. -Read more in the [migration guide](/docs/getting-started/migration/v2/). +Read more in the [migration guide](/docs/getting-started/migration/). ## Core technologies diff --git a/docs/content/docs/1.getting-started/3.migration/1.v2.md b/docs/content/docs/1.getting-started/3.migration.md similarity index 100% rename from docs/content/docs/1.getting-started/3.migration/1.v2.md rename to docs/content/docs/1.getting-started/3.migration.md diff --git a/docs/content/docs/1.getting-started/3.migration/.navigation.yml b/docs/content/docs/1.getting-started/3.migration/.navigation.yml deleted file mode 100644 index 8fab78883..000000000 --- a/docs/content/docs/1.getting-started/3.migration/.navigation.yml +++ /dev/null @@ -1 +0,0 @@ -shadow: true diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts index aac4f0098..e9edbf5fa 100644 --- a/docs/nuxt.config.ts +++ b/docs/nuxt.config.ts @@ -12,7 +12,7 @@ const pages = [ '/docs/getting-started/', '/docs/getting-started/installation/nuxt/', '/docs/getting-started/installation/vue/', - '/docs/getting-started/migration/v2/', + '/docs/getting-started/migration/', '/docs/getting-started/contribution/', '/docs/getting-started/theme/design-system/', '/docs/getting-started/theme/css-variables/', @@ -355,7 +355,9 @@ export default defineNuxtConfig({ '/raw/**': { headers: { Vary: 'Accept, User-Agent' } }, // v4 redirects - default root pages '/docs/': { redirect: '/docs/getting-started/', prerender: false }, - '/docs/getting-started/migration/': { redirect: '/docs/getting-started/migration/v2/', prerender: false }, + // the version lives in the package, not the url — `/migration/` is the page + '/docs/getting-started/migration/v2/': { redirect: { to: '/docs/getting-started/migration/', statusCode: 301 }, prerender: false }, + '/raw/docs/getting-started/migration/v2.md': { redirect: { to: '/raw/docs/getting-started/migration.md', statusCode: 301 }, prerender: false }, '/docs/getting-started/theme/': { redirect: '/docs/getting-started/theme/design-system/', prerender: false }, '/docs/getting-started/integrations/': { redirect: '/docs/getting-started/integrations/icons/', prerender: false }, '/docs/getting-started/ai/': { redirect: '/docs/getting-started/ai/llms-txt/', prerender: false }, diff --git a/docs/server/mcp/tools/b24-ui-get-migration-guide.ts b/docs/server/mcp/tools/b24-ui-get-migration-guide.ts index 171b042b2..117e27189 100644 --- a/docs/server/mcp/tools/b24-ui-get-migration-guide.ts +++ b/docs/server/mcp/tools/b24-ui-get-migration-guide.ts @@ -1,41 +1,33 @@ -import { z } from 'zod' import { queryCollection } from '@nuxt/content/server' import { withTrailingSlash } from 'ufo' export default defineMcpTool({ title: 'Get Migration Guide', - description: 'Retrieves version-specific migration guides and upgrade instructions', + description: 'Retrieves the migration guide and upgrade instructions for this version of Bitrix24 UI', annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, - inputSchema: { - version: z.enum(['v2']).describe('The migration version (e.g., v2)') - }, - inputExamples: [ - { version: 'v2' } - ], cache: '30m', - async handler({ version }) { + async handler() { const event = useEvent() const config = useRuntimeConfig() const page = await queryCollection(event, 'docs') - .where('path', 'LIKE', `%/migration/${version}`) + .where('path', '=', '/docs/getting-started/migration') .where('extension', '=', 'md') .select('title', 'description', 'path') .first() if (!page) { - throw createError({ status: 404, message: `Migration guide for '${version}' not found` }) + throw createError({ status: 404, message: 'Migration guide not found' }) } const documentation = await $fetch(`/raw${page.path}.md`) return { - version, title: page.title, description: page.description, path: `${config.public.baseUrl}${withTrailingSlash(page.path)}`,