From fc03a9211553b226bc53e1558d81500a81071baf Mon Sep 17 00:00:00 2001 From: Oto Macenauer Date: Fri, 4 Sep 2026 10:48:29 +0200 Subject: [PATCH 1/4] refactor: rename marketplace/mp identifiers to kb MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The project was once "docs marketplace". The name was gone from the UI but still prefixed every identifier in the contract and the codebase, where it collided with unrelated projects. data-mp-headless -> data-kb-headless .mp-* / #mp-* -> .kb-* / #kb-* MP_HEADLESS -> KB_HEADLESS src/styles/marketplace.css -> src/styles/knowledge-base.css "marketplace" in prose -> "knowledge base" Hard cut, no compatibility shim: nothing is in production, and the only producer of single-page HTML is this repo's own action. A stale artifact is still diagnosable — fetch-apps.js now distinguishes "carries the pre-rename marker" from "not headless at all" and says which, so a publisher is sent to the contract rather than to their build script. Two things deliberately left alone: * marketplace.json and marketplaceVersion. Both are artifact wire format, and #74 replaces them with a differently shaped kb-docs.json. Renaming them here would mean regenerating every fixture twice and would leave the new name briefly meaning the old shape. * The example repo's own class names and theme key inside the vendored tarball. Only data-mp-headless is rewritten in there, because that attribute is the contract; the rest belongs to that repo and moves with its own migration. Also corrects a contract line that told apps to expect a --mp-chrome-h offset variable. Nothing has injected it since the fixed chrome bar was removed, so renaming it would have invented a variable rather than documented one. Fixtures regenerated: the single-page bundle from setup-test-apps.mjs, and the docs-example tarball repacked with an identical member list. Suites green: 85 embedded, 22 standalone, action self-test 18. Closes #77 Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01PYtmxSeSXFg4wEXRcKCmAi --- .github/workflows/pages.yml | 2 +- .github/workflows/validate-doc-app.yml | 14 +- AGENTS.md | 4 +- CLAUDE.md | 22 +-- README.md | 20 +-- actions/publish-single-page-docs/README.md | 2 +- .../publish-single-page-docs/src/bundle.js | 8 +- .../publish-single-page-docs/src/markdown.js | 8 +- .../publish-single-page-docs/src/sanitize.js | 2 +- .../publish-single-page-docs/src/selftest.js | 16 +-- .../publish-single-page-docs/src/template.js | 130 +++++++++--------- contract/HEADLESS_RULES.md | 30 ++-- contract/SINGLE_PAGE.md | 20 +-- contract/STYLE_GUIDE.md | 12 +- contract/schema.json | 8 +- package.json | 12 +- scripts/build-vite.js | 18 +-- scripts/fetch-apps.js | 45 ++++-- scripts/hoist-inline-scripts.js | 6 +- scripts/setup-test-apps.mjs | 24 ++-- src/components/AppCard.astro | 8 +- src/components/Masthead.astro | 28 ++-- src/layouts/Base.astro | 14 +- src/pages/[...path].astro | 6 +- .../{marketplace.css => knowledge-base.css} | 68 ++++----- src/templates/shadow-compat.js | 6 +- src/utils/config.js | 4 +- src/utils/single-page.js | 4 +- src/utils/transform.js | 6 +- tests/artifact-safety.spec.js | 4 +- tests/build-integrity.spec.js | 48 +++---- tests/container.spec.js | 6 +- tests/fixtures/docs-example.dist.tar.gz | Bin 2950873 -> 2954072 bytes .../platform-overview/assets/doc.css | 108 +++++++-------- .../platform-overview/index.html | 18 +-- .../release-process/assets/doc.css | 108 +++++++-------- .../release-process/index.html | 8 +- tests/fragment-server.mjs | 2 +- tests/host/server.mjs | 2 +- tests/standalone.spec.js | 28 ++-- tests/support/fragment.js | 4 +- tests/web-fragment.spec.js | 28 ++-- 42 files changed, 471 insertions(+), 440 deletions(-) rename src/styles/{marketplace.css => knowledge-base.css} (88%) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 7009ed2..faa5c70 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -43,7 +43,7 @@ jobs: run: npm run build # Static Pages has no gateway/nginx to rewrite the fragment asset prefix, - # and /__wf/* is outside the project-site mount. Point the marketplace + # and /__wf/* is outside the project-site mount. Point the knowledge base # stylesheet at its real served path (/knowledge-base/style.css → dist/style.css). - name: Rewrite fragment asset paths for static hosting run: find dist -name '*.html' -exec sed -i 's#/__wf/knowledge-base/#/knowledge-base/#g' {} + diff --git a/.github/workflows/validate-doc-app.yml b/.github/workflows/validate-doc-app.yml index 4c424ef..ecca0a1 100644 --- a/.github/workflows/validate-doc-app.yml +++ b/.github/workflows/validate-doc-app.yml @@ -1,6 +1,6 @@ # Reusable workflow — validate a doc app against the knowledge-base contract. # -# Called by doc-app repos in their own CI to verify the app meets the marketplace +# Called by doc-app repos in their own CI to verify the app meets the knowledge base # contract before raising a PR or publishing a release. # # Usage in a doc repo (.github/workflows/validate.yml): @@ -28,7 +28,7 @@ permissions: jobs: validate: - name: Validate marketplace contract + name: Validate knowledge base contract runs-on: ubuntu-latest steps: - name: Checkout @@ -106,15 +106,15 @@ jobs: echo "✓ dist/${ENTRY} found" # ── Validate headless HTML structure ─────────────────────────────────── - - name: Check data-mp-headless attribute + - name: Check data-kb-headless attribute run: | ENTRY=$(node -e "const m=require('./marketplace.json'); console.log(m.entryPoint || 'index.html')") - if ! grep -q 'data-mp-headless="true"' "dist/${ENTRY}"; then - echo "::error file=dist/${ENTRY}::Missing data-mp-headless=\"true\" on element." - echo "Add data-mp-headless=\"true\" to the tag when building with --headless." + if ! grep -q 'data-kb-headless="true"' "dist/${ENTRY}"; then + echo "::error file=dist/${ENTRY}::Missing data-kb-headless=\"true\" on element." + echo "Add data-kb-headless=\"true\" to the tag when building with --headless." exit 1 fi - echo "✓ data-mp-headless=\"true\" found" + echo "✓ data-kb-headless=\"true\" found" - name: Check no fixed site header in headless output run: | diff --git a/AGENTS.md b/AGENTS.md index 110739b..6c5f3d8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -121,13 +121,13 @@ add a registry entry that requires network or a sibling checkout without it. ### Two build modes, one document Every page renders through `src/layouts/Base.astro`. Headless (web-fragment) and -standalone differ only by `data-mp-headless` and the shadow-DOM compat styles — +standalone differ only by `data-kb-headless` and the shadow-DOM compat styles — not by a different layout. Changes that add a mode-specific code path need a strong reason. ### Light only -The marketplace has no dark mode: no theme toggle, no persisted theme, no `dark` +The knowledge base has no dark mode: no theme toggle, no persisted theme, no `dark` class, no dark palette. A sub-app's own theme bootstrap is removed twice: `scripts/hoist-inline-scripts.js` deletes it while it is still inline, and `src/utils/transform.js` strips any that survives, along with a `dark` body diff --git a/CLAUDE.md b/CLAUDE.md index fc8b5de..5bdcc77 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -72,7 +72,7 @@ Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`. - `src/pages/index.astro` — Landing catalog page - `src/utils/apps.js` — `getAppPages()` enumerates sub-app HTML (manifest-driven or filesystem crawl) - `src/utils/transform.js` — `transformSubAppHtml()`: URL rewriting, document splitting (head/body/title/body-class), headless transforms -- `src/layouts/Base.astro` — The one document shell: head, marketplace CSS (which carries the self-hosted Inter faces), ``, shadow-DOM compat styles +- `src/layouts/Base.astro` — The one document shell: head, knowledge base CSS (which carries the self-hosted Inter faces), ``, shadow-DOM compat styles - `src/components/Masthead.astro` — Persistent Knowledge base header + Library/current-app sub-nav (all pages, both modes) - `src/components/AppCard.astro`, `src/components/AppIcon.astro` — Catalog card and its icon - `src/templates/shadow-compat.js` — Shadow-DOM design-token styles, injected into the body by the layout @@ -90,21 +90,21 @@ An `apps.json` entry is one of: - **default (packaged)** — a repo publishes a headless static site as `dist.tar.gz` plus `marketplace.json`. Every HTML file becomes a route. - **`type: "iframe"`** — no artifact; a single route renders a full-viewport `