Restructure into a monorepo (Turborepo) for the provider layers

[TitusKirch]

Before you start

• I searched existing issues and didn't find a duplicate

What problem are you trying to solve?

#74 and #75 each record the same decision: the official provider ships as an independently published companion layer in its own repository (@kirchdev/duxt-typesense, @kirchdev/duxt-meilisearch). Neither repository exists, and in this estate a new open-source repo is not one gh repo create away — it is provisioned from the infrastructure repo's OpenTofu (Discord forum, CodeQL/GHAS, branch protection) and then carries the full meta layer of its own: workflow stubs, release-please, Dependabot, CodeQL, LICENSE, README, .tituskirch-skills.json. That is the standing cost of two thin adapters over exactly one build-time hook.

Meanwhile the contract both consume — duxt:search:records, a frozen readonly DuxtSearchRecord[], landed by #16 as 059cd6a — lives here, in search-records.ts. Split across three repositories, every change to it becomes a cross-repo release dance: bump the layer, publish, widen each provider's peer range, publish. Nothing along that path proves the contract still holds for its consumers, because pnpm check here exercises the hook against no consumer at all.

Three consequences follow, and they are three different problems:

• The meta layer is duplicated per provider — every one of them maintained, bumped and reviewed separately, for packages whose whole content is one hook subscription.
• A contract change cannot be verified against its consumers in any single gate. The hook's own guardrail already says a second hook needs a consumer that cannot be written without it; today the first two such consumers would live where this repo's checks cannot see them.
• www/ cannot dogfood a provider without depending on a published version of it, so the development site — the thing that catches SSR failures here — never exercises the extension surface.

Proposed solution

Host the provider layers in this repository as workspace packages, still published independently. Two halves, and only the first is required to unblock #74 and #75:

1. Workspace and release (required). pnpm-workspace.yaml already lists . and www; it gains packages/*. release-please moves to per-package manifest mode (include-component-in-tag: true, one entry per package) so @kirchdev/duxt-typesense@0.1.0 and @kirchdev/duxt@0.2.0 tag and publish on their own cadence, and the publish job in release-please.yml becomes a matrix over whatever was released.

2. Turborepo (the open half). With four packages each running lint, typecheck, test and build, a task graph with caching stops being ceremony. pnpm check would call turbo run check, preserving this repo's rule that CI runs whatever check chains.

The root stays the layer. The cheapest shape puts packages/* beside today's root package rather than moving the layer into packages/duxt. CLAUDE.md's standing warning applies here with full force — "Nothing layer-relative resolves the way it reads": the layer() helper resolving against import.meta.url, the collection cwd computed as join(process.cwd(), 'docs'), the @duxt alias and the 37-entry files allowlist would every one of them need re-verifying if the layer moved. Not moving it costs nothing and avoids all of that.

Open — to be settled by this issue, not assumed:

• Does Turborepo earn its place, or do pnpm workspaces alone suffice? The measured expensive phase in this repo is www/'s prerender (117–190 s, already cached per image through og-image-cache.ts) — which turbo's cache does not touch. Answer it with a number: pnpm check wall-clock before and after, at four packages. The first half above lands either way.
• turbo against the permission policy. CLAUDE.md already names pnpm exec turbo run as an example of a rule that must never be allow-listed, because it runs arbitrary code. Adoption means the command stays in the prompting middle state, and .codex/rules/default.rules has to agree — pnpm check:policy enforces that parity.
• Whether www/ takes a provider as a devDependency to dogfood it, and whether that pulls a Typesense or Meilisearch SDK into the deploy. It must not reach @kirchdev/duxt's own dependencies.
• Dependabot — one ecosystem entry per package directory, grouped as the existing ones are.

Alternatives considered

• Two new repositories, as Add a Typesense provider layer #74 and Add a Meilisearch provider layer #75 record. Rejected as the default here, not as impossible: it is the shape both issues assumed, and it keeps each provider's releases and issues fully separate. The price is the full meta layer twice over plus OpenTofu provisioning per repo, for adapters that exist only to consume a hook this repo owns — and a contract no single gate can verify end to end.
• pnpm workspaces without Turborepo. Unblocks Add a Typesense provider layer #74 and Add a Meilisearch provider layer #75 on its own and is strictly less to maintain. This is the fallback if the number above does not justify turbo, and this issue is cut so that half can land alone.
• Nx instead of Turborepo. More capable, considerably more opinionated, and built around a generator model this repo has no use for.
• Optional exports of @kirchdev/duxt (a ./typesense subpath). Explicitly rejected by both Add a Typesense provider layer #74 and Add a Meilisearch provider layer #75, and it would put the SDKs in the layer's own dependency graph — precisely what both decisions exist to prevent.
• Leave the providers unofficial. Then consumers rebuild the source, version, locale and generated-section logic that the hook exists to hand them.

Additional context

• Blocks Add a Typesense provider layer #74 and Add a Meilisearch provider layer #75. Both are ai: ready today with their prerequisite (Decide the extension surface: hooks, plugins, or neither #16) landed, and stall solely on the missing repository.
• Decide the extension surface: hooks, plugins, or neither #16 landed duxt:search:records as 059cd6a; the contract lives in search-records.ts.
• Evaluate one search index across all sources #33 decides the built-in default (Pagefind) and is independent of where providers live.
• Today's shape: pnpm-workspace.yaml lists . and www, and the root is the published package (main: "./nuxt.config.ts", a 37-entry files allowlist).
• The outcome overrides the "own repository" decision recorded in Add a Typesense provider layer #74 and Add a Meilisearch provider layer #75, so it earns an ADR beside 0001–0009.

Decided (refinement pass, 2026-09-15):

• Turborepo is adopted. Supersedes the open point "Does Turborepo earn its place" and the pnpm-workspaces-only fallback above; no before/after number is required. turbo stays out of the permission allow list, as CLAUDE.md already requires.
• The layer moves, and the root stops being a package. @kirchdev/duxt moves to packages/duxt, the development site to apps/www, and the repository root keeps only workspace and meta configuration (turbo.json, pnpm-workspace.yaml, lint/format, husky, .github, agent files) plus docs/. Supersedes "The root stays the layer" above.
• The root-folder cleanup is part of this issue. The flat build-time modules (bruno-*.ts, openapi-*.ts, sources-*.ts, sections-*.ts, search-records.ts and the rest) sit in no package root: they move into topic folders inside packages/duxt (for example build/bruno/, build/sources/); exact names are the implementer's. The files allowlist shrinks accordingly. Every layer-relative path — layer(), content.config.ts's process.cwd(), repository-root.ts, the @duxt alias, the exports map — is re-verified by pnpm check, a Workers build with check:routes, and an npm pack of the layer installed into a scratch consumer.
• Structure only. No provider package is scaffolded here; packages/duxt-typesense and packages/duxt-meilisearch land with Add a Typesense provider layer #74 and Add a Meilisearch provider layer #75, and the open points on www/ dogfooding a provider and per-package Dependabot entries move with them.
• Independent versions, and a package without changes is never released. Each published package is its own release-please unit with its own version and changelog; a release publishes only the packages it bumped. No empty release of any package, ever — which is why a shared version was rejected: it republishes unchanged packages under a new number.
• Every package tags <name>@vX.Y.Z, the layer included — "tag-separator": "@" with component tags, so duxt@v0.4.0 beside duxt-typesense@v0.1.0. The version itself stays a bare number in package.json and on npm. The existing v0.1.0…v0.3.4 tags stay as they are; set last-release-sha once so release-please finds v0.3.4 as the layer's previous release despite the new pattern.
• Also part of this issue: duxt's tag-based versioning learns prefixed tags. Today parseTag in sources-git.ts, the checks in sources-resolve.ts and app/utils/version-choices.ts accept only v?X.Y.Z and silently skip anything else, so after the first duxt@v… tag www/'s latest would stay on v0.3.4 without any build failing. Wanted: <name>@vX.Y.Z tags are recognised by latest, the release selection and the switcher's sorting; a source can restrict itself to one component's tags, since a monorepo has several; the label and the URL segment show v0.4.0, never duxt@v0.4.0; plain vX.Y.Z tags keep working unchanged. It is a consumer feature as much as this repo's need — every release-please monorepo tags this way — and it must be merged before the first release after the move, not after.
• Providers peer-depend on @kirchdev/duxt with a wide range, >=0.4.0 <1 (the lower bound being whatever the provider first needs), never ^0.x: under 1.0 a caret would force every provider to release on every layer minor. The monorepo gate is what proves compatibility; the lower bound rises only when the hook contract changes incompatibly, as a feat! on the provider.
• Turborepo's cache is local only. No remote cache — no Vercel account, no token secret. Whether CI caches .turbo through actions/cache is the implementer's call, backed by a measurement.
• ADR 0011 records the outcome — the monorepo layout, independent versions with <name>@vX.Y.Z tags, and that it supersedes the "own repository" decision in Add a Typesense provider layer #74 and Add a Meilisearch provider layer #75. The "beside 0001–0009" line above is stale: 0010 exists.

[TitusKirch]

Implementation pushed to dev — ready for review

Commits

• 3487d48 feat(sources): recognise component-prefixed release tags
• a48d1a8 merge of origin/main into dev (brings in the v0.4.0 release commit)
• 790a546 build: restructure the repository into a Turborepo monorepo
• e5ea1ae docs(adr): record hosting the provider layers in a Turborepo monorepo

What changed

• Prefixed tags (lands first, in its own commit). parseVersionTag reads vX.Y.Z and <name>@vX.Y.Z; latest, release discovery, versionRelation and the switcher's order all go through it. The label and URL segment show v0.4.0; the ref keeps the full tag. A source may set tagComponent to restrict latest/releases to one package's tags. Plain tags still count under it, as the history from before component tags. Unset, behaviour is unchanged. apps/www's duxt source sets tagComponent: 'duxt'. Documented in the sources reference in all five languages.
• Layout. packages/duxt is the layer, with its build-time modules in build/{sources,sections,bruno,openapi,search,content,og-image,git,config,cli}. The files allowlist is now directories, and the exports map keeps every subpath name. apps/www is the site plus the scripts and tests that read its build. The root holds workspace/meta config, docs/ and the layer's CHANGELOG.md.
• Turborepo. Root scripts remain a pnpm <task> chain (the central CI body splits check on that shape) and delegate to turbo run. The cache is local only. test is cached with explicit cross-package inputs. typecheck, build and every check over a build are cache: false, because they resolve latest over the network. I added no CI caching of .turbo: nothing is measured yet to justify it.
• release-please. One manifest entry per package, include-component-in-tag with tag-separator: "@" (tags duxt@vX.Y.Z), and a top-level last-release-sha at v0.4.0's release commit.
• Publishing. release-please.yml now carries its own publish jobs, with the reason in its header. A package publishes when its <component>@v<version> tag exists and npm lacks that version. A dev-main prerelease goes out only for packages the push changed.
• ADR 0011, in all five languages plus the index rows. CLAUDE.md/AGENTS.md (byte-identical), README, CONTRIBUTING and the branding page are updated to the new layout.

Deviations from the brief, and why

• last-release-sha points at v0.4.0, not v0.3.4. v0.4.0 was released on main after the refinement pass, so it is the layer's previous release now. dev was brought level with main first (merge of origin/main), the same back-merge dev has done before. Without it, the moved package.json, the manifest and CHANGELOG.md would have conflicted in the next promotion.

• The layer's changelog stays at /CHANGELOG.md (changelog-path: "/CHANGELOG.md", which release-please 17.6 reads as root-relative). The site publishes the changelog of every version it serves from that version's own checkout, and every existing tag has the file at the root. check:a11y reads /releases and /releases/v0.1.0. Moving the file would have blanked the release pages of every earlier edition. The brief's "the root keeps only…" list does not mention it, so this is named here.

• publicHoistPattern for the layer's dependencies (35 of 41). While the root was the layer, www/ resolved 35 of the layer's 41 direct dependencies by walking up to the root node_modules. After the move, apps/www resolved only 9 of them. That broke two things:

  • nuxt typecheck: the generated declarations lost @nuxt/content and the other modules, so every Content query typed as never (26 errors).
  • The Workers build, which bundles dependencies: it could no longer resolve shiki and failed on shiki/dist/onig.wasm ("failed to resolve import env").

  I first hoisted only the 7 packages the typecheck needed; the Workers build then failed. The final list is every dependency that resolved from www/ before the move. A resolution check afterwards shows exactly the pre-move set still unresolvable (@nuxtjs/color-mode, @nuxtjs/mcp-toolkit, @nuxtjs/sitemap, shadcn-nuxt, tw-animate-css, vue-sonner).

• Own publish jobs instead of the central _publish-npm.yml. That body publishes the repository root, and _release-please.yml forwards only root outputs. The durable fix is a working-directory input plus the per-path outputs in kirchDev/workflows.

Test discipline

tdd drove the prefixed-tag slices from the brief's own wording, each red before green. Seams:

• latest within one component
• release selection with plain history included
• label and URL segment show the version
• the switcher order
• plain tags unchanged, and latest unrestricted without a component

The restructure is behaviour-preserving, so the existing suites are the seams. Some tests needed path updates because they read repository paths as strings: content-database, frontmatter-yaml, shortcuts-surface, docs-locales, check-seo, nuxt-process-guard. package-files was rewritten for a directory allowlist and now also refuses imports that leave the package.

Verification

All runs were on the pushed tree (e5ea1ae), in a worktree outside the repository.

• pnpm check: exit 0. It covers:
  • lint, format, tsc
  • typecheck:app (0 errors)
  • test: packages/duxt 82 files / 4,383 tests, apps/www 11 files / 129 tests, including the process-guard suite
  • check:policy, check:previews, build:app
  • check:a11y (15 pages), check:seo (4 pages), check:images (6 images), check:keyboard, check:overflow
• Workers build (pnpm build:www): exit 0. check:routes reported "15 routes verified against the cloudflare-module build artifact, and all 137 handlers it registers are classified or exempt". The prerender printed one [request error] for /api/_nuxt_icon/lucide.json?icons=settings; failOnError is off.
• npm pack smoke test: passed.
  • The tarball has 461 files: app, bin, build, i18n, modules, public, server, the configs, README.md and LICENSE, and no tests/ or scripts/. postpack removed the copied README and LICENSE again.
  • I installed it into a scratch Nuxt consumer (extends: ['@kirchdev/duxt'], one docs/index.md). nuxt build completed and prerendered 2 routes, and the built server answered / with 200 and /llms.txt with 200.
  • The first attempt failed the layer's validator with "collection docs contains no pages". The cause was a stray /tmp/.git above the scratch directory, which made repositoryRoot() stop at /tmp. Making the consumer its own git repository, as a real consumer is, fixed it. No packaging defect was involved.

Left for a human

• The local dev branch in the main checkout is behind origin/dev. A nuxt dev for www/ was running there (since 23:27), so the work was done in a separate worktree. The drain had reported that server stopped.
• npm Trusted Publishing is configured for release-please.yml. The workflow filename is unchanged. The first real publish from the new jobs will show whether the publisher entry needs anything else.
• Follow-up in kirchDev/workflows: a working-directory input on _publish-npm.yml and per-path outputs on _release-please.yml, so release-please.yml can become a stub again.
• The worktree /root/projects/comGithub/kirchDev/duxt-86 (detached, clean, fully pushed) is still on disk and can be removed with git worktree remove.
• The prerender [request error] for /api/_nuxt_icon/lucide.json?icons=settings did not fail the Workers build. I did not check whether it also appears in a pre-move build, so the first deploy log after promotion is where to compare.
• The first release after promotion will be tagged duxt@v0.4.1 or later. The publish-release job decides by tag and npm registry, so that run is the first real exercise of it.