From 6db8fca185336de4da612c15a95cc1a50bf5267e Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 12:31:55 +0800 Subject: [PATCH] chore: import upstream snapshot with attribution --- .gitattributes | 2 + .github/CODE_OF_CONDUCT.md | 48 + .github/CONTRIBUTING.md | 85 + .github/FUNDING.yml | 15 + .github/ISSUE_TEMPLATE/bug_report.yml | 58 + .github/ISSUE_TEMPLATE/feature_request.yml | 27 + .github/PULL_REQUEST_TEMPLATE.md | 16 + .github/SECURITY.md | 18 + .github/dependabot.yml | 44 + .github/workflows/ci.yml | 40 + .github/workflows/docker-publish.yml | 219 + .github/workflows/npm-publish.yml | 180 + .gitignore | 40 + LICENSE | 21 + README.de.md | 286 ++ README.es.md | 286 ++ README.fr.md | 286 ++ README.ja.md | 286 ++ README.md | 286 ++ README.wehub.md | 7 + README.zh.md | 286 ++ assets/docmd-cover.webp | Bin 0 -> 52906 bytes docker/.dockerignore | 83 + docker/DOCKER.md | 236 + docker/Dockerfile | 185 + docker/docker-entrypoint.sh | 67 + docker/docker-healthcheck.sh | 12 + eslint-rules/index.js | 16 + eslint-rules/no-unsafe-fs-read.js | 103 + eslint-rules/require-verify-client.js | 43 + eslint.config.mjs | 63 + package.json | 93 + packages/_playground/.threads/authors.json | 10 + packages/_playground/docmd.config.json | 90 + .../docs-05/getting-started/installation.md | 1 + packages/_playground/docs-05/index.md | 34 + .../_playground/docs/.threads/authors.json | 6 + packages/_playground/docs/en/index.md | 111 + .../_playground/docs/en/mermaid-icon-test.md | 22 + packages/_playground/docs/en/nested-page-1.md | 14 + packages/_playground/docs/en/nested-page-2.md | 11 + .../docs/en/practical-tests/README.md | 51 + .../phase-2/container-parser-determinism.md | 80 + .../phase-2/f1-nested-grids.md | 71 + .../phase-2/f2-self-closing-button.md | 48 + .../phase-2/f3-mismatched-close.md | 53 + .../phase-2/f4-triple-close.md | 52 + .../phase-2/f5-five-level-nesting.md | 61 + .../practical-tests/phase-3/cli-exit-codes.md | 72 + .../internal-link-with-trailing-slash.md | 58 + .../phase-3/llms-and-okf-default-locale.md | 99 + .../phase-3/okf-bundle-default.md | 64 + .../phase-3/okf-type-inference.md | 70 + .../phase-3/xss-in-frontmatter.md | 71 + packages/_playground/docs/hi/index.md | 14 + .../hi/practical-tests/phase-2-f1-hindi.md | 40 + packages/_playground/netlify.toml | 27 + packages/_playground/package.json | 16 + packages/_playground/vercel.json | 25 + packages/api/LICENSE | 21 + packages/api/README.md | 27 + packages/api/package.json | 66 + packages/api/registry/plugins.generated.json | 205 + packages/api/scripts/copy-registry.mjs | 31 + packages/api/src/engine.ts | 238 + packages/api/src/hooks.ts | 975 ++++ packages/api/src/index.ts | 117 + packages/api/src/rpc.ts | 133 + packages/api/src/runtime-deps.ts | 363 ++ packages/api/src/source.ts | 449 ++ packages/api/src/types.ts | 738 +++ packages/api/tsconfig.json | 10 + packages/core/LICENSE | 21 + packages/core/README.md | 277 ++ packages/core/package.json | 80 + packages/core/src/bin/docmd.ts | 313 ++ packages/core/src/commands/build.ts | 420 ++ packages/core/src/commands/deploy.ts | 93 + packages/core/src/commands/dev.ts | 511 ++ packages/core/src/commands/doctor.ts | 329 ++ packages/core/src/commands/init.ts | 426 ++ packages/core/src/commands/live.ts | 37 + packages/core/src/commands/mcp.ts | 558 +++ packages/core/src/commands/migrate.ts | 676 +++ packages/core/src/commands/stop.ts | 182 + packages/core/src/commands/validate.ts | 64 + packages/core/src/engine/assets.ts | 133 + packages/core/src/engine/generator.ts | 837 ++++ packages/core/src/engine/i18n.ts | 456 ++ packages/core/src/engine/versioning.ts | 247 + packages/core/src/engine/worker-parser.ts | 170 + packages/core/src/engine/workspace.ts | 768 +++ packages/core/src/env.d.ts | 5 + packages/core/src/index.ts | 50 + packages/core/src/utils/auto-router.ts | 153 + packages/core/src/utils/config-loader.ts | 447 ++ packages/core/src/utils/config-schema.ts | 421 ++ packages/core/src/utils/dev-utils.ts | 257 + packages/core/src/utils/exit.ts | 94 + packages/core/src/utils/ws-origin-guard.ts | 62 + packages/core/tsconfig.json | 10 + packages/deployer/LICENSE | 21 + packages/deployer/README.md | 78 + packages/deployer/package.json | 50 + packages/deployer/src/context.ts | 24 + packages/deployer/src/index.ts | 99 + packages/deployer/src/providers/caddy.ts | 64 + packages/deployer/src/providers/docker.ts | 64 + .../deployer/src/providers/github-pages.ts | 80 + packages/deployer/src/providers/netlify.ts | 64 + packages/deployer/src/providers/nginx.ts | 81 + packages/deployer/src/providers/vercel.ts | 60 + packages/deployer/tsconfig.json | 10 + packages/engines/js/LICENSE | 21 + packages/engines/js/README.md | 39 + packages/engines/js/package.json | 51 + packages/engines/js/src/index.ts | 300 ++ packages/engines/js/tsconfig.json | 11 + packages/engines/rust-binaries/LICENSE | 21 + packages/engines/rust-binaries/README.md | 55 + .../bin/docmd-engine-darwin-arm64.node | Bin 0 -> 771536 bytes packages/engines/rust-binaries/build.js | 137 + .../engines/rust-binaries/native/Cargo.lock | 362 ++ .../engines/rust-binaries/native/Cargo.toml | 32 + .../engines/rust-binaries/native/build.rs | 17 + .../engines/rust-binaries/native/src/lib.rs | 236 + packages/engines/rust-binaries/package.json | 41 + packages/engines/rust/LICENSE | 21 + packages/engines/rust/README.md | 54 + packages/engines/rust/package.json | 56 + packages/engines/rust/scripts/postinstall.cjs | 118 + packages/engines/rust/src/index.ts | 155 + packages/engines/rust/tsconfig.json | 11 + packages/legacy/doc.md/LICENSE | 21 + packages/legacy/doc.md/README.md | 21 + packages/legacy/doc.md/bin/docmd.js | 24 + packages/legacy/doc.md/package.json | 47 + packages/legacy/mgks/LICENSE | 21 + packages/legacy/mgks/README.md | 21 + packages/legacy/mgks/bin/docmd.js | 24 + packages/legacy/mgks/package.json | 47 + packages/live/LICENSE | 21 + packages/live/README.md | 28 + packages/live/bin/docmd-live.js | 18 + packages/live/package.json | 68 + packages/live/src/browser-entry.ts | 132 + packages/live/src/build.ts | 188 + packages/live/src/docmd-live-preview.css | 56 + packages/live/src/docmd-live.css | 371 ++ packages/live/src/index.html | 233 + packages/live/src/index.ts | 178 + packages/live/src/shims.js | 15 + packages/live/src/shims.ts | 15 + packages/live/tsconfig.json | 10 + packages/parser/LICENSE | 21 + packages/parser/README.md | 13 + packages/parser/package.json | 66 + packages/parser/src/features/basics.ts | 43 + packages/parser/src/features/buttons.ts | 106 + packages/parser/src/features/changelog.ts | 163 + .../parser/src/features/common-containers.ts | 270 ++ packages/parser/src/features/embed.ts | 57 + packages/parser/src/features/hero.ts | 218 + packages/parser/src/features/index.ts | 35 + packages/parser/src/features/steps.ts | 128 + packages/parser/src/features/tabs.ts | 192 + packages/parser/src/features/tags.ts | 109 + packages/parser/src/html-renderer.ts | 84 + packages/parser/src/index.ts | 62 + packages/parser/src/markdown-processor.ts | 567 +++ packages/parser/src/utils/container-helper.ts | 35 + .../parser/src/utils/container-normaliser.ts | 314 ++ packages/parser/src/utils/icon-renderer.ts | 60 + .../parser/src/utils/navigation-helper.ts | 95 + packages/parser/src/utils/normalize-href.ts | 195 + packages/parser/src/utils/url-utils.ts | 294 ++ packages/parser/src/utils/validator.ts | 125 + .../parser/test/container-normaliser.test.js | 814 ++++ packages/parser/tsconfig.json | 10 + packages/plugins/analytics/LICENSE | 21 + packages/plugins/analytics/README.md | 24 + packages/plugins/analytics/package.json | 64 + packages/plugins/analytics/src/index.ts | 130 + packages/plugins/analytics/tsconfig.json | 10 + packages/plugins/git/LICENSE | 21 + packages/plugins/git/README.md | 17 + packages/plugins/git/build.js | 39 + packages/plugins/git/i18n/de.json | 13 + packages/plugins/git/i18n/en.json | 13 + packages/plugins/git/i18n/ko.json | 13 + packages/plugins/git/i18n/zh.json | 13 + packages/plugins/git/package.json | 76 + .../plugins/git/src/client/git-widget.css | 169 + packages/plugins/git/src/client/git-widget.js | 97 + packages/plugins/git/src/index.ts | 596 +++ packages/plugins/git/tsconfig.json | 21 + packages/plugins/installer/LICENSE | 21 + packages/plugins/installer/README.md | 20 + packages/plugins/installer/package.json | 52 + .../plugins/installer/registry/plugins.json | 81 + .../plugins/installer/src/config-editor.ts | 382 ++ packages/plugins/installer/src/index.ts | 559 +++ packages/plugins/installer/tsconfig.json | 10 + packages/plugins/llms/LICENSE | 21 + packages/plugins/llms/README.md | 25 + packages/plugins/llms/package.json | 60 + packages/plugins/llms/src/index.ts | 198 + packages/plugins/llms/tests/llms.test.js | 170 + packages/plugins/llms/tsconfig.json | 10 + packages/plugins/math/LICENSE | 21 + packages/plugins/math/README.md | 25 + packages/plugins/math/package.json | 61 + packages/plugins/math/src/index.ts | 50 + packages/plugins/math/tsconfig.json | 10 + packages/plugins/mermaid/LICENSE | 21 + packages/plugins/mermaid/README.md | 23 + packages/plugins/mermaid/package.json | 67 + packages/plugins/mermaid/src/client.ts | 271 ++ packages/plugins/mermaid/src/index.ts | 55 + packages/plugins/mermaid/src/svg-utils.ts | 24 + .../plugins/mermaid/tests/svg-utils.test.ts | 117 + packages/plugins/mermaid/tsconfig.json | 10 + packages/plugins/okf/LICENSE | 21 + packages/plugins/okf/README.md | 90 + packages/plugins/okf/package.json | 63 + packages/plugins/okf/src/content.ts | 100 + packages/plugins/okf/src/graph-assets.ts | 41 + packages/plugins/okf/src/graph-runtime.ts | 567 +++ packages/plugins/okf/src/graph-styles.ts | 335 ++ packages/plugins/okf/src/graph-template.ts | 73 + packages/plugins/okf/src/index.ts | 285 ++ packages/plugins/okf/src/yaml.ts | 81 + packages/plugins/okf/tests/brute.test.ts | 585 +++ packages/plugins/okf/tests/index.test.ts | 310 ++ packages/plugins/okf/tests/tsconfig.json | 11 + packages/plugins/okf/tsconfig.build.json | 8 + packages/plugins/okf/tsconfig.json | 11 + packages/plugins/openapi/LICENSE | 21 + packages/plugins/openapi/README.md | 17 + packages/plugins/openapi/build.js | 32 + packages/plugins/openapi/package.json | 70 + packages/plugins/openapi/src/index.ts | 389 ++ packages/plugins/openapi/src/openapi.css | 221 + packages/plugins/openapi/tsconfig.json | 10 + packages/plugins/pwa/LICENSE | 21 + packages/plugins/pwa/README.md | 26 + packages/plugins/pwa/package.json | 67 + packages/plugins/pwa/src/index.ts | 197 + packages/plugins/pwa/tsconfig.json | 10 + packages/plugins/search/LICENSE | 21 + packages/plugins/search/README.md | 13 + packages/plugins/search/i18n/en.json | 10 + packages/plugins/search/i18n/hi.json | 10 + packages/plugins/search/i18n/ko.json | 10 + packages/plugins/search/i18n/zh.json | 10 + packages/plugins/search/package.json | 79 + packages/plugins/search/src/client.ts | 386 ++ packages/plugins/search/src/index.ts | 1051 ++++ .../plugins/search/src/semantic-client.ts | 302 ++ packages/plugins/search/src/worker.ts | 142 + packages/plugins/search/tsconfig.json | 10 + packages/plugins/seo/LICENSE | 21 + packages/plugins/seo/README.md | 31 + packages/plugins/seo/package.json | 68 + packages/plugins/seo/src/index.ts | 204 + packages/plugins/seo/tsconfig.json | 10 + packages/plugins/sitemap/LICENSE | 21 + packages/plugins/sitemap/README.md | 23 + packages/plugins/sitemap/package.json | 58 + packages/plugins/sitemap/src/index.ts | 83 + packages/plugins/sitemap/tsconfig.json | 10 + packages/plugins/threads/LICENSE | 21 + packages/plugins/threads/README.md | 19 + packages/plugins/threads/build.js | 31 + .../plugins/threads/e2e/basic-ui.e2e.spec.ts | 216 + .../threads/e2e/comment-display.e2e.spec.ts | 142 + .../threads/e2e/fixtures/playground-index.md | 76 + packages/plugins/threads/e2e/globals.d.ts | 8 + packages/plugins/threads/e2e/helpers.ts | 215 + .../threads/e2e/inline-editor.e2e.spec.ts | 266 ++ .../threads/e2e/navigation.e2e.spec.ts | 49 + .../plugins/threads/e2e/reactions.e2e.spec.ts | 273 ++ .../threads/e2e/replies-deletion.e2e.spec.ts | 256 + .../threads/e2e/resolve-threads.e2e.spec.ts | 104 + packages/plugins/threads/e2e/screenplay.ts | 326 ++ .../threads/e2e/thread-creation.e2e.spec.ts | 215 + packages/plugins/threads/e2e/tsconfig.json | 10 + packages/plugins/threads/i18n/en.json | 44 + packages/plugins/threads/i18n/hi.json | 44 + packages/plugins/threads/i18n/ko.json | 44 + packages/plugins/threads/i18n/zh.json | 44 + packages/plugins/threads/package.json | 78 + packages/plugins/threads/playwright.config.ts | 26 + .../threads/src/client/components/styles.ts | 954 ++++ .../src/client/components/threads-app.ts | 871 ++++ .../src/client/components/threads-comment.ts | 192 + .../src/client/components/threads-compose.ts | 55 + .../src/client/components/threads-identity.ts | 167 + .../components/threads-inline-editor.ts | 157 + .../src/client/components/threads-panel.ts | 153 + .../src/client/components/threads-popover.ts | 66 + .../src/client/components/threads-thread.ts | 91 + packages/plugins/threads/src/client/index.ts | 14 + .../plugins/threads/src/client/lib/api.ts | 113 + .../threads/src/client/lib/highlights.ts | 244 + .../plugins/threads/src/client/lib/i18n.ts | 60 + .../threads/src/client/lib/identity.ts | 160 + .../threads/src/client/lib/selection.ts | 124 + .../plugins/threads/src/client/lib/theme.ts | 72 + .../plugins/threads/src/client/tsconfig.json | 14 + packages/plugins/threads/src/index.ts | 90 + .../plugins/threads/src/plugin/actions.ts | 381 ++ .../plugins/threads/src/plugin/containers.ts | 263 + .../threads/src/plugin/highlight-rule.ts | 88 + packages/plugins/threads/src/plugin/parser.ts | 389 ++ packages/plugins/threads/src/types.ts | 83 + .../threads/test-results/.last-run.json | 4 + .../plugins/threads/tests/actions.test.js | 413 ++ .../plugins/threads/tests/containers.test.js | 308 ++ .../threads/tests/highlight-rule.test.js | 136 + .../plugins/threads/tests/integration.test.js | 426 ++ packages/plugins/threads/tests/parser.test.js | 304 ++ packages/plugins/threads/tsconfig.json | 20 + packages/templates/summer/LICENSE | 21 + packages/templates/summer/README.md | 90 + .../templates/summer/assets/css/summer.css | 4218 +++++++++++++++++ packages/templates/summer/assets/js/summer.js | 702 +++ packages/templates/summer/package.json | 77 + .../templates/summer/scripts/copy-assets.mjs | 60 + packages/templates/summer/src/index.ts | 92 + packages/templates/summer/templates/404.ejs | 156 + .../templates/summer/templates/layout.ejs | 611 +++ .../summer/templates/partials/footer.ejs | 69 + .../summer/templates/partials/menubar.ejs | 92 + .../templates/partials/options-menu.ejs | 45 + packages/templates/summer/templates/toc.ejs | 53 + packages/templates/summer/tsconfig.json | 10 + packages/themes/LICENSE | 21 + packages/themes/README.md | 28 + packages/themes/package.json | 56 + packages/themes/src/docmd-theme-retro.css | 287 ++ packages/themes/src/docmd-theme-ruby.css | 143 + packages/themes/src/docmd-theme-sky.css | 250 + packages/themes/src/index.ts | 43 + packages/themes/tsconfig.json | 10 + packages/tui/LICENSE | 21 + packages/tui/README.md | 34 + packages/tui/package.json | 54 + packages/tui/src/index.ts | 448 ++ packages/tui/tsconfig.json | 10 + packages/ui/LICENSE | 21 + packages/ui/README.md | 13 + .../ui/assets/css/docmd-highlight-dark.css | 95 + .../ui/assets/css/docmd-highlight-light.css | 95 + packages/ui/assets/css/docmd-main.css | 3825 +++++++++++++++ packages/ui/assets/favicon.ico | Bin 0 -> 15406 bytes packages/ui/assets/images/docmd-logo-dark.png | Bin 0 -> 3734 bytes .../ui/assets/images/docmd-logo-light.png | Bin 0 -> 2750 bytes packages/ui/assets/images/docmd-logo.png | Bin 0 -> 11563 bytes packages/ui/assets/js/docmd-api.js | 188 + packages/ui/assets/js/docmd-i18n-strings.js | 232 + packages/ui/assets/js/docmd-image-lightbox.js | 95 + packages/ui/assets/js/docmd-main.js | 1027 ++++ packages/ui/package.json | 62 + packages/ui/src/index.ts | 110 + packages/ui/src/template-resolver.ts | 259 + packages/ui/templates/404.ejs | 191 + packages/ui/templates/docmd-search.ejs | 159 + packages/ui/templates/layout.ejs | 327 ++ packages/ui/templates/navigation.ejs | 99 + packages/ui/templates/no-style.ejs | 250 + packages/ui/templates/partials/banner.ejs | 78 + .../ui/templates/partials/cookie-consent.ejs | 71 + packages/ui/templates/partials/footer.ejs | 59 + .../templates/partials/language-switcher.ejs | 84 + packages/ui/templates/partials/menubar.ejs | 134 + .../ui/templates/partials/options-menu.ejs | 42 + .../templates/partials/project-switcher.ejs | 78 + packages/ui/templates/partials/theme-init.js | 66 + .../templates/partials/version-dropdown.ejs | 59 + packages/ui/templates/toc.ejs | 43 + packages/ui/translations/de.json | 46 + packages/ui/translations/en.json | 46 + packages/ui/translations/es.json | 46 + packages/ui/translations/fr.json | 46 + packages/ui/translations/hi.json | 46 + packages/ui/translations/ja.json | 46 + packages/ui/translations/ko.json | 46 + packages/ui/translations/zh.json | 46 + packages/ui/tsconfig.json | 10 + packages/utils/LICENSE | 21 + packages/utils/README.md | 13 + packages/utils/package.json | 59 + packages/utils/src/fs-utils.ts | 64 + packages/utils/src/git.ts | 33 + packages/utils/src/hash.ts | 9 + packages/utils/src/html-escape.ts | 113 + packages/utils/src/index.ts | 7 + packages/utils/src/path.ts | 41 + packages/utils/src/watcher-utils.ts | 65 + packages/utils/src/worker-pool.ts | 169 + packages/utils/test/html-escape.test.js | 122 + packages/utils/test/path.test.js | 72 + packages/utils/tsconfig.json | 14 + pnpm-lock.yaml | 2800 +++++++++++ pnpm-workspace.yaml | 9 + scripts/build-plugin-registry.mjs | 169 + scripts/probe-threads-xss.mjs | 55 + tests/cli-contracts/asset-base-url.test.js | 273 ++ tests/cli-contracts/deploy.test.js | 116 + tests/cli-contracts/exit-codes.test.js | 113 + tests/cli-contracts/i18n.test.js | 183 + tests/cli-contracts/llms-and-tui.test.js | 151 + tests/cli-contracts/migrate-fix.test.js | 137 + tests/cli-contracts/migrate.test.js | 163 + tests/cli-contracts/offline-links.test.js | 152 + tests/cli-contracts/plugin-add-remove.test.js | 211 + .../plugin-assets-pipeline.test.js | 188 + tests/cli-contracts/plugin-contract.test.js | 361 ++ tests/cli-contracts/runtime-deps.test.js | 236 + tests/cli-contracts/source-tools.test.js | 147 + tests/cli-contracts/stop.test.js | 85 + .../cli-contracts/validate-workspace.test.js | 162 + tests/feature-integration.test.js | 960 ++++ tests/package.json | 3 + tests/runner.js | 334 ++ tests/security.test.js | 664 +++ tests/shared.js | 139 + tools/bump.js | 103 + tools/docker-prebuild.sh | 32 + tools/prep.js | 526 ++ tools/print-okf-runtime-deps.js | 99 + tools/resolve-ws-deps.js | 66 + tools/security-audit.mjs | 203 + tools/status.js | 94 + tools/verify.js | 70 + tsconfig.base.json | 14 + 437 files changed, 68762 insertions(+) create mode 100644 .gitattributes create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/FUNDING.yml create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/SECURITY.md create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/docker-publish.yml create mode 100644 .github/workflows/npm-publish.yml create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 README.de.md create mode 100644 README.es.md create mode 100644 README.fr.md create mode 100644 README.ja.md create mode 100644 README.md create mode 100644 README.wehub.md create mode 100644 README.zh.md create mode 100644 assets/docmd-cover.webp create mode 100644 docker/.dockerignore create mode 100644 docker/DOCKER.md create mode 100644 docker/Dockerfile create mode 100644 docker/docker-entrypoint.sh create mode 100644 docker/docker-healthcheck.sh create mode 100644 eslint-rules/index.js create mode 100644 eslint-rules/no-unsafe-fs-read.js create mode 100644 eslint-rules/require-verify-client.js create mode 100644 eslint.config.mjs create mode 100644 package.json create mode 100644 packages/_playground/.threads/authors.json create mode 100644 packages/_playground/docmd.config.json create mode 100644 packages/_playground/docs-05/getting-started/installation.md create mode 100644 packages/_playground/docs-05/index.md create mode 100644 packages/_playground/docs/.threads/authors.json create mode 100644 packages/_playground/docs/en/index.md create mode 100644 packages/_playground/docs/en/mermaid-icon-test.md create mode 100644 packages/_playground/docs/en/nested-page-1.md create mode 100644 packages/_playground/docs/en/nested-page-2.md create mode 100644 packages/_playground/docs/en/practical-tests/README.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-2/container-parser-determinism.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-2/f1-nested-grids.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-2/f2-self-closing-button.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-2/f3-mismatched-close.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-2/f4-triple-close.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-2/f5-five-level-nesting.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-3/cli-exit-codes.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-3/internal-link-with-trailing-slash.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-3/llms-and-okf-default-locale.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-3/okf-bundle-default.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-3/okf-type-inference.md create mode 100644 packages/_playground/docs/en/practical-tests/phase-3/xss-in-frontmatter.md create mode 100644 packages/_playground/docs/hi/index.md create mode 100644 packages/_playground/docs/hi/practical-tests/phase-2-f1-hindi.md create mode 100644 packages/_playground/netlify.toml create mode 100644 packages/_playground/package.json create mode 100644 packages/_playground/vercel.json create mode 100644 packages/api/LICENSE create mode 100644 packages/api/README.md create mode 100644 packages/api/package.json create mode 100644 packages/api/registry/plugins.generated.json create mode 100644 packages/api/scripts/copy-registry.mjs create mode 100644 packages/api/src/engine.ts create mode 100644 packages/api/src/hooks.ts create mode 100644 packages/api/src/index.ts create mode 100644 packages/api/src/rpc.ts create mode 100644 packages/api/src/runtime-deps.ts create mode 100644 packages/api/src/source.ts create mode 100644 packages/api/src/types.ts create mode 100644 packages/api/tsconfig.json create mode 100644 packages/core/LICENSE create mode 100644 packages/core/README.md create mode 100644 packages/core/package.json create mode 100755 packages/core/src/bin/docmd.ts create mode 100644 packages/core/src/commands/build.ts create mode 100644 packages/core/src/commands/deploy.ts create mode 100644 packages/core/src/commands/dev.ts create mode 100644 packages/core/src/commands/doctor.ts create mode 100644 packages/core/src/commands/init.ts create mode 100644 packages/core/src/commands/live.ts create mode 100644 packages/core/src/commands/mcp.ts create mode 100644 packages/core/src/commands/migrate.ts create mode 100644 packages/core/src/commands/stop.ts create mode 100644 packages/core/src/commands/validate.ts create mode 100644 packages/core/src/engine/assets.ts create mode 100644 packages/core/src/engine/generator.ts create mode 100644 packages/core/src/engine/i18n.ts create mode 100644 packages/core/src/engine/versioning.ts create mode 100644 packages/core/src/engine/worker-parser.ts create mode 100644 packages/core/src/engine/workspace.ts create mode 100644 packages/core/src/env.d.ts create mode 100644 packages/core/src/index.ts create mode 100644 packages/core/src/utils/auto-router.ts create mode 100644 packages/core/src/utils/config-loader.ts create mode 100644 packages/core/src/utils/config-schema.ts create mode 100644 packages/core/src/utils/dev-utils.ts create mode 100644 packages/core/src/utils/exit.ts create mode 100644 packages/core/src/utils/ws-origin-guard.ts create mode 100644 packages/core/tsconfig.json create mode 100644 packages/deployer/LICENSE create mode 100644 packages/deployer/README.md create mode 100644 packages/deployer/package.json create mode 100644 packages/deployer/src/context.ts create mode 100644 packages/deployer/src/index.ts create mode 100644 packages/deployer/src/providers/caddy.ts create mode 100644 packages/deployer/src/providers/docker.ts create mode 100644 packages/deployer/src/providers/github-pages.ts create mode 100644 packages/deployer/src/providers/netlify.ts create mode 100644 packages/deployer/src/providers/nginx.ts create mode 100644 packages/deployer/src/providers/vercel.ts create mode 100644 packages/deployer/tsconfig.json create mode 100644 packages/engines/js/LICENSE create mode 100644 packages/engines/js/README.md create mode 100644 packages/engines/js/package.json create mode 100644 packages/engines/js/src/index.ts create mode 100644 packages/engines/js/tsconfig.json create mode 100644 packages/engines/rust-binaries/LICENSE create mode 100644 packages/engines/rust-binaries/README.md create mode 100755 packages/engines/rust-binaries/bin/docmd-engine-darwin-arm64.node create mode 100644 packages/engines/rust-binaries/build.js create mode 100644 packages/engines/rust-binaries/native/Cargo.lock create mode 100644 packages/engines/rust-binaries/native/Cargo.toml create mode 100644 packages/engines/rust-binaries/native/build.rs create mode 100644 packages/engines/rust-binaries/native/src/lib.rs create mode 100644 packages/engines/rust-binaries/package.json create mode 100644 packages/engines/rust/LICENSE create mode 100644 packages/engines/rust/README.md create mode 100644 packages/engines/rust/package.json create mode 100644 packages/engines/rust/scripts/postinstall.cjs create mode 100644 packages/engines/rust/src/index.ts create mode 100644 packages/engines/rust/tsconfig.json create mode 100644 packages/legacy/doc.md/LICENSE create mode 100644 packages/legacy/doc.md/README.md create mode 100644 packages/legacy/doc.md/bin/docmd.js create mode 100644 packages/legacy/doc.md/package.json create mode 100644 packages/legacy/mgks/LICENSE create mode 100644 packages/legacy/mgks/README.md create mode 100755 packages/legacy/mgks/bin/docmd.js create mode 100644 packages/legacy/mgks/package.json create mode 100644 packages/live/LICENSE create mode 100644 packages/live/README.md create mode 100755 packages/live/bin/docmd-live.js create mode 100644 packages/live/package.json create mode 100644 packages/live/src/browser-entry.ts create mode 100644 packages/live/src/build.ts create mode 100644 packages/live/src/docmd-live-preview.css create mode 100644 packages/live/src/docmd-live.css create mode 100644 packages/live/src/index.html create mode 100644 packages/live/src/index.ts create mode 100644 packages/live/src/shims.js create mode 100644 packages/live/src/shims.ts create mode 100644 packages/live/tsconfig.json create mode 100644 packages/parser/LICENSE create mode 100644 packages/parser/README.md create mode 100644 packages/parser/package.json create mode 100644 packages/parser/src/features/basics.ts create mode 100644 packages/parser/src/features/buttons.ts create mode 100644 packages/parser/src/features/changelog.ts create mode 100644 packages/parser/src/features/common-containers.ts create mode 100644 packages/parser/src/features/embed.ts create mode 100644 packages/parser/src/features/hero.ts create mode 100644 packages/parser/src/features/index.ts create mode 100644 packages/parser/src/features/steps.ts create mode 100644 packages/parser/src/features/tabs.ts create mode 100644 packages/parser/src/features/tags.ts create mode 100644 packages/parser/src/html-renderer.ts create mode 100644 packages/parser/src/index.ts create mode 100644 packages/parser/src/markdown-processor.ts create mode 100644 packages/parser/src/utils/container-helper.ts create mode 100644 packages/parser/src/utils/container-normaliser.ts create mode 100644 packages/parser/src/utils/icon-renderer.ts create mode 100644 packages/parser/src/utils/navigation-helper.ts create mode 100644 packages/parser/src/utils/normalize-href.ts create mode 100644 packages/parser/src/utils/url-utils.ts create mode 100644 packages/parser/src/utils/validator.ts create mode 100644 packages/parser/test/container-normaliser.test.js create mode 100644 packages/parser/tsconfig.json create mode 100644 packages/plugins/analytics/LICENSE create mode 100644 packages/plugins/analytics/README.md create mode 100644 packages/plugins/analytics/package.json create mode 100644 packages/plugins/analytics/src/index.ts create mode 100644 packages/plugins/analytics/tsconfig.json create mode 100644 packages/plugins/git/LICENSE create mode 100644 packages/plugins/git/README.md create mode 100644 packages/plugins/git/build.js create mode 100644 packages/plugins/git/i18n/de.json create mode 100644 packages/plugins/git/i18n/en.json create mode 100644 packages/plugins/git/i18n/ko.json create mode 100644 packages/plugins/git/i18n/zh.json create mode 100644 packages/plugins/git/package.json create mode 100644 packages/plugins/git/src/client/git-widget.css create mode 100644 packages/plugins/git/src/client/git-widget.js create mode 100644 packages/plugins/git/src/index.ts create mode 100644 packages/plugins/git/tsconfig.json create mode 100644 packages/plugins/installer/LICENSE create mode 100644 packages/plugins/installer/README.md create mode 100644 packages/plugins/installer/package.json create mode 100644 packages/plugins/installer/registry/plugins.json create mode 100644 packages/plugins/installer/src/config-editor.ts create mode 100644 packages/plugins/installer/src/index.ts create mode 100644 packages/plugins/installer/tsconfig.json create mode 100644 packages/plugins/llms/LICENSE create mode 100644 packages/plugins/llms/README.md create mode 100644 packages/plugins/llms/package.json create mode 100644 packages/plugins/llms/src/index.ts create mode 100644 packages/plugins/llms/tests/llms.test.js create mode 100644 packages/plugins/llms/tsconfig.json create mode 100644 packages/plugins/math/LICENSE create mode 100644 packages/plugins/math/README.md create mode 100644 packages/plugins/math/package.json create mode 100644 packages/plugins/math/src/index.ts create mode 100644 packages/plugins/math/tsconfig.json create mode 100644 packages/plugins/mermaid/LICENSE create mode 100644 packages/plugins/mermaid/README.md create mode 100644 packages/plugins/mermaid/package.json create mode 100644 packages/plugins/mermaid/src/client.ts create mode 100644 packages/plugins/mermaid/src/index.ts create mode 100644 packages/plugins/mermaid/src/svg-utils.ts create mode 100644 packages/plugins/mermaid/tests/svg-utils.test.ts create mode 100644 packages/plugins/mermaid/tsconfig.json create mode 100644 packages/plugins/okf/LICENSE create mode 100644 packages/plugins/okf/README.md create mode 100644 packages/plugins/okf/package.json create mode 100644 packages/plugins/okf/src/content.ts create mode 100644 packages/plugins/okf/src/graph-assets.ts create mode 100644 packages/plugins/okf/src/graph-runtime.ts create mode 100644 packages/plugins/okf/src/graph-styles.ts create mode 100644 packages/plugins/okf/src/graph-template.ts create mode 100644 packages/plugins/okf/src/index.ts create mode 100644 packages/plugins/okf/src/yaml.ts create mode 100644 packages/plugins/okf/tests/brute.test.ts create mode 100644 packages/plugins/okf/tests/index.test.ts create mode 100644 packages/plugins/okf/tests/tsconfig.json create mode 100644 packages/plugins/okf/tsconfig.build.json create mode 100644 packages/plugins/okf/tsconfig.json create mode 100644 packages/plugins/openapi/LICENSE create mode 100644 packages/plugins/openapi/README.md create mode 100644 packages/plugins/openapi/build.js create mode 100644 packages/plugins/openapi/package.json create mode 100644 packages/plugins/openapi/src/index.ts create mode 100644 packages/plugins/openapi/src/openapi.css create mode 100644 packages/plugins/openapi/tsconfig.json create mode 100644 packages/plugins/pwa/LICENSE create mode 100644 packages/plugins/pwa/README.md create mode 100644 packages/plugins/pwa/package.json create mode 100644 packages/plugins/pwa/src/index.ts create mode 100644 packages/plugins/pwa/tsconfig.json create mode 100644 packages/plugins/search/LICENSE create mode 100644 packages/plugins/search/README.md create mode 100644 packages/plugins/search/i18n/en.json create mode 100644 packages/plugins/search/i18n/hi.json create mode 100644 packages/plugins/search/i18n/ko.json create mode 100644 packages/plugins/search/i18n/zh.json create mode 100644 packages/plugins/search/package.json create mode 100644 packages/plugins/search/src/client.ts create mode 100644 packages/plugins/search/src/index.ts create mode 100644 packages/plugins/search/src/semantic-client.ts create mode 100644 packages/plugins/search/src/worker.ts create mode 100644 packages/plugins/search/tsconfig.json create mode 100644 packages/plugins/seo/LICENSE create mode 100644 packages/plugins/seo/README.md create mode 100644 packages/plugins/seo/package.json create mode 100644 packages/plugins/seo/src/index.ts create mode 100644 packages/plugins/seo/tsconfig.json create mode 100644 packages/plugins/sitemap/LICENSE create mode 100644 packages/plugins/sitemap/README.md create mode 100644 packages/plugins/sitemap/package.json create mode 100644 packages/plugins/sitemap/src/index.ts create mode 100644 packages/plugins/sitemap/tsconfig.json create mode 100644 packages/plugins/threads/LICENSE create mode 100644 packages/plugins/threads/README.md create mode 100644 packages/plugins/threads/build.js create mode 100644 packages/plugins/threads/e2e/basic-ui.e2e.spec.ts create mode 100644 packages/plugins/threads/e2e/comment-display.e2e.spec.ts create mode 100644 packages/plugins/threads/e2e/fixtures/playground-index.md create mode 100644 packages/plugins/threads/e2e/globals.d.ts create mode 100644 packages/plugins/threads/e2e/helpers.ts create mode 100644 packages/plugins/threads/e2e/inline-editor.e2e.spec.ts create mode 100644 packages/plugins/threads/e2e/navigation.e2e.spec.ts create mode 100644 packages/plugins/threads/e2e/reactions.e2e.spec.ts create mode 100644 packages/plugins/threads/e2e/replies-deletion.e2e.spec.ts create mode 100644 packages/plugins/threads/e2e/resolve-threads.e2e.spec.ts create mode 100644 packages/plugins/threads/e2e/screenplay.ts create mode 100644 packages/plugins/threads/e2e/thread-creation.e2e.spec.ts create mode 100644 packages/plugins/threads/e2e/tsconfig.json create mode 100644 packages/plugins/threads/i18n/en.json create mode 100644 packages/plugins/threads/i18n/hi.json create mode 100644 packages/plugins/threads/i18n/ko.json create mode 100644 packages/plugins/threads/i18n/zh.json create mode 100644 packages/plugins/threads/package.json create mode 100644 packages/plugins/threads/playwright.config.ts create mode 100644 packages/plugins/threads/src/client/components/styles.ts create mode 100644 packages/plugins/threads/src/client/components/threads-app.ts create mode 100644 packages/plugins/threads/src/client/components/threads-comment.ts create mode 100644 packages/plugins/threads/src/client/components/threads-compose.ts create mode 100644 packages/plugins/threads/src/client/components/threads-identity.ts create mode 100644 packages/plugins/threads/src/client/components/threads-inline-editor.ts create mode 100644 packages/plugins/threads/src/client/components/threads-panel.ts create mode 100644 packages/plugins/threads/src/client/components/threads-popover.ts create mode 100644 packages/plugins/threads/src/client/components/threads-thread.ts create mode 100644 packages/plugins/threads/src/client/index.ts create mode 100644 packages/plugins/threads/src/client/lib/api.ts create mode 100644 packages/plugins/threads/src/client/lib/highlights.ts create mode 100644 packages/plugins/threads/src/client/lib/i18n.ts create mode 100644 packages/plugins/threads/src/client/lib/identity.ts create mode 100644 packages/plugins/threads/src/client/lib/selection.ts create mode 100644 packages/plugins/threads/src/client/lib/theme.ts create mode 100644 packages/plugins/threads/src/client/tsconfig.json create mode 100644 packages/plugins/threads/src/index.ts create mode 100644 packages/plugins/threads/src/plugin/actions.ts create mode 100644 packages/plugins/threads/src/plugin/containers.ts create mode 100644 packages/plugins/threads/src/plugin/highlight-rule.ts create mode 100644 packages/plugins/threads/src/plugin/parser.ts create mode 100644 packages/plugins/threads/src/types.ts create mode 100644 packages/plugins/threads/test-results/.last-run.json create mode 100644 packages/plugins/threads/tests/actions.test.js create mode 100644 packages/plugins/threads/tests/containers.test.js create mode 100644 packages/plugins/threads/tests/highlight-rule.test.js create mode 100644 packages/plugins/threads/tests/integration.test.js create mode 100644 packages/plugins/threads/tests/parser.test.js create mode 100644 packages/plugins/threads/tsconfig.json create mode 100644 packages/templates/summer/LICENSE create mode 100644 packages/templates/summer/README.md create mode 100644 packages/templates/summer/assets/css/summer.css create mode 100644 packages/templates/summer/assets/js/summer.js create mode 100644 packages/templates/summer/package.json create mode 100644 packages/templates/summer/scripts/copy-assets.mjs create mode 100644 packages/templates/summer/src/index.ts create mode 100644 packages/templates/summer/templates/404.ejs create mode 100644 packages/templates/summer/templates/layout.ejs create mode 100644 packages/templates/summer/templates/partials/footer.ejs create mode 100644 packages/templates/summer/templates/partials/menubar.ejs create mode 100644 packages/templates/summer/templates/partials/options-menu.ejs create mode 100644 packages/templates/summer/templates/toc.ejs create mode 100644 packages/templates/summer/tsconfig.json create mode 100644 packages/themes/LICENSE create mode 100644 packages/themes/README.md create mode 100644 packages/themes/package.json create mode 100644 packages/themes/src/docmd-theme-retro.css create mode 100644 packages/themes/src/docmd-theme-ruby.css create mode 100644 packages/themes/src/docmd-theme-sky.css create mode 100644 packages/themes/src/index.ts create mode 100644 packages/themes/tsconfig.json create mode 100644 packages/tui/LICENSE create mode 100644 packages/tui/README.md create mode 100644 packages/tui/package.json create mode 100644 packages/tui/src/index.ts create mode 100644 packages/tui/tsconfig.json create mode 100644 packages/ui/LICENSE create mode 100644 packages/ui/README.md create mode 100644 packages/ui/assets/css/docmd-highlight-dark.css create mode 100644 packages/ui/assets/css/docmd-highlight-light.css create mode 100644 packages/ui/assets/css/docmd-main.css create mode 100644 packages/ui/assets/favicon.ico create mode 100644 packages/ui/assets/images/docmd-logo-dark.png create mode 100644 packages/ui/assets/images/docmd-logo-light.png create mode 100644 packages/ui/assets/images/docmd-logo.png create mode 100644 packages/ui/assets/js/docmd-api.js create mode 100644 packages/ui/assets/js/docmd-i18n-strings.js create mode 100644 packages/ui/assets/js/docmd-image-lightbox.js create mode 100644 packages/ui/assets/js/docmd-main.js create mode 100644 packages/ui/package.json create mode 100644 packages/ui/src/index.ts create mode 100644 packages/ui/src/template-resolver.ts create mode 100644 packages/ui/templates/404.ejs create mode 100644 packages/ui/templates/docmd-search.ejs create mode 100644 packages/ui/templates/layout.ejs create mode 100644 packages/ui/templates/navigation.ejs create mode 100644 packages/ui/templates/no-style.ejs create mode 100644 packages/ui/templates/partials/banner.ejs create mode 100644 packages/ui/templates/partials/cookie-consent.ejs create mode 100644 packages/ui/templates/partials/footer.ejs create mode 100644 packages/ui/templates/partials/language-switcher.ejs create mode 100644 packages/ui/templates/partials/menubar.ejs create mode 100644 packages/ui/templates/partials/options-menu.ejs create mode 100644 packages/ui/templates/partials/project-switcher.ejs create mode 100644 packages/ui/templates/partials/theme-init.js create mode 100644 packages/ui/templates/partials/version-dropdown.ejs create mode 100644 packages/ui/templates/toc.ejs create mode 100644 packages/ui/translations/de.json create mode 100644 packages/ui/translations/en.json create mode 100644 packages/ui/translations/es.json create mode 100644 packages/ui/translations/fr.json create mode 100644 packages/ui/translations/hi.json create mode 100644 packages/ui/translations/ja.json create mode 100644 packages/ui/translations/ko.json create mode 100644 packages/ui/translations/zh.json create mode 100644 packages/ui/tsconfig.json create mode 100644 packages/utils/LICENSE create mode 100644 packages/utils/README.md create mode 100644 packages/utils/package.json create mode 100644 packages/utils/src/fs-utils.ts create mode 100644 packages/utils/src/git.ts create mode 100644 packages/utils/src/hash.ts create mode 100644 packages/utils/src/html-escape.ts create mode 100644 packages/utils/src/index.ts create mode 100644 packages/utils/src/path.ts create mode 100644 packages/utils/src/watcher-utils.ts create mode 100644 packages/utils/src/worker-pool.ts create mode 100644 packages/utils/test/html-escape.test.js create mode 100644 packages/utils/test/path.test.js create mode 100644 packages/utils/tsconfig.json create mode 100644 pnpm-lock.yaml create mode 100644 pnpm-workspace.yaml create mode 100644 scripts/build-plugin-registry.mjs create mode 100644 scripts/probe-threads-xss.mjs create mode 100644 tests/cli-contracts/asset-base-url.test.js create mode 100644 tests/cli-contracts/deploy.test.js create mode 100644 tests/cli-contracts/exit-codes.test.js create mode 100644 tests/cli-contracts/i18n.test.js create mode 100644 tests/cli-contracts/llms-and-tui.test.js create mode 100644 tests/cli-contracts/migrate-fix.test.js create mode 100644 tests/cli-contracts/migrate.test.js create mode 100644 tests/cli-contracts/offline-links.test.js create mode 100644 tests/cli-contracts/plugin-add-remove.test.js create mode 100644 tests/cli-contracts/plugin-assets-pipeline.test.js create mode 100644 tests/cli-contracts/plugin-contract.test.js create mode 100644 tests/cli-contracts/runtime-deps.test.js create mode 100644 tests/cli-contracts/source-tools.test.js create mode 100644 tests/cli-contracts/stop.test.js create mode 100644 tests/cli-contracts/validate-workspace.test.js create mode 100644 tests/feature-integration.test.js create mode 100644 tests/package.json create mode 100644 tests/runner.js create mode 100644 tests/security.test.js create mode 100644 tests/shared.js create mode 100644 tools/bump.js create mode 100755 tools/docker-prebuild.sh create mode 100644 tools/prep.js create mode 100644 tools/print-okf-runtime-deps.js create mode 100644 tools/resolve-ws-deps.js create mode 100644 tools/security-audit.mjs create mode 100644 tools/status.js create mode 100644 tools/verify.js create mode 100644 tsconfig.base.json diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..eba1110 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# Auto detect text files and perform LF normalization +* text=auto \ No newline at end of file diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..063f369 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,48 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at hello@mgks.dev. +All complaints will be reviewed and investigated promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html \ No newline at end of file diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..e9f4607 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,85 @@ +# Contributing to `docmd` + + +Thank you for your interest in contributing to `docmd`! We appreciate all contributions, from bug fixes and documentation improvements to new features and design suggestions. + +## Development Environment + +`docmd` is a monorepo managed with [pnpm](https://pnpm.io/). + +### Prerequisites + +- **Node.js**: v22.x or later (LTS recommended) +- **pnpm**: v10.x or later + +### Project Setup + +Clone the repository and set up the development environment: + +```bash +git clone https://github.com/docmd-io/docmd.git +cd docmd +pnpm prep +``` + +To also link the local `docmd` command globally for testing in other projects: + +```bash +pnpm prep --link +``` + +### Local Development + +Run the documentation site while watching for changes in the core engine: + +```bash +pnpm run dev +``` + +To watch internal source files (engine, templates, and plugins), set the `DOCMD_DEV` environment variable: + +```bash +DOCMD_DEV=true pnpm run dev +``` + +## Quality Standards + +Before submitting a Pull Request, please ensure your changes pass the verification suite: + +```bash +pnpm verify +``` + +### Commit Guidelines + +We use [Conventional Commits](https://www.conventionalcommits.org/). Please prefix your commit messages with: +- `feat:` (New features) +- `fix:` (Bug fixes) +- `docs:` (Documentation changes) +- `refactor:` (Code changes that neither fix bugs nor add features) + +### Source Headers + +All new files within the `packages/` directory MUST include the standard project copyright header to maintain consistency and compliance. + +```javascript +/** + * -------------------------------------------------------------------- + * docmd : the minimalist, zero-config documentation generator. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ +``` + +## GitHub Workflow + +1. **Fork and Branch**: Create a feature branch from the latest `main`. +2. **Verify**: Ensure `pnpm verify` returns `๐Ÿ›ก๏ธ docmd is ready for production!`. +3. **Pull Request**: Open a PR with a clear description of the problem solved or the feature added. \ No newline at end of file diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..30d952a --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,15 @@ +# These are supported funding model platforms + +github: mgks # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] +patreon: # Replace with a single Patreon username +open_collective: # Replace with a single Open Collective username +ko_fi: # Replace with a single Ko-fi username +tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel +community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry +liberapay: # Replace with a single Liberapay username +issuehunt: # Replace with a single IssueHunt username +lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry +polar: # Replace with a single Polar username +buy_me_a_coffee: # Replace with a single Buy Me a Coffee username +thanks_dev: # Replace with a single thanks.dev username +custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..661cf65 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,58 @@ +name: ๐Ÿž Bug Report +description: Create a report to help us improve docmd +title: "[Bug]: " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! + - type: input + id: version + attributes: + label: docmd version + description: What version of docmd are you using? (e.g. 0.2.6) + placeholder: 0.2.6 + validations: + required: true + - type: input + id: node-version + attributes: + label: Node.js version + placeholder: v20.x + validations: + required: true + - type: dropdown + id: os + attributes: + label: OS/Browser + options: + - macOS / Safari + - Windows / Edge + - Linux / Chrome + validations: + required: true + - type: textarea + id: description + attributes: + label: Description + description: A clear and concise description of what the bug is. + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: Please provide the steps to reproduce the behavior. + placeholder: | + 1. Run 'docmd init' + 2. Add configuration... + 3. Run 'docmd build' + 4. See error... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: A clear and concise description of what you expected to happen. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..d817464 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,27 @@ +name: ๐Ÿ’ก Feature Request +description: Suggest an idea for this project +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a new feature! + - type: textarea + id: problem + attributes: + label: Is your feature request related to a problem? + description: A clear and concise description of what the problem is. + placeholder: I'm always frustrated when... + - type: textarea + id: solution + attributes: + label: Describe the solution you'd like + description: A clear and concise description of what you want to happen. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Describe alternatives you've considered + description: A clear and concise description of any alternative solutions or features you've considered. \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..8ac63f6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,16 @@ +## Description + + +Fixes # (issue) + +## Type of change +- [ ] ๐Ÿ› Bug fix (non-breaking change which fixes an issue) +- [ ] โœจ New feature (non-breaking change which adds functionality) +- [ ] ๐Ÿ’ฅ Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] ๐Ÿ“ Documentation update + +## Checklist: +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings \ No newline at end of file diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..82782f8 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,18 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +| ------- | ------------------ | +| 0.2.x | :white_check_mark: | +| 0.1.x | :x: | + +## Reporting a Vulnerability + +Use this section to tell people how to report a vulnerability. + +Please do not report security vulnerabilities through public GitHub issues. + +If you have discovered a security vulnerability in `docmd`, please email hello@mgks.dev. + +We will do our best to respond within 48 hours. \ No newline at end of file diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..a0efb43 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,44 @@ +version: 2 +updates: + # ------------------------------------------------------- + # 1. GitHub Actions (Universal for all your projects) + # Keeps your workflow files (checkout, setup-node) updated + # ------------------------------------------------------- + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + groups: + actions: + patterns: + - "*" + + # ------------------------------------------------------- + # 2. NPM (Specific to tree-fs / Node projects) + # ------------------------------------------------------- + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + # Ignore major updates automatically to prevent breaking changes + # Remove this 'ignore' block if you want to see v1 -> v2 updates + ignore: + - dependency-name: "*" + update-types: ["version-update:semver-major"] + groups: + # Group all minor/patch updates into one PR + npm-dependencies: + patterns: + - "*" + + # ------------------------------------------------------- + # 3. (Optional) Uncomment for Python projects + # ------------------------------------------------------- + # - package-ecosystem: "pip" + # directory: "/" + # schedule: + # interval: "weekly" + # groups: + # python-deps: + # patterns: + # - "*" \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..4eb04d4 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,40 @@ +name: docmd CI verification + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + workflow_dispatch: + +permissions: + contents: read + +jobs: + verify: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v7 + + - name: Install pnpm + uses: pnpm/action-setup@v6 + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: '24' + cache: 'pnpm' + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Build packages + run: pnpm -r run build + + - name: Run verification + run: pnpm verify --skip-setup + + - name: Run Linting + run: pnpm lint \ No newline at end of file diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml new file mode 100644 index 0000000..2b9073a --- /dev/null +++ b/.github/workflows/docker-publish.yml @@ -0,0 +1,219 @@ +# -------------------------------------------------------------------- +# docmd : the minimalist, zero-config documentation generator. +# +# @package @docmd/core (and ecosystem) +# @website https://docmd.io +# @repository https://github.com/docmd-io/docmd +# @license MIT +# @copyright Copyright (c) 2025-present docmd.io +# +# [docmd-source] - Please do not remove this header. +# -------------------------------------------------------------------- +# +# GitHub Actions workflow for building and publishing Docker images +# Uses OIDC (OpenID Connect) for passwordless authentication to GHCR +# +# Triggers: +# - Release published on GitHub +# - Manual workflow dispatch +# - Push to main (for testing) +# +# -------------------------------------------------------------------- + +name: Build and Push Docker Image + +on: + release: + types: [published] + push: + tags: + - 'v*' + workflow_dispatch: + inputs: + push_image: + description: 'Push image to registry' + required: false + default: true + type: boolean + version: + description: 'Version tag (e.g., X.Y.Z)' + required: false + type: string + tag_latest: + description: 'Also tag this build as :latest (use only for stable releases)' + required: false + default: false + type: boolean + +permissions: + contents: read + packages: write + id-token: write # Required for OIDC + +env: + REGISTRY: ghcr.io + +jobs: + # --------------------------------------------------------------------------- + # Build and push Docker image + # --------------------------------------------------------------------------- + build: + name: Build Docker Image + runs-on: ubuntu-latest + outputs: + version: ${{ steps.meta.outputs.version }} + tags: ${{ steps.meta.outputs.tags }} + + steps: + - name: Checkout repository + uses: actions/checkout@v7 + + # ------------------------------------------------------------------------- + # Set up Docker Buildx for multi-platform builds + # ------------------------------------------------------------------------- + - name: Set up QEMU + uses: docker/setup-qemu-action@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v4 + + # ------------------------------------------------------------------------- + # Login to GitHub Container Registry using OIDC + # The id-token: write permission enables passwordless authentication + # ------------------------------------------------------------------------- + - name: Login to GitHub Container Registry + uses: docker/login-action@v4 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + # ------------------------------------------------------------------------- + # Extract metadata for Docker + # ------------------------------------------------------------------------- + - name: Extract Docker metadata + # Skip on plain branch pushes (the "for testing" trigger) โ€” the + # build below is local-only (push: is gated to release / manual), + # so no tags are needed and the action's tag rules don't apply. + if: github.event_name != 'push' || startsWith(github.ref, 'refs/tags/') + id: meta + uses: docker/metadata-action@v6 + with: + images: ${{ env.REGISTRY }}/${{ github.repository }} + # Two and only two tags are ever produced for any single image: + # - The version (e.g. X.Y.Z, v-prefix stripped) + # - The floating `:latest` alias + # `:latest` is only ever applied to released versions. A branch + # build or unreleased commit can never be pulled as `:latest`. + # flavor=latest=false disables the action's auto-latest so the + # only source of `:latest` is the explicit rule below. + flavor: | + latest=false + tags: | + # Version: ref on tag push and release events (strips 'v' prefix) + type=ref,event=tag + # :latest โ€” only on release events + type=raw,value=latest,enable=${{ github.event_name == 'release' }} + # Manual dispatch: use provided version + optional :latest + type=raw,value=${{ inputs.version }},enable=${{ github.event_name == 'workflow_dispatch' && inputs.version != '' }} + type=raw,value=latest,enable=${{ github.event_name == 'workflow_dispatch' && inputs.tag_latest }} + labels: | + org.opencontainers.image.title=docmd + org.opencontainers.image.description=The minimalist, zero-config documentation generator + org.opencontainers.image.vendor=docmd.io + org.opencontainers.image.licenses=MIT + + # ------------------------------------------------------------------------- + # Build and push Docker image + # Multi-platform: linux/amd64, linux/arm64 + # ------------------------------------------------------------------------- + - name: Build and push Docker image + uses: docker/build-push-action@v7 + with: + context: . + file: ./docker/Dockerfile + platforms: linux/amd64,linux/arm64 + push: ${{ github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.push_image) }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max + provenance: true + sbom: true + + # ------------------------------------------------------------------------- + # Output build info + # ------------------------------------------------------------------------- + - name: Output image info + run: | + echo "## Docker Image Published! :whale:" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Image Details" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY + echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY + echo "| Registry | \`${{ env.REGISTRY }}\` |" >> $GITHUB_STEP_SUMMARY + echo "| Image | \`${{ env.REGISTRY }}/${{ github.repository }}:${{ steps.meta.outputs.version }}\` |" >> $GITHUB_STEP_SUMMARY + echo "| Version | \`${{ steps.meta.outputs.version }}\` |" >> $GITHUB_STEP_SUMMARY + echo "| Platforms | \`linux/amd64, linux/arm64\` |" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Usage" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo '```bash' >> $GITHUB_STEP_SUMMARY + echo "# Pull the image" >> $GITHUB_STEP_SUMMARY + echo "docker pull ${{ env.REGISTRY }}/${{ github.repository }}:${{ steps.meta.outputs.version }}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "# Run development server" >> $GITHUB_STEP_SUMMARY + echo "docker run -v \$(pwd)/docs:/docs -p 3000:3000 ${{ env.REGISTRY }}/${{ github.repository }}:${{ steps.meta.outputs.version }}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "# Build static site" >> $GITHUB_STEP_SUMMARY + echo "docker run -v \$(pwd)/docs:/docs -v \$(pwd)/site:/site ${{ env.REGISTRY }}/${{ github.repository }}:${{ steps.meta.outputs.version }} build" >> $GITHUB_STEP_SUMMARY + echo '```' >> $GITHUB_STEP_SUMMARY + + # --------------------------------------------------------------------------- + # Test the Docker image (optional but recommended) + # --------------------------------------------------------------------------- + test: + name: Test Docker Image + needs: build + runs-on: ubuntu-latest + if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && inputs.push_image) + + steps: + - name: Checkout repository + uses: actions/checkout@v7 + + - name: Login to GitHub Container Registry + uses: docker/login-action@v4 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Pull image + run: docker pull ${{ env.REGISTRY }}/${{ github.repository }}:${{ needs.build.outputs.version }} + + - name: Test build command + run: | + # Create test directory with proper permissions for container user (UID 1001) + mkdir -p /tmp/docmd-test + sudo chown -R 1001:1001 /tmp/docmd-test + + # Simulate exactly what a new user does: init a project then build it + docker run --rm \ + -v /tmp/docmd-test:/workspace \ + --workdir /workspace \ + --entrypoint sh \ + ${{ env.REGISTRY }}/${{ github.repository }}:${{ needs.build.outputs.version }} \ + -c "cp -r /template/. /workspace/ && docmd build" + + - name: Verify build output + run: | + if [ -f "/tmp/docmd-test/site/index.html" ]; then + echo "โœ… Build successful - site/index.html exists" + echo "๐Ÿ“Š Site size: $(du -sh /tmp/docmd-test/site | cut -f1)" + else + echo "โŒ Build failed - site/index.html not found" + ls -la /tmp/docmd-test/ + exit 1 + fi \ No newline at end of file diff --git a/.github/workflows/npm-publish.yml b/.github/workflows/npm-publish.yml new file mode 100644 index 0000000..98b192a --- /dev/null +++ b/.github/workflows/npm-publish.yml @@ -0,0 +1,180 @@ +name: Release docmd to NPM + +on: + release: + types: [published] + workflow_dispatch: + +permissions: + contents: read + id-token: write + packages: write + +# --------------------------------------------------------------------------- +# Job 1: Build Rust native binaries (matrix, one runner per platform) +# +# Each runner compiles the napi-rs addon for its target, then uploads the +# resulting .node file as a workflow artifact. The publish job downloads +# all artifacts and places them in rust-binaries/bin/ before publishing. +# --------------------------------------------------------------------------- +jobs: + build-native: + name: Build native (${{ matrix.target }}) + strategy: + fail-fast: false + matrix: + include: + - os: macos-latest # Apple Silicon runner (M-series) + target: aarch64-apple-darwin + binary: docmd-engine-darwin-arm64.node + lib: libdocmd_engine.dylib + + - os: macos-latest # Cross-compile Intel binary on ARM64 runner (Faster) + target: x86_64-apple-darwin + binary: docmd-engine-darwin-x64.node + lib: libdocmd_engine.dylib + + - os: ubuntu-latest # Cross-compile Linux x64 binary on ARM64 runner (Faster) + target: x86_64-unknown-linux-gnu + binary: docmd-engine-linux-x64.node + lib: libdocmd_engine.so + + - os: ubuntu-24.04-arm # GitHub-hosted ARM64 Linux runner + target: aarch64-unknown-linux-gnu + binary: docmd-engine-linux-arm64.node + lib: libdocmd_engine.so + + - os: windows-latest # Cross-compile Windows x64 binary on ARM64 runner (Faster) + target: x86_64-pc-windows-msvc + binary: docmd-engine-win32-x64.node + lib: docmd_engine.dll + + runs-on: ${{ matrix.os }} + + steps: + - uses: actions/checkout@v7 + + - name: Install Rust toolchain + run: | + rustup toolchain install stable --profile minimal --target ${{ matrix.target }} + rustup default stable + + - name: Cache Rust build + uses: Swatinem/rust-cache@v2 + with: + workspaces: packages/engines/rust-binaries/native + + - name: Debug cargo environment + run: | + echo "PATH: $PATH" + which cargo + cargo --version + rustup show + + - name: Build native addon + working-directory: packages/engines/rust-binaries/native + run: cargo build --release --target ${{ matrix.target }} + + # Copy the built library to bin/ with the correct name + - name: Collect binary (Unix) + if: runner.os != 'Windows' + run: | + mkdir -p packages/engines/rust-binaries/bin + cp packages/engines/rust-binaries/native/target/${{ matrix.target }}/release/${{ matrix.lib }} \ + packages/engines/rust-binaries/bin/${{ matrix.binary }} + + - name: Collect binary (Windows) + if: runner.os == 'Windows' + shell: pwsh + run: | + New-Item -ItemType Directory -Force -Path packages/engines/rust-binaries/bin + Copy-Item "packages/engines/rust-binaries/native/target/${{ matrix.target }}/release/${{ matrix.lib }}" ` + "packages/engines/rust-binaries/bin/${{ matrix.binary }}" + + - name: Upload artifact + uses: actions/upload-artifact@v7 + with: + name: native-${{ matrix.target }} + path: packages/engines/rust-binaries/bin/${{ matrix.binary }} + if-no-files-found: error + + # --------------------------------------------------------------------------- + # Job 2: Publish all packages to npm + # + # Runs after all matrix builds succeed. Downloads every .node artifact into + # rust-binaries/bin/ so the package contains the binaries when npm publish runs. + # --------------------------------------------------------------------------- + publish: + name: Publish to npm + needs: build-native + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v7 + + - name: Install pnpm + uses: pnpm/action-setup@v6 + + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: '24' + registry-url: 'https://registry.npmjs.org' + cache: 'pnpm' + + - name: Upgrade npm (required for OIDC provenance) + run: npm install -g npm@11.12.1 + + - name: Install dependencies + run: pnpm install --frozen-lockfile --ignore-scripts + + # Download all .node binaries built by the matrix into rust-binaries/bin/ + - name: Download native binaries + uses: actions/download-artifact@v8 + with: + pattern: native-* + path: packages/engines/rust-binaries/bin + merge-multiple: true + + - name: Verify binaries + run: ls -lh packages/engines/rust-binaries/bin/ + + # Build TypeScript for all packages + - name: Build packages + run: pnpm -r run build + + - name: Run verification + run: pnpm verify --skip-setup + + - name: Copy LICENSE into each package + run: | + find packages -mindepth 1 -maxdepth 4 -name "package.json" \ + -not -path "*/node_modules/*" \ + -exec dirname {} \; | xargs -I % cp LICENSE % + + - name: Resolve workspace dependencies + run: node tools/resolve-ws-deps.js + + - name: Publish to npm + run: | + for dir in packages/* packages/legacy/* packages/plugins/* packages/engines/* packages/templates/*; do + if [ -f "$dir/package.json" ]; then + # Skip private packages + if grep -q '"private": true' "$dir/package.json"; then + echo "::notice::Skipping $dir: private package" + continue + fi + echo "Publishing $dir..." + exit_code=0 + publish_output=$(npm publish "./$dir" --access public --provenance 2>&1) || exit_code=$? + if [ $exit_code -ne 0 ]; then + if echo "$publish_output" | grep -q 'previously published versions\|EPRIVATE'; then + echo "::notice::Skipping $dir: Already published or private." + else + echo "::error::Failed to publish $dir" + echo "$publish_output" + exit 1 + fi + fi + fi + done \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a57f3d4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,40 @@ +# Dependencies +node_modules/ +.pnpm-debug.log* + +# Logs +logs/ +*.log + +# Build Outputs +dist/ +public/ +site/ +out/ +*.tsbuildinfo + +# OS Specific +.DS_Store +Thumbs.db + +# Project Specific +genctx.config.json +genctx.context.md +_backup/ +_documentation/ +temp-*/ +.cache/ +.vscode/ + +# Environment +.env* +!.env.example +temp-live-test.mjs + +# Rust Engine +packages/engines/rust/bin/*.node +packages/engines/rust-binaries/native/target/ + +# Docmd Cache +.docmd/ +.docmd-search/ \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.de.md b/README.de.md new file mode 100644 index 0000000..1419e26 --- /dev/null +++ b/README.de.md @@ -0,0 +1,286 @@ +
+ + EN  |  ES  |  DE  |  ๆ—ฅๆœฌ่ชž  |  FR  |  ไธญๆ–‡ + +
+ +
+ + + + + + docmd + + + +
+ +

Produktionsreife Dokumentation aus Markdown, in Sekunden.
Zero Config. AI-nativ. Fรผr Entwickler gebaut.

+ +

+ npm version + monatliche Downloads + GitHub-Sterne + Lizenz +

+ +

+ Website  ยท  + Dokumentation  ยท  + Live-Editor  ยท  + Agent Skills  ยท  + Bug melden +

+ +
+ + + docmd Standard-Theme โ€” Vorschau Light- und Dark-Mode + + +

+ +
+ +## Schnellstart + +Starten Sie docmd in jedem Ordner mit Markdown-Dateien โ€” keine Installation nรถtig: + +```bash +npx @docmd/core dev +``` + +
+ ร–ffnet unter http://localhost:3000
+ +```bash + _ _ + _| |___ ___ _____ _| | + | . | . | _| | . | + |___|___|___|_|_|_|___| + + v1.x.x + +โ”Œโ”€ Build +โ”‚ Engine JS +โ”‚ Source docs/ +โ”‚ Output site/ +โ”‚ Versions 2 (06, 05) +โ”‚ Locales 7 (en, hi, zh, es, de, ja, fr) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Data Indexing +โ”‚ [ DONE ] Syncing git metadata +โ”‚ [ DONE ] Building semantic search index (multi-version) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Publishing +โ”‚ [ DONE ] Generated robots.txt +โ”‚ [ DONE ] Generated .nojekyll (disables Jekyll on GitHub Pages) +โ”‚ [ DONE ] Generated sitemap +โ”‚ [ DONE ] Generating LLMs context files +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +โฌข Initial build completed in 1.2s. + +โ”Œโ”€ Watching +โ”‚ Source ./docs +โ”‚ Config ./docmd.config.json +โ”‚ Assets ./assets +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Development Server Running +โ”‚ Local Access http://127.0.0.1:3000 +โ”‚ Network Access http://192.168.1.6:3000 +โ”‚ Serving from ./site +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +``` +
+ +

+ docmd Dev-Server Vorschau +

+ +Die Navigation wird aus Ihrer Verzeichnisstruktur generiert. Keine Config-Datei, kein Frontmatter nรถtig, kein Framework zu lernen. + +**Wenn Sie bereit zum Verรถffentlichen sind:** + +```bash +npx @docmd/core build +``` + +Dies erzeugt eine hochoptimierte statische Site (SPA), bereit fรผr das Deployment zu Vercel, Cloudflare Pages, Netlify, GitHub Pages oder jedem beliebigen Static Host. + +**Anforderungen:** Node.js 18+ + +
+ Oder global installieren / per Docker
+ +```bash +# Global via npm installieren +npm install -g @docmd/core + +# Oder via pnpm +pnpm add -g @docmd/core + +# Ausfรผhren +docmd dev # Dev-Server starten +docmd build # Fรผr Deployment bauen +``` + +Oder per Docker: + +```bash +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.7 +``` + +> Versionieren Sie fรผr reproduzierbare Builds. + +
+ +## Warum docmd? + +| Feature | docmd | Docusaurus | MkDocs | VitePress | Mintlify | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **Config erforderlich** | **Keine** | `docusaurus.config.js` | `mkdocs.yml` | `config.mts` | `docs.json` | +| **JS-Payload** | **~18 kb** | ~250 kb | ~40 kb | ~50 kb | ~120 kb | +| **Navigation** | **Sofortige SPA** | React SPA | Vollstรคndiger Reload | Vue SPA | Gehostete SPA | +| **Versionierung** | **Nativ** | Nativ (komplex) | mike-Plugin | Manuell | Nativ | +| **i18n** | **Nativ** | Nativ (komplex) | Plugin-basiert | Nativ | Nativ | +| **Multi-Projekt** | **Nativ** | Plugin | Plugin | - | - | +| **Suche** | **Eingebaut** | Algolia (Cloud) | Eingebaut | MiniSearch | Cloud | +| **AI-Kontext (`llms.txt`)** | **Eingebaut** | - | - | - | Eingebaut | +| **MCP-Server** | **Eingebaut** | - | - | - | Eingebaut | +| **Agent Skills** | **Eingebaut** | - | - | - | - | +| **Docker-Image** | **Offiziell** | - | Offiziell | - | - | +| **Self-hosted** | **Ja** | Ja | Ja | Ja | - | +| **Kosten** | **Frei (OSS)** | Frei (OSS) | Frei (OSS) | Frei (OSS) | Freemium | + +## Features + +### Zero Config, sofortiger Start +Zeigen Sie docmd auf einen beliebigen Markdown-Ordner und es lรคuft. Die Navigation wird automatisch aus Ihrer Verzeichnisstruktur erstellt. Sie kรถnnen Ihre erste Doku schreiben und in unter einer Minute live haben โ€” kein Boilerplate, keine zu konfigurierende Build-Pipeline, keine Vorab-Entscheidungen. + +### Winzig standardmรครŸig, schnell รผberall +Der Standard-JavaScript-Payload ist ~18 kb. Seiten navigieren als sofortige SPA. Die Ausgabe ist statisches HTML โ€” SEO-optimiert, mit Sitemap, kanonischen URLs und Open-Graph-Metadaten. Offline-Volltextsuche ist eingebaut, kein Cloud-Dienst nรถtig. + +### AI-nativ +docmd ist fรผr die Art gebaut, wie Dokumentation heute gelesen und genutzt wird: +- **MCP-Server** โ€” `docmd mcp` stellt Ihre Doku AI-Agenten รผber stdio zur Verfรผgung, damit diese direkt suchen, lesen und Inhalte validieren kรถnnen. +- **Kontext (`llms.txt` / `llms-full.txt`)** โ€” vollstรคndiger Dokumentations-Kontext, zur Build-Zeit generiert, bereit fรผr jedes LLM. +- **Agent Skills** โ€” modulare Anleitungs-Sets fรผr LLMs und IDE-Agenten ([docmd-skills](https://github.com/docmd-io/docmd-skills)). +- **Als Markdown kopieren / Kontext kopieren** โ€” Ein-Klick-Buttons im Browser, optimiert zum Einfรผgen in AI-Chats. + +### Auf Skalierung ausgelegt +- Internationalisierung mit Multi-Locale-Builds +- Versionierung fรผr mehrere Dokumentations-Releases +- Workspaces fรผr Monorepos und Multi-Projekt-Setups +- Plugin-System zur Erweiterung der Kern-Funktionalitรคt +- Volle Theming-Unterstรผtzung, eingebaute Templates, eigenes CSS/JS, Light/Dark-Mode + +## CLI + +```bash +docmd dev # lokaler Dev-Server +docmd build # Fรผr Deployment bauen +docmd live # Browser-basierter Live-Editor +docmd init # neue docmd.config.json im aktuellen Ordner anlegen +docmd stop # laufende `docmd dev` / `docmd live` Server stoppen +docmd doctor # Vorab-Check: Konfiguration + Plugin-Installationsstatus +docmd migrate # Import aus Docusaurus, VitePress, MkDocs oder Starlight +docmd deploy # Config fรผr Docker, NGINX, Caddy, Vercel, Netlify generieren +docmd validate # Alle internen Links prรผfen +docmd mcp # Als MCP-Server รผber stdio betreiben +docmd add # Plugin oder Template installieren +``` + +## Plugins + +Die Kern-Funktionalitรคt wird von einem robusten Plugin-System bereitgestellt. Die Grundlagen sind standardmรครŸig enthalten, optionale Plugins kรถnnen fรผr spezifische Bedรผrfnisse hinzugefรผgt werden. + +| Plugin | Status | Beschreibung | +| :--- | :---: | :--- | +| `search` | Kern | Offline-Volltextsuche mit Fuzzy-Matching | +| `seo` | Kern | SEO-Tags und Open-Graph-Metadaten | +| `sitemap` | Kern | Generiert `sitemap.xml` | +| `git` | Kern | Git-Commit-Historie und letzte Aktualisierungsdaten | +| `analytics` | Kern | Schlanke Analytics-Integration | +| `llms` | Kern | AI-Kontext-Generierung (`llms.txt` / `llms-full.txt`) | +| `mermaid` | Kern | Mermaid-Diagramm-Unterstรผtzung | +| `openapi` | Kern | Build-Time-OpenAPI-3.x-Spec-Renderer | +| `okf` | Core | Open Knowledge Format Bundles fรผr KI-Agenten (pro Locale) | +| `pwa` | Optional | Progressive Web App โ€” Offline-Navigation | +| `threads` | Optional | Inline-Diskussions-Threads *(von @svallory)* | +| `math` | Optional | KaTeX / LaTeX-Mathematik-Rendering | + +Optionale Plugins installieren: + +```bash +docmd add +``` + +Eigene bauen: [Plugin-Entwicklungs-Leitfaden](https://docs.docmd.io/development/building-plugins/) + +## Konfiguration + +Keine Konfiguration ist nรถtig, um zu starten. Fรผgen Sie eine `docmd.config.json` (oder `.ts` / `.js`) im Projektstamm nur dann hinzu, wenn Sie mehr Kontrolle brauchen: + +```json +{ + "title": "Mein Projekt", + "url": "https://docs.meinprojekt.de", + "src": "./docs", + "out": "./dist" +} +``` + +TypeScript- und JavaScript-Konfigurationsdateien werden fรผr dynamische Werte unterstรผtzt. + +Vollstรคndige Referenz: [Konfigurations-รœbersicht](https://docs.docmd.io/configuration/overview) + +## Projektstruktur + +```text +my-docs/ +โ”œโ”€โ”€ docs/ โ† Ihre Markdown-Dateien +โ”œโ”€โ”€ assets/ โ† Bilder und statische Dateien +โ”œโ”€โ”€ docmd.config.json โ† Optionale Konfiguration +โ””โ”€โ”€ package.json +``` + +## Live-Editor + +Ein browserbasierter Editor zum Schreiben und Vorschauen von Doku โ€” kein lokales Setup erforderlich. + +

+ docmd Live-Editor Vorschau +

+ +**Probieren Sie es aus auf [live.docmd.io](https://live.docmd.io)** + +## Programmatische API + +Verwenden Sie docmd in Node.js-Skripten, CI-Pipelines oder benutzerdefinierten Build-Schritten. (Unterstรผtzt sowohl CommonJS als auch ESM.) + +```javascript +import { build } from '@docmd/core'; + +await build('./docmd.config.json', { isDev: false }); +``` + +Vollstรคndige Referenz: [Node-API](https://docs.docmd.io/development/node-api-reference/) + +## Community + +- **Bugs & Probleme** โ†’ [GitHub Issues](https://github.com/docmd-io/docmd/issues) +- **Fragen & Ideen** โ†’ [Discussions](https://github.com/orgs/docmd-io/discussions) +- **Beitragen** โ†’ [CONTRIBUTING.md](.github/CONTRIBUTING.md) +- **Roadmap** โ†’ [GitHub Discussions](https://github.com/orgs/docmd-io/discussions/2) + +## Unterstรผtzung + +- docmd bekannt zu machen ist der direkteste Weg, seine Entwicklung zu unterstรผtzen. [Teilen Sie es auf X](https://twitter.com/intent/tweet?url=https://github.com/docmd-io/docmd&text=docmd%20-%20Produktionsreife%20Doku%20aus%20Markdown%20in%20Sekunden.) mit Freunden oder geben Sie ihm einen Stern. +- Falls docmd Ihnen Zeit spart, hilft ein [GitHub-Sponsoring](https://github.com/sponsors/mgks) sehr weiter. +- Ideen oder Bugs? Erรถffnen Sie ein Issue oder eine PR, gerne auch mit eigenen Plugins. + +## Lizenz + +MIT โ€” siehe [`LICENSE`](./LICENSE) fรผr Details. \ No newline at end of file diff --git a/README.es.md b/README.es.md new file mode 100644 index 0000000..cd571e1 --- /dev/null +++ b/README.es.md @@ -0,0 +1,286 @@ +
+ + EN  |  ES  |  DE  |  ๆ—ฅๆœฌ่ชž  |  FR  |  ไธญๆ–‡ + +
+ +
+ + + + + + docmd + + + +
+ +

Documentaciรณn lista para producciรณn desde Markdown, en segundos.
Zero config. AI-nativo. Construido para desarrolladores.

+ +

+ npm version + descargas mensuales + estrellas de GitHub + licencia +

+ +

+ Sitio web  ยท  + Documentaciรณn  ยท  + Editor en vivo  ยท  + Agent Skills  ยท  + Reportar un bug +

+ +
+ + + docmd tema por defecto โ€” vista previa en modo claro y oscuro + + +

+ +
+ +## Inicio rรกpido + +Ejecuta docmd en cualquier carpeta con archivos Markdown โ€” sin instalaciรณn: + +```bash +npx @docmd/core dev +``` + +
+ Abre en http://localhost:3000
+ +```bash + _ _ + _| |___ ___ _____ _| | + | . | . | _| | . | + |___|___|___|_|_|_|___| + + v1.x.x + +โ”Œโ”€ Build +โ”‚ Engine JS +โ”‚ Source docs/ +โ”‚ Output site/ +โ”‚ Versions 2 (06, 05) +โ”‚ Locales 7 (en, hi, zh, es, de, ja, fr) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Data Indexing +โ”‚ [ DONE ] Syncing git metadata +โ”‚ [ DONE ] Building semantic search index (multi-version) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Publishing +โ”‚ [ DONE ] Generated robots.txt +โ”‚ [ DONE ] Generated .nojekyll (disables Jekyll on GitHub Pages) +โ”‚ [ DONE ] Generated sitemap +โ”‚ [ DONE ] Generating LLMs context files +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +โฌข Initial build completed in 1.2s. + +โ”Œโ”€ Watching +โ”‚ Source ./docs +โ”‚ Config ./docmd.config.json +โ”‚ Assets ./assets +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Development Server Running +โ”‚ Local Access http://127.0.0.1:3000 +โ”‚ Network Access http://192.168.1.6:3000 +โ”‚ Serving from ./site +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +``` +
+ +

+ vista previa del servidor de desarrollo docmd +

+ +La navegaciรณn se genera a partir de la estructura de archivos. Sin archivo de configuraciรณn, sin frontmatter obligatorio, sin framework que aprender. + +**Cuando estรฉs listo para publicar:** + +```bash +npx @docmd/core build +``` + +Esto produce un sitio estรกtico altamente optimizado (SPA) listo para desplegar en Vercel, Cloudflare Pages, Netlify, GitHub Pages o cualquier host estรกtico. + +**Requisitos:** Node.js 18+ + +
+ O instala globalmente / vรญa Docker
+ +```bash +# Instalar globalmente vรญa npm +npm install -g @docmd/core + +# O vรญa pnpm +pnpm add -g @docmd/core + +# Ejecutarlo +docmd dev # iniciar el servidor de desarrollo +docmd build # construir para desplegar +``` + +O ejecuta vรญa Docker: + +```bash +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.7 +``` + +> Fije una versiรณn para compilaciones reproducibles. + +
+ +## ยฟPor quรฉ docmd? + +| Caracterรญstica | docmd | Docusaurus | MkDocs | VitePress | Mintlify | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **Configuraciรณn requerida** | **Ninguna** | `docusaurus.config.js` | `mkdocs.yml` | `config.mts` | `docs.json` | +| **Payload JS** | **~18 kb** | ~250 kb | ~40 kb | ~50 kb | ~120 kb | +| **Navegaciรณn** | **SPA instantรกnea** | React SPA | Recarga completa | Vue SPA | SPA alojada | +| **Versionado** | **Nativo** | Nativo (complejo) | Plugin mike | Manual | Nativo | +| **i18n** | **Nativo** | Nativo (complejo) | Basado en plugin | Nativo | Nativo | +| **Multi-proyecto** | **Nativo** | Plugin | Plugin | - | - | +| **Bรบsqueda** | **Integrada** | Algolia (nube) | Integrada | MiniSearch | Nube | +| **Contexto IA (`llms.txt`)** | **Integrado** | - | - | - | Integrado | +| **Servidor MCP** | **Integrado** | - | - | - | Integrado | +| **Agent Skills** | **Integrado** | - | - | - | - | +| **Imagen Docker** | **Oficial** | - | Oficial | - | - | +| **Autoalojado** | **Sรญ** | Sรญ | Sรญ | Sรญ | - | +| **Coste** | **Gratis (OSS)** | Gratis (OSS) | Gratis (OSS) | Gratis (OSS) | Freemium | + +## Funcionalidades + +### Zero config, inicio instantรกneo +Apunta docmd a cualquier carpeta de Markdown y se ejecuta. La navegaciรณn se genera automรกticamente a partir de la estructura de archivos. Puedes escribir tu primer doc y tenerlo en vivo en menos de un minuto โ€” sin boilerplate, sin pipeline de build que configurar, sin decisiones que tomar por adelantado. + +### Diminuto por defecto, rรกpido en todas partes +El payload de JavaScript por defecto es ~18 kb. Las pรกginas navegan como una SPA instantรกnea. La salida es HTML estรกtico โ€” optimizado para SEO, con sitemap, URLs canรณnicas y metadatos Open Graph incluidos. Bรบsqueda offline de texto completo integrada, sin servicio en la nube necesario. + +### AI-nativo +docmd estรก construido para la forma en que la documentaciรณn se lee y se usa hoy: +- **Servidor MCP** โ€” `docmd mcp` expone tu documentaciรณn a agentes de IA sobre stdio, permitiรฉndoles buscar, leer y validar contenido directamente. +- **Contexto (`llms.txt` / `llms-full.txt`)** โ€” contexto completo de documentaciรณn generado en tiempo de build, listo para cualquier LLM. +- **Agent Skills** โ€” conjuntos de instrucciones modulares para LLMs y agentes de IDE ([docmd-skills](https://github.com/docmd-io/docmd-skills)). +- **Copiar como Markdown / Copiar contexto** โ€” botones de un clic en el navegador, optimizados para pegar en chats de IA. + +### Construido para escalar +- Internacionalizaciรณn con builds multi-idioma +- Versionado para mรบltiples releases de documentaciรณn +- Workspaces para monorepos y setups multi-proyecto +- Sistema de plugins para extender el comportamiento del nรบcleo +- Soporte completo de temas, plantillas integradas, CSS/JS personalizado, modo claro/oscuro + +## CLI + +```bash +docmd dev # servidor de desarrollo local +docmd build # construir para desplegar +docmd live # Editor en vivo basado en navegador +docmd init # crear un nuevo docmd.config.json en la carpeta actual +docmd stop # detener servidores `docmd dev` / `docmd live` en ejecuciรณn +docmd doctor # verificaciรณn previa: config + estado de instalaciรณn de plugins +docmd migrate # importar desde Docusaurus, VitePress, MkDocs o Starlight +docmd deploy # generar configuraciรณn para Docker, NGINX, Caddy, Vercel, Netlify +docmd validate # comprobar todos los enlaces internos +docmd mcp # ejecutar como servidor MCP sobre stdio +docmd add # instalar un plugin o plantilla +``` + +## Plugins + +La funcionalidad principal estรก impulsada por un sistema de plugins robusto. Lo esencial viene incluido por defecto, mientras que los plugins opcionales pueden aรฑadirse segรบn necesidades especรญficas. + +| Plugin | Estado | Descripciรณn | +| :--- | :---: | :--- | +| `search` | Nรบcleo | Bรบsqueda offline de texto completo con coincidencia difusa | +| `seo` | Nรบcleo | Etiquetas SEO y metadatos Open Graph | +| `sitemap` | Nรบcleo | Genera `sitemap.xml` | +| `git` | Nรบcleo | Historial de commits de Git y fechas de รบltima actualizaciรณn | +| `analytics` | Nรบcleo | Integraciรณn ligera de analytics | +| `llms` | Nรบcleo | Generaciรณn de contexto IA (`llms.txt` / `llms-full.txt`) | +| `mermaid` | Nรบcleo | Soporte de diagramas Mermaid | +| `openapi` | Nรบcleo | Renderizador de especificaciรณn OpenAPI 3.x en tiempo de build | +| `okf` | Core | Bundles Open Knowledge Format para agentes IA (por locale) | +| `pwa` | Opcional | Progressive Web App โ€” navegaciรณn offline | +| `threads` | Opcional | Hilos de discusiรณn inline *(por @svallory)* | +| `math` | Opcional | Renderizado matemรกtico KaTeX / LaTeX | + +Instalar plugins opcionales: + +```bash +docmd add +``` + +Crea el tuyo: [Guรญa de desarrollo de plugins](https://docs.docmd.io/development/building-plugins/) + +## Configuraciรณn + +No se requiere configuraciรณn para comenzar. Aรฑade un `docmd.config.json` (o `.ts` / `.js`) en la raรญz de tu proyecto solo cuando necesites mรกs control: + +```json +{ + "title": "Mi Proyecto", + "url": "https://docs.miproyecto.com", + "src": "./docs", + "out": "./dist" +} +``` + +Se admiten archivos de configuraciรณn TypeScript y JavaScript para valores dinรกmicos. + +Referencia completa: [Resumen de configuraciรณn](https://docs.docmd.io/configuration/overview) + +## Estructura del proyecto + +```text +my-docs/ +โ”œโ”€โ”€ docs/ โ† Tus archivos markdown +โ”œโ”€โ”€ assets/ โ† Imรกgenes y archivos estรกticos +โ”œโ”€โ”€ docmd.config.json โ† Configuraciรณn opcional +โ””โ”€โ”€ package.json +``` + +## Editor en vivo + +Un editor basado en navegador para escribir y previsualizar documentaciรณn โ€” sin configuraciรณn local. + +

+ vista previa del editor en vivo docmd +

+ +**Pruรฉbalo en [live.docmd.io](https://live.docmd.io)** + +## API programรกtica + +Usa docmd en scripts de Node.js, pipelines de CI o pasos de build personalizados. (Soporta tanto CommonJS como ESM.) + +```javascript +import { build } from '@docmd/core'; + +await build('./docmd.config.json', { isDev: false }); +``` + +Referencia completa: [Node API](https://docs.docmd.io/development/node-api-reference/) + +## Comunidad + +- **Bugs y problemas** โ†’ [GitHub Issues](https://github.com/docmd-io/docmd/issues) +- **Preguntas e ideas** โ†’ [Discussions](https://github.com/orgs/docmd-io/discussions) +- **Contribuir** โ†’ [CONTRIBUTING.md](.github/CONTRIBUTING.md) +- **Roadmap** โ†’ [GitHub Discussions](https://github.com/orgs/docmd-io/discussions/2) + +## Soporte + +- Dar a conocer docmd es la forma mรกs directa de apoyar su desarrollo. [Compรกrtelo en X](https://twitter.com/intent/tweet?url=https://github.com/docmd-io/docmd&text=docmd%20-%20Documentaciรณn%20lista%20para%20producciรณn%20desde%20Markdown%20en%20segundos.) con amigos o dale una estrella. +- Si docmd te ahorra tiempo, un [sponsorship en GitHub](https://github.com/sponsors/mgks) ayuda mucho. +- ยฟIdeas o bugs? Abre un issue o PR, siรฉntete libre de contribuir con tus propios plugins. + +## Licencia + +MIT โ€” consulta [`LICENSE`](./LICENSE) para mรกs detalles. \ No newline at end of file diff --git a/README.fr.md b/README.fr.md new file mode 100644 index 0000000..38f88db --- /dev/null +++ b/README.fr.md @@ -0,0 +1,286 @@ +
+ + EN  |  ES  |  DE  |  ๆ—ฅๆœฌ่ชž  |  FR  |  ไธญๆ–‡ + +
+ +
+ + + + + + docmd + + + +
+ +

Documentation prรชte pour la production ร  partir de Markdown, en quelques secondes.
Zero config. Native IA. Conรงu pour les dรฉveloppeurs.

+ +

+ npm version + tรฉlรฉchargements mensuels + รฉtoiles GitHub + licence +

+ +

+ Site web  ยท  + Documentation  ยท  + ร‰diteur en direct  ยท  + Agent Skills  ยท  + Signaler un bug +

+ +
+ + + docmd thรจme par dรฉfaut โ€” aperรงu en mode clair et sombre + + +

+ +
+ +## Dรฉmarrage rapide + +Lancez docmd dans n'importe quel dossier contenant des fichiers Markdown โ€” aucune installation requise : + +```bash +npx @docmd/core dev +``` + +
+ Ouvre sur http://localhost:3000
+ +```bash + _ _ + _| |___ ___ _____ _| | + | . | . | _| | . | + |___|___|___|_|_|_|___| + + v1.x.x + +โ”Œโ”€ Build +โ”‚ Engine JS +โ”‚ Source docs/ +โ”‚ Output site/ +โ”‚ Versions 2 (06, 05) +โ”‚ Locales 7 (en, hi, zh, es, de, ja, fr) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Data Indexing +โ”‚ [ DONE ] Syncing git metadata +โ”‚ [ DONE ] Building semantic search index (multi-version) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Publishing +โ”‚ [ DONE ] Generated robots.txt +โ”‚ [ DONE ] Generated .nojekyll (disables Jekyll on GitHub Pages) +โ”‚ [ DONE ] Generated sitemap +โ”‚ [ DONE ] Generating LLMs context files +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +โฌข Initial build completed in 1.2s. + +โ”Œโ”€ Watching +โ”‚ Source ./docs +โ”‚ Config ./docmd.config.json +โ”‚ Assets ./assets +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Development Server Running +โ”‚ Local Access http://127.0.0.1:3000 +โ”‚ Network Access http://192.168.1.6:3000 +โ”‚ Serving from ./site +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +``` +
+ +

+ aperรงu du serveur de dรฉveloppement docmd +

+ +La navigation est gรฉnรฉrรฉe ร  partir de votre structure de fichiers. Pas de fichier de configuration, pas de frontmatter obligatoire, pas de framework ร  apprendre. + +**Quand vous รชtes prรชt ร  publier :** + +```bash +npx @docmd/core build +``` + +Cela produit un site statique (SPA) hautement optimisรฉ, prรชt ร  รชtre dรฉployรฉ sur Vercel, Cloudflare Pages, Netlify, GitHub Pages, ou n'importe quel hรฉbergeur statique. + +**Prรฉrequis :** Node.js 18+ + +
+ Ou installer globalement / via Docker
+ +```bash +# Installer globalement via npm +npm install -g @docmd/core + +# Ou via pnpm +pnpm add -g @docmd/core + +# Lancer +docmd dev # dรฉmarrer le serveur de dรฉveloppement +docmd build # construire pour le dรฉploiement +``` + +Ou via Docker : + +```bash +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.7 +``` + +> ร‰pinglez une version pour des builds reproductibles. + +
+ +## Pourquoi docmd ? + +| Fonctionnalitรฉ | docmd | Docusaurus | MkDocs | VitePress | Mintlify | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **Configuration requise** | **Aucune** | `docusaurus.config.js` | `mkdocs.yml` | `config.mts` | `docs.json` | +| **Payload JS** | **~18 ko** | ~250 ko | ~40 ko | ~50 ko | ~120 ko | +| **Navigation** | **SPA instantanรฉe** | React SPA | Rechargement complet | Vue SPA | SPA hรฉbergรฉe | +| **Versioning** | **Natif** | Natif (complexe) | Plugin mike | Manuel | Natif | +| **i18n** | **Natif** | Natif (complexe) | Basรฉ sur plugin | Natif | Natif | +| **Multi-projet** | **Natif** | Plugin | Plugin | - | - | +| **Recherche** | **Intรฉgrรฉe** | Algolia (cloud) | Intรฉgrรฉe | MiniSearch | Cloud | +| **Contexte IA (`llms.txt`)** | **Intรฉgrรฉ** | - | - | - | Intรฉgrรฉ | +| **Serveur MCP** | **Intรฉgrรฉ** | - | - | - | Intรฉgrรฉ | +| **Agent Skills** | **Intรฉgrรฉ** | - | - | - | - | +| **Image Docker** | **Officielle** | - | Officielle | - | - | +| **Auto-hรฉbergรฉ** | **Oui** | Oui | Oui | Oui | - | +| **Coรปt** | **Libre (OSS)** | Libre (OSS) | Libre (OSS) | Libre (OSS) | Freemium | + +## Fonctionnalitรฉs + +### Zรฉro config, dรฉmarrage instantanรฉ +Pointez docmd vers n'importe quel dossier de Markdown et il s'exรฉcute. La navigation est gรฉnรฉrรฉe automatiquement ร  partir de votre structure de fichiers. Vous pouvez รฉcrire votre premier doc et l'avoir en ligne en moins d'une minute โ€” pas de boilerplate, pas de pipeline de build ร  configurer, pas de dรฉcisions ร  prendre ร  l'avance. + +### Minuscule par dรฉfaut, rapide partout +Le payload JavaScript par dรฉfaut est de ~18 ko. Les pages naviguent comme une SPA instantanรฉe. La sortie est du HTML statique โ€” optimisรฉ pour le SEO, avec sitemap, URLs canoniques et mรฉtadonnรฉes Open Graph intรฉgrรฉes. Recherche full-text hors ligne intรฉgrรฉe, sans service cloud requis. + +### Native IA +docmd est conรงu pour la faรงon dont la documentation est lue et utilisรฉe aujourd'hui : +- **Serveur MCP** โ€” `docmd mcp` expose votre documentation aux agents IA sur stdio, leur permettant de chercher, lire et valider le contenu directement. +- **Contexte (`llms.txt` / `llms-full.txt`)** โ€” contexte complet de la documentation gรฉnรฉrรฉ au build, prรชt pour tout LLM. +- **Agent Skills** โ€” ensembles d'instructions modulaires pour les LLMs et les agents IDE ([docmd-skills](https://github.com/docmd-io/docmd-skills)). +- **Copier en Markdown / Copier le contexte** โ€” boutons en un clic dans le navigateur, optimisรฉs pour coller dans un chat IA. + +### Conรงu pour passer ร  l'รฉchelle +- Internationalisation avec builds multilingues +- Versioning pour plusieurs versions de documentation +- Workspaces pour les monorepos et les configurations multi-projets +- Systรจme de plugins pour รฉtendre le comportement du cล“ur +- Support complet du theming, modรจles intรฉgrรฉs, CSS/JS personnalisรฉ, mode clair/sombre + +## CLI + +```bash +docmd dev # serveur de dรฉveloppement local +docmd build # construire pour le dรฉploiement +docmd live # รฉditeur en direct basรฉ sur le navigateur +docmd init # gรฉnรฉrer un nouveau docmd.config.json dans le dossier courant +docmd stop # arrรชter les serveurs `docmd dev` / `docmd live` en cours +docmd doctor # vรฉrification prรฉalable : config + statut d'installation des plugins +docmd migrate # importer depuis Docusaurus, VitePress, MkDocs ou Starlight +docmd deploy # gรฉnรฉrer la configuration pour Docker, NGINX, Caddy, Vercel, Netlify +docmd validate # vรฉrifier tous les liens internes +docmd mcp # exรฉcuter comme serveur MCP sur stdio +docmd add # installer un plugin ou un modรจle +``` + +## Plugins + +La fonctionnalitรฉ principale repose sur un systรจme de plugins robuste. L'essentiel est inclus par dรฉfaut, tandis que des plugins optionnels peuvent รชtre ajoutรฉs selon les besoins spรฉcifiques. + +| Plugin | Statut | Description | +| :--- | :---: | :--- | +| `search` | Cล“ur | Recherche full-text hors ligne avec correspondance approximative | +| `seo` | Cล“ur | Balises SEO et mรฉtadonnรฉes Open Graph | +| `sitemap` | Cล“ur | Gรฉnรจre `sitemap.xml` | +| `git` | Cล“ur | Historique des commits Git et dates de derniรจre mise ร  jour | +| `analytics` | Cล“ur | Intรฉgration lรฉgรจre d'analytics | +| `llms` | Cล“ur | Gรฉnรฉration du contexte IA (`llms.txt` / `llms-full.txt`) | +| `mermaid` | Cล“ur | Support des diagrammes Mermaid | +| `openapi` | Cล“ur | Rendu de spรฉcification OpenAPI 3.x au build | +| `okf` | Core | Bundles Open Knowledge Format pour agents IA (par locale) | +| `pwa` | Optionnel | Progressive Web App โ€” navigation hors ligne | +| `threads` | Optionnel | Fils de discussion inline *(par @svallory)* | +| `math` | Optionnel | Rendu mathรฉmatique KaTeX / LaTeX | + +Installer des plugins optionnels : + +```bash +docmd add +``` + +Crรฉez le vรดtre : [Guide de dรฉveloppement de plugins](https://docs.docmd.io/development/building-plugins/) + +## Configuration + +Aucune configuration n'est requise pour commencer. Ajoutez un `docmd.config.json` (ou `.ts` / `.js`) ร  la racine de votre projet uniquement lorsque vous avez besoin de plus de contrรดle : + +```json +{ + "title": "Mon Projet", + "url": "https://docs.monprojet.fr", + "src": "./docs", + "out": "./dist" +} +``` + +Les fichiers de configuration TypeScript et JavaScript sont pris en charge pour les valeurs dynamiques. + +Rรฉfรฉrence complรจte : [Aperรงu de la configuration](https://docs.docmd.io/configuration/overview) + +## Structure du projet + +```text +my-docs/ +โ”œโ”€โ”€ docs/ โ† Vos fichiers markdown +โ”œโ”€โ”€ assets/ โ† Images et fichiers statiques +โ”œโ”€โ”€ docmd.config.json โ† Configuration optionnelle +โ””โ”€โ”€ package.json +``` + +## ร‰diteur en direct + +Un รฉditeur basรฉ sur navigateur pour รฉcrire et prรฉvisualiser la documentation โ€” aucune configuration locale requise. + +

+ aperรงu de l'รฉditeur en direct docmd +

+ +**Essayez-le sur [live.docmd.io](https://live.docmd.io)** + +## API programmatique + +Utilisez docmd dans des scripts Node.js, des pipelines CI ou des รฉtapes de build personnalisรฉes. (Supporte CommonJS et ESM.) + +```javascript +import { build } from '@docmd/core'; + +await build('./docmd.config.json', { isDev: false }); +``` + +Rรฉfรฉrence complรจte : [Node API](https://docs.docmd.io/development/node-api-reference/) + +## Communautรฉ + +- **Bugs et problรจmes** โ†’ [GitHub Issues](https://github.com/docmd-io/docmd/issues) +- **Questions et idรฉes** โ†’ [Discussions](https://github.com/orgs/docmd-io/discussions) +- **Contribuer** โ†’ [CONTRIBUTING.md](.github/CONTRIBUTING.md) +- **Roadmap** โ†’ [GitHub Discussions](https://github.com/orgs/docmd-io/discussions/2) + +## Soutien + +- Faire connaรฎtre docmd est la faรงon la plus directe de soutenir son dรฉveloppement. [Partagez-le sur X](https://twitter.com/intent/tweet?url=https://github.com/docmd-io/docmd&text=docmd%20-%20Documentation%20prรชte%20pour%20la%20production%20ร %20partir%20de%20Markdown%20en%20quelques%20secondes.) avec vos amis ou attribuez-lui une รฉtoile. +- Si docmd vous fait gagner du temps, un [sponsorship GitHub](https://github.com/sponsors/mgks) est trรจs apprรฉciable. +- Des idรฉes ou des bugs ? Ouvrez une issue ou une PR, n'hรฉsitez pas ร  contribuer avec vos propres plugins. + +## Licence + +MIT โ€” voir [`LICENSE`](./LICENSE) pour plus de dรฉtails. \ No newline at end of file diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..6ec1002 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,286 @@ +
+ + EN  |  ES  |  DE  |  ๆ—ฅๆœฌ่ชž  |  FR  |  ไธญๆ–‡ + +
+ +
+ + + + + + docmd + + + +
+ +

Markdown ใ‹ใ‚‰ๆ•ฐ็ง’ใงใƒ—ใƒญใƒ€ใ‚ฏใ‚ทใƒงใƒณๅ“่ณชใฎใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใ‚’ใ€‚
Zero configใ€‚AI ใƒใ‚คใƒ†ใ‚ฃใƒ–ใ€‚้–‹็™บ่€…ใฎใŸใ‚ใซใ€‚

+ +

+ npm version + monthly downloads + GitHub stars + license +

+ +

+ ใ‚ฆใ‚งใƒ–ใ‚ตใ‚คใƒˆ  ยท  + ใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆ  ยท  + ใƒฉใ‚คใƒ–ใ‚จใƒ‡ใ‚ฃใ‚ฟ  ยท  + Agent Skills  ยท  + ใƒใ‚ฐๅ ฑๅ‘Š +

+ +
+ + + docmd ใƒ‡ใƒ•ใ‚ฉใƒซใƒˆใƒ†ใƒผใƒž โ€” ใƒฉใ‚คใƒˆ/ใƒ€ใƒผใ‚ฏใƒขใƒผใƒ‰ใฎใƒ—ใƒฌใƒ“ใƒฅใƒผ + + +

+ +
+ +## ใ‚ฏใ‚คใƒƒใ‚ฏใ‚นใ‚ฟใƒผใƒˆ + +Markdown ใƒ•ใ‚กใ‚คใƒซใŒใ‚ใ‚‹ไปปๆ„ใฎใƒ•ใ‚ฉใƒซใƒ€ใง docmd ใ‚’ๅฎŸ่กŒ โ€” ใ‚คใƒณใ‚นใƒˆใƒผใƒซไธ่ฆ๏ผš + +```bash +npx @docmd/core dev +``` + +
+ http://localhost:3000 ใง้–‹ใใพใ™
+ +```bash + _ _ + _| |___ ___ _____ _| | + | . | . | _| | . | + |___|___|___|_|_|_|___| + + v1.x.x + +โ”Œโ”€ Build +โ”‚ Engine JS +โ”‚ Source docs/ +โ”‚ Output site/ +โ”‚ Versions 2 (06, 05) +โ”‚ Locales 7 (en, hi, zh, es, de, ja, fr) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Data Indexing +โ”‚ [ DONE ] Syncing git metadata +โ”‚ [ DONE ] Building semantic search index (multi-version) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Publishing +โ”‚ [ DONE ] Generated robots.txt +โ”‚ [ DONE ] Generated .nojekyll (disables Jekyll on GitHub Pages) +โ”‚ [ DONE ] Generated sitemap +โ”‚ [ DONE ] Generating LLMs context files +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +โฌข Initial build completed in 1.2s. + +โ”Œโ”€ Watching +โ”‚ Source ./docs +โ”‚ Config ./docmd.config.json +โ”‚ Assets ./assets +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Development Server Running +โ”‚ Local Access http://127.0.0.1:3000 +โ”‚ Network Access http://192.168.1.6:3000 +โ”‚ Serving from ./site +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +``` +
+ +

+ docmd dev ใ‚ตใƒผใƒใƒผใฎใƒ—ใƒฌใƒ“ใƒฅใƒผ +

+ +ใƒŠใƒ“ใ‚ฒใƒผใ‚ทใƒงใƒณใฏใƒ•ใ‚กใ‚คใƒซๆง‹้€ ใ‹ใ‚‰่‡ชๅ‹•็”Ÿๆˆใ•ใ‚Œใพใ™ใ€‚่จญๅฎšใƒ•ใ‚กใ‚คใƒซไธ่ฆใ€frontmatter ๅฟ…้ ˆใชใ—ใ€ๅญฆใถในใใƒ•ใƒฌใƒผใƒ ใƒฏใƒผใ‚ฏใ‚‚ใ‚ใ‚Šใพใ›ใ‚“ใ€‚ + +**ๅ…ฌ้–‹ใฎๆบ–ๅ‚™ใŒใงใใŸใ‚‰๏ผš** + +```bash +npx @docmd/core build +``` + +ใ“ใ‚Œใฏ Vercelใ€Cloudflare Pagesใ€Netlifyใ€GitHub Pagesใ€ใใฎไป–ใฎ้™็š„ใƒ›ใ‚นใƒˆใซใƒ‡ใƒ—ใƒญใ‚คๅฏ่ƒฝใชใ€้ซ˜ๅบฆใซๆœ€้ฉๅŒ–ใ•ใ‚ŒใŸ้™็š„ใ‚ตใ‚คใƒˆ๏ผˆSPA๏ผ‰ใ‚’ๅ‡บๅŠ›ใ—ใพใ™ใ€‚ + +**่ฆไปถ๏ผš** Node.js 18+ + +
+ ใพใŸใฏใ‚ฐใƒญใƒผใƒใƒซใ‚คใƒณใ‚นใƒˆใƒผใƒซ / Docker ็ตŒ็”ฑ
+ +```bash +# npm ใงใ‚ฐใƒญใƒผใƒใƒซใ‚คใƒณใ‚นใƒˆใƒผใƒซ +npm install -g @docmd/core + +# ใพใŸใฏ pnpm +pnpm add -g @docmd/core + +# ๅฎŸ่กŒ +docmd dev # dev ใ‚ตใƒผใƒใƒผใ‚’่ตทๅ‹• +docmd build # ใƒ‡ใƒ—ใƒญใ‚ค็”จใซใƒ“ใƒซใƒ‰ +``` + +ใพใŸใฏ Docker ็ตŒ็”ฑ๏ผš + +```bash +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.7 +``` + +> ๅ†็พๅฏ่ƒฝใชใƒ“ใƒซใƒ‰ใฎใŸใ‚ใซใƒใƒผใ‚ธใƒงใƒณใ‚’ๅ›บๅฎšใ—ใฆใใ ใ•ใ„ใ€‚ + +
+ +## ใชใœ docmd๏ผŸ + +| ๆฉŸ่ƒฝ | docmd | Docusaurus | MkDocs | VitePress | Mintlify | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **่จญๅฎšใŒๅฟ…่ฆ** | **ใชใ—** | `docusaurus.config.js` | `mkdocs.yml` | `config.mts` | `docs.json` | +| **JS ใƒšใ‚คใƒญใƒผใƒ‰** | **~18 kb** | ~250 kb | ~40 kb | ~50 kb | ~120 kb | +| **ใƒŠใƒ“ใ‚ฒใƒผใ‚ทใƒงใƒณ** | **ๅณๆ™‚ SPA** | React SPA | ใƒ•ใƒซใƒชใƒญใƒผใƒ‰ | Vue SPA | ใƒ›ใ‚นใƒˆๅž‹ SPA | +| **ใƒใƒผใ‚ธใƒงใƒณ็ฎก็†** | **ใƒใ‚คใƒ†ใ‚ฃใƒ–** | ใƒใ‚คใƒ†ใ‚ฃใƒ–๏ผˆ่ค‡้›‘๏ผ‰ | mike ใƒ—ใƒฉใ‚ฐใ‚คใƒณ | ๆ‰‹ๅ‹• | ใƒใ‚คใƒ†ใ‚ฃใƒ– | +| **i18n** | **ใƒใ‚คใƒ†ใ‚ฃใƒ–** | ใƒใ‚คใƒ†ใ‚ฃใƒ–๏ผˆ่ค‡้›‘๏ผ‰ | ใƒ—ใƒฉใ‚ฐใ‚คใƒณใƒ™ใƒผใ‚น | ใƒใ‚คใƒ†ใ‚ฃใƒ– | ใƒใ‚คใƒ†ใ‚ฃใƒ– | +| **ใƒžใƒซใƒใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆ** | **ใƒใ‚คใƒ†ใ‚ฃใƒ–** | ใƒ—ใƒฉใ‚ฐใ‚คใƒณ | ใƒ—ใƒฉใ‚ฐใ‚คใƒณ | - | - | +| **ๆคœ็ดข** | **็ต„ใฟ่พผใฟ** | Algolia๏ผˆใ‚ฏใƒฉใ‚ฆใƒ‰๏ผ‰ | ็ต„ใฟ่พผใฟ | MiniSearch | ใ‚ฏใƒฉใ‚ฆใƒ‰ | +| **AI ใ‚ณใƒณใƒ†ใ‚ญใ‚นใƒˆ (`llms.txt`)** | **็ต„ใฟ่พผใฟ** | - | - | - | ็ต„ใฟ่พผใฟ | +| **MCP ใ‚ตใƒผใƒใƒผ** | **็ต„ใฟ่พผใฟ** | - | - | - | ็ต„ใฟ่พผใฟ | +| **Agent Skills** | **็ต„ใฟ่พผใฟ** | - | - | - | - | +| **Docker ใ‚คใƒกใƒผใ‚ธ** | **ๅ…ฌๅผ** | - | ๅ…ฌๅผ | - | - | +| **ใ‚ปใƒซใƒ•ใƒ›ใ‚นใƒˆ** | **ๅฏ** | ๅฏ | ๅฏ | ๅฏ | - | +| **ใ‚ณใ‚นใƒˆ** | **็„กๆ–™ (OSS)** | ็„กๆ–™ (OSS) | ็„กๆ–™ (OSS) | ็„กๆ–™ (OSS) | ใƒ•ใƒชใƒผใƒŸใ‚ขใƒ  | + +## ๆฉŸ่ƒฝ + +### Zero configใ€ๅณๆ™‚ใ‚นใ‚ฟใƒผใƒˆ +ไปปๆ„ใฎ Markdown ใƒ•ใ‚ฉใƒซใƒ€ใ‚’ docmd ใซๆŒ‡ๅฎšใ™ใ‚‹ใ ใ‘ใงๅฎŸ่กŒใงใใพใ™ใ€‚ใƒŠใƒ“ใ‚ฒใƒผใ‚ทใƒงใƒณใฏใƒ•ใ‚กใ‚คใƒซๆง‹้€ ใ‹ใ‚‰่‡ชๅ‹•็”Ÿๆˆใ•ใ‚Œใพใ™ใ€‚ๆœ€ๅˆใฎใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใ‚’ๆ›ธใ„ใฆ 1 ๅˆ†ไปฅๅ†…ใซๅ…ฌ้–‹ๅฏ่ƒฝ โ€” ใƒœใ‚คใƒฉใƒผใƒ—ใƒฌใƒผใƒˆใชใ—ใ€ใƒ“ใƒซใƒ‰ใƒ‘ใ‚คใƒ—ใƒฉใ‚คใƒณใฎ่จญๅฎšใชใ—ใ€ไบ‹ๅ‰ใฎๆ„ๆ€ๆฑบๅฎšใฏไธ่ฆใงใ™ใ€‚ + +### ๆจ™ๆบ–ใง่ปฝ้‡ใ€ใฉใ“ใงใ‚‚้ซ˜้€Ÿ +ใƒ‡ใƒ•ใ‚ฉใƒซใƒˆใฎ JavaScript ใƒšใ‚คใƒญใƒผใƒ‰ใฏ ~18 kbใ€‚ใƒšใƒผใ‚ธใฏๅณๆ™‚ SPA ใจใ—ใฆใƒŠใƒ“ใ‚ฒใƒผใƒˆใ—ใพใ™ใ€‚ๅ‡บๅŠ›ใฏ้™็š„ HTML โ€” SEO ๆœ€้ฉๅŒ–ๆธˆใฟใ€sitemapใ€ๆญฃ่ฆ URLใ€Open Graph ใƒกใ‚ฟใƒ‡ใƒผใ‚ฟใ‚’ๅซใ‚€ใ€‚ใ‚ชใƒ•ใƒฉใ‚คใƒณใฎๅ…จๆ–‡ๆคœ็ดขใ‚’ๅ†…่”ตใ€ใ‚ฏใƒฉใ‚ฆใƒ‰ใ‚ตใƒผใƒ“ใ‚นไธ่ฆใ€‚ + +### AI ใƒใ‚คใƒ†ใ‚ฃใƒ– +docmd ใฏไปŠใƒ‰ใ‚ญใฎใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใฎ่ชญใฟๆ–นใƒปไฝฟใ‚ใ‚Œๆ–นใซๅˆใ‚ใ›ใฆๆง‹็ฏ‰ใ•ใ‚Œใฆใ„ใพใ™๏ผš +- **MCP ใ‚ตใƒผใƒใƒผ** โ€” `docmd mcp` ใŒใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใ‚’ stdio ็ตŒ็”ฑใง AI Agent ใซๅ…ฌ้–‹ใ—ใ€ๆคœ็ดขใƒป่ชญใฟๅ–ใ‚Šใƒปๆคœ่จผใ‚’็›ดๆŽฅ่กŒใˆใพใ™ใ€‚ +- **ใ‚ณใƒณใƒ†ใ‚ญใ‚นใƒˆ (`llms.txt` / `llms-full.txt`)** โ€” ใƒ“ใƒซใƒ‰ๆ™‚ใซ็”Ÿๆˆใ•ใ‚Œใ‚‹ๅฎŒๅ…จใชใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใ‚ณใƒณใƒ†ใ‚ญใ‚นใƒˆใ€ใ‚ใ‚‰ใ‚†ใ‚‹ LLM ใงๅณๅˆฉ็”จๅฏ่ƒฝใ€‚ +- **Agent Skills** โ€” LLM ใจ IDE Agent ๅ‘ใ‘ใฎใƒขใ‚ธใƒฅใƒผใƒซๅผใ‚คใƒณใ‚นใƒˆใƒฉใ‚ฏใ‚ทใƒงใ‚ปใƒƒใƒˆ ([docmd-skills](https://github.com/docmd-io/docmd-skills))ใ€‚ +- **Markdown ใจใ—ใฆใ‚ณใƒ”ใƒผ / ใ‚ณใƒณใƒ†ใ‚ญใ‚นใƒˆใ‚’ใ‚ณใƒ”ใƒผ** โ€” ใƒ–ใƒฉใ‚ฆใ‚ถๅ†…ใฎใƒฏใƒณใ‚ฏใƒชใƒƒใ‚ฏใƒœใ‚ฟใƒณใ€‚AI ใƒใƒฃใƒƒใƒˆใธใฎ่ฒผใ‚Šไป˜ใ‘ใซๆœ€้ฉๅŒ–ใ€‚ + +### ใ‚นใ‚ฑใƒผใƒซใ‚’่ฆ‹ๆฎใˆใฆๆง‹็ฏ‰ +- ใƒžใƒซใƒใƒญใ‚ฑใƒผใƒซใƒ“ใƒซใƒ‰ใซใ‚ˆใ‚‹ๅ›ฝ้š›ๅŒ– +- ่ค‡ๆ•ฐใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใƒชใƒชใƒผใ‚นใซๅฏพๅฟœใ™ใ‚‹ใƒใƒผใ‚ธใƒงใƒณ็ฎก็† +- ใƒขใƒŽใƒฌใƒใƒปใƒžใƒซใƒใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆๆง‹ๆˆๅ‘ใ‘ Workspaces +- ใ‚ณใ‚ขๆฉŸ่ƒฝใ‚’ๆ‹กๅผตใ™ใ‚‹ใƒ—ใƒฉใ‚ฐใ‚คใƒณใ‚ทใ‚นใƒ†ใƒ  +- ๅฎŒๅ…จใชใƒ†ใƒผใƒžๅฏพๅฟœใ€ใƒ“ใƒซใƒˆใ‚คใƒณใƒ†ใƒณใƒ—ใƒฌใƒผใƒˆใ€ใ‚ซใ‚นใ‚ฟใƒ  CSS/JSใ€ใƒฉใ‚คใƒˆ/ใƒ€ใƒผใ‚ฏใƒขใƒผใƒ‰ + +## CLI + +```bash +docmd dev # ใƒญใƒผใ‚ซใƒซ dev ใ‚ตใƒผใƒใƒผ +docmd build # ใƒ‡ใƒ—ใƒญใ‚ค็”จใƒ“ใƒซใƒ‰ +docmd live # ใƒ–ใƒฉใ‚ฆใ‚ถใƒ™ใƒผใ‚นใฎใƒฉใ‚คใƒ–ใ‚จใƒ‡ใ‚ฃใ‚ฟ +docmd init # ็พๅœจใฎใƒ‡ใ‚ฃใƒฌใ‚ฏใƒˆใƒชใซๆ–ฐใ—ใ„ docmd.config.json ใ‚’ไฝœๆˆ +docmd stop # ๅฎŸ่กŒไธญใฎ `docmd dev` / `docmd live` ใ‚ตใƒผใƒใƒผใ‚’ๅœๆญข +docmd doctor # ไบ‹ๅ‰ใƒใ‚งใƒƒใ‚ฏ: ่จญๅฎš + ใƒ—ใƒฉใ‚ฐใ‚คใƒณใฎใ‚คใƒณใ‚นใƒˆใƒผใƒซ็Šถๆณ +docmd migrate # Docusaurus / VitePress / MkDocs / Starlight ใ‹ใ‚‰ๅ–ใ‚Š่พผใฟ +docmd deploy # Docker / NGINX / Caddy / Vercel / Netlify ็”จ่จญๅฎšใ‚’็”Ÿๆˆ +docmd validate # ๅ†…้ƒจใƒชใƒณใ‚ฏใ‚’ๅ…จใฆใƒใ‚งใƒƒใ‚ฏ +docmd mcp # stdio ไธŠใง MCP ใ‚ตใƒผใƒใƒผใจใ—ใฆๅ‹•ไฝœ +docmd add # ใƒ—ใƒฉใ‚ฐใ‚คใƒณใพใŸใฏใƒ†ใƒณใƒ—ใƒฌใƒผใƒˆใ‚’ใ‚คใƒณใ‚นใƒˆใƒผใƒซ +``` + +## ใƒ—ใƒฉใ‚ฐใ‚คใƒณ + +ใ‚ณใ‚ขๆฉŸ่ƒฝใฏๅ …็‰ขใชใƒ—ใƒฉใ‚ฐใ‚คใƒณใ‚ทใ‚นใƒ†ใƒ ใซใ‚ˆใฃใฆๆ”ฏใˆใ‚‰ใ‚Œใฆใ„ใพใ™ใ€‚ๅฟ…้ ˆๆฉŸ่ƒฝใฏๆจ™ๆบ–ใงๅซใพใ‚ŒใฆใŠใ‚Šใ€็‰นๅฎšใฎใƒ‹ใƒผใ‚บใซๅฟœใ˜ใฆใ‚ชใƒ—ใ‚ทใƒงใƒŠใƒซใƒ—ใƒฉใ‚ฐใ‚คใƒณใ‚’่ฟฝๅŠ ใงใใพใ™ใ€‚ + +| ใƒ—ใƒฉใ‚ฐใ‚คใƒณ | ใ‚นใƒ†ใƒผใ‚ฟใ‚น | ่ชฌๆ˜Ž | +| :--- | :---: | :--- | +| `search` | ใ‚ณใ‚ข | ใ‚ใ„ใพใ„ไธ€่‡ดๅฏพๅฟœใฎใ‚ชใƒ•ใƒฉใ‚คใƒณๅ…จๆ–‡ๆคœ็ดข | +| `seo` | ใ‚ณใ‚ข | SEO ใ‚ฟใ‚ฐใจ Open Graph ใƒกใ‚ฟใƒ‡ใƒผใ‚ฟ | +| `sitemap` | ใ‚ณใ‚ข | `sitemap.xml` ใ‚’็”Ÿๆˆ | +| `git` | ใ‚ณใ‚ข | Git ใฎใ‚ณใƒŸใƒƒใƒˆๅฑฅๆญดใจๆœ€็ต‚ๆ›ดๆ–ฐๆ—ฅ | +| `analytics` | ใ‚ณใ‚ข | ่ปฝ้‡ใชใ‚ขใƒŠใƒชใƒ†ใ‚ฃใ‚ฏใ‚น้€ฃๆบ | +| `llms` | ใ‚ณใ‚ข | AI ใ‚ณใƒณใƒ†ใ‚ญใ‚นใƒˆ็”Ÿๆˆ (`llms.txt` / `llms-full.txt`) | +| `mermaid` | ใ‚ณใ‚ข | Mermaid ๅ›ณๅฏพๅฟœ | +| `openapi` | ใ‚ณใ‚ข | ใƒ“ใƒซใƒ‰ๆ™‚ใฎ OpenAPI 3.x ใ‚นใƒšใƒƒใ‚ฏใƒฌใƒณใƒ€ใƒฉใƒผ | +| `okf` | Core | AI ใ‚จใƒผใ‚ธใ‚งใƒณใƒˆๅ‘ใ‘ Open Knowledge Format ใƒใƒณใƒ‰ใƒซ (ใƒญใ‚ฑใƒผใƒซๅˆฅ) | +| `pwa` | ใ‚ชใƒ—ใ‚ทใƒงใƒณ | Progressive Web App โ€” ใ‚ชใƒ•ใƒฉใ‚คใƒณใƒŠใƒ“ใ‚ฒใƒผใ‚ทใƒงใƒณ | +| `threads` | ใ‚ชใƒ—ใ‚ทใƒงใƒณ | ใ‚คใƒณใƒฉใ‚คใƒณใƒ‡ใ‚ฃใ‚นใ‚ซใƒƒใ‚ทใƒงใƒณใ‚นใƒฌใƒƒใƒ‰ *(by @svallory)* | +| `math` | ใ‚ชใƒ—ใ‚ทใƒงใƒณ | KaTeX / LaTeX ๆ•ฐๅผใƒฌใƒณใƒ€ใƒชใƒณใ‚ฐ | + +ใ‚ชใƒ—ใ‚ทใƒงใƒŠใƒซใƒ—ใƒฉใ‚ฐใ‚คใƒณใฎใ‚คใƒณใ‚นใƒˆใƒผใƒซ๏ผš + +```bash +docmd add +``` + +่‡ชไฝœ๏ผš[ใƒ—ใƒฉใ‚ฐใ‚คใƒณ้–‹็™บใ‚ฌใ‚คใƒ‰](https://docs.docmd.io/development/building-plugins/) + +## ่จญๅฎš + +ๅง‹ใ‚ใ‚‹ใฎใซ่จญๅฎšใฏไธ่ฆใงใ™ใ€‚ใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆใƒซใƒผใƒˆใซ `docmd.config.json`๏ผˆใพใŸใฏ `.ts` / `.js`๏ผ‰ใ‚’่ฟฝๅŠ ใ™ใ‚‹ใฎใฏใ€ใ‚ˆใ‚Š่ฉณ็ดฐใชๅˆถๅพกใŒๅฟ…่ฆใชๅ ดๅˆใฎใฟใงใ™๏ผš + +```json +{ + "title": "ใƒžใ‚คใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆ", + "url": "https://docs.myproject.com", + "src": "./docs", + "out": "./dist" +} +``` + +TypeScript / JavaScript ๅฝขๅผใฎ่จญๅฎšใƒ•ใ‚กใ‚คใƒซใฏๅ‹•็š„ใชๅ€คใฎๆŒ‡ๅฎšใซๅฏพๅฟœใ—ใฆใ„ใพใ™ใ€‚ + +ใƒชใƒ•ใ‚กใƒฌใƒณใ‚นๅ…จไฝ“๏ผš[่จญๅฎšๆฆ‚่ฆ](https://docs.docmd.io/configuration/overview) + +## ใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆๆง‹ๆˆ + +```text +my-docs/ +โ”œโ”€โ”€ docs/ โ† ใ‚ใชใŸใฎ Markdown ใƒ•ใ‚กใ‚คใƒซ +โ”œโ”€โ”€ assets/ โ† ็”ปๅƒใจ้™็š„ใƒ•ใ‚กใ‚คใƒซ +โ”œโ”€โ”€ docmd.config.json โ† ไปปๆ„ใฎ่จญๅฎš +โ””โ”€โ”€ package.json +``` + +## ใƒฉใ‚คใƒ–ใ‚จใƒ‡ใ‚ฃใ‚ฟ + +ใƒ–ใƒฉใ‚ฆใ‚ถใƒ™ใƒผใ‚นใฎใ‚จใƒ‡ใ‚ฃใ‚ฟใงใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใ‚’ๅŸท็ญ†ใƒปใƒ—ใƒฌใƒ“ใƒฅใƒผ โ€” ใƒญใƒผใ‚ซใƒซ็’ฐๅขƒๆง‹็ฏ‰ใฏไธ่ฆใ€‚ + +

+ docmd ใƒฉใ‚คใƒ–ใ‚จใƒ‡ใ‚ฃใ‚ฟใฎใƒ—ใƒฌใƒ“ใƒฅใƒผ +

+ +**[live.docmd.io](https://live.docmd.io) ใง่ฉฆใ™** + +## ใƒ—ใƒญใ‚ฐใƒฉใƒžใƒ†ใ‚ฃใƒƒใ‚ฏ API + +Node.js ใ‚นใ‚ฏใƒชใƒ—ใƒˆใ€CI ใƒ‘ใ‚คใƒ—ใƒฉใ‚คใƒณใ€ใ‚ซใ‚นใ‚ฟใƒ ใƒ“ใƒซใƒ‰ใ‚นใƒ†ใƒƒใƒ—ใง docmd ใ‚’ๅˆฉ็”จใงใใพใ™ใ€‚๏ผˆCommonJS / ESM ใฎไธกๅฏพๅฟœใ€‚๏ผ‰ + +```javascript +import { build } from '@docmd/core'; + +await build('./docmd.config.json', { isDev: false }); +``` + +ใƒชใƒ•ใ‚กใƒฌใƒณใ‚นๅ…จไฝ“๏ผš[Node API](https://docs.docmd.io/development/node-api-reference/) + +## ใ‚ณใƒŸใƒฅใƒ‹ใƒ†ใ‚ฃ + +- **ใƒใ‚ฐๅ ฑๅ‘Šใƒปๅ•้กŒ** โ†’ [GitHub Issues](https://github.com/docmd-io/docmd/issues) +- **่ณชๅ•ใƒปใ‚ขใ‚คใƒ‡ใ‚ข** โ†’ [Discussions](https://github.com/orgs/docmd-io/discussions) +- **ใ‚ณใƒณใƒˆใƒชใƒ“ใƒฅใƒผใ‚ทใƒงใƒณ** โ†’ [CONTRIBUTING.md](.github/CONTRIBUTING.md) +- **ใƒญใƒผใƒ‰ใƒžใƒƒใƒ—** โ†’ [GitHub Discussions](https://github.com/orgs/docmd-io/discussions/2) + +## ใ‚ตใƒใƒผใƒˆ + +- docmd ใฎ้–‹็™บใ‚’ๆœ€ใ‚‚็›ดๆŽฅ็š„ใซๆ”ฏๆดใ™ใ‚‹ๆ–นๆณ•ใฏใ€ๅ‘จใ‚Šใฎไบบใซ็Ÿฅใ‚‰ใ›ใ‚‹ใ“ใจใงใ™ใ€‚X ใง [ใ‚ทใ‚งใ‚ข](https://twitter.com/intent/tweet?url=https://github.com/docmd-io/docmd&text=docmd%20-%20Markdown%20ใ‹ใ‚‰%20ๆ•ฐ็ง’ใง%20ใƒ—ใƒญใƒ€ใ‚ฏใ‚ทใƒงใƒณๅ“่ณชใฎ%20ใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใ‚’ใ€‚) ใ—ใŸใ‚Šใ€ใ‚นใ‚ฟใƒผใ‚’ไป˜ใ‘ใ‚‹ใฎใ‚‚่‰ฏใ„ใงใ—ใ‚‡ใ†ใ€‚ +- docmd ใŒใ‚ใชใŸใฎๆ™‚้–“ใ‚’็ฏ€็ด„ใงใใฆใ„ใ‚‹ใชใ‚‰ใ€[GitHub Sponsorship](https://github.com/sponsors/mgks) ใฏๅคงใใชๅŠฑใฟใซใชใ‚Šใพใ™ใ€‚ +- ใ‚ขใ‚คใƒ‡ใ‚ขใ‚„ใƒใ‚ฐใŒใ‚ใ‚Œใฐ Issue ใ‚„ PR ใ‚’ใŠๆฐ—่ปฝใซใ€‚ใƒ—ใƒฉใ‚ฐใ‚คใƒณใฎใ‚ณใƒณใƒˆใƒชใƒ“ใƒฅใƒผใ‚ทใƒงใƒณใ‚‚ๆญ“่ฟŽใ—ใพใ™ใ€‚ + +## ใƒฉใ‚คใ‚ปใƒณใ‚น + +MIT โ€” ่ฉณ็ดฐใฏ [`LICENSE`](./LICENSE) ใ‚’ๅ‚็…งใ€‚ \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..3c1eb4a --- /dev/null +++ b/README.md @@ -0,0 +1,286 @@ +
+ + EN  |  ES  |  DE  |  ๆ—ฅๆœฌ่ชž  |  FR  |  ไธญๆ–‡ + +
+ +
+ + + + + + docmd + + + +
+ +

Production-ready documentation from Markdown, in seconds.
Zero config. AI-native. Built for developers.

+ +

+ npm version + monthly downloads + GitHub stars + license +

+ +

+ Website  ยท  + Documentation  ยท  + Live Editor  ยท  + Agent Skills  ยท  + Report a Bug +

+ +
+ + + docmd default theme โ€” light and dark mode preview + + +

+ +
+ +## Quick Start + +Run docmd in any folder with Markdown files โ€” no install needed: + +```bash +npx @docmd/core dev +``` + +
+ Opens at http://localhost:3000
+ +```bash + _ _ + _| |___ ___ _____ _| | + | . | . | _| | . | + |___|___|___|_|_|_|___| + + v1.x.x + +โ”Œโ”€ Build +โ”‚ Engine JS +โ”‚ Source docs/ +โ”‚ Output site/ +โ”‚ Versions 2 (06, 05) +โ”‚ Locales 7 (en, hi, zh, es, de, ja, fr) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Data Indexing +โ”‚ [ DONE ] Syncing git metadata +โ”‚ [ DONE ] Building semantic search index (multi-version) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Publishing +โ”‚ [ DONE ] Generated robots.txt +โ”‚ [ DONE ] Generated .nojekyll (disables Jekyll on GitHub Pages) +โ”‚ [ DONE ] Generated sitemap +โ”‚ [ DONE ] Generating LLMs context files +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +โฌข Initial build completed in 1.2s. + +โ”Œโ”€ Watching +โ”‚ Source ./docs +โ”‚ Config ./docmd.config.json +โ”‚ Assets ./assets +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Development Server Running +โ”‚ Local Access http://127.0.0.1:3000 +โ”‚ Network Access http://192.168.1.6:3000 +โ”‚ Serving from ./site +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +``` +
+ +

+ docmd dev server preview +

+ +Navigation is generated from your file structure. No config file, no frontmatter required, no framework to learn. + +**When you're ready to ship:** + +```bash +npx @docmd/core build +``` + +This outputs a highly optimized static site (SPA) ready for deployment to Vercel, Cloudflare Pages, Netlify, GitHub Pages, or any static host. + +**Requirements:** Node.js 18+ + +
+ Or install globally / via Docker
+ +```bash +# Install globally via npm +npm install -g @docmd/core + +# Or via pnpm +pnpm add -g @docmd/core + +# Run it +docmd dev # start dev server +docmd build # build for deployment +``` + +Or run via Docker: + +```bash +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.7 +``` + +> Pin a version for reproducible builds. + +
+ +## Why docmd? + +| Feature | docmd | Docusaurus | MkDocs | VitePress | Mintlify | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **Config required** | **None** | `docusaurus.config.js` | `mkdocs.yml` | `config.mts` | `docs.json` | +| **JS payload** | **~18 kb** | ~250 kb | ~40 kb | ~50 kb | ~120 kb | +| **Navigation** | **Instant SPA** | React SPA | Full reload | Vue SPA | Hosted SPA | +| **Versioning** | **Native** | Native (complex) | mike plugin | Manual | Native | +| **i18n** | **Native** | Native (complex) | Plugin-based | Native | Native | +| **Multi-project** | **Native** | Plugin | Plugin | - | - | +| **Search** | **Built-in** | Algolia (cloud) | Built-in | MiniSearch | Cloud | +| **AI context (`llms.txt`)** | **Built-in** | - | - | - | Built-in | +| **MCP server** | **Built-in** | - | - | - | Built-in | +| **Agent skills** | **Built-in** | - | - | - | - | +| **Docker image** | **Official** | - | Official | - | - | +| **Self-hosted** | **Yes** | Yes | Yes | Yes | - | +| **Cost** | **Free (OSS)** | Free (OSS) | Free (OSS) | Free (OSS) | Freemium | + +## Features + +### Zero config, instant start +Point docmd at any Markdown folder and it runs. Navigation is built automatically from your file structure. You can write your first doc and have it live in under a minute โ€” no boilerplate, no build pipeline to configure, no decisions to make upfront. + +### Tiny by default, fast everywhere +The default JavaScript payload is ~18 kb. Pages navigate as an instant SPA. The output is static HTML โ€” SEO-optimised, with sitemap, canonical URLs, and Open Graph metadata included. Offline full-text search is built in, no cloud service required. + +### AI-native +docmd is built for the way documentation is read and used today: +- **MCP Server** โ€” `docmd mcp` exposes your docs to AI agents over stdio, letting them search, read, and validate content directly. +- **Context (`llms.txt` / `llms-full.txt`)** โ€” complete documentation context generated at build time, ready for any LLM. +- **Agent Skills** โ€” modular instruction sets for LLMs and IDE agents ([docmd-skills](https://github.com/docmd-io/docmd-skills)). +- **Copy as Markdown / Copy Context** โ€” one-click buttons in the browser, optimised for pasting into AI chat. + +### Built to scale +- Internationalisation with multi-locale builds (per-locale search index, llms, okf, hreflang) +- Versioning for multiple doc releases (with auto-detection of the current version) +- Workspaces for monorepos and multi-project setups +- Plugin system for extending core behaviour (per-hook return-type validation, async-friendly) +- Full theming support, built-in templates, custom CSS/JS, light/dark mode + +## CLI + +```bash +docmd dev # local development server +docmd build # build for deployment +docmd live # browser-based Live Editor +docmd init # scaffold a new docmd.config.json in the current folder +docmd stop # stop any running `docmd dev` / `docmd live` servers +docmd doctor # pre-flight check: config + plugin install status +docmd migrate # migrate to docmd from Docusaurus, VitePress, MkDocs, or Starlight +docmd deploy # generate config for Docker, NGINX, Caddy, Vercel, Netlify +docmd validate # check all internal links +docmd mcp # run as an MCP server over stdio +docmd add # install a plugin or template +``` + +## Plugins + +Core functionality is powered by a robust plugin system. The essentials are included by default, while optional plugins can be added for specific needs. + +| Plugin | Status | Description | +| :--- | :---: | :--- | +| `search` | Core | Offline full-text search (keyword + optional semantic via `docmd-search`) | +| `seo` | Core | SEO tags and Open Graph metadata | +| `sitemap` | Core | Generates `sitemap.xml` | +| `git` | Core | Git commit history and last-updated dates | +| `analytics` | Core | Lightweight analytics integration | +| `llms` | Core | AI context generation (`llms.txt` / `llms-full.txt`) | +| `okf` | Core | Open Knowledge Format bundles for AI agents (per-locale) | +| `mermaid` | Core | Mermaid diagram support | +| `openapi` | Core | Build-time OpenAPI 3.x spec renderer | +| `pwa` | Optional | Progressive Web App โ€” offline navigation | +| `threads` | Optional | Inline discussion threads *(by @svallory)* | +| `math` | Optional | KaTeX / LaTeX math rendering | + +Install optional plugins: + +```bash +docmd add +``` + +Build your own: [Plugin Development Guide](https://docs.docmd.io/development/building-plugins/) + +## Configuration + +No configuration is required to get started. Add a `docmd.config.json` (or `.ts` / `.js`) in your project root only when you need more control: + +```json +{ + "title": "My Project", + "url": "https://docs.myproject.com", + "src": "./docs", + "out": "./dist" +} +``` + +TypeScript and JavaScript config files are supported for dynamic values. + +Full reference: [Configuration Overview](https://docs.docmd.io/configuration/overview) + +## Project Structure + +```text +my-docs/ +โ”œโ”€โ”€ docs/ โ† Your markdown files +โ”œโ”€โ”€ assets/ โ† Images and static files +โ”œโ”€โ”€ docmd.config.json โ† Optional configuration +โ””โ”€โ”€ package.json +``` + +## Live Editor + +A browser-based editor for writing and previewing docs โ€” no local setup required. + +

+ docmd live editor preview +

+ +**Try it at [live.docmd.io](https://live.docmd.io)** + +## Programmatic API + +Use docmd in Node.js scripts, CI pipelines, or custom build steps. (Supports both CommonJS and ESM). + +```javascript +import { build } from '@docmd/core'; + +await build('./docmd.config.json', { isDev: false }); +``` + +Full reference: [Node API](https://docs.docmd.io/development/node-api-reference/) + +## Community + +- **Bugs & issues** โ†’ [GitHub Issues](https://github.com/docmd-io/docmd/issues) +- **Questions & ideas** โ†’ [Discussions](https://github.com/orgs/docmd-io/discussions) +- **Contributing** โ†’ [CONTRIBUTING.md](.github/CONTRIBUTING.md) +- **Roadmap** โ†’ [GitHub Discussions](https://github.com/orgs/docmd-io/discussions/2) + +## Support + +- Getting the word out is the most direct way to support docmd's development. [Share it on X](https://twitter.com/intent/tweet?url=https://github.com/docmd-io/docmd&text=docmd%20-%20Production-ready%20docs%20from%20Markdown%20in%20seconds.) with friends or give it a star. +- If docmd saves you time, a [GitHub sponsorship](https://github.com/sponsors/mgks) goes a long way. +- Got ideas or bugs? Open an issue or PR, feel free to contribute your own plugins. + +## License + +MIT License. See `LICENSE` for details. \ No newline at end of file diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..e8284e1 --- /dev/null +++ b/README.wehub.md @@ -0,0 +1,7 @@ +# WeHub ๆฅๆบ่ฏดๆ˜Ž + +- ๅŽŸๅง‹้กน็›ฎ๏ผš`docmd-io/docmd` +- ๅŽŸๅง‹ไป“ๅบ“๏ผšhttps://github.com/docmd-io/docmd +- ๅฏผๅ…ฅๆ–นๅผ๏ผšไธŠๆธธ้ป˜่ฎคๅˆ†ๆ”ฏ็š„ๆœ€ๆ–ฐๅฟซ็…ง +- ๅŽŸไฝœ่€…ใ€็‰ˆๆƒๅ’Œ่ฎธๅฏ่ฏไฟกๆฏไปฅๅŽŸๅง‹ไป“ๅบ“ๅŠๆœฌไป“ๅบ“ LICENSE ไธบๅ‡† +- ๆœฌๆ–‡ไปถไป…็”จไบŽ่ฎฐๅฝ•ๆฅๆบ๏ผŒไธไปฃ่กจ WeHub ๆ˜ฏๅŽŸ้กน็›ฎไฝœ่€… diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 0000000..0397940 --- /dev/null +++ b/README.zh.md @@ -0,0 +1,286 @@ +
+ + EN  |  ES  |  DE  |  ๆ—ฅๆœฌ่ชž  |  FR  |  ไธญๆ–‡ + +
+ +
+ + + + + + docmd + + + +
+ +

ๅ‡ ็ง’ๅ†…ไปŽ Markdown ็”Ÿๆˆ็”Ÿไบงๅฏ็”จ็š„ๆ–‡ๆกฃ็ซ™็‚นใ€‚
้›ถ้…็ฝฎใ€‚AI ๅŽŸ็”Ÿใ€‚ไธบๅผ€ๅ‘่€…ๆ‰“้€ ใ€‚

+ +

+ npm version + ๆฏๆœˆไธ‹่ฝฝ + GitHub stars + license +

+ +

+ ๅฎ˜็ฝ‘  ยท  + ๆ–‡ๆกฃ  ยท  + ๅœจ็บฟ็ผ–่พ‘ๅ™จ  ยท  + Agent Skills  ยท  + ๅ้ฆˆ Bug +

+ +
+ + + docmd ้ป˜่ฎคไธป้ข˜ โ€” ๆต…่‰ฒไธŽๆทฑ่‰ฒๆจกๅผ้ข„่งˆ + + +

+ +
+ +## ๅฟซ้€Ÿๅผ€ๅง‹ + +ๅœจไปปไฝ•ๅŒ…ๅซ Markdown ๆ–‡ไปถ็š„็›ฎๅฝ•ไธ‹็›ดๆŽฅ่ฟ่กŒ docmd โ€”โ€” ๆ— ้œ€ๅฎ‰่ฃ…๏ผš + +```bash +npx @docmd/core dev +``` + +
+ ๅœจ http://localhost:3000 ๆ‰“ๅผ€
+ +```bash + _ _ + _| |___ ___ _____ _| | + | . | . | _| | . | + |___|___|___|_|_|_|___| + + v1.x.x + +โ”Œโ”€ Build +โ”‚ Engine JS +โ”‚ Source docs/ +โ”‚ Output site/ +โ”‚ Versions 2 (06, 05) +โ”‚ Locales 7 (en, hi, zh, es, de, ja, fr) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Data Indexing +โ”‚ [ DONE ] Syncing git metadata +โ”‚ [ DONE ] Building semantic search index (multi-version) +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Publishing +โ”‚ [ DONE ] Generated robots.txt +โ”‚ [ DONE ] Generated .nojekyll (disables Jekyll on GitHub Pages) +โ”‚ [ DONE ] Generated sitemap +โ”‚ [ DONE ] Generating LLMs context files +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +โฌข Initial build completed in 1.2s. + +โ”Œโ”€ Watching +โ”‚ Source ./docs +โ”‚ Config ./docmd.config.json +โ”‚ Assets ./assets +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +โ”Œโ”€ Development Server Running +โ”‚ Local Access http://127.0.0.1:3000 +โ”‚ Network Access http://192.168.1.6:3000 +โ”‚ Serving from ./site +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +``` +
+ +

+ docmd dev ๆœๅŠกๅ™จ้ข„่งˆ +

+ +ๅฏผ่ˆช็”ฑไฝ ็š„็›ฎๅฝ•็ป“ๆž„่‡ชๅŠจ็”Ÿๆˆใ€‚ๆ— ้œ€้…็ฝฎๆ–‡ไปถใ€ไธๅผบๅˆถ frontmatterใ€ไธๅฟ…ๅญฆไน ๆก†ๆžถใ€‚ + +**ๅฝ“ๅ‡†ๅค‡ๅ‘ๅธƒๆ—ถ๏ผš** + +```bash +npx @docmd/core build +``` + +่ฟ™ไผš่พ“ๅ‡บไธ€ไธช้ซ˜ๅบฆไผ˜ๅŒ–็š„้™ๆ€็ซ™็‚น๏ผˆSPA๏ผ‰๏ผŒๅฏ็›ดๆŽฅ้ƒจ็ฝฒๅˆฐ Vercelใ€Cloudflare Pagesใ€Netlifyใ€GitHub Pages ๆˆ–ไปปไฝ•้™ๆ€ไธปๆœบใ€‚ + +**็Žฏๅขƒ่ฆๆฑ‚๏ผš** Node.js 18+ + +
+ ๆˆ–ๅ…จๅฑ€ๅฎ‰่ฃ… / ้€š่ฟ‡ Docker
+ +```bash +# ้€š่ฟ‡ npm ๅ…จๅฑ€ๅฎ‰่ฃ… +npm install -g @docmd/core + +# ๆˆ–้€š่ฟ‡ pnpm +pnpm add -g @docmd/core + +# ่ฟ่กŒ +docmd dev # ๅฏๅŠจๅผ€ๅ‘ๆœๅŠกๅ™จ +docmd build # ๆž„ๅปบ็”จไบŽ้ƒจ็ฝฒ +``` + +ๆˆ–้€š่ฟ‡ Docker ่ฟ่กŒ๏ผš + +```bash +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.7 +``` + +> ๅ›บๅฎšไธ€ไธช็‰ˆๆœฌไปฅ่Žทๅพ—ๅฏๅค็Žฐ็š„ๆž„ๅปบใ€‚ + +
+ +## ไธบไป€ไนˆ้€‰ๆ‹ฉ docmd๏ผŸ + +| ็‰นๆ€ง | docmd | Docusaurus | MkDocs | VitePress | Mintlify | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **้œ€่ฆ้…็ฝฎ** | **ๆ— ้œ€** | `docusaurus.config.js` | `mkdocs.yml` | `config.mts` | `docs.json` | +| **JS ไฝ“็งฏ** | **~18 kb** | ~250 kb | ~40 kb | ~50 kb | ~120 kb | +| **ๅฏผ่ˆช** | **ๅณๆ—ถ SPA** | React SPA | ๅ…จ้‡้‡่ฝฝ | Vue SPA | ๆ‰˜็ฎก SPA | +| **็‰ˆๆœฌ็ฎก็†** | **ๅŽŸ็”Ÿ** | ๅŽŸ็”Ÿ๏ผˆๅคๆ‚๏ผ‰ | mike ๆ’ไปถ | ๆ‰‹ๅŠจ | ๅŽŸ็”Ÿ | +| **i18n** | **ๅŽŸ็”Ÿ** | ๅŽŸ็”Ÿ๏ผˆๅคๆ‚๏ผ‰ | ๆ’ไปถๆ–นๅผ | ๅŽŸ็”Ÿ | ๅŽŸ็”Ÿ | +| **ๅคš้กน็›ฎ** | **ๅŽŸ็”Ÿ** | ๆ’ไปถ | ๆ’ไปถ | - | - | +| **ๆœ็ดข** | **ๅ†…็ฝฎ** | Algolia๏ผˆไบ‘๏ผ‰ | ๅ†…็ฝฎ | MiniSearch | ไบ‘ | +| **AI ไธŠไธ‹ๆ–‡ (`llms.txt`)** | **ๅ†…็ฝฎ** | - | - | - | ๅ†…็ฝฎ | +| **MCP ๆœๅŠกๅ™จ** | **ๅ†…็ฝฎ** | - | - | - | ๅ†…็ฝฎ | +| **Agent Skills** | **ๅ†…็ฝฎ** | - | - | - | - | +| **Docker ้•œๅƒ** | **ๅฎ˜ๆ–น** | - | ๅฎ˜ๆ–น | - | - | +| **่‡ชๆ‰˜็ฎก** | **ๅฏ** | ๅฏ | ๅฏ | ๅฏ | - | +| **่ดน็”จ** | **ๅ…่ดน (OSS)** | ๅ…่ดน (OSS) | ๅ…่ดน (OSS) | ๅ…่ดน (OSS) | Freemium | + +## ๅŠŸ่ƒฝ็‰นๆ€ง + +### ้›ถ้…็ฝฎ๏ผŒๅณๆ—ถๅฏๅŠจ +ๆŠŠ docmd ๆŒ‡ๅ‘ไปปๆ„ Markdown ็›ฎๅฝ•๏ผŒๅฎƒๅฐฑไผš่ฟ่กŒใ€‚ๅฏผ่ˆชไผšๆ นๆฎไฝ ็š„็›ฎๅฝ•็ป“ๆž„่‡ชๅŠจ็”Ÿๆˆใ€‚ไฝ ๅฏไปฅๅœจไธๅˆฐไธ€ๅˆ†้’Ÿ็š„ๆ—ถ้—ดๅ†…ๅ†™ๅฅฝ็ฌฌไธ€็ฏ‡ๆ–‡ๆกฃๅนถไธŠ็บฟ โ€”โ€” ๆฒกๆœ‰ๆจกๆฟไปฃ็ ๏ผŒๆฒกๆœ‰้œ€่ฆ้…็ฝฎ็š„ๆž„ๅปบๆต็จ‹๏ผŒไนŸไธ้œ€่ฆๆๅ‰ๅšๆŠ€ๆœฏๅ†ณ็ญ–ใ€‚ + +### ้ป˜่ฎค่ฝป้‡๏ผŒๅค„ๅค„้ซ˜้€Ÿ +้ป˜่ฎค็š„ JavaScript ไฝ“็งฏ็บฆ 18 kb๏ผŒ้กต้ขไปฅๅณๆ—ถ SPA ็š„ๆ–นๅผๅˆ‡ๆขใ€‚่พ“ๅ‡บไธบ้™ๆ€ HTML โ€”โ€” ๅทฒๅšๅฅฝ SEO ไผ˜ๅŒ–๏ผŒๅŒ…ๅซ sitemapใ€canonical URL ไธŽ Open Graph ๅ…ƒๆ•ฐๆฎใ€‚ๅ†…็ฝฎ็ฆป็บฟๅ…จๆ–‡ๆœ็ดข๏ผŒๆ— ้œ€ไปปไฝ•ไบ‘ๆœๅŠกใ€‚ + +### AI ๅŽŸ็”Ÿ +docmd ็š„่ฎพ่ฎก่ดดๅˆๆ–‡ๆกฃๅœจๅฝ“ไปŠ่ขซ้˜…่ฏปไธŽไฝฟ็”จ็š„ๆ–นๅผ๏ผš +- **MCP ๆœๅŠกๅ™จ** โ€” `docmd mcp` ้€š่ฟ‡ stdio ๆŠŠไฝ ็š„ๆ–‡ๆกฃๆšด้œฒ็ป™ AI Agent๏ผŒ่ฎฉๅฎƒไปฌๅฏไปฅ็›ดๆŽฅๆœ็ดขใ€้˜…่ฏปๅนถๆ ก้ชŒๅ†…ๅฎนใ€‚ +- **ไธŠไธ‹ๆ–‡ (`llms.txt` / `llms-full.txt`)** โ€” ๅœจๆž„ๅปบๆ—ถ็”ŸๆˆๅฎŒๆ•ด็š„ๆ–‡ๆกฃไธŠไธ‹ๆ–‡๏ผŒๅฏ่ขซไปปไฝ• LLM ็ซ‹ๅณๆถˆ่ดนใ€‚ +- **Agent Skills** โ€” ้ขๅ‘ LLM ไธŽ IDE Agent ็š„ๆจกๅ—ๅŒ–ๆŒ‡ไปค้›†ๅˆ๏ผˆ[docmd-skills](https://github.com/docmd-io/docmd-skills)๏ผ‰ใ€‚ +- **ๅคๅˆถไธบ Markdown / ๅคๅˆถไธŠไธ‹ๆ–‡** โ€” ๆต่งˆๅ™จๅ†…ไธ€้”ฎๆŒ‰้’ฎ๏ผŒไธ“้—จไธบ็ฒ˜่ดดๅˆฐ AI ๅฏน่ฏไธญๅšไบ†ไผ˜ๅŒ–ใ€‚ + +### ไธบ่ง„ๆจกๅŒ–่€Œ็”Ÿ +- ้€š่ฟ‡ๅคš่ฏญ่จ€ๆž„ๅปบๅฎž็Žฐๅ›ฝ้™…ๅŒ– +- ๆ”ฏๆŒๅคšไธชๆ–‡ๆกฃ็‰ˆๆœฌ็š„็‰ˆๆœฌ็ฎก็† +- ้ขๅ‘ monorepo ไธŽๅคš้กน็›ฎๅœบๆ™ฏ็š„ Workspaces +- ็”จไบŽๆ‰ฉๅฑ•ๆ ธๅฟƒ่กŒไธบ็š„ๆ’ไปถไฝ“็ณป +- ๅฎŒๆ•ด็š„ Theming ๆ”ฏๆŒใ€ๅ†…็ฝฎๆจกๆฟใ€่‡ชๅฎšไน‰ CSS/JS๏ผŒไปฅๅŠๆต…่‰ฒ / ๆทฑ่‰ฒๆจกๅผ + +## CLI + +```bash +docmd dev # ๆœฌๅœฐๅผ€ๅ‘ๆœๅŠกๅ™จ +docmd build # ๆž„ๅปบ็”จไบŽ้ƒจ็ฝฒ +docmd live # ๆต่งˆๅ™จ็ซฏๅœจ็บฟ็ผ–่พ‘ๅ™จ +docmd init # ๅœจๅฝ“ๅ‰็›ฎๅฝ•็”Ÿๆˆๆ–ฐ็š„ docmd.config.json +docmd stop # ๅœๆญขๆญฃๅœจ่ฟ่กŒ็š„ `docmd dev` / `docmd live` ๆœๅŠกๅ™จ +docmd doctor # ้ข„ๆฃ€ๆŸฅ: ้…็ฝฎ + ๆ’ไปถๅฎ‰่ฃ…็Šถๆ€ +docmd migrate # ไปŽ Docusaurus / VitePress / MkDocs / Starlight ๅฏผๅ…ฅ +docmd deploy # ็”Ÿๆˆ Docker / NGINX / Caddy / Vercel / Netlify ้…็ฝฎ +docmd validate # ๆฃ€ๆŸฅๅ…จ้ƒจๅ†…้ƒจ้“พๆŽฅ +docmd mcp # ไปฅ MCP ๆœๅŠกๅ™จๆ–นๅผๅœจ stdio ไธŠ่ฟ่กŒ +docmd add # ๅฎ‰่ฃ…ๆ’ไปถๆˆ–ๆจกๆฟ +``` + +## ๆ’ไปถ + +ๆ ธๅฟƒๅŠŸ่ƒฝ็”ฑไธ€ๅฅ—็จณๅฅ็š„ๆ’ไปถ็ณป็ปŸ้ฉฑๅŠจใ€‚ๅŸบ็ก€่ƒฝๅŠ›้ป˜่ฎคๅทฒๅŒ…ๅซ๏ผŒ็‰นๅฎš้œ€ๆฑ‚ๅฏๅŠ ่ฃ…ๅฏ้€‰ๆ’ไปถใ€‚ + +| ๆ’ไปถ | ็Šถๆ€ | ๆ่ฟฐ | +| :--- | :---: | :--- | +| `search` | ๆ ธๅฟƒ | ๅธฆๆจก็ณŠๅŒน้…็š„็ฆป็บฟๅ…จๆ–‡ๆœ็ดข | +| `seo` | ๆ ธๅฟƒ | SEO ๆ ‡็ญพไธŽ Open Graph ๅ…ƒๆ•ฐๆฎ | +| `sitemap` | ๆ ธๅฟƒ | ็”Ÿๆˆ `sitemap.xml` | +| `git` | ๆ ธๅฟƒ | Git ๆไบคๅŽ†ๅฒไธŽๆœ€ๅŽๆ›ดๆ–ฐๆ—ถ้—ด | +| `analytics` | ๆ ธๅฟƒ | ่ฝป้‡็บงๅˆ†ๆž้›†ๆˆ | +| `llms` | ๆ ธๅฟƒ | AI ไธŠไธ‹ๆ–‡็”Ÿๆˆ๏ผˆ`llms.txt` / `llms-full.txt`๏ผ‰ | +| `mermaid` | ๆ ธๅฟƒ | Mermaid ๅ›พ่กจๆ”ฏๆŒ | +| `openapi` | ๆ ธๅฟƒ | ๆž„ๅปบๆœŸ OpenAPI 3.x ่ง„่ŒƒๆธฒๆŸ“ๅ™จ | +| `okf` | Core | ้ขๅ‘ AI ไปฃ็†็š„ Open Knowledge Format ๅŒ… (ๆŒ‰ locale) | +| `pwa` | ๅฏ้€‰ | Progressive Web App โ€”โ€” ็ฆป็บฟๅฏผ่ˆช | +| `threads` | ๅฏ้€‰ | ๅ†…่”่ฎจ่ฎบไธฒ *(by @svallory)* | +| `math` | ๅฏ้€‰ | KaTeX / LaTeX ๆ•ฐๅญฆๅ…ฌๅผๆธฒๆŸ“ | + +ๅฎ‰่ฃ…ๅฏ้€‰ๆ’ไปถ๏ผš + +```bash +docmd add +``` + +ๅผ€ๅ‘ไฝ ่‡ชๅทฑ็š„ๆ’ไปถ๏ผš[ๆ’ไปถๅผ€ๅ‘ๆŒ‡ๅ—](https://docs.docmd.io/development/building-plugins/) + +## ้…็ฝฎ + +ไธŠๆ‰‹ๆ— ้œ€ไปปไฝ•้…็ฝฎใ€‚ไป…ๅœจ้œ€่ฆๆ›ดๅคšๆŽงๅˆถๆ—ถ๏ผŒๅœจ้กน็›ฎๆ น็›ฎๅฝ•ๆทปๅŠ  `docmd.config.json`๏ผˆๆˆ– `.ts` / `.js`๏ผ‰๏ผš + +```json +{ + "title": "ๆˆ‘็š„้กน็›ฎ", + "url": "https://docs.myproject.com", + "src": "./docs", + "out": "./dist" +} +``` + +TypeScript ไธŽ JavaScript ๆ ผๅผ็š„้…็ฝฎๆ–‡ไปถๆ”ฏๆŒๅŠจๆ€ๅ€ผใ€‚ + +ๅฎŒๆ•ดๅ‚่€ƒ๏ผš[้…็ฝฎๆฆ‚่งˆ](https://docs.docmd.io/configuration/overview) + +## ้กน็›ฎ็ป“ๆž„ + +```text +my-docs/ +โ”œโ”€โ”€ docs/ โ† ไฝ ็š„ Markdown ๆ–‡ไปถ +โ”œโ”€โ”€ assets/ โ† ๅ›พ็‰‡ไธŽ้™ๆ€่ต„ๆบ +โ”œโ”€โ”€ docmd.config.json โ† ๅฏ้€‰้…็ฝฎ +โ””โ”€โ”€ package.json +``` + +## ๅœจ็บฟ็ผ–่พ‘ๅ™จ + +ๅŸบไบŽๆต่งˆๅ™จ็š„็ผ–่พ‘ๅ™จ๏ผŒๆ‰€่งๅณๆ‰€ๅพ—ๅœฐๆ’ฐๅ†™ๅนถ้ข„่งˆๆ–‡ๆกฃ โ€”โ€” ๆ— ้œ€ไปปไฝ•ๆœฌๅœฐ้…็ฝฎใ€‚ + +

+ docmd ๅœจ็บฟ็ผ–่พ‘ๅ™จ้ข„่งˆ +

+ +**ๅ‰ๅพ€ [live.docmd.io](https://live.docmd.io) ไฝ“้ชŒ** + +## ็ผ–็จ‹ๅผ API + +ๅœจ Node.js ่„šๆœฌใ€CI ๆตๆฐด็บฟๆˆ–่‡ชๅฎšไน‰ๆž„ๅปบๆญฅ้ชคไธญไฝฟ็”จ docmdใ€‚๏ผˆๅŒๆ—ถๆ”ฏๆŒ CommonJS ไธŽ ESMใ€‚๏ผ‰ + +```javascript +import { build } from '@docmd/core'; + +await build('./docmd.config.json', { isDev: false }); +``` + +ๅฎŒๆ•ดๅ‚่€ƒ๏ผš[Node API](https://docs.docmd.io/development/node-api-reference/) + +## ็คพๅŒบ + +- **Bug ไธŽ้—ฎ้ข˜** โ†’ [GitHub Issues](https://github.com/docmd-io/docmd/issues) +- **้—ฎ้ข˜ไธŽๆƒณๆณ•** โ†’ [Discussions](https://github.com/orgs/docmd-io/discussions) +- **ๅ‚ไธŽ่ดก็Œฎ** โ†’ [CONTRIBUTING.md](.github/CONTRIBUTING.md) +- **่ทฏ็บฟๅ›พ** โ†’ [GitHub Discussions](https://github.com/orgs/docmd-io/discussions/2) + +## ๆ”ฏๆŒๆˆ‘ไปฌ + +- ่ฎฉๆ›ดๅคšไบบ็Ÿฅ้“ docmd ๆ˜ฏๆ”ฏๆŒๅ…ถๅผ€ๅ‘ๆœ€็›ดๆŽฅ็š„ๆ–นๅผ โ€”โ€” ๅœจ X ไธŠ [ๅˆ†ไบซ็ป™ไฝ ็š„ๆœ‹ๅ‹](https://twitter.com/intent/tweet?url=https://github.com/docmd-io/docmd&text=docmd%20-%20ๅ‡ ็ง’ๅ†…ไปŽ%20Markdown%20็”Ÿๆˆ็”Ÿไบงๅฏ็”จ็š„ๆ–‡ๆกฃ็ซ™็‚นใ€‚)๏ผŒๆˆ–็‚นไธช Starใ€‚ +- ๅฆ‚ๆžœ docmd ่Š‚็œไบ†ไฝ ็š„ๆ—ถ้—ด๏ผŒ[GitHub Sponsorship](https://github.com/sponsors/mgks) ๆ˜ฏๅทจๅคง็š„้ผ“ๅŠฑใ€‚ +- ๆœ‰ๆƒณๆณ•ๆˆ–ๅ‘็Žฐ Bug๏ผŸๆฌข่ฟŽๆ Issue ๆˆ– PR๏ผŒๆฌข่ฟŽ่ดก็Œฎไฝ ่‡ชๅทฑ็š„ๆ’ไปถใ€‚ + +## ่ฎธๅฏ + +MIT โ€”โ€” ่ฏฆ่ง [`LICENSE`](./LICENSE)ใ€‚ \ No newline at end of file diff --git a/assets/docmd-cover.webp b/assets/docmd-cover.webp new file mode 100644 index 0000000000000000000000000000000000000000..47f01ab0cde56c89d288a9b8aff152323007d50a GIT binary patch literal 52906 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 The examples below use `:latest` so you can copy-paste and run them immediately. +> **For production, CI, and any reproducible build**, replace `:latest` with the specific version you want โ€” see [Available Tags](#available-tags). + +### Pull the Image + +```bash +# Pull from GitHub Container Registry (GHCR) +docker pull ghcr.io/docmd-io/docmd:latest +``` + +### Run Demo Site + +The image ships with a demo template in `/template`. When you run the container with no volume mount, the entrypoint copies `/template` into `/docs` on first start, so the demo site comes up immediately. + +```bash +# Start with built-in demo site โ€” works out of the box +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:latest + +# Visit http://localhost:3000 +``` + +### Initialize New Project + +```bash +# Create and initialize a new project +mkdir my-docs && cd my-docs +docker run -v $(pwd):/workspace ghcr.io/docmd-io/docmd:latest init + +# Start dev server +docker run -v $(pwd):/workspace -p 3000:3000 ghcr.io/docmd-io/docmd:latest dev +``` + +### Use Existing Docs + +Mounting your own docs into `/docs` always wins โ€” the entrypoint only seeds the demo template when `/docs` is completely empty, so your content is never overwritten. + +```bash +# Mount your docs and start dev server +docker run -v $(pwd)/docs:/docs -p 3000:3000 ghcr.io/docmd-io/docmd:latest + +# Build static site +docker run -v $(pwd)/docs:/docs -v $(pwd)/site:/site ghcr.io/docmd-io/docmd:latest build +``` + +## Available Tags + +The image is published with two tags per release: + +| Tag | Description | When to use | +|-----|-------------|-------------| +| `latest` | Floating alias for the most recent stable release | Quick start, local exploration, throwaway CI | +| `` | Pinned stable release (substitute the version you want) | Production, CI/CD, anything that must be reproducible | + +> **Pin a specific version in production.** The examples below use `:latest` so you can copy-paste and run them immediately. For any pipeline whose output must be reproducible (or whose contracts you don't want silently changing), replace `:latest` with the specific version you want (e.g. `0.8.7`). Check the [package versions page](https://github.com/orgs/docmd-io/packages/container/docmd/versions) for the full list. + +## Multi-Platform Support + +The image is built for multiple architectures: + +- `linux/amd64` - Standard x86_64 servers +- `linux/arm64` - ARM-based servers (AWS Graviton, Raspberry Pi, Apple Silicon) + +Docker automatically pulls the correct image for your platform. + +## Usage Examples + +### Docker Compose + +```yaml +# Replace `:latest` with a specific version (e.g. `0.8.7`) for reproducible +# production builds. See the GitHub releases page for available versions. +services: + docmd: + image: ghcr.io/docmd-io/docmd:latest + ports: + - "3000:3000" + volumes: + - ./docs:/docs + - ./site:/site + # The dev server defaults to 127.0.0.1 (loopback). For LAN access from + # other devices, set DOCMD_HOST=0.0.0.0 or pass --host 0.0.0.0 explicitly. + command: dev +``` + +### GitHub Actions CI/CD + +```yaml +name: Build Docs + +on: + push: + branches: [main] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Build documentation + # Pin to a specific version (replace `:latest`) for reproducible CI runs. + run: | + docker run --rm \ + -v ${{ github.workspace }}/docs:/docs \ + -v ${{ github.workspace }}/site:/site \ + ghcr.io/docmd-io/docmd:latest \ + build + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./site +``` + +### Kubernetes Deployment + +```yaml +# Replace `:latest` with a specific version (e.g. `0.8.7`) for reproducible +# production deploys. Update the tag when you upgrade. +apiVersion: apps/v1 +kind: Deployment +metadata: + name: docmd-server +spec: + replicas: 1 + selector: + matchLabels: + app: docmd + template: + metadata: + labels: + app: docmd + spec: + containers: + - name: docmd + image: ghcr.io/docmd-io/docmd:latest + ports: + - containerPort: 3000 + volumeMounts: + - name: docs + mountPath: /docs + # The dev server defaults to 127.0.0.1. For LAN access, set + # DOCMD_HOST=0.0.0.0 or pass --host 0.0.0.0 explicitly. + command: ["docmd", "dev"] + volumes: + - name: docs + configMap: + name: docs-content +``` + +## Environment Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `NODE_ENV` | Node environment | `production` | +| `DOCMD_CONTAINER` | Container mode flag | `true` | + +## Building Locally + +```bash +# Clone the repository +git clone https://github.com/docmd-io/docmd.git +cd docmd + +# Build the image +docker build -t docmd:local -f docker/Dockerfile . + +# Test the build +docker run --rm -v $(pwd)/docs:/docs docmd:local --version +``` + +## Security Features + +- Runs as non-root user (`docmd`) +- Minimal Alpine Linux base image +- Multi-stage build reduces attack surface +- SBOM (Software Bill of Materials) included +- OCI provenance attestation + +## Health Check + +The image includes a health check that verifies the dev server is running: + +```bash +# Check container health +docker inspect --format='{{.State.Health.Status}}' +``` + +## Troubleshooting + +### Permission Issues + +The entrypoint automatically remaps to the uid:gid of the mounted directory, so files are always owned by the correct host user. If you hit permission issues, verify the mounted path exists and is writable on the host. + +The dev server defaults to 127.0.0.1 (loopback only). To expose it to the LAN +from inside a container, pass the host flag explicitly: + +```bash +# Loopback only (default) โ€” access via http://localhost:3000 from the host +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:latest dev + +# LAN access โ€” the dev server binds to 0.0.0.0 inside the container, and +# the port mapping makes it reachable from other devices on the host's network. +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:latest dev --host 0.0.0.0 +``` + +> **Security**: when you bind to 0.0.0.0, every host that can reach the +> container's port can connect. Only do this on trusted networks. The dev +> server's WebSocket requires an Origin that matches the bind host +> (defence against CSWSH, CWE-1385), but loopback-only is the safer default.nsure you're binding to 0.0.0.0 +docker run -p 3000:3000 ghcr.io/docmd-io/docmd:latest dev --host 0.0.0.0 +``` + +### Memory Issues + +```bash +# For large documentation sites +docker run --memory=2g -v $(pwd)/docs:/docs ghcr.io/docmd-io/docmd:latest build +``` + +## License + +MIT License - see [LICENSE](../LICENSE) for details. + +## Support + +- **Issues**: [GitHub Issues](https://github.com/docmd-io/docmd/issues) +- **Documentation**: [docs.docmd.io](https://docs.docmd.io) +- **Website**: [docmd.io](https://docmd.io) \ No newline at end of file diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..b446e55 --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,185 @@ +# -------------------------------------------------------------------- +# docmd : the minimalist, zero-config documentation generator. +# +# @package @docmd/core (and ecosystem) +# @website https://docmd.io +# @repository https://github.com/docmd-io/docmd +# @license MIT +# @copyright Copyright (c) 2025-present docmd.io +# +# [docmd-source] - Please do not remove this header. +# -------------------------------------------------------------------- +# +# Multi-stage Dockerfile for docmd +# Creates a minimal production image with docmd CLI pre-installed +# +# Usage: +# Quick Start (with demo site): +# docker run -p 3000:3000 docmd:latest +# +# Initialize new project in current directory: +# docker run -v $(pwd):/workspace docmd:latest init +# +# Run dev server with your docs: +# docker run -v $(pwd)/my-docs:/docs -p 3000:3000 docmd:latest dev +# +# Build static site: +# docker run -v $(pwd)/docs:/docs -v $(pwd)/site:/site docmd:latest build +# +# -------------------------------------------------------------------- + +# ----------------------------------------------------------------------------- +# Stage 1: Build stage - compiles TypeScript and prepares the application +# ----------------------------------------------------------------------------- +FROM node:20-alpine AS builder + +# Install build dependencies for native modules +RUN apk add --no-cache \ + python3 \ + make \ + g++ \ + git \ + curl + +# Install pnpm directly โ€” avoids corepack version resolution issues in CI. +# Bump the pinned version here whenever the monorepo's packageManager field changes. +RUN npm install -g pnpm@10.33.2 + +WORKDIR /app + +# Copy everything (excluding files via .dockerignore) +COPY . . + +# Install dependencies +RUN pnpm install --frozen-lockfile + +# Stub out packages that can't build in Docker before running the full build: +# - engine-rust-binaries: requires cargo; pre-built .node files are in the repo +# - _playground: dev sandbox, not part of the production image +RUN sh tools/docker-prebuild.sh + +# Build all packages +RUN pnpm -r run build + +# Resolve workspace:* deps to real version numbers for standalone use +RUN node tools/resolve-ws-deps.js + +# Pack all packages into tarballs (mimics npm publish) +RUN pnpm -r pack --pack-destination /tarballs + +# Generate a package.json listing every external (non-@docmd) runtime dep of +# @docmd/core's transitive tree. The production stage installs from this file +# instead of a hand-rolled list in the Dockerfile, so adding a dep to any +# @docmd/* package automatically propagates to the Docker image. +RUN node tools/print-okf-runtime-deps.js --emit-pkg=/tarballs/runtime-deps.json + +# ----------------------------------------------------------------------------- +# Stage 2: Production stage - minimal image with only runtime dependencies +# ----------------------------------------------------------------------------- +FROM node:20-alpine AS production + +# Install runtime dependencies +RUN apk add --no-cache \ + git \ + curl \ + bash \ + su-exec + +# Create non-root user for security +RUN addgroup -g 1001 -S docmd && \ + adduser -S -D -H -u 1001 -h /app -s /bin/bash -G docmd -g docmd docmd + +WORKDIR /app + +# Copy packed tarballs from builder +COPY --from=builder /tarballs /tarballs + +# Install only @docmd/* packages (the transitive deps of @docmd/core). +# We extract each docmd-*.tgz tarball into /usr/local/lib/node_modules/@docmd/. +# This bypasses npm/pnpm registry lookups (packages aren't published yet at +# build time). Legacy wrappers (doc.md, @mgks/docmd) and the monorepo root +# tarball are excluded by only matching the docmd-* prefix. +RUN mkdir -p /usr/local/lib/node_modules && \ + for tarball in /tarballs/docmd-*.tgz; do \ + fname=$(basename "$tarball" .tgz) && \ + pkg="${fname%-*}" && \ + scoped="@docmd/${pkg#docmd-}" && \ + mkdir -p "/usr/local/lib/node_modules/$scoped" && \ + tar -xzf "$tarball" -C "/usr/local/lib/node_modules/$scoped" --strip-components=1; \ + done + +# Install external deps from the auto-generated runtime-deps.json produced by +# the builder stage. We extract the dep list with node and pass it straight to +# `npm install -g`, which puts packages into /usr/local/lib/node_modules โ€” +# exactly where Node's global resolution path looks. No hand-rolled list in the +# Dockerfile: adding a dep to any @docmd/* package propagates automatically on +# the next build because the builder stage regenerates runtime-deps.json fresh. +RUN node -e "\ + const p=JSON.parse(require('fs').readFileSync('/tarballs/runtime-deps.json','utf8')); \ + const args=Object.entries(p.dependencies).map(([k,v])=>k+'@'+v); \ + const {execFileSync}=require('child_process'); \ + execFileSync('npm',['install','-g','--omit=dev','--no-audit','--no-fund',...args],{stdio:'inherit'}); \ +" + +# Symlink the docmd CLI onto PATH (chmod +x on the script too โ€” some +# base images strip the executable bit during COPY). +RUN ln -sf /usr/local/lib/node_modules/@docmd/core/dist/bin/docmd.js /usr/local/bin/docmd \ + && chmod +x /usr/local/bin/docmd /usr/local/lib/node_modules/@docmd/core/dist/bin/docmd.js + +# Clean up tarballs to reduce image size +RUN rm -rf /tarballs + +# Create directories for user content +RUN mkdir -p /docs /site && chown -R docmd:docmd /docs /site + +# Seed the default template by running docmd init non-interactively. +# This ensures the image ships exactly what a real `docmd init` produces. +# +# Build does NOT fail on init failure: the image still publishes (so users +# who mount their own /docs are unaffected), but the demo experience is +# degraded and a clear warning is printed. Full stderr from `docmd init` +# is in the build log above this block for diagnosis. +RUN mkdir -p /template && \ + cd /template && \ + if docmd init --yes; then \ + if [ ! -f /template/docmd.config.json ]; then \ + printf '\n[docmd-docker] WARNING: docmd init exited 0 but /template/docmd.config.json is missing.\n' >&2; \ + printf '[docmd-docker] Demo seeding will not work. Mount your own /docs.\n' >&2; \ + fi; \ + else \ + printf '\n[docmd-docker] WARNING: docmd init failed during image build.\n' >&2; \ + printf '[docmd-docker] The `docker run` demo experience will not work. Mount your own /docs.\n' >&2; \ + printf '[docmd-docker] Full error from docmd init is in the build log above this block.\n' >&2; \ + fi + +# Install entrypoint + healthcheck scripts (see docker/docker-entrypoint.sh +# and docker/docker-healthcheck.sh). The entrypoint seeds /docs from +# /template when /docs is empty, so `docker run` with no volume mount +# still works out of the box. The healthcheck probes a port range because +# `docmd dev` may auto-increment past 3000 if the port is already taken. +COPY docker/docker-entrypoint.sh /usr/local/bin/docmd-entrypoint.sh +COPY docker/docker-healthcheck.sh /usr/local/bin/docmd-healthcheck.sh +RUN chmod +x /usr/local/bin/docmd-entrypoint.sh /usr/local/bin/docmd-healthcheck.sh + +# Set environment variables +ENV NODE_ENV=production +ENV DOCMD_CONTAINER=true + +# Run as root so the entrypoint can inspect /docs ownership and use +# su-exec to re-exec as the correct uid:gid. The entrypoint never stays +# as root โ€” it always drops to the detected uid before exec-ing docmd. +# This is the same pattern used by postgres, redis, and other official images. + +# Set working directory to docs (where user content will be mounted) +WORKDIR /docs + +# Expose default port (dev server may pick a higher one if 3000 is in use) +EXPOSE 3000 + +# Health check โ€” probes 3000-3005 to follow the dev server's actual port +HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 CMD ["/usr/local/bin/docmd-healthcheck.sh"] + +# Default command โ€” entrypoint detects /docs uid, drops privileges, then +# seeds /docs if empty and execs the supplied command. +ENTRYPOINT ["/usr/local/bin/docmd-entrypoint.sh"] +CMD ["dev", "--host", "0.0.0.0"] \ No newline at end of file diff --git a/docker/docker-entrypoint.sh b/docker/docker-entrypoint.sh new file mode 100644 index 0000000..8563c5d --- /dev/null +++ b/docker/docker-entrypoint.sh @@ -0,0 +1,67 @@ +#!/bin/sh +# docmd Docker entrypoint +# +# Handles two cases: +# +# 1. No volume / empty /docs โ†’ seeds the demo template so `docmd dev` +# works out of the box with no arguments. +# +# 2. Host-mounted volume โ†’ detects the uid:gid that owns /docs and +# re-execs as that identity (via su-exec), so file writes from any +# subcommand โ€” including `docmd init` โ€” land with the correct host +# ownership without needing `-u $(id -u):$(id -g)` from the caller. +# +# This mirrors the pattern used by official images (postgres, redis, etc.). +set -e + +FIRST_ARG="${1:-}" + +# โ”€โ”€ uid remapping โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +# If we are currently running as root (the entrypoint is exec'd as root so it +# can inspect /docs ownership), detect the uid:gid of /docs and re-exec as +# that user. This lets `docmd init` and `docmd dev` write to host-mounted +# volumes without permission errors regardless of the host user's uid. +if [ "$(id -u)" = "0" ] && [ -d /docs ]; then + DOCS_UID=$(stat -c '%u' /docs 2>/dev/null || echo "1001") + DOCS_GID=$(stat -c '%g' /docs 2>/dev/null || echo "1001") + + # If /docs is owned by root (uid 0) on the host, fall back to the docmd + # user โ€” writing as root inside the container is a security anti-pattern. + if [ "$DOCS_UID" = "0" ]; then + DOCS_UID="1001" + DOCS_GID="1001" + fi + + # โ”€โ”€ writability check (N-18) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + # Catch read-only volume mounts early with a clear message instead of + # letting docmd crash mid-build with a cryptic EROFS / EACCES error. + # Only applies to write commands โ€” `dev`, `build`, `init`. + # Read-only mounts are valid for `validate`, `mcp`, etc. + case "$FIRST_ARG" in + dev|build|init) + if ! touch /docs/.docmd_write_test 2>/dev/null; then + printf '\n[docmd] ERROR: /docs is read-only (or not writable by uid %s).\n' "$DOCS_UID" >&2 + printf '[docmd] Mount a writable directory:\n' >&2 + printf '[docmd] docker run -v $(pwd)/docs:/docs ghcr.io/docmd-io/docmd\n' >&2 + printf '[docmd] Or check directory permissions on the host.\n' >&2 + exit 1 + fi + rm -f /docs/.docmd_write_test + ;; + esac + + # Seed demo template before dropping privileges (root can always write). + if [ "$FIRST_ARG" != "init" ] && \ + [ -z "$(ls -A /docs 2>/dev/null)" ] && \ + [ -d /template ]; then + echo "[docmd] /docs is empty โ€” seeding demo template from /template" + cp -r /template/. /docs/ + chown -R "$DOCS_UID:$DOCS_GID" /docs 2>/dev/null || true + fi + + # Re-exec as the detected uid:gid so all subsequent writes are correctly owned. + exec su-exec "$DOCS_UID:$DOCS_GID" "$0" "$@" +fi + +# โ”€โ”€ already the right user (re-exec path lands here) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +exec docmd "$@" \ No newline at end of file diff --git a/docker/docker-healthcheck.sh b/docker/docker-healthcheck.sh new file mode 100644 index 0000000..d4cfa98 --- /dev/null +++ b/docker/docker-healthcheck.sh @@ -0,0 +1,12 @@ +#!/bin/sh +# docmd Docker healthcheck +# +# The dev server may auto-increment its port (3000, 3001, ...) if the +# default port is in use, so we probe a small range instead of hard- +# coding a single port. Returns 0 as soon as any port responds. +for port in 3000 3001 3002 3003 3004 3005; do + if curl -fs --connect-timeout 2 "http://127.0.0.1:${port}/" >/dev/null 2>&1; then + exit 0 + fi +done +exit 1 \ No newline at end of file diff --git a/eslint-rules/index.js b/eslint-rules/index.js new file mode 100644 index 0000000..7961a10 --- /dev/null +++ b/eslint-rules/index.js @@ -0,0 +1,16 @@ +// eslint-rules/index.js โ€” docmd internal ESLint rules. +// Registered in eslint.config.mjs as plugin "docmd". + +import noUnsafeFsRead from './no-unsafe-fs-read.js'; +import requireVerifyClient from './require-verify-client.js'; + +export default { + meta: { + name: 'docmd-internal-rules', + version: '0.0.1' + }, + rules: { + 'no-unsafe-fs-read': noUnsafeFsRead, + 'require-verify-client': requireVerifyClient + } +}; \ No newline at end of file diff --git a/eslint-rules/no-unsafe-fs-read.js b/eslint-rules/no-unsafe-fs-read.js new file mode 100644 index 0000000..5d19a2d --- /dev/null +++ b/eslint-rules/no-unsafe-fs-read.js @@ -0,0 +1,103 @@ +// eslint-rules/no-unsafe-fs-read.js +// Flags fs.* file calls whose path argument was not resolved through +// safePath(root, ...). See DEVELOPMENT-BENCHMARK.md S1 (CWE-22). + +const TARGET_METHODS = new Set([ + 'readFile', 'readFileSync', + 'writeFile', 'writeFileSync', + 'appendFile', 'appendFileSync', + 'unlink', 'unlinkSync', + 'stat', 'statSync', + 'lstat', 'lstatSync', + 'readdir', 'readdirSync', + 'mkdir', 'mkdirSync', + 'rmdir', 'rmdirSync', + 'access', 'accessSync' +]); + +const FS_ROOT_NAMES = new Set(['fs', 'fsPromises', 'nodeFs', 'nodefs', 'fsp']); + +function getFsMethod(node) { + if (node.type !== 'CallExpression') return null; + const callee = node.callee; + if (callee.type !== 'MemberExpression' || callee.computed) return null; + const prop = callee.property; + if (prop.type !== 'Identifier') return null; + if (!TARGET_METHODS.has(prop.name)) return null; + // Only flag when the root object of the call chain is a known fs import. + // Wrappers like ctx.readFile(...) and sourceTools.readFile(...) are NOT flagged + // because they typically perform their own safePath() validation internally. + let obj = callee.object; + while (obj && obj.type === 'MemberExpression' && !obj.computed) { + obj = obj.object; + } + if (!obj || obj.type !== 'Identifier') return null; + if (!FS_ROOT_NAMES.has(obj.name)) return null; + return prop.name; +} + +function isSafeExpr(node, safeNames) { + if (!node) return false; + if (node.type === 'CallExpression' && + node.callee.type === 'Identifier' && + node.callee.name === 'safePath') { + return true; + } + if (node.type === 'Identifier') { + return safeNames.has(node.name); + } + return false; +} + +export default { + meta: { + type: 'problem', + docs: { + description: 'Disallow fs.* file calls whose path argument was not resolved through safePath(root, ...).' + }, + schema: [], + messages: { + unsafe: 'fs.{{ method }}() path argument must be resolved via safePath(projectRoot, userPath). CWE-22 path traversal prevention โ€” see DEVELOPMENT-BENCHMARK.md S1.' + } + }, + + create(context) { + const safeNames = new Set(); + + function isSafePathCall(node) { + return node && + node.type === 'CallExpression' && + node.callee.type === 'Identifier' && + node.callee.name === 'safePath'; + } + + function trackSafePathReturn(node) { + if (!node.init) return; + if (node.id.type !== 'Identifier') return; + if (isSafePathCall(node.init)) { + safeNames.add(node.id.name); + } + } + + function trackAssignment(node) { + // Pattern: x = safePath(...) + if (node.left.type !== 'Identifier') return; + if (node.operator !== '=') return; + if (isSafePathCall(node.right)) { + safeNames.add(node.left.name); + } + } + + return { + VariableDeclarator: trackSafePathReturn, + AssignmentExpression: trackAssignment, + CallExpression(node) { + const method = getFsMethod(node); + if (!method) return; + const firstArg = node.arguments[0]; + if (isSafeExpr(firstArg, safeNames)) return; + context.report({ node, messageId: 'unsafe', data: { method } }); + } + }; + } +}; \ No newline at end of file diff --git a/eslint-rules/require-verify-client.js b/eslint-rules/require-verify-client.js new file mode 100644 index 0000000..eea8605 --- /dev/null +++ b/eslint-rules/require-verify-client.js @@ -0,0 +1,43 @@ +// eslint-rules/require-verify-client.js +// Requires every new WebSocketServer({...}) to include a verifyClient +// callback. See DEVELOPMENT-BENCHMARK.md S3 (CWE-1385). + +export default { + meta: { + type: 'problem', + docs: { + description: 'Require WebSocketServer({...}) to include a verifyClient callback that validates the Origin header.' + }, + schema: [], + messages: { + missing: 'new WebSocketServer({...}) must include a verifyClient callback that validates the Origin header. CWE-1385 (CSWSH) prevention โ€” see DEVELOPMENT-BENCHMARK.md S3.' + } + }, + + create(context) { + function hasVerifyClient(objExpr) { + return objExpr.properties.some((p) => ( + p.type === 'Property' && + !p.computed && + p.key.type === 'Identifier' && + p.key.name === 'verifyClient' + )); + } + + return { + NewExpression(node) { + if (node.callee.type !== 'Identifier') return; + if (node.callee.name !== 'WebSocketServer') return; + if (node.arguments.length === 0) { + context.report({ node, messageId: 'missing' }); + return; + } + const arg = node.arguments[0]; + if (arg.type !== 'ObjectExpression') return; + if (!hasVerifyClient(arg)) { + context.report({ node, messageId: 'missing' }); + } + } + }; + } +}; \ No newline at end of file diff --git a/eslint.config.mjs b/eslint.config.mjs new file mode 100644 index 0000000..cdcdd4e --- /dev/null +++ b/eslint.config.mjs @@ -0,0 +1,63 @@ +import eslint from '@eslint/js'; +import tseslint from 'typescript-eslint'; +import docmdRules from './eslint-rules/index.js'; + +export default [ + eslint.configs.recommended, + ...tseslint.configs.recommended, + { + languageOptions: { + globals: { + process: 'readonly', + console: 'readonly', + require: 'readonly', + module: 'readonly', + __dirname: 'readonly', + __filename: 'readonly', + setTimeout: 'readonly', + clearTimeout: 'readonly', + requestAnimationFrame: 'readonly', + cancelAnimationFrame: 'readonly', + Buffer: 'readonly', + exports: 'writable', + document: 'readonly', + window: 'readonly', + localStorage: 'readonly', + IntersectionObserver: 'readonly', + fetch: 'readonly', + DOMParser: 'readonly', + history: 'readonly', + CustomEvent: 'readonly', + Event: 'readonly', + MouseEvent: 'readonly', + KeyboardEvent: 'readonly', + getComputedStyle: 'readonly', + navigator: 'readonly', + location: 'readonly', + URL: 'readonly' + } + }, + rules: { + '@typescript-eslint/no-require-imports': 'off', + '@typescript-eslint/no-unused-vars': 'warn', + '@typescript-eslint/no-explicit-any': 'warn', + 'preserve-caught-error': 'off', + '@typescript-eslint/ban-ts-comment': 'warn', + 'no-useless-escape': 'off', + 'no-useless-assignment': 'off', + '@typescript-eslint/no-unused-expressions': 'off' + } + }, + { + ignores: ['**/dist/**', '**/node_modules/**', '**/site/**', 'temp-*/**', '**/public/**'] + }, + { + // docmd internal security rules โ€” Phase 0 failsafe for DEVELOPMENT-BENCHMARK.md S1 and S3. + // Promoted to 'error' after Phase 1 cleans up the surface area. + plugins: { docmd: docmdRules }, + rules: { + 'docmd/no-unsafe-fs-read': 'warn', + 'docmd/require-verify-client': 'error' + } + } +]; \ No newline at end of file diff --git a/package.json b/package.json new file mode 100644 index 0000000..f5ece4b --- /dev/null +++ b/package.json @@ -0,0 +1,93 @@ +{ + "name": "@docmd/monorepo", + "version": "0.8.12", + "private": true, + "description": "The minimalist, zero-config documentation generator monorepo.", + "scripts": { + "dev": "pnpm docmd dev", + "live": "pnpm docmd-live", + "build": "pnpm -r run build", + "doctor": "pnpm docmd doctor", + "validate": "pnpm docmd validate", + "migrate": "pnpm docmd migrate", + "gen:deploy": "pnpm docmd deploy", + "mcp": "pnpm docmd mcp", + "plugin:add": "pnpm docmd add", + "plugin:remove": "pnpm docmd remove", + "docmd": "node packages/core/dist/bin/docmd.js --cwd packages/_playground", + "docmd-live": "node packages/live/bin/docmd-live.js --cwd packages/_playground", + "prep": "node tools/prep.js", + "verify": "node tools/verify.js", + "lint": "eslint .", + "bump": "node tools/bump.js", + "docker:build": "docker build -t docmd:latest -f docker/Dockerfile .", + "docker:build:version": "node -e \"const v=require('./package.json').version; require('child_process').execSync('docker build -t docmd:' + v + ' -t docmd:latest -f docker/Dockerfile .', {stdio:'inherit'})\"", + "docker:test": "docker run --rm -v $(pwd)/docs:/docs docmd:latest --version", + "docker:run": "docker run -p 3000:3000 docmd:latest", + "stop": "node packages/core/dist/bin/docmd.js stop >/dev/null 2>&1 || true", + "clean": "rm -rf node_modules packages/*/node_modules packages/plugins/*/node_modules packages/engines/*/node_modules packages/*/dist packages/plugins/*/dist packages/engines/*/dist packages/engines/rust/native/bin/*.node packages/*/public packages/plugins/*/public packages/*/site packages/plugins/*/site *.tsbuildinfo temp-* >/dev/null 2>&1;", + "unlink": "npm uninstall -g @docmd/core @docmd/monorepo docmd docmd-live -s >/dev/null 2>&1 || true; pnpm uninstall -g @docmd/core @docmd/monorepo docmd docmd-live -s >/dev/null 2>&1 || true; rm -f $(which -a docmd 2>/dev/null) $(which -a docmd-live 2>/dev/null) >/dev/null 2>&1 || true;", + "reset": "node tools/status.js start:reset && pnpm -s stop && pnpm -s unlink && pnpm -s clean && node tools/status.js reset" + }, + "devDependencies": { + "@eslint/js": "^10.0.1", + "@types/node": "^24.13.3", + "chalk": "^4.1.2", + "docmd-search": "^0.1.0", + "esbuild": "^0.28.1", + "eslint": "^10.6.0", + "globals": "^17.7.0", + "typescript": "^5.9.3", + "typescript-eslint": "^8.63.0" + }, + "engines": { + "node": ">=18" + }, + "packageManager": "pnpm@10.33.2", + "pnpm": { + "onlyBuiltDependencies": [ + "esbuild" + ], + "overrides": {}, + "peerDependencyRules": { + "ignoreMissing": [ + "docmd-search" + ] + } + }, + "keywords": [ + "docmd", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "documentation", + "typescript", + "javascript", + "nodejs", + "html", + "browser", + "website", + "generator", + "parser", + "hosted", + "cli", + "ssg", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/_playground/.threads/authors.json b/packages/_playground/.threads/authors.json new file mode 100644 index 0000000..a34a129 --- /dev/null +++ b/packages/_playground/.threads/authors.json @@ -0,0 +1,10 @@ +{ + "testuser": { + "name": "TestUser", + "avatarUrl": "https://gravatar.com/avatar/3d5ff960d1bb8dd8c99ef041d5ed5f21?s=80&d=mp" + }, + "ghazi": { + "name": "Ghazi", + "avatarUrl": "https://gravatar.com/avatar/3d5ff960d1bb8dd8c99ef041d5ed5f21?s=80&d=mp" + } +} diff --git a/packages/_playground/docmd.config.json b/packages/_playground/docmd.config.json new file mode 100644 index 0000000..359bc04 --- /dev/null +++ b/packages/_playground/docmd.config.json @@ -0,0 +1,90 @@ +{ + "engine": "rust", + "title": "_playground", + "favicon": "assets/favicon.ico", + "theme": { + "name": "summer", + "customCss": [] + }, + "layout": { + "menubar": { + "enabled": true, + "position": "header", + "left": [ { "text": "Menu 1", "url": "/" }, { "text": "Menu 2", "url": "/nostyle" } ] + }, + "optionsMenu": { + "position": "menubar", + "components": { + "search": true, + "themeSwitch": true, + "sponsor": "https://github.com/sponsors/mgks" + } + }, + "footer": { + "style": "minimal" + } + }, + "plugins": { + "search": { + "semantic": true, + "showConfidence": true + }, + "seo": {}, + "sitemap": {}, + "analytics": { + "googleV4": { "measurementId": "G-X9WTDL262N" } + }, + "llms": {}, + "mermaid": {}, + "git": { + "repo": "https://github.com/docmd-io/docmd" + }, + "openapi": {}, + "math": {}, + "okf": { + "graph": true + } + }, + + "versions": { + "current": "06", + "position": "sidebar-top", + "all": [ + { "id": "06", "dir": "docs", "label": "v0.6.0" }, + { "id": "05", "dir": "docs-05", "label": "v0.5.0", + "navigation": [ + { "title": "V0.5 Home", "path": "/", "icon": "home" }, + { "title": "V0.5 Install", "path": "/getting-started/installation", "icon": "download" } + ] + } + ] + }, + + "i18n": { + "default": "en", + "locales": [ + { "id": "en", "label": "English", "dir": "ltr" }, + { "id": "hi", "label": "เคนเคฟเคจเฅเคฆเฅ€", "dir": "ltr" }, + { "id": "zh", "label": "ไธญๆ–‡", "dir": "ltr" }, + { "id": "es", "label": "Espaรฑol", "dir": "ltr" } + ] + }, + + "navigation": [ + { + "title": "Getting Started", + "children": [ + { "title": "Latest Home", "path": "/", "icon": "home" }, + { + "title": "Mermaid icon test", + "path": "/mermaid-icon-test", + "icon": "mermaid", + "children": [ + { "title": "Nested Page 1", "path": "/nested-page-1" }, + { "title": "Nested Page 2", "path": "/nested-page-2" } + ] + } + ] + } + ] +} \ No newline at end of file diff --git a/packages/_playground/docs-05/getting-started/installation.md b/packages/_playground/docs-05/getting-started/installation.md new file mode 100644 index 0000000..32142ed --- /dev/null +++ b/packages/_playground/docs-05/getting-started/installation.md @@ -0,0 +1 @@ +# V0.5.1 Installation diff --git a/packages/_playground/docs-05/index.md b/packages/_playground/docs-05/index.md new file mode 100644 index 0000000..08d83fa --- /dev/null +++ b/packages/_playground/docs-05/index.md @@ -0,0 +1,34 @@ +# V0.5.0 Overview + +This is the documentation for version 0.5.0 of docmd. This version introduces several new features for developers. + +## Features + +- **Developer Tools**: Enhanced debugging capabilities +- **Performance**: Faster build times for large documentation sites +- **Search**: Improved keyword search with better relevance scoring +- **Plugins**: New plugin API for extending functionality + +## Getting Started + +To get started with version 0.5.0, install the package: + +```bash +npm install @docmd/core@0.5.0 +``` + +## Developer Guide + +This version is designed with developers in mind. The new developer tools make it easier to debug and customize your documentation site. + +### Configuration + +Configure your site by creating a `docmd.config.js` file in your project root. + +### Building + +Run the build command to generate your documentation: + +```bash +npx docmd build +``` \ No newline at end of file diff --git a/packages/_playground/docs/.threads/authors.json b/packages/_playground/docs/.threads/authors.json new file mode 100644 index 0000000..6ee4509 --- /dev/null +++ b/packages/_playground/docs/.threads/authors.json @@ -0,0 +1,6 @@ +{ + "ghazi": { + "name": "Ghazi", + "avatarUrl": "https://gravatar.com/avatar/3d5ff960d1bb8dd8c99ef041d5ed5f21?s=80&d=mp" + } +} diff --git a/packages/_playground/docs/en/index.md b/packages/_playground/docs/en/index.md new file mode 100644 index 0000000..9b9418c --- /dev/null +++ b/packages/_playground/docs/en/index.md @@ -0,0 +1,111 @@ +--- +title: "docmd _playground" +description: "A testing ground for docmd core engine features." +--- + +This playground is used to verify core engine changes in real-time. Use this to ensure your modifications to the Markdown parser or UI components behave as expected. + +::: callout tip "How to work here" +To test your changes, keep the dev server running (`pnpm run dev`). Any change you make to `packages/core` or `packages/parser` will trigger a hot-reload here instantly. +::: + +# H1 Test Heading + +This is a test H1 heading to verify it appears in the TOC and has proper anchor links. + +### Component Verification + +Test your UI components and parser rules here to ensure consistency: + +::: card "Container Test" + Test nested callouts and containers. + + ::: callout warning "Warning" + Ensure nested items render correctly. + ::: +::: + +::: tabs +== tab "Feature A" +#### Feature A +Verification content. +== tab "Feature B" +#### Feature B +Verification content. +::: + +### ๐Ÿ”— Useful Links + +- [Official Documentation](https://docs.docmd.io) +- [GitHub Repository](https://github.com/docmd-io/docmd) +- [Report an Issue](https://github.com/docmd-io/docmd/issues) + +### ๐Ÿงช Developer Checklist +- [ ] **Parser:** Does the Markdown output match the HTML in `packages/parser/src/html-renderer.js`? +- [ ] **UI:** Does the theme CSS apply to this page correctly? +- [ ] **SPA:** Does navigation between pages work without a hard refresh? + +### ๐Ÿงœโ€โ™€๏ธ Mermaid Interactive Test + +Test the new interactive controls (Pan, Zoom, Fullscreen) and Lucide icon support here: + +#### Complex Flowchart +```mermaid +graph TD + Start((Start)) --> Process1[Process One] + Process1 --> Decision{Is it valid?} + Decision -- Yes --> Process2[Process Two] + Decision -- No --> Error[Error Handling] + Process2 --> Subgraph1 + subgraph Subgraph1 [Critical Path] + Step1[Step 1] --> Step2[Step 2] + end + Step2 --> End((End)) + Error --> End +``` + +#### Architecture Diagram (Lucide Icons) +```mermaid +flowchart TD + A[Trigger: aaaa] --> B[take an action] + B --> C[x] + C --> D{yyy?} + D -->|No| E[Return] + D -->|Yes| F{zzz?} +``` + +#### Code Block with Title +```typescript "main.ts" +function hello() { + console.log("Hello from docmd!"); +} +``` + +#### Math Plugin Test + +$$ +\sum_{i=1}^n i^2 = \frac{n(n+1)(2n+1)}{6} +$$ + +### ๐Ÿชœ Steps Container Test + +::: steps +1. #### Step One: Initialization + Install dependencies and configure your environment. +2. #### Step Two: Configuration + Modify `docmd.config.json` to suit your project needs. +3. #### Step Three: Build + Run `pnpm build` to compile the templates and documents. +::: + +### ๐Ÿ“… Changelog Container Test + +::: changelog +== v0.8.7 - "Refining Summer Theme" +Refined the Summer theme Table of Contents thread, active ancestor branch indicators, and spacing of components. +* Fixed search modal styling. +* Added custom styling for steps, tabs, cards, and details containers. + +== v0.8.0 - "Release of docmd 0.8" +Initial preview of the zero-config documentation engine with monorepo workspace support. +::: \ No newline at end of file diff --git a/packages/_playground/docs/en/mermaid-icon-test.md b/packages/_playground/docs/en/mermaid-icon-test.md new file mode 100644 index 0000000..ae919bd --- /dev/null +++ b/packages/_playground/docs/en/mermaid-icon-test.md @@ -0,0 +1,22 @@ +--- +title: "Mermaid Icon Test" +--- + +# Mermaid Icon Test + +This diagram tests the generic `icon:` prefix (which maps to the Lucide icon pack): + +```mermaid +architecture-beta + group api(icon:cloud)[API] + service db(icon:database)[Database] in api + service disk(icon:hard-drive)[Storage] in api + db:L -- R:disk +``` + +Check if icons appear correctly. + + +# Tag Test +This is a ::: tag "v0.7.4" color:#f0f inline tag. +And this is a ::: tag "With Icon" icon:star color:blue link:https://google.com inline tag. diff --git a/packages/_playground/docs/en/nested-page-1.md b/packages/_playground/docs/en/nested-page-1.md new file mode 100644 index 0000000..2d127af --- /dev/null +++ b/packages/_playground/docs/en/nested-page-1.md @@ -0,0 +1,14 @@ +--- +title: Nested Page 1 +--- + +# Nested Page 1 + +This is the first nested page for verifying sidebar multi-level navigation. + +::: steps + +1. First step of verification. + +2. Second step of verification. +::: \ No newline at end of file diff --git a/packages/_playground/docs/en/nested-page-2.md b/packages/_playground/docs/en/nested-page-2.md new file mode 100644 index 0000000..b6a5810 --- /dev/null +++ b/packages/_playground/docs/en/nested-page-2.md @@ -0,0 +1,11 @@ +--- +title: Nested Page 2 +--- + +# Nested Page 2 + +This is the second nested page for verifying sidebar multi-level navigation. + +::: callout info +This callout tests the styling consistency within nested pages. +::: \ No newline at end of file diff --git a/packages/_playground/docs/en/practical-tests/README.md b/packages/_playground/docs/en/practical-tests/README.md new file mode 100644 index 0000000..c34d40b --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/README.md @@ -0,0 +1,51 @@ +--- +title: "Practical test index" +description: "Test pages that exercise every Phase 1โ€“3 fix and the OKF plugin in the actual _playground build." +noindex: false +--- + +# Practical test index + +These pages are **deliberately constructed test fixtures** that +exercise every fix shipped in 0.8.8. They live inside the +`_playground` site (alongside the real docs) and are included in +every build. Each page is annotated with a header block that +names the test and the report section it covers. + +The intent is that running `pnpm docmd build` from +`packages/_playground/` produces an output where every Phase +1โ€“3 + OKF fix is observable in a real build, not just in unit +tests. + +## What each page tests + +| Page | Phase | Fix | +|---|---|---| +| [`phase-2/f1-nested-grids`](./phase-2/f1-nested-grids) | 2 | F1 โ€” `::: grids` + Nร— `::: grid` + 1 close per card | +| [`phase-2/f2-self-closing-button`](./phase-2/f2-self-closing-button) | 2 | F2 โ€” self-closing `::: button` + orphan `:::` | +| [`phase-2/f3-mismatched-close`](./phase-2/f3-mismatched-close) | 2 | F3 โ€” `::: callout` closed by `::: card` | +| [`phase-2/f4-triple-close`](./phase-2/f4-triple-close) | 2 | F4 โ€” triple `:::` after balanced callout | +| [`phase-2/f5-five-level-nesting`](./phase-2/f5-five-level-nesting) | 2 | F5 โ€” 5-level nested callouts render all 5 levels | +| [`phase-3/okf-bundle-default`](./phase-3/okf-bundle-default) | 3 + OKF | OKF default-enabled, type inference, noindex opt-out | +| [`phase-3/internal-link-with-trailing-slash`](./phase-3/internal-link-with-trailing-slash) | 3 | M-1 โ€” `validate` accepts trailing-slash links | +| [`phase-3/xss-in-frontmatter`](./phase-3/xss-in-frontmatter) | 1 | T-S3 / S-4 / S-5 โ€” frontmatter XSS payloads escaped | + +> Each page documents, in its own body, what it would render as +> *before* the fix and what it renders as *after* the fix. + +## How to verify + +```bash +cd packages/_playground +node ../../packages/core/dist/bin/docmd.js build +# OKF bundle at site/okf/ (default-enabled โ€” no config needed) +# Generated output in site/ +node ../../packages/core/dist/bin/docmd.js validate +# exit 0 โ€” internal-link-with-trailing-slash.md links to a real page +node ../../packages/core/dist/bin/docmd.js validate --json +# exit 0 (no errors) โ€” JSON output unchanged +``` + +After the build, the OKF bundle at `site/okf/` includes a +`concepts/` directory containing one entry per page. Inspect +`site/okf/okf.yaml` to see the typed manifest. \ No newline at end of file diff --git a/packages/_playground/docs/en/practical-tests/phase-2/container-parser-determinism.md b/packages/_playground/docs/en/practical-tests/phase-2/container-parser-determinism.md new file mode 100644 index 0000000..4c2049b --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-2/container-parser-determinism.md @@ -0,0 +1,80 @@ +--- +title: "Phase 2 โ€” Container parser determinism across worker threads" +description: "Demonstrates that the container normaliser is a pure function of its input. Two workers, 100 concurrent parses, all produce byte-identical HTML." +okf: + type: reference +--- + +# Container parser determinism + +This page documents the **determinism contract** that backs the +Phase 2 parser. The container normaliser is a pure function of +its input โ€” no `Date.now()`, no `Math.random()`, no module-level +mutable state. Two worker threads given the same source produce +byte-identical HTML. + +## How the determinism is enforced + +Three layers, each guarding the next: + +1. **Declarative** โ€” `packages/parser/src/utils/container-normaliser.ts` + has a `DETERMINISM AUDIT` block in the file header that + documents the four non-deterministic primitives the module + deliberately does NOT use (`Date.now()`, `Math.random()`, + module-level `let`/`var`, `process.env` reads). + +2. **Empirical** โ€” `packages/parser/test/container-normaliser.test.js` + has 60 assertions including a 100-way concurrent parse test + AND a real `node:worker_threads` cross-worker parse. Both + assert byte-identical output. + +3. **Regression-proof** โ€” `packages/core/src/engine/worker-parser.ts` + has a `verifyDeterminismAtBoot()` function that runs at the + end of `init()`. It parses a known input through the + freshly-built processor and asserts the output equals a + frozen snapshot. If a future code change introduces + non-determinism, the worker throws at boot and the build + fails immediately. + +## The 100-way test + +The test fixture in `container-normaliser.test.js`: + +```js +test('determinism: 100 concurrent parses of the same source produce identical HTML', async () => { + const md = freshProcessor(); + const src = ''; + const N = 100; + const results = await Promise.all( + Array.from({ length: N }, () => processContentAsync(src, md, {}, { filePath: 'det.md' })) + ); + const first = results[0].htmlContent; + for (let i = 1; i < N; i++) { + assert.equal(results[i].htmlContent, first, `divergence at index ${i}`); + } +}); +``` + +100 parallel parses, byte-identical output. This is the +strongest empirical guarantee we have that parallel workers +won't produce inconsistent output. + +## Why determinism matters + +docmd is built around a **worker pool** โ€” the build process +shards pages across multiple threads, parses each shard +independently, then writes the results. If the parser were +non-deterministic (e.g. depended on a global counter, a +timestamp, or a shared cache), two workers given the same +input would produce different HTML. That would break: +- Caching layers (the same content rendered twice should + hash the same). +- The boot-time self-test (any non-determinism crashes the + worker at init, before the first message is processed). +- Reproducible builds (`pnpm build` should produce the same + output every time, given the same source). + +## OKF classification + +`okf.type: reference` โ€” explicit. The page is included in the +OKF bundle as a `reference` concept. diff --git a/packages/_playground/docs/en/practical-tests/phase-2/f1-nested-grids.md b/packages/_playground/docs/en/practical-tests/phase-2/f1-nested-grids.md new file mode 100644 index 0000000..7586506 --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-2/f1-nested-grids.md @@ -0,0 +1,71 @@ +--- +title: "F1: nested grids with one close per card" +description: "The pre-Phase 2 parser dumped the whole grids block as raw

::: grids
::: grid
...
:::

text. Post-fix it renders four grid-items, each containing one card." +okf: + type: guide +--- + +# F1 โ€” nested grids with one close per card + +This page exercises the **F1 container parser fix** from +`battle-test-reports/test-report.md ยงF1`. The pattern below used +to be the user-reported "grids don't work" bug. + +## The pattern + +```markdown +::: grids + ::: grid + ::: card "Fast" + Lightning fast. + ::: + ::: grid + ::: card "Simple" + Zero config. + ::: + ::: grid + ::: card "Open" + Fully open source. + ::: + ::: grid + ::: card "Live" + Edit in browser. + ::: +::: +``` + +## The rendered result (post-fix) + +::: grids + ::: grid + ::: card "Fast" + Lightning fast. + ::: + ::: grid + ::: card "Simple" + Zero config. + ::: + ::: grid + ::: card "Open" + Fully open source. + ::: + ::: grid + ::: card "Live" + Edit in browser. + ::: +::: + +The normaliser balances the missing closes so the `grids` rule +matches and the inner `grid` and `card` rules can do their work. + +## What the pre-fix output looked like + +A single `

::: grids
::: grid
::: card "Fast"
...
:::

` +text block. The whole nested structure was dumped as a +paragraph of source code. + +## OKF classification + +This page declares `okf.type: guide` explicitly. In the OKF +bundle, it lives in `concepts/practical-tests-phase-2-f1-nested-grids.md` +with the `type: guide` field set. diff --git a/packages/_playground/docs/en/practical-tests/phase-2/f2-self-closing-button.md b/packages/_playground/docs/en/practical-tests/phase-2/f2-self-closing-button.md new file mode 100644 index 0000000..6857644 --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-2/f2-self-closing-button.md @@ -0,0 +1,48 @@ +--- +title: "F2: self-closing button + orphan :::" +description: "The pre-Phase 2 parser treated self-closing ::: button as a non-self-closing container, corrupting the depth counter for everything that followed. Post-fix the orphan ::: is removed with a [normaliser] WARNING." +okf: + type: guide +--- + +# F2 โ€” self-closing button + orphan `:::` + +This page exercises the **F2 self-closing tag fix** from +`battle-test-reports/test-report.md ยงF2`. The pattern below used +to leave an orphan `:::` visible in the page AND corrupt the +depth counter for any container that followed. + +## The pattern + +```markdown +::: card "Cards with self-closing buttons" +Some text. +::: button "Get Started" /getting-started +::: +``` + +## The rendered result (post-fix) + +::: card "Cards with self-closing buttons" +Some text. +::: button "Get Started" /getting-started +::: + +The `::: button` is a self-closing tag (per the parser's +`SELF_CLOSING_CONTAINER_NAMES` set). The orphan `:::` is +removed by the container normaliser with a `[normaliser] WARNING +...` line in the build log. The card is closed correctly. + +## What the pre-fix output looked like + +The `::: button` was pushed to the depth stack as a normal +container. The orphan `:::` decremented depth of the wrong +container (not the button, not the card โ€” an arbitrary parent +in the parser's state). Any container after this point on the +page would have its open/close count misaligned. + +## OKF classification + +`okf.type: guide` โ€” explicit. In the OKF bundle, this page is +classified as a `guide` and the frontmatter's `okf` block is +preserved. diff --git a/packages/_playground/docs/en/practical-tests/phase-2/f3-mismatched-close.md b/packages/_playground/docs/en/practical-tests/phase-2/f3-mismatched-close.md new file mode 100644 index 0000000..fa0f7fc --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-2/f3-mismatched-close.md @@ -0,0 +1,53 @@ +--- +title: "F3: mismatched close types" +description: "The pre-Phase 2 parser dumped the ::: callout opener as raw text when the page contained a ::: card opener in the middle. Post-fix the callout is auto-closed at EOF with a [normaliser] ERROR." +okf: + type: guide +--- + +# F3 โ€” mismatched close types + +This page exercises the **F3 mismatched close types fix** from +`battle-test-reports/test-report.md ยงF3`. The pattern below used +to silently re-root the parser โ€” the `::: callout` opener was +dumped as text, the `::: card` rendered standalone, and the +`:::` close was miscounted. + +## The pattern + +```markdown +::: callout info "x" +body +::: card "wrong close" +oops +::: +``` + +## The rendered result (post-fix) + +::: callout info "x" +body +::: card "wrong close" +oops +::: + +The `callout` rule matches its own body; the inner `card` rule +matches its own body; the trailing `:::` closes the card. The +outer callout is auto-closed at EOF with a `[normaliser] ERROR +... Unclosed from line 1 โ€” auto-closed at EOF` line in +the build log. + +## What the pre-fix output looked like + +A `

::: callout info "x"
body

` paragraph (the callout +opener was dumped as text), followed by the card rendered +standalone โ€” the callout's open/close count was off by 1 because +the inner `::: card` was miscounted as a depth-incrementing +container, so the `:::` close dropped the count to 1 instead of +0, and the callout rule never matched. + +## OKF classification + +`okf.type: guide` โ€” explicit. This page deliberately has an +unclosed container; the OKF bundle still includes it (it +generates a per-page warning, but does not exclude the page). diff --git a/packages/_playground/docs/en/practical-tests/phase-2/f4-triple-close.md b/packages/_playground/docs/en/practical-tests/phase-2/f4-triple-close.md new file mode 100644 index 0000000..3d26079 --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-2/f4-triple-close.md @@ -0,0 +1,52 @@ +--- +title: "F4: triple close erases content" +description: "The pre-Phase 2 parser left bare ::: lines visible in the page as

:::

paragraphs. Post-fix the orphans are removed with [normaliser] WARNINGs." +okf: + type: guide +--- + +# F4 โ€” triple close erases content + +This page exercises the **F4 triple-close / orphan `:::` fix** +from `battle-test-reports/test-report.md ยงF4`. The pattern below +used to leak `

:::

` paragraphs into the rendered page. + +## The pattern + +```markdown +::: callout info "x" +body +::: +::: +::: +``` + +## The rendered result (post-fix) + +::: callout info "x" +body +::: +::: +::: + +The first `:::` closes the callout (matching). The second and +third are stray โ€” the normaliser removes them with two +`[normaliser] WARNING ... Stray \`:::\` removed` lines in the +build log. The rendered page contains the callout block and +NOTHING ELSE (no orphan `

:::

` leak). + +## What the pre-fix output looked like + +The callout rendered correctly (one close matched the opener). +But the next two `:::` lines were outside any container, so +markdown-it rendered them as a single paragraph: +`

:::
:::

`. Users saw two `:::` characters inline with +their content โ€” a visible artefact of the parser's loose +matching. + +## OKF classification + +`okf.type: guide` โ€” explicit. Despite the unclosed trailing +container, the page IS included in the OKF bundle (the orphan +removal happens in the page body, not in frontmatter; OKF +itself has no unclosed containers). diff --git a/packages/_playground/docs/en/practical-tests/phase-2/f5-five-level-nesting.md b/packages/_playground/docs/en/practical-tests/phase-2/f5-five-level-nesting.md new file mode 100644 index 0000000..f0fb5e1 --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-2/f5-five-level-nesting.md @@ -0,0 +1,61 @@ +--- +title: "F5: 5-level nested callouts render all 5 levels" +description: "The pre-Phase 2 parser collapsed 5-level nested callouts into the outer level. Post-fix all 5 levels render in the output HTML." +okf: + type: guide +--- + +# F5 โ€” 5-level nested callouts + +This page exercises the **F5 5-level nested callout fix** from +`battle-test-reports/test-report.md ยงF5`. The pattern below used +to collapse the inner levels โ€” the user saw `
l1
` with only the "deep" body and no +intermediate levels. + +## The pattern + +```markdown +::: callout info "l1" +::: callout tip "l2" +::: callout warning "l3" +::: callout danger "l4" +::: callout success "l5" +deep +::: +::: +::: +::: +::: +``` + +## The rendered result (post-fix) + +::: callout info "l1" +::: callout tip "l2" +::: callout warning "l3" +::: callout danger "l4" +::: callout success "l5" +deep +::: +::: +::: +::: +::: + +The container normaliser adds four implicit closes when the +user's single `:::` close closes the outer callout. Each inner +`callout` rule then matches its own body recursively. + +## What the pre-fix output looked like + +A single `
` containing only +the text "deep" โ€” the inner callouts were dropped silently +because the depth counter never reached 0 at the expected +position. + +## OKF classification + +`okf.type: guide` โ€” explicit. The page is treated as a single +`guide` concept in the OKF bundle. The nested callouts are +preserved in the page body verbatim (OKF copies `rawMarkdown`). diff --git a/packages/_playground/docs/en/practical-tests/phase-3/cli-exit-codes.md b/packages/_playground/docs/en/practical-tests/phase-3/cli-exit-codes.md new file mode 100644 index 0000000..22ccb1f --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-3/cli-exit-codes.md @@ -0,0 +1,72 @@ +--- +title: "Phase 3 โ€” CLI exit codes (F6, M-12)" +description: "The pre-Phase 3 docmd CLI exited 0 on many documented failure paths. Post-fix every documented error path exits 1. This page documents the contract." +--- + +# Phase 3 โ€” CLI exit codes (F6, M-12) + +This page documents the **Phase 3 PR 3.A exit-code contract fix** +from `battle-test-reports/test-report.md ยงF6` and +`battle-test-reports/more-report.md ยงM-12`. + +## The contract + +Every documented `docmd ` failure path MUST exit with +a non-zero code so CI pipelines can gate on it. Before this fix, +several paths printed a clear error message but exited 0, +silently passing broken builds. + +## The 5 paths that were fixed + +| Command | Failure case | Pre-fix exit | Post-fix exit | +|---|---|---|---| +| `docmd build` | Unknown plugin in config | 0 | 1 | +| `docmd migrate` | No `--docusaurus`/`--mkdocs`/etc. flag | 0 | 1 | +| `docmd migrate --help` | (it's a help print) | 0 | 0 (unchanged) | +| `docmd remove ` | Plugin not in registry | 0 | 1 | +| `docmd validate --json` | Broken links in any page | 0 | 1 | + +## The mechanism + +A new helper module `packages/core/src/utils/exit.ts` exports +three functions: + +- `exitCodeFor(err)` โ€” returns the numeric exit code. Today + always 1 (operational error); the indirection lets us + introduce code-2/3/4 later without rewriting every call site. +- `exitWithError(err, opts?)` โ€” calls `TUI.error` (or prints + JSON when `opts.json === true`) and `process.exit(code)`. +- `failWith(message, opts?)` โ€” convenience wrapper for the + "plain message, no Error object" case. + +For `migrate` and `remove`, the `TUI.error(...); return;` pattern +was replaced with `process.exit(1)` (or, in `migrate.ts`, a +`exitWithError` call). For `build`, the new `getPluginLoadErrors()` +in `@docmd/api` returns a list of plugins that failed to load, +and `build.ts` throws if the list is non-empty โ€” the existing +catch block turns the throw into `process.exit(1)`. + +## How to verify + +```bash +cd packages/_playground + +# F6: unknown plugin โ†’ exit 1 +mkdir -p /tmp/f6 && cd /tmp/f6 +echo '{"title":"F6","plugins":{"nope":{}}}' > docmd.config.json +node ../../packages/core/dist/bin/docmd.js build +echo $? # 1 + +# M-12: validate --json with broken links โ†’ exit 1 +cd /tmp/m12 && echo '[bad](/nope)' > docs/index.md +node ../../packages/core/dist/bin/docmd.js validate --json +echo $? # 1 + +# Sanity: --help still exits 0 +node ../../packages/core/dist/bin/docmd.js migrate --help +echo $? # 0 +``` + +The test matrix is `scripts/brute-test.js` test 26 (7 assertions, +regression-tested in the categorised test suite under +`tests/cli-contracts/exit-codes.test.js`). diff --git a/packages/_playground/docs/en/practical-tests/phase-3/internal-link-with-trailing-slash.md b/packages/_playground/docs/en/practical-tests/phase-3/internal-link-with-trailing-slash.md new file mode 100644 index 0000000..b7a1158 --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-3/internal-link-with-trailing-slash.md @@ -0,0 +1,58 @@ +--- +title: "M-1: internal link with trailing slash" +description: "The pre-Phase 3 docmd validate command false-positived every internal link with a trailing slash. Post-fix the trailing slash is stripped before the .md existence check." +--- + +# M-1 โ€” internal link with trailing slash + +This page exercises the **M-1 trailing-slash false-positive fix** +from `battle-test-reports/more-report.md ยงM-1`. The link below +used to be reported as a broken link by `docmd validate` even +though the target file existed. + +## The pattern + +A markdown link with a trailing slash to a sibling page (one +directory up, then down into `phase-2`): + +```markdown +Links to [F1 grids test](../phase-2/f1-nested-grids/). +``` + +## The rendered result (post-fix) + +Links to [F1 grids test](../phase-2/f1-nested-grids/). + +The link's `href` is `../../phase-2/f1-nested-grids/`. The build +treats this as equivalent to `../../phase-2/f1-nested-grids` +(without slash) โ€” both resolve to the same generated HTML page. +`docmd validate` now agrees. + +## What the pre-fix output looked like + +`docmd validate` reported: + +``` +[docs/en/practical-tests/phase-3/internal-link-with-trailing-slash.md:N] + ../../phase-2/f1-nested-grids/ -> Broken link: target resolved to + docs/en/practical-tests/phase-2/f1-nested-grids does not exist +``` + +The validator did `fs.existsSync('docs/en/practical-tests/phase-2/f1-nested-grids/.md')` +which is always false. CI pipelines that gated on +`docmd validate` exited 0 (because exit 0 is the default for +no-broken-links), so broken-link regressions slipped through. + +## How to verify + +```bash +cd packages/_playground +node ../../packages/core/dist/bin/docmd.js validate +# exit 0 โ€” no broken links +node ../../packages/core/dist/bin/docmd.js validate --json | jq '.errors | length' +# 0 +``` + +The fix lives in `packages/core/src/commands/mcp.ts` +`validateLinks()` โ€” a single `stripped` variable drops the +trailing `/` before the four `fs.existsSync` checks. diff --git a/packages/_playground/docs/en/practical-tests/phase-3/llms-and-okf-default-locale.md b/packages/_playground/docs/en/practical-tests/phase-3/llms-and-okf-default-locale.md new file mode 100644 index 0000000..3d0c248 --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-3/llms-and-okf-default-locale.md @@ -0,0 +1,99 @@ +--- +title: "LLMS and OKF: default-locale-only by default" +description: "Both the @docmd/plugin-llms and @docmd/plugin-okf plugins write the default locale's files at the bundle root by default. Non-default locales are only written when the user explicitly opts in via plugins.llms.i18n: true or plugins.okf.localeStrategy: 'folders'." +--- + +# LLMS and OKF โ€” default-locale-only by default + +This page documents the **i18n contract** for the two AI-agent +plugins shipped with docmd 0.8.8: + +- `@docmd/plugin-llms` โ€” generates `llms.txt` / `llms-full.txt` / `llms.json` +- `@docmd/plugin-okf` โ€” generates the OKF bundle (`site/okf/`) + +Both plugins used to write **per-locale** output by default. That +default was wrong for two reasons: + +1. The `llms.txt` filename is the standard single-file name that + downstream consumers (Cursor, Claude, GPT, etc.) look for. + Splitting it into `llms.en.txt` + `llms.hi.txt` + `llms.fr.txt` + broke every existing integration. + +2. The OKF bundle is meant to be a "knowledge base" โ€” the user + doesn't want to push 6 locale variants of every concept to a + vector store. They want the primary-language version, with + non-default locales as opt-in extras. + +## The new default + +| Plugin | Default behaviour | File name | +|---|---|---| +| `llms` | Default locale only | `llms.txt`, `llms-full.txt`, `llms.json` | +| `okf` | Default locale only | `site/okf/okf.yaml`, `site/okf/concepts/*.md`, etc. | + +The default locale is whatever `config.i18n.default` resolves to. +Single-locale sites (no `config.i18n` block) are unaffected โ€” they +get the same single set of files as before. + +## Opting into multi-locale + +Set the corresponding option in `docmd.config.json`: + +```json +{ + "plugins": { + "llms": { "i18n": true }, + "okf": { "localeStrategy": "folders" } + } +} +``` + +With both options set, the plugins write per-locale output: + +``` +site/llms.txt โ† default locale (en) โ€” UNSUFFIXED +site/llms-full.txt โ† default locale (en) โ€” UNSUFFIXED +site/llms.json โ† default locale (en) โ€” UNSUFFIXED +site/llms.hi.txt โ† hi โ€” suffixed +site/llms-full.hi.txt โ† hi โ€” suffixed +site/llms.hi.json โ† hi โ€” suffixed +site/llms.fr.txt โ† fr โ€” suffixed +site/llms-full.fr.txt โ† fr โ€” suffixed +site/llms.fr.json โ† fr โ€” suffixed + +site/okf/ โ† default locale +โ”œโ”€โ”€ okf.yaml +โ”œโ”€โ”€ index.md +โ”œโ”€โ”€ concepts/ +โ”‚ โ””โ”€โ”€ root.md +โ””โ”€โ”€ _meta/, graph.html, graph.json, ... + +site/okf/hi/ โ† hi โ€” suffixed directory +โ”œโ”€โ”€ concepts/ +โ”‚ โ””โ”€โ”€ hi.md + +site/okf/fr/ โ† fr โ€” suffixed directory +โ”œโ”€โ”€ concepts/ +โ”‚ โ””โ”€โ”€ fr.md +``` + +Notice the pattern: **the default locale never gets a suffix or a +subdirectory** โ€” it sits at the bundle root where existing +consumers expect it. Only the non-default locales get the +`/` (OKF) or `.` (LLMS) suffix. + +## How to verify + +The current `_playground` is a single-locale project (en only), +so both plugins write a single set of files at the root โ€” no +suffix, no subdirectory. To test multi-locale, set +`config.i18n.locales` to include more than one locale AND enable +the opt-in flags shown above. + +## OKF classification + +This page sits at `/en/practical-tests/phase-3/llms-and-okf-default-locale/` +which doesn't match any of the OKF type-inference prefixes +(`/api/`, `/guides/`, etc.). It falls back to the default type: +`concept`. In the OKF bundle, it lives at +`site/okf/concepts/llms-and-okf-default-locale.md`. diff --git a/packages/_playground/docs/en/practical-tests/phase-3/okf-bundle-default.md b/packages/_playground/docs/en/practical-tests/phase-3/okf-bundle-default.md new file mode 100644 index 0000000..04e06d5 --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-3/okf-bundle-default.md @@ -0,0 +1,64 @@ +--- +title: "OKF default-enabled + type inference" +description: "This page is included in the OKF bundle by default (no plugins.okf config needed), demonstrates the path-prefix type inference map, and shows the noindex + okf: false opt-out paths in the body." +--- + +# OKF โ€” default-enabled + type inference + +This page exercises the **OKF plugin (0.8.8)**: + +- **Default-enabled** โ€” the `site/okf/` bundle is generated + even when `docmd.config.json` has no `plugins.okf` entry. + See [`README.md` of `@docmd/plugin-okf`][okf-readme] for the + callout. +- **Type inference** โ€” pages under `/api/` are auto-classified + as `api`, pages under `/guides/` as `guide`, etc. The path + prefix map is documented in the OKF README. +- **Per-page opt-out** โ€” pages with `noindex: true` or + `okf: false` in frontmatter are excluded from the bundle. + +[okf-readme]: ../../../../plugins/okf/README.md + +## How OKF classifies this page + +This page is at `/en/practical-tests/phase-3/okf-bundle-default/` +which doesn't match any of the type-inference prefixes +(`guides/`, `api/`, `reference/`, `concepts/`, `runbooks/`, +`datasets/`, `metrics/`, `tables/`). So OKF falls back to the +default type: `concept`. Look at `site/okf/okf.yaml` after +the build to see this page listed under the `concept` type. + +## OKF: false opt-out + +A page with this frontmatter would be excluded from the bundle: + +```markdown +--- +okf: false +--- +``` + +We don't actually use that here (because we want to verify the +page IS in the bundle), but the OKF plugin's `onPostBuild` +filters pages where `p.frontmatter.okf === false`. + +## `noindex: true` opt-out + +A page with `noindex: true` is excluded from the OKF bundle +AND from the sitemap, search index, and llms.txt. This is the +standard docmd opt-out โ€” applies to multiple plugins uniformly. + +## What to inspect after the build + +After running `pnpm docmd build` from `packages/_playground/`: + +```bash +ls site/okf/concepts/ | head # one .md per page +cat site/okf/okf.yaml | head -30 # typed manifest +open site/okf/graph.html # interactive graph viewer +``` + +The `okf.yaml` file lists every concept in the bundle with its +type, path, locale, and version. The graph viewer renders a +force-directed graph of the concept relationships inferred from +internal markdown links. diff --git a/packages/_playground/docs/en/practical-tests/phase-3/okf-type-inference.md b/packages/_playground/docs/en/practical-tests/phase-3/okf-type-inference.md new file mode 100644 index 0000000..8cc9053 --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-3/okf-type-inference.md @@ -0,0 +1,70 @@ +--- +title: "OKF type inference โ€” no frontmatter needed" +description: "OKF classifies pages by URL path prefix even when frontmatter has no okf.type. /api/ โ†’ api, /guides/ โ†’ guide, etc. This page sits in /en/practical-tests/ which doesn't match any prefix, so it falls back to the default type 'concept'." +--- + +# OKF type inference โ€” no frontmatter needed + +This page exercises the **OKF type inference** feature: when a +page has no explicit `okf.type` in frontmatter, OKF infers a +type from the URL path prefix. + +## The inference map + +| URL prefix | Inferred type | +|---|---| +| `/api/` | `api` | +| `/guides/` | `guide` | +| `/reference/` | `reference` | +| `/concepts/` | `concept` | +| `/runbooks/` | `runbook` | +| `/datasets/` | `dataset` | +| `/metrics/` | `metric` | +| `/tables/` | `table` | +| (anything else) | `concept` (the defaultType) | + +The map is implemented in `packages/plugins/okf/src/index.ts` +`PATH_TYPE_MAP`. + +## This page's inferred type + +This page is at `/en/practical-tests/phase-3/okf-type-inference/`. +That path doesn't match any of the inference prefixes. The +page has no `okf.type` in frontmatter, so OKF falls back to the +default type: **`concept`**. Look at `site/okf/okf.yaml` after +the build to see this page classified under the `concept` +type. + +## What happens with explicit frontmatter + +If this page had: + +```yaml +--- +okf: + type: api +--- +``` + +โ€ฆthen OKF would classify it as `api` (explicit overrides +inferred). The precedence in `resolveType()` is: + +1. `frontmatter.okf.type` (nested) โ€” explicit +2. `frontmatter.` (top-level) โ€” usually `type:` in + modern docmd pages +3. `frontmatter.okfType` (legacy) โ€” old alias +4. Path-prefix inference (this section) +5. `defaultType` from config (default: `concept`) + +## How to verify + +After `pnpm docmd build` from `packages/_playground/`: + +```bash +grep -A 2 "okf-type-inference" site/okf/okf.yaml +# Should list this page with type: concept +``` + +To see explicit-vs-inferred, edit the frontmatter of this page +to add `okf.type: guide` and rebuild. The YAML will show +`type: guide` instead of `type: concept`. diff --git a/packages/_playground/docs/en/practical-tests/phase-3/xss-in-frontmatter.md b/packages/_playground/docs/en/practical-tests/phase-3/xss-in-frontmatter.md new file mode 100644 index 0000000..b2f0127 --- /dev/null +++ b/packages/_playground/docs/en/practical-tests/phase-3/xss-in-frontmatter.md @@ -0,0 +1,71 @@ +--- +title: "T-S3: XSS payloads in frontmatter are HTML-escaped" +description: "The pre-Phase 1 build rendered XSS payloads in frontmatter title and description fields as live HTML in og:/twitter: meta tags and the page . Post-fix every interpolation goes through attrEsc() or escHtml()." +--- + +# T-S3 โ€” XSS payloads in frontmatter are HTML-escaped + +This page exercises the **T-S3 XSS via og:/twitter: meta tags +fix** from `battle-test-reports/test-report.md ยงS3` and +`ยงT-S3`. The frontmatter below contains classic XSS payloads. +Pre-Phase 1 they were rendered as live HTML in the generated +page. Post-fix they are HTML-escaped everywhere they appear. + +## The pattern + +The frontmatter of this page contains: + +```yaml +--- +title: '"><img src=x onerror=alert(1)> - Site' +description: '<script>alert("fm-xss")</script> Page description' +--- +``` + +## The rendered result (post-fix) + +The `<title>` of the generated page contains the escaped version: + +```html +<title>"><img src=x onerror=alert(1)> - Site +``` + +The og:title / twitter:title meta tags: + +```html + + +``` + +No live `` in the page. No `onerror` +handler. The payloads are visible in the browser as literal +text โ€” exactly what the user typed. + +## What the pre-fix output looked like + +```html +"><img src=x onerror=alert(1)> - Site + - Site"> +``` + +The XSS payload fired as soon as the page loaded. CI pipelines +that scanned for `` : ''; + + // Determine Absolute Base (usually '/' unless 'base' config is set) + const absoluteRoot = config.base && config.base !== '/' ? config.base.replace(/\/$/, '') + '/' : '/'; + + const full404Html = await renderTemplateAsync(notFoundTemplateStr, { + pageTitle: resolvedTitle, + title: resolvedTitle, + content: resolvedContent, + logo: config.logo, + t, + activeLocale, + + // Context for Assets + relativePathToRoot: absoluteRoot, + buildHash, + appearance: config.theme?.appearance || config.theme?.defaultMode || 'system', + defaultMode: config.theme?.appearance || config.theme?.defaultMode || 'system', + theme: config.theme, + customCssFiles: config.theme.customCss || [], + + faviconLinkHtml: config.favicon ? `` : '', + themeInitScript + }); + + await fs.writeFile(path.join(rootOutputDir, '404.html'), full404Html); + + // --- 4. GENERATE STATIC REDIRECTS --- + if (config.redirects && Object.keys(config.redirects).length > 0) { + for (const [from, to] of Object.entries(config.redirects)) { + let cleanFrom = from.replace(/^\//, ''); + if (!cleanFrom.endsWith('.html')) cleanFrom = path.join(cleanFrom, 'index.html'); + + const redirectPath = path.join(rootOutputDir, cleanFrom); + const redirectHtml = `Redirecting...

Redirecting to ${to}...

`; + + await fs.ensureDir(path.dirname(redirectPath)); + await fs.writeFile(redirectPath, redirectHtml); + } + } + + // --- 5. Post Build Hooks --- + // Only run on full builds. Split into: + // Data Indexing โ†’ search (appended to already-open section from git above) + // Publishing โ†’ sitemap, llms, pwa, etc. + if (!options.targetFiles) { + const postBuildCtx = { + config, + pages: allGeneratedPages, + outputDir: rootOutputDir, + log: (msg: string, status: 'DONE'|'SKIP'|'FAIL'|'WAIT' = 'DONE') => { + if (!options.quiet) TUI.step(msg, status, TUI.blue); + }, + tui: TUI, + options: { ...options, quiet: options.quiet }, + runWorkerTask(modulePath: string, functionName: string, args: any[]) { + if (!config._workerPool) throw new Error('WorkerPool is not initialized'); + return config._workerPool.runTask({ type: 'plugin-task', modulePath, functionName, args }); + } + }; + + // Indexing โ€” search runs in the already-open Data Indexing section + for (const fn of indexingHooks) await fn(postBuildCtx); + if (hasIndexingWork && !options.quiet) TUI.footer(TUI.blue); + + // Publishing โ€” each plugin renders as a parent line + indented children + if (publishingHooks.length > 0) { + if (!options.quiet) TUI.section('Publishing', TUI.blue); + for (const fn of publishingHooks) { + const pluginName = String((fn as any)._pluginName || 'plugin'); + const entries: Array<{ msg: string; status: 'DONE'|'SKIP'|'FAIL'|'WAIT' }> = []; + const pluginCtx = { + ...postBuildCtx, + log: (msg: string, status: 'DONE'|'SKIP'|'FAIL'|'WAIT' = 'DONE') => { + entries.push({ msg, status }); + }, + }; + await fn(pluginCtx); + if (!options.quiet) TUI.pluginTree(pluginName, entries, TUI.blue); + } + if (!options.quiet) TUI.footer(TUI.blue); + } + } + + if (!options.isDev && !options.quiet) { + flushNormaliserWarnings(); + TUI.success(`Build complete. Generated ${allGeneratedPages.length} pages in ${elapsed()}.`); + } + + if (!opts.workerPool) { + await workerPool.terminateAll(); + } + + const { getPluginErrors } = await import('@docmd/api'); + const errors = getPluginErrors(); + if (errors.length > 0) { + // N-12: surface every plugin error in one place. Previously the + // user saw "Build complete" and only later discovered failures when + // a generated page was missing or a downstream tool choked on a + // bad artifact. The summary lists every error with its plugin + + // hook, so the operator can grep for any of them. + if (!options.isDev && !options.quiet) { + TUI.error('Plugin errors during build', ''); + for (const err of errors) { + const filePart = err.filePath ? ` (${err.filePath})` : ''; + console.error(` ${TUI.red('โ€ข')} ${err.plugin} :: ${err.hook}${filePart} โ€” ${err.message}`); + } + } + throw new Error(`Build failed: ${errors.length} plugin error(s) occurred during execution.`); + } + + } catch (e: any) { + if (!options.isDev && !options.quiet) { + TUI.error('Build failed', e.message); + // Show full stack trace if we are in a testing/CI environment + if (process.env.npm_lifecycle_event === 'test' || process.env.CI) { + console.error(e.stack); + } + process.exit(1); + } + throw e; + } +} \ No newline at end of file diff --git a/packages/core/src/commands/deploy.ts b/packages/core/src/commands/deploy.ts new file mode 100644 index 0000000..fed01a1 --- /dev/null +++ b/packages/core/src/commands/deploy.ts @@ -0,0 +1,93 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { generateDeployConfigs } from '@docmd/deployer'; +import { loadConfig } from '../utils/config-loader.js'; +import { normalizeConfig } from '../utils/config-schema.js'; +import { TUI } from '@docmd/api'; +import { readFileSync } from 'node:fs'; + +const pkgUrl = new URL('../../package.json', import.meta.url); +const { version } = JSON.parse(readFileSync(pkgUrl, 'utf-8')); + +interface DeployFlags { + docker?: boolean; + nginx?: boolean; + caddy?: boolean; + githubPages?: boolean; + vercel?: boolean; + netlify?: boolean; + force?: boolean; + config?: string; +} + +async function resolveDeployContext(configPath: string) { + let config: any; + try { + config = await loadConfig(configPath, { isDev: false, quiet: true }); + } catch { + config = normalizeConfig({}); + } + + const title = config.title; + const outDir = config.out; + const siteUrl = config.url ?? null; + const isSpa = config.layout?.spa !== false; + const configFile = configPath !== 'docmd.config.js' ? configPath : null; + + let hostname = ''; + if (siteUrl) { + try { + hostname = new URL(siteUrl).hostname; + } catch { + hostname = siteUrl.replace(/^https?:\/\//, '').split('/')[0]; + } + } + + return { title, outDir, siteUrl, hostname, isSpa, configFile, version }; +} + +export async function initDeploy(opts: DeployFlags) { + const hasTarget = opts.docker || opts.nginx || opts.caddy || opts.githubPages || opts.vercel || opts.netlify; + + if (!hasTarget) { + TUI.section('Deployment Configuration'); + TUI.info('Please specify a target to configure:'); + console.log(''); + console.log(` Self-hosted`); + console.log(` ${TUI.cyan('--docker')} Generate Dockerfile & .dockerignore`); + console.log(` ${TUI.cyan('--nginx')} Generate production nginx.conf`); + console.log(` ${TUI.cyan('--caddy')} Generate production Caddyfile`); + console.log(''); + console.log(` Cloud / CI`); + console.log(` ${TUI.cyan('--github-pages')} Generate GitHub Actions deploy workflow`); + console.log(` ${TUI.cyan('--vercel')} Generate vercel.json`); + console.log(` ${TUI.cyan('--netlify')} Generate netlify.toml`); + console.log(''); + TUI.footer(); + process.exit(0); + } + + try { + const ctx = await resolveDeployContext(opts.config || 'docmd.config.js'); + TUI.section('Generating Deployment Configs'); + await generateDeployConfigs(ctx, opts); + TUI.footer(); + TUI.success('Deployment configurations generated successfully!'); + TUI.info(`Remember to run ${TUI.cyan('docmd build')} first to generate your static site content.`); + } catch (err: any) { + TUI.error('Failed to generate deployment config', err.message); + process.exit(1); + } +} \ No newline at end of file diff --git a/packages/core/src/commands/dev.ts b/packages/core/src/commands/dev.ts new file mode 100644 index 0000000..dcf65b2 --- /dev/null +++ b/packages/core/src/commands/dev.ts @@ -0,0 +1,511 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import http from 'http'; +import { WebSocketServer, WebSocket } from 'ws'; +import nativeFs from 'node:fs'; +import path from 'path'; +import { fsUtils as fs, WorkerPool, FileSignatureTracker } from '@docmd/utils'; +import { createOriginVerify } from '../utils/ws-origin-guard.js'; +import { TUI } from '@docmd/api'; +import { buildSite } from './build.js'; +import { loadConfig } from '../utils/config-loader.js'; +import { createRequire } from 'module'; +import { createActionDispatcher, loadPlugins, hooks } from '@docmd/api'; +import { + formatPathForDisplay, getNetworkIp, serveStatic, findAvailablePort, openBrowser, +} from '../utils/dev-utils.js'; + +const __dirname = path.dirname(new URL(import.meta.url).pathname); +const require = createRequire(import.meta.url); + +// Main Dev Function +export async function startDevServer(configPathOption: string, opts: any = {}) { + const options = { + preserve: opts.preserve || false, + port: opts.port || undefined, + }; + + // โ”€โ”€ Multi-Project (Workspace) Detection โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + if (!process.env.DOCMD_PROJECT_OUT) { + const { detectWorkspace, devWorkspace } = await import('../engine/workspace.js'); + const workspaceConfig = await detectWorkspace(configPathOption); + if (workspaceConfig) { + await devWorkspace(workspaceConfig, options); + return; + } + } + + let config; + try { + config = await loadConfig(configPathOption, { isDev: true, quiet: true }); + } catch (e) { + if (e.silent) { + process.exit(0); // Exit gracefully if it's a known non-project folder error + } + // Config validation errors already print their details - exit cleanly + if (e.message === 'Invalid configuration file.' || e.message?.startsWith('Error parsing config')) { + TUI.error('Build failed', e.message); + process.exit(1); + } + throw e; + } + const CWD = process.cwd(); + + // Config Fallback Logic + const actualConfigPath = config._resolvedPath || path.resolve(CWD, configPathOption); + + const resolveConfigPaths = (currentConfig) => ({ + outputDir: path.resolve(CWD, currentConfig.out), + srcDirToWatch: path.resolve(CWD, currentConfig.src), + configFileToWatch: actualConfigPath, + userAssetsDir: path.resolve(CWD, 'assets'), + }); + + let paths = resolveConfigPaths(config); + + // Create Server - uses a mutable reference so config restarts update the output dir + const state = { outputDir: paths.outputDir }; + const server = http.createServer((req, res) => serveStatic(req, res, state.outputDir)); + let wss; + + function broadcastReload() { + if (wss) { + wss.clients.forEach((client) => { + if (client.readyState === WebSocket.OPEN) client.send('reload'); + }); + } + } + + // โ”€โ”€ Initial Build โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + const initialElapsed = TUI.timer(); + + const rootOutputDir = path.resolve(CWD, config.out || 'site'); + + let workerPool: WorkerPool; + + try { + const workerScript = path.resolve(__dirname, '../engine/worker-parser.js'); + workerPool = new WorkerPool(workerScript, { config, cwd: CWD }); + // Clean output dir before initial build to remove stale files from previous builds. + // Without this, files generated under old URL structures (e.g. from a different + // auto-router behaviour) persist alongside new files and cause 404 on nav links. + if (await fs.exists(rootOutputDir)) { + await fs.remove(rootOutputDir); + } + await buildSite(configPathOption, { isDev: true, preserve: options.preserve, quiet: false, showStats: false, workerPool }); + TUI.info(`Initial build completed in ${initialElapsed()}.`); + } catch (error: any) { + TUI.error('Initial build failed', error.message); + } + + // โ”€โ”€ Watcher Setup โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + const userAssetsDirExists = await fs.pathExists(paths.userAssetsDir); + const configWatchPath = paths.configFileToWatch; + const hasConfigFile = await fs.pathExists(configWatchPath); + + TUI.section('Watching', TUI.blue); + TUI.item('Source', formatPathForDisplay(paths.srcDirToWatch, CWD), TUI.dim, TUI.blue); + if (hasConfigFile) { + TUI.item('Config', formatPathForDisplay(configWatchPath, CWD), TUI.dim, TUI.blue); + } + if (userAssetsDirExists) { + TUI.item('Assets', formatPathForDisplay(paths.userAssetsDir, CWD), TUI.dim, TUI.blue); + } + TUI.footer(TUI.blue); + + const watchers: nativeFs.FSWatcher[] = []; + let isRebuilding = false; + let rebuildQueued = false; + let rebuildTimeout: any = null; + let lastContentRebuildAt = 0; + let lastConfigRebuildAt = 0; + // Quiet windows after a rebuild to absorb phantom fs.watch events that + // macOS emits for newly-written nearby files. The primary guard is the + // content-signature check (FileSignatureTracker) below โ€” these windows + // are just a secondary cushion. + // - 1000ms after a content (markdown / asset) rebuild โ€” quick to recover + // - 2500ms after a full config rebuild โ€” longer because the build + // cascades through every project file + const CONTENT_QUIET_MS = 1000; + const CONFIG_QUIET_MS = 2500; + // Tracks each watched file's mtime+size signature so phantom fs.watch + // events that don't actually mutate the file are silently ignored. + const signatureTracker = new FileSignatureTracker(); + + // Resolved output dir for robust exclusion (never retrigger on build output) + const resolvedOutputDir = path.resolve(CWD, config.out || 'site'); + + let configLock = false; + let configDebounce: any = null; + async function reloadConfigAndRebuild(changedFilePath: string) { + if (configLock) return; + configLock = true; + + const baseName = path.basename(changedFilePath); + const configElapsed = TUI.timer(); + TUI.step(`Reloading config and rebuilding due to change in: ${baseName}`, 'WAIT', TUI.blue, true); + + try { + // Close all watchers + watchers.forEach(w => w.close()); + watchers.length = 0; + if (rebuildTimeout) { clearTimeout(rebuildTimeout); rebuildTimeout = null; } + isRebuilding = false; + rebuildQueued = false; + + // Reload config + config = await loadConfig(configPathOption, { isDev: true, quiet: true }); + paths = resolveConfigPaths(config); + state.outputDir = paths.outputDir; + + if (workerPool) await workerPool.terminateAll(); + const workerScript = path.resolve(__dirname, '../engine/worker-parser.js'); + workerPool = new WorkerPool(workerScript, { config, cwd: CWD }); + + // Full rebuild + await buildSite(configPathOption, { + isDev: true, + preserve: options.preserve, + quiet: true, + workerPool + }); + + lastConfigRebuildAt = Date.now(); + // Reset the signature tracker: after a full rebuild the file + // mtimes on disk may have shifted, and we want the next user edit + // to be detected as a fresh change rather than filtered as a + // phantom duplicate. + signatureTracker.reset(); + TUI.step(`Config reloaded and rebuilt in ${configElapsed()}`, 'DONE', TUI.blue, true); + + // Re-setup watchers after the longer config quiet window so any + // macOS phantom events from the build settle before we start + // listening again. + setTimeout(() => { + setupContentWatchers(); + setupConfigWatcher(); + configLock = false; + }, CONFIG_QUIET_MS); + + broadcastReload(); + } catch (error: any) { + TUI.step(`Config reload: ${baseName}`, 'FAIL', TUI.blue, true); + TUI.error('Config reload failed', error.message); + + // Re-setup watchers to continue listening. Use the same longer config + // quiet window so phantom events fired during the failed reload + // settle before we start listening again. + setTimeout(() => { + setupContentWatchers(); + setupConfigWatcher(); + configLock = false; + }, CONFIG_QUIET_MS); + } + } + + function setupContentWatchers() { + const contentPaths = [paths.srcDirToWatch]; + if (nativeFs.existsSync(paths.userAssetsDir)) contentPaths.push(paths.userAssetsDir); + + if (process.env.DOCMD_DEV === 'true') { + const DOCMD_ROOT = path.resolve(__dirname, '..'); + contentPaths.push( + path.join(DOCMD_ROOT, 'templates'), + path.join(DOCMD_ROOT, 'assets'), + path.join(DOCMD_ROOT, 'engine'), + path.join(DOCMD_ROOT, 'plugins'), + path.join(DOCMD_ROOT, 'utils') + ); + } + + // Resolved output dir โ€” used for robust exclusion below + const resolvedOut = path.resolve(CWD, paths.outputDir); + + for (const watchPath of contentPaths) { + if (!nativeFs.existsSync(watchPath)) continue; + + const watcher = nativeFs.watch(watchPath, { recursive: true }, (event, filename) => { + if (!filename) return; + + // Post-rebuild quiet period: swallow stale fs.watch events + if (Date.now() - lastContentRebuildAt < CONTENT_QUIET_MS) return; + if (Date.now() - lastConfigRebuildAt < CONFIG_QUIET_MS) return; + + const filePath = path.resolve(watchPath, filename); + + // Exclude build output dir (absolute path check โ€” reliable across platforms) + if (filePath.startsWith(resolvedOut + path.sep) || filePath === resolvedOut) return; + + // Content-signature gate: ignore phantom events that don't actually + // mutate the file (Spotlight reindex, iCloud sync, Time Machine, + // macOS metadata reads, etc.). This is the primary defence. + if (!signatureTracker.hasChanged(filePath)) return; + + // Common noise exclusions + if ( + filename.includes('.git') || + filename.includes('node_modules') || + filename.startsWith('.') || + filename.includes('.DS_Store') + ) return; + + const relativeFilePath = path.relative(CWD, filePath); + const isAsset = filePath.startsWith(path.resolve(paths.userAssetsDir)); + const isConfigOrNav = + filename.includes('navigation.json') || + (filename.includes('docmd.config') && !filename.includes('docmd.config-')); + + if (isConfigOrNav) { + // Debounce config/nav reloads separately to collapse macOS multi-fire + if (configDebounce) clearTimeout(configDebounce); + configDebounce = setTimeout(() => { + configDebounce = null; + reloadConfigAndRebuild(filePath); + }, 400); + return; + } + + // Debounce: wait until user stops making changes before rebuilding. + // Each new save resets this timer, so the build only runs after + // the last change โ€” like Vite's approach. + if (rebuildTimeout) clearTimeout(rebuildTimeout); + rebuildTimeout = setTimeout(() => { + const executeBuildFn = async () => { + if (isRebuilding) { rebuildQueued = true; return; } + + const rebuildElapsed = TUI.timer(); + const sp = TUI.spinner(`Rebuilding: ${relativeFilePath}`, TUI.blue); + isRebuilding = true; + rebuildQueued = false; + try { + await buildSite(configPathOption, { + isDev: true, + preserve: options.preserve, + quiet: true, + targetFiles: isAsset ? undefined : [filePath], + workerPool + }); + lastContentRebuildAt = Date.now(); + sp.done(`Rebuilt: ${relativeFilePath} in ${rebuildElapsed()}`, true); + broadcastReload(); + } catch (error: any) { + sp.fail(`Rebuild: ${relativeFilePath}`, true); + TUI.error('Rebuild failed', error.message); + } finally { + isRebuilding = false; + if (rebuildQueued) executeBuildFn(); + } + }; + executeBuildFn(); + }, 600); // 600ms: rebuild fires 600ms after user stops saving + }); + watchers.push(watcher); + } + } + + const setupConfigWatcher = () => { + if (!hasConfigFile) return; + let cfgDebounce: any = null; + // Watch the config's parent directory, not the file directly โ€” fs.watch + // on a single file is the worst case on macOS and fires phantom events + // from Spotlight / iCloud / Time Machine. Watching a directory and + // filtering to our basename is dramatically more stable. + const watchDir = path.dirname(configWatchPath); + const configBaseName = path.basename(configWatchPath); + + const configWatcher = nativeFs.watch(watchDir, (event, filename) => { + if (!filename) return; + // Only react to our specific config file (filter out sibling writes) + if (filename !== configBaseName) return; + + // Post-rebuild quiet period: a config reload closes+reopens + // watchers, so any phantom events that fired during the rebuild are + // already swallowed. This covers the brief window after reopen. + if (Date.now() - lastConfigRebuildAt < CONFIG_QUIET_MS) return; + + // Content-signature gate: ignore phantom events that don't actually + // mutate the file. This is the primary defence โ€” without it, a + // single Spotlight reindex every few seconds would trigger a full + // site rebuild indefinitely. + if (!signatureTracker.hasChanged(configWatchPath)) return; + + // Debounce: collapse the 3-6 rapid events macOS fires per save into one + if (cfgDebounce) clearTimeout(cfgDebounce); + cfgDebounce = setTimeout(() => { + cfgDebounce = null; + reloadConfigAndRebuild(configWatchPath); + }, 500); + }); + watchers.push(configWatcher); + }; + + setupContentWatchers(); + setupConfigWatcher(); + + // Server Startup Logic + const PORT = parseInt(options.port || process.env.PORT || 3000, 10); + // Phase 1.D: default to loopback. Set DOCMD_HOST=0.0.0.0 to expose on LAN + // (with the verifyClient callback below still guarding the Origin header). + const BIND_HOST = process.env.DOCMD_HOST || '127.0.0.1'; + + function tryStartServer(port) { + server.listen(port, BIND_HOST) + .once('listening', async () => { + if (BIND_HOST !== '127.0.0.1' && BIND_HOST !== '::1' && BIND_HOST !== 'localhost') { + TUI.warn(`Dev server bound to ${BIND_HOST} (LAN). Any host able to reach this port can connect; verifyClient guards Origin.`); + } + // Phase 1.D: CWE-1385 CSWSH fix (N-S1). verifyClient validates the + // Origin header against the loopback allowlist before accepting the + // WebSocket handshake. + wss = new WebSocketServer({ + server, + verifyClient: createOriginVerify(), + }); + wss.on('error', (e: any) => TUI.error('WebSocket Error', e.message)); + + // Action dispatcher for plugin actions/events + await loadPlugins(config, { resolvePaths: [__dirname] }); + const dispatcher = createActionDispatcher(hooks, { + projectRoot: CWD, + config, + broadcast: (event: string, data: any) => { + wss.clients.forEach((client: any) => { + if (client.readyState === WebSocket.OPEN) { + client.send(JSON.stringify({ type: 'event', name: event, data })); + } + }); + } + }); + + // Execute onDevServerReady hooks + for (const fn of hooks.onDevServerReady) { + await fn(server, wss); + } + + wss.on('connection', (ws: any) => { + ws.on('message', async (raw: any) => { + let msg: any; + try { msg = JSON.parse(raw.toString()); } catch { return; } + + if (msg.type === 'call') { + try { + const { result } = await dispatcher.handleCall(msg.action, msg.payload); + // Don't send reload flag to client - let the file watcher detect + // the change, rebuild, and send the reload via broadcastReload() + ws.send(JSON.stringify({ id: msg.id, type: 'response', result, reload: false })); + } catch (e: any) { + ws.send(JSON.stringify({ id: msg.id, type: 'response', error: e.message })); + } + } else if (msg.type === 'event') { + dispatcher.handleEvent(msg.name, msg.data); + } + }); + }); + + const indexHtmlPath = path.join(paths.outputDir, 'index.html'); + const networkIp = getNetworkIp(); + const localUrl = `http://127.0.0.1:${port}`; + const networkUrl = networkIp ? `http://${networkIp}:${port}` : null; + + TUI.section('Development Server Running', TUI.green); + TUI.item('', '', TUI.dim, TUI.green); + TUI.item('Local Access', localUrl, TUI.bold, TUI.green); + if (networkUrl) { + TUI.item('Network Access', networkUrl, TUI.bold, TUI.green); + } + TUI.item('Serving from', formatPathForDisplay(paths.outputDir, CWD), TUI.dim, TUI.green); + // Show engine + locale/version summary โ€” same details build shows (N-23). + const devDetails = TUI.extractProjectDetails(config, paths.outputDir, CWD); + if (devDetails.engine) TUI.item('Engine', devDetails.engine === 'rust' ? 'rust (preview)' : devDetails.engine, TUI.dim, TUI.green); + if (devDetails.versions) TUI.item('Versions', `${devDetails.versions.count} (${devDetails.versions.labels})`, TUI.dim, TUI.green); + if (devDetails.locales) TUI.item('Locales', `${devDetails.locales.count} (${devDetails.locales.labels})`, TUI.dim, TUI.green); + TUI.item('','', TUI.dim, TUI.green); + TUI.footer(TUI.green); + + if (!await fs.pathExists(path.join(paths.outputDir, 'index.html'))) { + TUI.warn('Root index.html not found. Build may be incomplete.'); + } + + // Auto-launch localhost URL in default browser + openBrowser(localUrl); + }) + .once('error', (err: any) => { + if (err.code === 'EADDRINUSE') { + server.close(); + tryStartServer(port + 1); + } else { + TUI.error('Failed to start server', err.message); + process.exit(1); + } + }); + } + + // Execution Flow + (async () => { + const finalPort = await findAvailablePort(PORT); + tryStartServer(finalPort); + })(); + + let isShuttingDown = false; + + // Suppress ^C display and handle graceful shutdown + if (process.stdin.isTTY) { + process.stdin.setRawMode(true); + process.stdin.resume(); + process.stdin.on('data', (data) => { + // Ctrl+C = 0x03 + if (data[0] === 0x03) { + process.emit('SIGINT' as any); + } + }); + } + + // M-11: extracted graceful-shutdown logic so both SIGINT and SIGTERM + // run the same cleanup. Previously SIGTERM called process.exit(0) + // directly, which bypassed the watchers / wss / server / workerPool + // shutdown path and could leave child processes or live sockets + // hanging. + async function gracefulShutdown() { + if (isShuttingDown) return; + isShuttingDown = true; + + if (process.stdin.isTTY) process.stdin.setRawMode(false); + + TUI.success('Shutting down...\n'); + + // Force exit after a shorter timeout if graceful shutdown hangs + const forceExitTimeout = setTimeout(() => { + process.exit(0); + }, 500); + forceExitTimeout.unref(); + + try { + const closures: any[] = []; + watchers.forEach(w => closures.push(new Promise(resolve => { w.close(); resolve(); }))); + if (wss) closures.push(new Promise(resolve => wss.close(resolve))); + if (server) closures.push(new Promise(resolve => server.close(resolve))); + if (workerPool) closures.push(workerPool.terminateAll()); + + await Promise.all(closures); + clearTimeout(forceExitTimeout); + process.exit(0); + } catch { + process.exit(0); + } + } + + process.on('SIGINT', gracefulShutdown); + process.on('SIGTERM', gracefulShutdown); +} \ No newline at end of file diff --git a/packages/core/src/commands/doctor.ts b/packages/core/src/commands/doctor.ts new file mode 100644 index 0000000..7657352 --- /dev/null +++ b/packages/core/src/commands/doctor.ts @@ -0,0 +1,329 @@ +/** + * -------------------------------------------------------------------- + * docmd doctor : pre-flight check command. + * + * Walks the user's config, checks every configured plugin and template + * against the official registry, and prints a single status report. No + * filesystem writes, no build side-effects โ€” purely a diagnostic tool. + * + * Flags: + * --fix Auto-install missing official plugins/templates. + * --json Emit the report as JSON (for tooling). + * --config Path to docmd.config (defaults to the same search the + * build commands use). + * + * Exit codes: + * 0 โ€” every check passed (or --fix resolved everything). + * 1 โ€” at least one problem remains (missing plugin, version mismatch, + * broken manifest). + * 2 โ€” usage error. + * -------------------------------------------------------------------- + */ + +import path from 'node:path'; +import fs from 'node:fs'; +import { createRequire } from 'node:module'; +import { fileURLToPath } from 'node:url'; +import { TUI } from '@docmd/tui'; +import { loadConfig } from '../utils/config-loader.js'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); + +interface PluginReport { + name: string; + status: 'ok' | 'missing' | 'mismatch' | 'third-party' | 'unknown'; + declaredVersion?: string; + installedVersion?: string; + fixable: boolean; + hint?: string; +} + +interface DoctorReport { + config: string | null; + core: { name: string; version: string; status: 'ok' | 'missing' }; + plugins: PluginReport[]; + template?: { requested: string; resolved: string; status: 'ok' | 'missing' }; + engines: Array<{ name: string; status: 'ok' | 'missing' | 'unknown' }>; + autoInstallCandidates: string[]; + warnings: string[]; + errors: string[]; +} + +interface DoctorOptions { + configPath?: string; + fix: boolean; + json: boolean; +} + +export async function runDoctor(opts: DoctorOptions): Promise { + // 1. Resolve the config. + const configPath = opts.configPath ? path.resolve(opts.configPath) : null; + let config: any = {}; + let configError: string | null = null; + if (configPath) { + try { + const loaded = await loadConfig(configPath); + config = loaded?.config || loaded || {}; + } catch (e: any) { + configError = e.message; + } + } else { + // loadConfig requires an explicit path; we don't have a built-in + // "find a config" helper yet. The user can re-run with --config. + configError = 'No config path provided. Use --config to point at docmd.config.{json,ts,js,mjs}.'; + } + + // 2. Build the report. + const report: DoctorReport = { + config: configPath, + core: { name: '@docmd/core', version: 'unknown', status: 'ok' }, + plugins: [], + engines: [], + autoInstallCandidates: [], + warnings: [], + errors: configError ? [configError] : [], + }; + + // 3. Check @docmd/core version. We try a chain of strategies so the + // doctor works in three real-world layouts: + // (a) a real user install โ€” `node_modules/@docmd/core/package.json` + // is reachable via standard `createRequire` resolution. + // (b) monorepo dev with a built dist โ€” the build output sits under + // `packages/core/dist/commands/`, and `import.meta.url` lets us + // derive the package root and read the in-tree `package.json`. + // (c) pnpm's symlinked `node_modules/@docmd/core` from inside the + // playground โ€” walk up from cwd and try every ancestor. + // + // If all strategies fail, we genuinely don't have `@docmd/core` on the + // resolve path; we report that rather than guessing. + report.core = resolveCorePackage(); + if (report.core.status === 'missing') { + report.errors.push('@docmd/core is not installed'); + } + + // 4. Check configured plugins. + const configuredPlugins: Record = (config.plugins || {}); + for (const [key, userOpts] of Object.entries(configuredPlugins)) { + if (userOpts === false) continue; + const pkgName = key.startsWith('@docmd/') ? key : `@docmd/plugin-${key}`; + const installed = tryReadPackage(pkgName); + if (installed) { + report.plugins.push({ + name: key, + status: 'ok', + installedVersion: installed.version, + fixable: false, + }); + } else { + report.plugins.push({ + name: key, + status: 'missing', + fixable: true, + hint: `Run \`docmd add ${key}\` or add "${pkgName}" to your dependencies.`, + }); + report.autoInstallCandidates.push(pkgName); + } + } + + // 5. Check the active template. + if (config.theme?.template) { + const tplName = String(config.theme.template).trim(); + const tplPkg = tplName.startsWith('@docmd/') ? tplName : `@docmd/template-${tplName}`; + const installed = tryReadPackage(tplPkg); + report.template = { + requested: tplName, + resolved: tplPkg, + status: installed ? 'ok' : 'missing', + }; + if (!installed) { + report.autoInstallCandidates.push(tplPkg); + } + } + + // 6. Check engines. (The JS engine ships with core; the Rust engine is optional.) + const requestedEngine = (config.engine || 'js').toLowerCase(); + report.engines.push({ name: 'js', status: 'ok' }); + if (requestedEngine === 'rust' || config.engines?.rust) { + const rustInstalled = tryReadPackage('@docmd/engine-rust'); + report.engines.push({ name: 'rust', status: rustInstalled ? 'ok' : 'missing' }); + } + + // 7. Optional auto-fix. + if (opts.fix && report.autoInstallCandidates.length > 0) { + const { execSync } = await import('node:child_process'); + const cwd = process.cwd(); + const pkgManager = detectPackageManager(cwd); + const cmd = `${pkgManager} add ${report.autoInstallCandidates.join(' ')}`; + try { + execSync(cmd, { stdio: 'inherit', cwd, timeout: 180000 }); + } catch (e: any) { + report.errors.push(`Auto-install failed: ${e.message}`); + } + } + + // 8. Emit. + if (opts.json) { + console.log(JSON.stringify(report, null, 2)); + } else { + printReport(report); + } + + return report.errors.length > 0 ? 1 : 0; +} + +function printReport(r: DoctorReport): void { + console.log(''); + console.log('โ”Œโ”€ docmd pre-flight check'); + console.log('โ”‚'); + console.log(`โ”‚ ${r.core.name.padEnd(28)} ${r.core.version.padEnd(10)} ${r.core.status === 'ok' ? TUI.green('โœ“ installed') : TUI.red('โœ— missing')}`); + console.log('โ”‚'); + console.log('โ”‚ Configured plugins (' + r.plugins.length + ')'); + for (const p of r.plugins) { + const sym = p.status === 'ok' ? TUI.green('โœ“') : p.status === 'missing' ? TUI.yellow('โš ') : TUI.dim('ยท'); + const ver = p.installedVersion ? ` (${p.installedVersion})` : ''; + console.log(`โ”‚ ${sym} ${p.name.padEnd(20)}${ver}${p.hint ? ' ' + TUI.dim(p.hint) : ''}`); + } + if (r.template) { + const sym = r.template.status === 'ok' ? TUI.green('โœ“') : TUI.yellow('โš '); + console.log(`โ”‚`); + console.log(`โ”‚ Template`); + console.log(`โ”‚ ${sym} ${r.template.resolved}${r.template.status === 'missing' ? ' ' + TUI.dim('not installed') : ''}`); + } + if (r.engines.length) { + console.log('โ”‚'); + console.log('โ”‚ Engines'); + for (const e of r.engines) { + const sym = e.status === 'ok' ? TUI.green('โœ“') : TUI.yellow('โš '); + console.log(`โ”‚ ${sym} ${e.name}`); + } + } + if (r.autoInstallCandidates.length) { + console.log('โ”‚'); + console.log('โ”‚ ' + TUI.yellow(`Auto-install candidates (${r.autoInstallCandidates.length})`) + ' โ€” run `docmd doctor --fix`'); + for (const c of r.autoInstallCandidates) { + console.log(`โ”‚ โ€ข ${c}`); + } + } + if (r.errors.length) { + console.log('โ”‚'); + console.log('โ”‚ ' + TUI.red('Errors')); + for (const e of r.errors) console.log(`โ”‚ ${e}`); + } + console.log('โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€'); + console.log(''); +} + +/** + * Resolve `@docmd/core`'s version with a chain of strategies. Returns + * `{ name, version, status: 'ok' }` on success, or + * `{ name, version: 'unknown', status: 'missing' }` if the package is + * genuinely not on the resolve path. + * + * Strategy order: + * 1. `createRequire(import.meta.url)` from the doctor file's URL โ€” + * this works for a real user install where the doctor runs from + * `node_modules/@docmd/core/dist/commands/doctor.js`. + * 2. Walk up from `process.cwd()` looking for a `node_modules/@docmd/core/package.json` + * โ€” this covers pnpm's symlinked layout from the playground and + * yarn's hoisted layout in monorepos. + * 3. Walk up from the doctor file's location looking for an in-tree + * `package.json` whose `name` is `@docmd/core` โ€” this covers the + * monorepo dev case where the dist files are run directly without + * being installed into a `node_modules` tree. + */ +function resolveCorePackage(): { name: string; version: string; status: 'ok' | 'missing' } { + const FAIL = { name: '@docmd/core', version: 'unknown', status: 'missing' as const }; + const SEARCH_NAMES = new Set(['@docmd/core', 'docmd']); + + // Strategy 1: createRequire from this file's URL. + try { + const req = createRequire(import.meta.url); + const pkg = req('@docmd/core/package.json'); + return { name: pkg.name, version: pkg.version, status: 'ok' }; + } catch { /* fall through */ } + + // Strategy 2: walk up from cwd looking for node_modules/@docmd/core/package.json. + for (let dir = process.cwd(); dir !== path.parse(dir).root; dir = path.dirname(dir)) { + const candidate = path.join(dir, 'node_modules', '@docmd', 'core', 'package.json'); + if (fs.existsSync(candidate)) { + try { + const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8')); + if (SEARCH_NAMES.has(pkg.name)) { + return { name: pkg.name, version: pkg.version, status: 'ok' }; + } + } catch { /* try next ancestor */ } + } + } + + // Strategy 3: walk up from the doctor file's location looking for an + // in-tree package.json whose name is @docmd/core. This is the monorepo + // dev case where the dist files are run directly without being installed + // into a node_modules tree. + let dir = __dirname; + while (dir !== path.parse(dir).root) { + const candidate = path.join(dir, 'package.json'); + if (fs.existsSync(candidate)) { + try { + const pkg = JSON.parse(fs.readFileSync(candidate, 'utf8')); + if (SEARCH_NAMES.has(pkg.name)) { + return { name: pkg.name, version: pkg.version, status: 'ok' }; + } + } catch { /* try next ancestor */ } + } + dir = path.dirname(dir); + } + + return FAIL; +} + +/** + * Read a package's `package.json` from any of the three strategies above. + * Used to detect configured plugins and engines. + */ +function tryReadPackage(name: string): { name: string; version: string } | null { + // Strategy 1: createRequire from this file's URL. + try { + const req = createRequire(import.meta.url); + const pkg = req(`${name}/package.json`); + return { name: pkg.name, version: pkg.version }; + } catch { /* fall through */ } + + // Strategy 2: walk up from cwd. + for (let dir = process.cwd(); dir !== path.parse(dir).root; dir = path.dirname(dir)) { + const candidate = path.join(dir, 'node_modules', ...name.split('/'), 'package.json'); + if (fs.existsSync(candidate)) { + try { + return JSON.parse(fs.readFileSync(candidate, 'utf8')); + } catch { /* try next ancestor */ } + } + } + + // Strategy 3: walk up from the doctor file's location. + let dir = __dirname; + while (dir !== path.parse(dir).root) { + const candidate = path.join(dir, 'node_modules', ...name.split('/'), 'package.json'); + if (fs.existsSync(candidate)) { + try { + return JSON.parse(fs.readFileSync(candidate, 'utf8')); + } catch { /* try next ancestor */ } + } + dir = path.dirname(dir); + } + + return null; +} + +function detectPackageManager(cwd: string): 'pnpm' | 'yarn' | 'bun' | 'npm' { + let dir = cwd; + const { existsSync } = require('node:fs') as typeof import('node:fs'); + const { join } = require('node:path') as typeof import('node:path'); + while (dir !== require('node:path').parse(dir).root) { + if (existsSync(join(dir, 'pnpm-lock.yaml'))) return 'pnpm'; + if (existsSync(join(dir, 'yarn.lock'))) return 'yarn'; + if (existsSync(join(dir, 'bun.lockb'))) return 'bun'; + if (existsSync(join(dir, 'package-lock.json'))) return 'npm'; + dir = require('node:path').dirname(dir); + } + return 'npm'; +} \ No newline at end of file diff --git a/packages/core/src/commands/init.ts b/packages/core/src/commands/init.ts new file mode 100644 index 0000000..0ee2c2c --- /dev/null +++ b/packages/core/src/commands/init.ts @@ -0,0 +1,426 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { TUI } from '@docmd/api'; +import { fsUtils as fs } from '@docmd/utils'; +import path from 'path'; +import readline from 'readline'; +import { createRequire } from 'module'; + +const require = createRequire(import.meta.url); +const { version } = require('../../package.json'); + +const defaultConfigContent = `{ + "title": "My Documentation", + "url": "https://docs.myproject.com", + "src": "docs", + "out": "site", + "engine": "js", + "layout": { + "spa": true, + "header": { + "enabled": true + }, + "sidebar": { + "collapsible": true, + "defaultCollapsed": false + }, + "optionsMenu": { + "position": "sidebar-top", + "components": { + "search": true, + "themeSwitch": true + } + }, + "footer": { + "style": "minimal", + "content": "ยฉ ${new Date().getFullYear()} My Project.", + "branding": true + } + }, + "theme": { + "name": "default", + "appearance": "system", + "codeHighlight": true + }, + "minify": true, + "autoTitleFromH1": true, + "copyCode": true, + "pageNavigation": true, + "navigation": [ + { "title": "Quick Start", "path": "/", "icon": "zap" }, + { "title": "Agent Skills", "path": "/skills/", "icon": "brain-circuit" }, + { + "title": "Quick Guide", + "icon": "book-open", + "collapsible": false, + "children": [ + { "title": "Install", "path": "https://docs.docmd.io/getting-started/installation/", "icon": "download", "external": true }, + { "title": "Configure", "path": "https://docs.docmd.io/configuration/overview/", "icon": "settings", "external": true }, + { "title": "Migrate", "path": "https://docs.docmd.io/migration/overview/", "icon": "arrow-left-right", "external": true }, + { "title": "Deploy", "path": "https://docs.docmd.io/deployment/", "icon": "rocket", "external": true } + ] + }, + { "title": "GitHub", "path": "https://github.com/docmd-io/docmd", "icon": "github", "external": true } + ], + "plugins": { + "git": { + "commitHistory": true, + "maxCommits": 5 + }, + "seo": { + "defaultDescription": "Documentation built with docmd." + } + } +} +`; + +const defaultIndexMdContent = `--- +title: "Quick Start" +description: "Welcome to your new documentation site." +--- + +# Quick Start Your Docs ๐Ÿš€ + +This is the home page of your new **docmd** project. You're currently viewing \`docs/index.md\` โ€” edit it, and your site updates. + +## Run the dev server + +\`\`\`bash +npx @docmd/core dev +\`\`\` + +Open \`http://localhost:3000\` โ€” the page auto-reloads as you edit. + +## Build for production + +\`\`\`bash +npx @docmd/core build +\`\`\` + +Output goes to \`site/\`. Deploy that folder anywhere that serves static files. + +## Project structure + +\`\`\`text +. +โ”œโ”€โ”€ docs/ # Your markdown content +โ”‚ โ””โ”€โ”€ index.md # You are here +โ”œโ”€โ”€ assets/ # Custom CSS, JS, and images +โ”œโ”€โ”€ docmd.config.json # Site configuration +โ””โ”€โ”€ package.json # Node dependencies + scripts +\`\`\` + +## Features + +### 1. Smart containers + +\`\`\`markdown +::: callout tip "Did you know?" +You can nest containers, add titles, and use icons. +::: + +::: card "Flexible" icon:layout-grid +Organise content with cards. + +[View the docs โ†’](https://docs.docmd.io){.docmd-button} +::: +\`\`\` + +Renders as a styled callout and a card with a button. + +### 2. Tabs and code + +\`\`\`\`markdown +::: tabs +== tab "JavaScript" icon:braces +\`\`\`javascript +console.log('Hello World'); +\`\`\` + +== tab "Python" icon:code +\`\`\`python +print('Hello World') +\`\`\` +::: +\`\`\`\` + +### 3. Built-in plugins + +docmd ships with these plugins enabled by default โ€” no install needed: + +- **Search** โ€” full-text + semantic search (optional) +- **Sitemap** + **SEO** meta tags +- **LLMs context** โ€” \`llms.txt\` and \`llms.json\` for AI agents +- **OKF** โ€” Open Knowledge Format bundle at \`site/okf/\` +- **Mermaid** diagrams +- **Git** last-modified timestamps +- **Math** (KaTeX) โ€” enable with \`docmd add math\` + +See the [full plugin list](https://docs.docmd.io/plugins/usage/). + +## Next steps + +- **[Install docmd](https://docs.docmd.io/getting-started/installation/)** +- **[Configure your site](https://docs.docmd.io/configuration/overview/)** +- **[Browse templates](https://docs.docmd.io/theming/templates/)** +- **[Deploy to production](https://docs.docmd.io/deployment/)** +- **[GitHub repo](https://github.com/docmd-io/docmd/)** + +Happy documenting! ๐ŸŽ‰`; + +const defaultSkillsMdContent = `--- +title: "Agent Skills" +description: "Teach AI coding agents to work with docmd projects" +--- + +# Agent Skills + +docmd ships a **modular skill set** for AI coding agents (Claude Code, Cursor, Windsurf, Copilot, etc.). The skills teach your agent the \`docmd\` CLI, configuration, plugin system, and the \`docmd mcp\` server โ€” so it can build, configure, validate, and deploy sites for you. + +## What gets installed + +The [\`docmd-skills\`](https://www.npmjs.com/package/docmd-skills) npm package contains three skill modules: + +| Skill | When your agent loads it | +|---|---| +| **\`docmd-skills\`** | A docmd **site operator**. Knows the \`npx @docmd/core\` CLI, \`docmd.config.json\`, plugins, themes, deployment, and the \`docmd mcp\` server. | +| **\`docmd-dev\`** | A docmd **framework contributor**. Knows the monorepo layout, how to author plugins and templates, the JS / Rust engine loaders, and the public Node API (\`EngineLoader\`, \`createActionDispatcher\`, \`TemplateSlot\`). | +| **\`docmd-writer\`** | A **multi-language documentation writer**. Drafts and reviews prose in any language, with SEO awareness and docmd's markdown conventions (containers, frontmatter, file-title rule). | + +## Install + +Pick the directory your agent reads skills from and run **one** command: + +### Claude Code + +\`\`\`bash +npx docmd-skills ~/.claude/skills +\`\`\` + +### Cursor + +\`\`\`bash +npx docmd-skills ~/.cursor/skills +\`\`\` + +### Project-local (any agent) + +\`\`\`bash +npx docmd-skills ./.skills +\`\`\` + +After install, the \`docmd-skills\`, \`docmd-dev\`, and \`docmd-writer\` modules are available to your agent. + +Run \`npx docmd-skills --help\` for the full list of commands. + +## How it works at runtime + +Once installed, your agent automatically loads the right skill based on the files in scope: + +- When you ask "add a plugin to my docmd site" โ†’ \`docmd-skills\` loads +- When you ask "add a new template" inside the cloned \`docmd-io/docmd\` monorepo โ†’ \`docmd-dev\` loads +- When you ask "write the intro for my new docs" โ†’ \`docmd-writer\` loads + +## Update or remove + +The CLI is idempotent โ€” running it again updates the skills to latest: + +\`\`\`bash +npx docmd-skills # updates all three +npx docmd-skills remove # deletes all three +\`\`\` +`; + +const defaultPackageJson = { + name: "my-docs", + version: "0.0.1", + private: true, + type: "module", + scripts: { + "dev": "docmd dev", + "build": "docmd build", + "preview": "npx serve site" + }, + dependencies: { + "@docmd/core": `^${version}` + } +}; + +export async function initProject(opts: { force?: boolean; yes?: boolean } = {}) { + const baseDir = process.cwd(); + const packageJsonFile = path.join(baseDir, 'package.json'); + const configFile = path.join(baseDir, 'docmd.config.json'); + const docsDir = path.join(baseDir, 'docs'); + const indexMdFile = path.join(docsDir, 'index.md'); + const skillsMdFile = path.join(docsDir, 'skills.md'); + const skillFile = path.join(baseDir, 'SKILL.md'); + const assetsDir = path.join(baseDir, 'assets'); + const assetsCssDir = path.join(assetsDir, 'css'); + const assetsJsDir = path.join(assetsDir, 'js'); + const assetsImagesDir = path.join(assetsDir, 'images'); + + const existingFiles = []; + const dirExists = { + docs: false, + assets: false + }; + + TUI.section('Project Setup'); + + // Check if package.json exists + if (!await fs.pathExists(packageJsonFile)) { + await fs.writeJson(packageJsonFile, defaultPackageJson, { spaces: 2 }); + TUI.step('Created package.json', 'DONE'); + } else { + TUI.step('Using existing package.json', 'SKIP'); + } + + // Check each configuration file variant individually + if (await fs.pathExists(configFile)) { + existingFiles.push('docmd.config.json'); + } + const jsConfigFile = path.join(baseDir, 'docmd.config.js'); + if (await fs.pathExists(jsConfigFile)) { + existingFiles.push('docmd.config.js'); + } + const tsConfigFile = path.join(baseDir, 'docmd.config.ts'); + if (await fs.pathExists(tsConfigFile)) { + existingFiles.push('docmd.config.ts'); + } + + // Check for the legacy config.js + const oldConfigFile = path.join(baseDir, 'config.js'); + if (await fs.pathExists(oldConfigFile)) { + existingFiles.push('config.js'); + } + + // Check if docs directory exists + if (await fs.pathExists(docsDir)) { + dirExists.docs = true; + if (await fs.pathExists(indexMdFile)) { + existingFiles.push('docs/index.md'); + } + if (await fs.pathExists(skillsMdFile)) { + existingFiles.push('docs/skills.md'); + } + } + + // Check if assets directory exists + if (await fs.pathExists(assetsDir)) { + dirExists.assets = true; + } + + // Determine if we should override existing files + let shouldOverride = !!opts.force; + if (existingFiles.length > 0 && !shouldOverride) { + TUI.warn('Existing files detected:'); + existingFiles.forEach(file => TUI.item('', file)); + + // In a non-interactive environment (CI, piped input, Docker without -it, + // npx with no TTY), skip the prompt. Default to "no" for safety unless + // --yes is passed. + const isInteractive = !!process.stdin.isTTY; + if (!isInteractive) { + if (opts.yes) { + shouldOverride = true; + TUI.dim(' (non-interactive mode + --yes: overriding existing files)'); + } else { + shouldOverride = false; + TUI.dim(' (non-interactive mode: keeping existing files. Pass --force to override.)'); + } + } else { + const rl = readline.createInterface({ + input: process.stdin, + output: process.stdout + }); + + const answer = await new Promise(resolve => { + rl.question(`\n ${TUI.bold('Do you want to override these files?')} (y/N): `, resolve); + }); + + rl.close(); + + shouldOverride = (answer as string).toLowerCase() === 'y'; + } + + if (!shouldOverride) { + TUI.step('Maintaining existing files', 'SKIP'); + } + } else if (existingFiles.length > 0 && shouldOverride) { + TUI.warn(`Overriding ${existingFiles.length} existing file(s) (--force)`); + } + + // Create docs directory if it doesn't exist + if (!dirExists.docs) { + await fs.ensureDir(docsDir); + TUI.step('Created docs/ directory', 'DONE'); + } else { + TUI.step('Using existing docs/ directory', 'SKIP'); + } + + // Create assets directory structure if it doesn't exist + if (!dirExists.assets) { + await fs.ensureDir(assetsDir); + await fs.ensureDir(assetsCssDir); + await fs.ensureDir(assetsJsDir); + await fs.ensureDir(assetsImagesDir); + TUI.step('Created assets/ infrastructure', 'DONE'); + } else { + TUI.step('Using existing assets/ directory', 'SKIP'); + if (!await fs.pathExists(assetsCssDir)) await fs.ensureDir(assetsCssDir); + if (!await fs.pathExists(assetsJsDir)) await fs.ensureDir(assetsJsDir); + if (!await fs.pathExists(assetsImagesDir)) await fs.ensureDir(assetsImagesDir); + } + + // Write config file if it doesn't exist or user confirmed override + if (!await fs.pathExists(configFile) && !await fs.pathExists(jsConfigFile) && !await fs.pathExists(tsConfigFile) || shouldOverride) { + await fs.writeFile(configFile, defaultConfigContent, 'utf8'); + TUI.step(`${shouldOverride ? 'Updated' : 'Created'} docmd.config.json`, 'DONE'); + } else { + TUI.step('Using existing configuration', 'SKIP'); + } + + // Write index.md file if it doesn't exist or user confirmed override + if (!await fs.pathExists(indexMdFile)) { + await fs.writeFile(indexMdFile, defaultIndexMdContent, 'utf8'); + TUI.step('Created docs/index.md', 'DONE'); + } else if (shouldOverride) { + await fs.writeFile(indexMdFile, defaultIndexMdContent, 'utf8'); + TUI.step('Updated docs/index.md', 'DONE'); + } else { + TUI.step('Using existing docs/index.md', 'SKIP'); + } + + // Write skills.md (the Agent Skills docs page) if it doesn't exist or user confirmed override + if (!await fs.pathExists(skillsMdFile)) { + await fs.writeFile(skillsMdFile, defaultSkillsMdContent, 'utf8'); + TUI.step('Created docs/skills.md', 'DONE'); + } else if (shouldOverride) { + await fs.writeFile(skillsMdFile, defaultSkillsMdContent, 'utf8'); + TUI.step('Updated docs/skills.md', 'DONE'); + } else { + TUI.step('Using existing docs/skills.md', 'SKIP'); + } + + // Write SKILL.md if it doesn't exist or user confirmed override + if (!await fs.pathExists(skillFile) || shouldOverride) { + TUI.dim(' Run `npx docmd-skills ` to install the full agent skill set.'); + } else { + TUI.step('Using existing SKILL.md', 'SKIP'); + } + + TUI.footer(); + TUI.success('Initialisation complete. Run `npm install` to setup dependencies.'); +} \ No newline at end of file diff --git a/packages/core/src/commands/live.ts b/packages/core/src/commands/live.ts new file mode 100644 index 0000000..8266795 --- /dev/null +++ b/packages/core/src/commands/live.ts @@ -0,0 +1,37 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { createRequire } from 'module'; + +const _require = createRequire(import.meta.url); + +import { fsUtils as fs } from '@docmd/utils'; +import path from 'path'; +import { TUI } from '@docmd/api'; + +export async function buildLive(options: any = {}) { + // Delegate to the standalone package + const livePkg = await import('@docmd/live'); + + // If explicitly asked NOT to serve (for testing), just build + if (options.serve === false) { + TUI.section('Building Live Editor'); + TUI.step('Compiling standalone runtime', 'WAIT'); + await livePkg.build(process.cwd()); + TUI.footer(); + } else { + // Default behavior: Build + Serve + await livePkg.start(); + } +} \ No newline at end of file diff --git a/packages/core/src/commands/mcp.ts b/packages/core/src/commands/mcp.ts new file mode 100644 index 0000000..fbc084c --- /dev/null +++ b/packages/core/src/commands/mcp.ts @@ -0,0 +1,558 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import readline from 'readline'; +import fs from 'fs'; +import path from 'path'; +import { buildSite } from './build.js'; +import { loadConfig } from '../utils/config-loader.js'; +import { safePath, asUserPath } from '@docmd/utils'; + +const pkgUrl = new URL('../../package.json', import.meta.url); +const { version } = JSON.parse(fs.readFileSync(pkgUrl, 'utf-8')); + +// Helpers to find and search markdown files +function findMarkdownFiles(dir: string): string[] { + const results: string[] = []; + try { + const list = fs.readdirSync(dir); + for (const file of list) { + const fullPath = path.join(dir, file); + const stat = fs.statSync(fullPath); + if (stat && stat.isDirectory()) { + if (file !== 'node_modules' && !file.startsWith('.')) { + results.push(...findMarkdownFiles(fullPath)); + } + } else if (file.endsWith('.md') || file.endsWith('.markdown')) { + results.push(fullPath); + } + } + } catch { /* ignore filesystem errors */ } + return results; +} + +export function validateLinks(docsDir: string): { file: string; line: number; link: string; error: string }[] { + const errors: { file: string; line: number; link: string; error: string }[] = []; + if (!fs.existsSync(docsDir)) return errors; + + const mdFiles = findMarkdownFiles(docsDir); + + for (const filePath of mdFiles) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + const lines = content.split('\n'); + const relativeFile = path.relative(process.cwd(), filePath); + + lines.forEach((lineText, lineIdx) => { + const lineNum = lineIdx + 1; + const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g; + let match; + while ((match = linkRegex.exec(lineText)) !== null) { + const linkTarget = match[2].trim().split('#')[0]; // strip anchors + if (!linkTarget) continue; + + // Skip external, anchors, mailto, etc. + if ( + linkTarget.startsWith('http://') || + linkTarget.startsWith('https://') || + linkTarget.startsWith('mailto:') || + linkTarget.startsWith('tel:') || + linkTarget.startsWith('#') + ) { + continue; + } + + // Resolve link relative to file's directory + let resolvedPath = ''; + if (linkTarget.startsWith('/')) { + resolvedPath = path.join(docsDir, linkTarget); + } else { + resolvedPath = path.resolve(path.dirname(filePath), linkTarget); + } + + // Phase 3 PR 3.C (M-1): strip trailing slash before the + // `.md` / `.markdown` / `index.*` existence checks. Most + // markdown editors add a trailing slash to internal links + // (e.g. `[page 2](/page-2/)`), and the previous code did + // `fs.existsSync('docs/page-2/.md')` which is always false. + // The build itself produces `page-2/index.html` and treats + // the trailing-slash and no-slash forms as the same link, + // so the validator MUST agree or it false-positives every + // valid link. + const stripped = resolvedPath.endsWith('/') && resolvedPath.length > 1 + ? resolvedPath.slice(0, -1) + : resolvedPath; + + const exists = + fs.existsSync(stripped) || + fs.existsSync(stripped + '.md') || + fs.existsSync(stripped + '.markdown') || + fs.existsSync(path.join(stripped, 'index.md')) || + fs.existsSync(path.join(stripped, 'index.markdown')); + + if (!exists) { + errors.push({ + file: relativeFile, + line: lineNum, + link: linkTarget, + error: `Broken link: target resolved to ${path.relative(process.cwd(), resolvedPath)} does not exist` + }); + } + } + }); + } catch { /* ignore read errors */ } + } + + return errors; +} + +export async function runMcpServer() { + console.error("docmd MCP server starting..."); + + const rl = readline.createInterface({ + input: process.stdin, + output: undefined, + terminal: false + }); + + const sendResponse = (id: any, result: any) => { + process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, result }) + "\n"); + }; + + const sendError = (id: any, code: number, message: string, data?: any) => { + process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, error: { code, message, data } }) + "\n"); + }; + + rl.on('line', async (line) => { + if (!line.trim()) return; + try { + const message = JSON.parse(line); + if (message.jsonrpc !== "2.0") { + sendError(message.id || null, -32600, "Invalid Request"); + return; + } + + const { method, params, id } = message; + + if (method === "initialize") { + sendResponse(id, { + protocolVersion: "2025-03-26", + capabilities: { + resources: {}, + tools: {}, + prompts: {} + }, + serverInfo: { + name: "docmd-mcp-server", + version + } + }); + return; + } + + if (method === "notifications/initialized" || method === "initialized") { + // Notification, no response needed + return; + } + + if (method === "ping") { + sendResponse(id, {}); + return; + } + + // Handle Prompts Listing + // The prompts capability is declared in initialize for forward + // compatibility. docmd ships no built-in prompts yet, so return an + // empty list rather than leaving the client to hit an unhandled-method error. + if (method === "prompts/list") { + sendResponse(id, { prompts: [] }); + return; + } + + // Handle Tools Listing + if (method === "tools/list") { + sendResponse(id, { + tools: [ + { + name: "search_docs", + description: "Search the documentation content for a specific query.", + inputSchema: { + type: "object", + properties: { + query: { type: "string", description: "The term or phrase to search for." } + }, + required: ["query"] + } + }, + { + name: "list_docs", + description: "List all documentation files in the project. Returns relative paths so the agent can navigate the docs structure before reading individual files.", + inputSchema: { + type: "object", + properties: { + subdir: { type: "string", "description": "Optional subdirectory to scope the listing (e.g. 'en', 'v1', 'guides'). Defaults to the configured source directory root." } + } + } + }, + { + name: "read_doc", + description: "Read the raw markdown content of a documentation file.", + inputSchema: { + type: "object", + properties: { + route: { type: "string", description: "Relative path to the markdown file from root (e.g. docs/getting-started.md)." } + }, + required: ["route"] + } + }, + { + name: "get_config", + description: "Retrieve the resolved docmd project configuration (docmd.config.json). Exposes the source directory, output directory, configured locales, versions, and enabled plugins so the agent understands the project structure.", + inputSchema: { + type: "object", + properties: {} + } + }, + { + name: "validate_docs", + description: "Validates and lints all local markdown links to detect broken paths.", + inputSchema: { + type: "object", + properties: {} + } + }, + { + name: "get_llms_context", + description: "Retrieve the unified prompt context of the entire documentation site (llms.txt content).", + inputSchema: { + type: "object", + properties: {} + } + } + ] + }); + return; + } + + // Handle Resources Listing + if (method === "resources/list") { + sendResponse(id, { + resources: [ + { + uri: "docmd://context/llms.txt", + name: "llms.txt Context", + mimeType: "text/plain", + description: "Unified text context containing the entire documentation site" + }, + { + uri: "docmd://context/skill", + name: "Agent SKILL.md", + mimeType: "text/markdown", + description: "Instruction manual and skills reference for docmd" + } + ] + }); + return; + } + + // Handle Resources Read + if (method === "resources/read") { + const { uri } = params || {}; + if (!uri) { + sendResponse(id, { content: [{ type: "text", text: "Error: URI parameter is required." }] }); + return; + } + + let config: any; + try { + config = await loadConfig('docmd.config.js', { quiet: true }); + } catch { + config = { src: 'docs', out: 'site' }; + } + + if (uri === "docmd://context/llms.txt") { + const llmsFullFile = path.resolve(process.cwd(), config.out || 'site', 'llms-full.txt'); + if (fs.existsSync(llmsFullFile)) { + try { + const fullContext = fs.readFileSync(llmsFullFile, 'utf8'); + sendResponse(id, { + contents: [{ + uri, + mimeType: "text/plain", + text: fullContext + }] + }); + } catch (err: any) { + sendResponse(id, { content: [{ type: "text", text: `Error reading context file: ${err.message}` }] }); + } + } else { + sendResponse(id, { content: [{ type: "text", text: "Error: llms-full.txt context file has not been generated." }] }); + } + return; + } + + if (uri === "docmd://context/skill") { + const skillFile = path.resolve(process.cwd(), 'SKILL.md'); + let content = ''; + if (fs.existsSync(skillFile)) { + try { + content = fs.readFileSync(skillFile, 'utf8'); + } catch (err: any) { + sendResponse(id, { content: [{ type: "text", text: `Error reading SKILL.md: ${err.message}` }] }); + return; + } + } else { + content = [ + "---", + "name: docmd", + "description: Fallback agent instruction set for docmd.", + "skills: docmd-skills (npm)", + "docs: https://docs.docmd.io", + "llms-context: https://docs.docmd.io/llms-full.txt", + "---", + "", + "# docmd Agent Skills", + "", + "This project uses **docmd**, the zero-config AI-first documentation engine.", + "", + "## Get the full skill set (single-line install)", + "", + "Run this once per machine to install the full agent skill set into your agent's skills directory:", + "", + "```bash", + "npx docmd-skills ~/.claude/skills", + "```", + "", + "Replace `~/.claude/skills` with the directory your agent reads skills from: `~/.cursor/skills` (Cursor), `./.skills` (project-local), etc. Run `npx docmd-skills --help` for the full subcommand list. The single install command pulls in the `docmd-skills`, `docmd-dev`, and `docmd-writer` skill modules โ€” see https://github.com/docmd-io/docmd-skills for details.", + "", + "## Project-local override", + "This fallback content covers the general case. For project-specific instructions, create a `SKILL.md` at the root of the docmd project โ€” `docmd mcp`'s `get_skill` tool returns that local file in preference to this fallback." + ].join('\n'); + } + + sendResponse(id, { + contents: [{ + uri, + mimeType: "text/markdown", + text: content + }] + }); + return; + } + + sendError(id, -32602, `Resource not found: ${uri}`); + return; + } + + // Handle Tools Execution + if (method === "tools/call") { + const { name, arguments: args } = params; + + // Resolve workspace parameters + let config: any; + try { + config = await loadConfig('docmd.config.js', { quiet: true }); + } catch { + // Fallback zero config + config = { src: 'docs', out: 'site' }; + } + const docsDir = path.resolve(process.cwd(), config.src || 'docs'); + + if (name === "search_docs") { + const query = (args?.query || "").toLowerCase(); + if (!query) { + sendResponse(id, { content: [{ type: "text", text: "Error: Query parameter is required." }] }); + return; + } + + if (!fs.existsSync(docsDir)) { + sendResponse(id, { content: [{ type: "text", text: `Error: Source directory "${docsDir}" does not exist.` }] }); + return; + } + + const mdFiles = findMarkdownFiles(docsDir); + const matches: string[] = []; + + for (const filePath of mdFiles) { + try { + const fileContent = fs.readFileSync(filePath, 'utf8'); + const lines = fileContent.split('\n'); + const fileRelPath = path.relative(process.cwd(), filePath); + let foundInFile = false; + + lines.forEach((lineText, idx) => { + if (lineText.toLowerCase().includes(query)) { + if (!foundInFile) { + matches.push(`\n### File: ${fileRelPath}`); + foundInFile = true; + } + matches.push(`Line ${idx + 1}: ${lineText.trim()}`); + } + }); + } catch { /* ignore file errors */ } + } + + const textResult = matches.length > 0 + ? `Found search matches:\n${matches.join('\n')}` + : `No matches found for query: "${query}"`; + + sendResponse(id, { content: [{ type: "text", text: textResult }] }); + return; + } + + if (name === "list_docs") { + const subdir = (args?.subdir || "").trim(); + let listRoot = docsDir; + if (subdir) { + // CWE-22 guard: same safePath treatment as read_doc. + if (path.isAbsolute(subdir)) { + sendResponse(id, { content: [{ type: "text", text: `Error: Absolute paths are not allowed.` }] }); + return; + } + try { + listRoot = safePath(docsDir, asUserPath(subdir)); + } catch { + sendResponse(id, { content: [{ type: "text", text: `Error: Path "${subdir}" escapes the source directory.` }] }); + return; + } + } + if (!fs.existsSync(listRoot)) { + sendResponse(id, { content: [{ type: "text", text: `Error: Directory "${path.relative(process.cwd(), listRoot)}" does not exist.` }] }); + return; + } + const files = findMarkdownFiles(listRoot).map(f => path.relative(process.cwd(), f)); + const sorted = files.sort(); + const textResult = sorted.length > 0 + ? `Documentation files (${sorted.length}):\n${sorted.join('\n')}` + : `No markdown files found under "${path.relative(process.cwd(), listRoot)}".`; + sendResponse(id, { content: [{ type: "text", text: textResult }] }); + return; + } + + if (name === "get_config") { + try { + const resolvedConfig = await loadConfig('docmd.config.js', { quiet: true }); + // Surface only the structural keys an agent needs. Omit + // potentially sensitive values (API keys, analytics IDs) by + // reconstructing a safe summary from the resolved config. + const safeSummary: Record = { + title: resolvedConfig.title || 'Untitled', + src: resolvedConfig.src || 'docs', + out: resolvedConfig.out || 'site', + url: resolvedConfig.url || null, + theme: resolvedConfig.theme?.name || 'default', + i18n: resolvedConfig.i18n + ? { + default: resolvedConfig.i18n.default, + locales: (resolvedConfig.i18n.locales || []).map((l: any) => ({ id: l.id, label: l.label, dir: l.dir })) + } + : null, + versions: resolvedConfig.versions + ? { + current: resolvedConfig.versions.current, + all: (resolvedConfig.versions.all || []).map((v: any) => ({ id: v.id, dir: v.dir, label: v.label })) + } + : null, + plugins: resolvedConfig.plugins + ? Object.keys(resolvedConfig.plugins).map(k => ({ + name: k, + enabled: resolvedConfig.plugins[k] !== false + })) + : [] + }; + sendResponse(id, { content: [{ type: "text", text: JSON.stringify(safeSummary, null, 2) }] }); + } catch (err: any) { + sendResponse(id, { content: [{ type: "text", text: `Error loading config: ${err.message}\n\nThe project may be running in zero-config mode (source: ./docs, output: ./site).` }] }); + } + return; + } + + if (name === "read_doc") { + const route = args?.route || ""; + if (!route) { + sendResponse(id, { content: [{ type: "text", text: "Error: Route is required." }] }); + return; + } + // Phase 1.A: CWE-22 fix (S-3, T-S1). Reject absolute paths outright and + // require relative paths to resolve inside the project root (cwd) via safePath(). + // Preserves the pre-fix semantic where route was resolved against process.cwd(). + if (path.isAbsolute(route)) { + sendResponse(id, { content: [{ type: "text", text: `Error: Absolute paths are not allowed.` }] }); + return; + } + let resolvedFilePath: string; + try { + resolvedFilePath = safePath(process.cwd(), asUserPath(route)); + } catch (_e: any) { + sendResponse(id, { content: [{ type: "text", text: `Error: Path "${route}" escapes project root.` }] }); + return; + } + if (!fs.existsSync(resolvedFilePath)) { + sendResponse(id, { content: [{ type: "text", text: `Error: File not found at path "${route}".` }] }); + return; + } + + try { + const rawContent = fs.readFileSync(resolvedFilePath, 'utf8'); + sendResponse(id, { content: [{ type: "text", text: rawContent }] }); + } catch (err: any) { + sendResponse(id, { content: [{ type: "text", text: `Error reading file: ${err.message}` }] }); + } + return; + } + + if (name === "validate_docs") { + const errors = validateLinks(docsDir); + if (errors.length === 0) { + sendResponse(id, { content: [{ type: "text", text: "Documentation links validated successfully! No broken links found." }] }); + } else { + const errorReport = errors.map(e => `[${e.file}:${e.line}] -> ${e.link} (${e.error})`).join('\n'); + sendResponse(id, { content: [{ type: "text", text: `Validation errors found:\n${errorReport}` }] }); + } + return; + } + + if (name === "get_llms_context") { + // Trigger build to ensure context is up to date + try { + console.error("Building site context..."); + await buildSite('docmd.config.js', { quiet: true, isDev: false }); + } catch (err: any) { + console.error(`Build warning: ${err.message}`); + } + + const llmsFullFile = path.resolve(process.cwd(), config.out || 'site', 'llms-full.txt'); + if (fs.existsSync(llmsFullFile)) { + try { + const fullContext = fs.readFileSync(llmsFullFile, 'utf8'); + sendResponse(id, { content: [{ type: "text", text: fullContext }] }); + } catch (err: any) { + sendResponse(id, { content: [{ type: "text", text: `Error reading context file: ${err.message}` }] }); + } + } else { + sendResponse(id, { content: [{ type: "text", text: "Error: llms-full.txt context file has not been generated. Please make sure the build finishes successfully." }] }); + } + return; + } + + sendError(id, -32601, `Method not found: ${name}`); + return; + } + + sendError(id, -32601, `Method not found: ${method}`); + } catch (err: any) { + sendError(null, -32700, `Parse error: ${err.message}`); + } + }); +} \ No newline at end of file diff --git a/packages/core/src/commands/migrate.ts b/packages/core/src/commands/migrate.ts new file mode 100644 index 0000000..d20afc6 --- /dev/null +++ b/packages/core/src/commands/migrate.ts @@ -0,0 +1,676 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { fsUtils as fs } from '@docmd/utils'; +import path from 'path'; +import nativeFs from 'fs'; +import { TUI } from '@docmd/api'; + +function serializeConfig(obj: any) { + const json = JSON.stringify(obj, null, 2); + const cleanJs = json.replace(/"([^"]+)":/g, '$1:'); + return `export default ${cleanJs};\n`; +} + +export async function migrateProject(options: { docusaurus?: boolean; mkdocs?: boolean; vitepress?: boolean; starlight?: boolean; upgrade?: boolean; dryRun?: boolean }) { + const CWD = process.cwd(); + const dryRun = options.dryRun === true; + + const moveFilesToBackup = async (backupDir: string) => { + const backupName = path.basename(backupDir); + const files = await nativeFs.promises.readdir(CWD); + for (const file of files) { + // N-10: keep lockfiles and package manifests in place โ€” moving them + // into the backup dir means `npm install` and `pnpm install` + // would re-resolve from scratch on a recovery. Lockfiles and + // package.json are part of the user's repo state, not migration + // input. + if (file === 'node_modules' || file === '.git' || file === backupName || file === 'docmd.config.js') continue; + if (file === 'package.json' || file === 'package-lock.json' || file === 'yarn.lock' || file === 'pnpm-lock.yaml' || file === 'bun.lockb' || file === 'bun.lock') continue; + const oldPath = path.resolve(CWD, file); + const newPath = path.resolve(backupDir, file); + await nativeFs.promises.rename(oldPath, newPath); + } + }; + + /** + * Build the list of files that `moveFilesToBackup` would move. Used + * by `--dry-run` to show the user what would change without writing. + * Returns filenames (relative to CWD). + */ + const planBackupMoves = async (backupName: string): Promise => { + const files = await nativeFs.promises.readdir(CWD); + return files.filter((f) => + f !== 'node_modules' && + f !== '.git' && + f !== backupName && + f !== 'docmd.config.js' && + f !== 'package.json' && + f !== 'package-lock.json' && + f !== 'yarn.lock' && + f !== 'pnpm-lock.yaml' && + f !== 'bun.lockb' && + f !== 'bun.lock' + ); + }; + + /** + * Pretty-print a dry-run plan for a source-migration path and exit 0. + */ + const printAndExitDryRun = async (sourceName: string, backupName: string, docmdConfig: object): Promise => { + const moves = await planBackupMoves(backupName); + TUI.section(`Dry run: ${sourceName} migration`); + TUI.item('Would move', `${moves.length} file${moves.length === 1 ? '' : 's'} โ†’ ${backupName}/`); + if (moves.length > 0 && moves.length <= 12) { + for (const f of moves) TUI.item(' ', f); + } else if (moves.length > 12) { + for (const f of moves.slice(0, 10)) TUI.item(' ', f); + TUI.item(' ', `โ€ฆ and ${moves.length - 10} more`); + } + TUI.item('Would write', 'docmd.config.js'); + TUI.item('Config', JSON.stringify(docmdConfig)); + TUI.footer(); + TUI.info('No changes made. Re-run without --dry-run to apply.'); + }; + + /** + * N-9: best-effort MkDocs `nav:` parser. MkDocs nav is a YAML + * nested list; we use a tiny line-by-line YAML-aware scanner + * (no `yaml` dependency) that handles the common shape: + * + * nav: + * - Home: index.md + * - Guide: + * - Getting Started: start.md + * - Reference: ref.md + * + * Sections without an explicit file (`- Guide:` with no value) are + * kept as parents; their children are nested under `children`. + * Anything fancier (external links, multi-line strings, anchors) + * is left to the runtime auto-router. + */ + const parseMkDocsNav = (rawYaml: string): any[] | null => { + const lines = rawYaml.split('\n'); + const navIdx = lines.findIndex((l) => /^nav\s*:\s*$/.test(l)); + if (navIdx === -1) return null; + + const root: any[] = []; + const stack: { indent: number; items: any[] }[] = [{ indent: -1, items: root }]; + for (let i = navIdx + 1; i < lines.length; i++) { + const line = lines[i]; + // `- Title: file.md` (most common) OR `- Title:` (section header). + // The colon + value are optional. The title capture is non-greedy + // so it stops at the colon, and we strip a trailing `:` from the + // captured title (which happens when the line is `- Title:` with + // no file). + const m = line.match(/^(\s*)-\s+(.+?)(?::\s*(.+?))?\s*$/); + if (!m) continue; + const indent = m[1].length; + // Strip a trailing `:` from the title (which happens when the + // line is `- Title:` with no file value, the section-header + // shape in MkDocs). + const title = m[2].trim().replace(/:\s*$/, ''); + const file = (m[3] || '').trim(); + const item: any = file + ? { title, path: file.replace(/\.(md|markdown)$/i, '/') } + : { title }; + while (stack.length > 1 && stack[stack.length - 1].indent >= indent) stack.pop(); + const top = stack[stack.length - 1]; + top.items.push(item); + if (i + 1 < lines.length) { + const next = lines[i + 1]; + const nm = next.match(/^(\s+)-/); + if (nm && nm[1].length > indent) { + item.children = []; + stack.push({ indent, items: item.children }); + } + } + } + return root.length > 0 ? root : null; + }; + + /** + * T-Z14 / T-Z17: walk a freshly-copied docs directory and translate + * Docusaurus-specific frontmatter keys to their docmd equivalents. + * + * `id:` โ†’ removed (docmd derives route ids from filenames) + * `sidebar_label:`โ†’ `nav_title:` (the docmd-supported nav override) + * + * The translation is best-effort: a file that fails to parse keeps + * its original content. Returns the count of files touched. + */ + const translateDocusaurusFrontmatter = async (docsDir: string): Promise => { + const targets: string[] = []; + const walk = async (dir: string): Promise => { + const entries = await nativeFs.promises.readdir(dir, { withFileTypes: true }); + for (const entry of entries) { + const full = path.join(dir, entry.name); + if (entry.isDirectory()) { + if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue; + await walk(full); + } else if (entry.isFile() && /\.(md|mdx|markdown)$/i.test(entry.name)) { + targets.push(full); + } + } + }; + await walk(docsDir); + + let count = 0; + for (const file of targets) { + const raw = await nativeFs.promises.readFile(file, 'utf8'); + const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/); + if (!m) continue; + // Line-by-line parse: we only care about top-level `key: value` + // lines. Docusaurus lets these be unquoted, single-quoted, or + // double-quoted. Nested objects (e.g. `sidebar:` with sub-keys) + // are preserved as-is. + const lines = m[1].split('\n'); + let changed = false; + const newLines = lines.map((line) => { + const stripped = line.replace(/\r$/, ''); + const idMatch = stripped.match(/^\s*id\s*:\s*(.*?)\s*$/); + if (idMatch) { changed = true; return null; } + const slMatch = stripped.match(/^(\s*)sidebar_label\s*:\s*(.*?)\s*$/); + if (slMatch) { + changed = true; + const indent = slMatch[1]; + let val = slMatch[2]; + // Strip wrapping quotes if present so the rewritten value + // matches the original document's quote style as closely as + // possible. docmd accepts both forms. + const qm = val.match(/^['"](.*)['"]$/); + if (qm) val = qm[1]; + return `${indent}nav_title: ${val}`; + } + return stripped; + }).filter((l) => l !== null) as string[]; + + if (!changed) continue; + const newFm = newLines.join('\n'); + const newContent = raw.replace(/^---\r?\n[\s\S]*?\r?\n---/, `---\n${newFm}\n---`); + await nativeFs.promises.writeFile(file, newContent); + count++; + } + return count; + }; + + if (options.docusaurus) { + TUI.section('Docusaurus Migration'); + const configPath = path.resolve(CWD, 'docusaurus.config.js'); + const tsConfigPath = path.resolve(CWD, 'docusaurus.config.ts'); + + let activeConfigPath = ''; + if (nativeFs.existsSync(configPath)) activeConfigPath = configPath; + else if (nativeFs.existsSync(tsConfigPath)) activeConfigPath = tsConfigPath; + else { + TUI.error('Missing configuration', 'docusaurus.config.js or docusaurus.config.ts not found.'); + // Phase 3 PR 3.A (F6): exit 1 so CI pipelines can gate on it. + process.exit(1); + } + + const backupDir = path.resolve(CWD, 'docusaurus-backup'); + + const rawConfig = await nativeFs.promises.readFile(activeConfigPath, 'utf8'); + let title = 'Docmd Site'; + const titleMatch = rawConfig.match(/title:\s*['"]([^'"]+)['"]/); + if (titleMatch) title = titleMatch[1]; + + // N-22: preserve the original Docusaurus staticDir if set (default + // is `static`). Falling back to `dist` only when the user hasn't + // overridden it โ€” overwriting a `site/` directory because we + // hardcoded `dist` is the most common silent-clobber pattern. + let out = 'dist'; + const staticDirMatch = rawConfig.match(/staticDir\s*:\s*['"]([^'"]+)['"]/); + if (staticDirMatch) out = staticDirMatch[1].replace(/^\.\//, '').replace(/\/$/, '') || 'static'; + + const docmdConfig = { title, src: 'docs', out, theme: { appearance: 'system' } }; + // N-3: dry-run must run BEFORE any side effects (ensureDir, rename). + if (dryRun) { + await printAndExitDryRun('Docusaurus', 'docusaurus-backup', docmdConfig); + return; + } + + await fs.ensureDir(backupDir); + await moveFilesToBackup(backupDir); + TUI.step('Created backup directory', 'DONE'); + + const backupDocsDir = path.resolve(backupDir, 'docs'); + const newDocsDir = path.resolve(CWD, 'docs'); + if (nativeFs.existsSync(backupDocsDir)) { + await fs.copy(backupDocsDir, newDocsDir); + TUI.step('Migrated documentation content', 'DONE'); + } else { + await fs.ensureDir(newDocsDir); + TUI.step('Created new docs directory', 'DONE'); + } + + // T-Z14 / T-Z17: translate Docusaurus-specific frontmatter keys. + // docmd derives route ids from filenames, so Docusaurus `id:` is + // dropped. `sidebar_label:` is preserved as `nav_title:` (a + // docmd-supported override of the auto-generated nav title). + // The translation is best-effort: files that fail to parse keep + // their original frontmatter, and a TUI line reports the count. + let fmTranslated = 0; + try { + const translated = await translateDocusaurusFrontmatter(newDocsDir); + fmTranslated = translated; + } catch (err: any) { + TUI.warn(`Frontmatter translation skipped: ${err.message}`); + } + if (fmTranslated > 0) { + TUI.step(`Translated Docusaurus frontmatter in ${fmTranslated} file(s)`, 'DONE'); + } + + await nativeFs.promises.writeFile(path.resolve(CWD, 'docmd.config.js'), serializeConfig(docmdConfig)); + TUI.step('Generated docmd.config.js', 'DONE'); + + TUI.footer(); + TUI.success('Docusaurus migration complete.'); + TUI.info(`Original files moved to: ${TUI.cyan('docusaurus-backup/')}`); + TUI.info(`Run ${TUI.cyan('docmd dev')} to preview your site.`); + + } else if (options.mkdocs) { + TUI.section('MkDocs Migration'); + const configPath = path.resolve(CWD, 'mkdocs.yml'); + + if (!nativeFs.existsSync(configPath)) { + TUI.error('Missing configuration', 'mkdocs.yml not found.'); + // Phase 3 PR 3.A (F6): exit 1 so CI pipelines can gate on it. + process.exit(1); + } + + const backupDir = path.resolve(CWD, 'mkdocs-backup'); + + const rawConfig = await nativeFs.promises.readFile(configPath, 'utf8'); + let title = 'Docmd Site'; + const titleMatch = rawConfig.match(/^site_name:\s*['"]?([^'"\n]+)['"]?/m); + if (titleMatch) title = titleMatch[1].trim(); + + // N-22: preserve the original `site_dir` (MkDocs default is `site`). + // N-9 (partial): also build a basic nav tree from MkDocs `nav:`. + let out = 'site'; + const siteDirMatch = rawConfig.match(/^site_dir\s*:\s*['"]?([^'"\n]+)['"]?/m); + if (siteDirMatch) out = siteDirMatch[1].trim(); + // N-9: parse a simple top-level nav. This is a best-effort translation; + // complex MkDocs nav trees (multi-level, with external links) fall + // back to auto-generated nav at runtime. + const nav = parseMkDocsNav(rawConfig); + + const docmdConfig: any = { title, src: 'docs', out, theme: { appearance: 'system' } }; + if (nav && nav.length > 0) docmdConfig.navigation = nav; + // N-3: dry-run must run BEFORE any side effects (ensureDir, rename). + if (dryRun) { + await printAndExitDryRun('MkDocs', 'mkdocs-backup', docmdConfig); + return; + } + + await fs.ensureDir(backupDir); + await moveFilesToBackup(backupDir); + TUI.step('Created backup directory', 'DONE'); + + const backupDocsDir = path.resolve(backupDir, 'docs'); + const newDocsDir = path.resolve(CWD, 'docs'); + if (nativeFs.existsSync(backupDocsDir)) { + await fs.copy(backupDocsDir, newDocsDir); + TUI.step('Migrated documentation content', 'DONE'); + } else { + await fs.ensureDir(newDocsDir); + TUI.step('Created new docs directory', 'DONE'); + } + + await nativeFs.promises.writeFile(path.resolve(CWD, 'docmd.config.js'), serializeConfig(docmdConfig)); + TUI.step('Generated docmd.config.js', 'DONE'); + + TUI.footer(); + TUI.success('MkDocs migration complete.'); + TUI.info(`Original files moved to: ${TUI.cyan('mkdocs-backup/')}`); + TUI.info(`Run ${TUI.cyan('docmd dev')} to preview your site.`); + + } else if (options.vitepress) { + TUI.section('VitePress Migration'); + const CWD = process.cwd(); + + let configDir = ''; + let activeConfigPath = ''; + + // Check if config is in root or docs + for (const dir of ['.vitepress', 'docs/.vitepress']) { + for (const ext of ['js', 'ts', 'mjs']) { + const p = path.resolve(CWD, `${dir}/config.${ext}`); + if (nativeFs.existsSync(p)) { + configDir = dir; + activeConfigPath = p; + break; + } + } + if (activeConfigPath) break; + } + + if (!activeConfigPath) { + TUI.error('Missing configuration', '.vitepress/config.[js|ts|mjs] not found.'); + // Phase 3 PR 3.A (F6): exit 1 so CI pipelines can gate on it. + process.exit(1); + } + + const backupDir = path.resolve(CWD, 'vitepress-backup'); + + const rawConfig = await nativeFs.promises.readFile(activeConfigPath, 'utf8'); + let title = 'Docmd Site'; + const titleMatch = rawConfig.match(/title:\s*['"]([^'"]+)['"]/); + if (titleMatch) title = titleMatch[1]; + + const docmdConfig = { title, src: 'docs', out: 'dist', theme: { appearance: 'system' } }; + // N-3: dry-run must run BEFORE any side effects. + if (dryRun) { + await printAndExitDryRun('VitePress', 'vitepress-backup', docmdConfig); + return; + } + + await fs.ensureDir(backupDir); + await moveFilesToBackup(backupDir); + TUI.step('Created backup directory', 'DONE'); + + const isDocsInRoot = configDir === '.vitepress'; + const newDocsDir = path.resolve(CWD, 'docs'); + await fs.ensureDir(newDocsDir); + + if (isDocsInRoot) { + const files = await nativeFs.promises.readdir(backupDir); + for (const file of files) { + if (file.endsWith('.md')) { + await fs.copy(path.resolve(backupDir, file), path.resolve(newDocsDir, file)); + } + } + TUI.step('Migrated root content to docs/', 'DONE'); + } else { + const backupDocsDir = path.resolve(backupDir, 'docs'); + if (nativeFs.existsSync(backupDocsDir)) { + await fs.copy(backupDocsDir, newDocsDir); + await fs.remove(path.resolve(newDocsDir, '.vitepress')); + TUI.step('Migrated docs content', 'DONE'); + } + } + + await nativeFs.promises.writeFile(path.resolve(CWD, 'docmd.config.js'), serializeConfig(docmdConfig)); + TUI.step('Generated docmd.config.js', 'DONE'); + + TUI.footer(); + TUI.success('VitePress migration complete.'); + TUI.info(`Original files moved to: ${TUI.cyan('vitepress-backup/')}`); + TUI.info(`Run ${TUI.cyan('docmd dev')} to preview your site.`); + + } else if (options.starlight) { + TUI.section('Starlight Migration'); + const configPath = path.resolve(CWD, 'astro.config.mjs'); + const tsConfigPath = path.resolve(CWD, 'astro.config.ts'); + + let activeConfigPath = ''; + if (nativeFs.existsSync(configPath)) activeConfigPath = configPath; + else if (nativeFs.existsSync(tsConfigPath)) activeConfigPath = tsConfigPath; + else { + TUI.error('Missing configuration', 'astro.config.mjs or astro.config.ts not found.'); + // Phase 3 PR 3.A (F6): exit 1 so CI pipelines can gate on it. + process.exit(1); + } + + const backupDir = path.resolve(CWD, 'starlight-backup'); + + const rawConfig = await nativeFs.promises.readFile(activeConfigPath, 'utf8'); + let title = 'Docmd Site'; + const titleMatch = rawConfig.match(/title:\s*['"]([^'"]+)['"]/); + if (titleMatch) title = titleMatch[1]; + + const docmdConfig = { title, src: 'docs', out: 'dist', theme: { appearance: 'system' } }; + // N-3: dry-run must run BEFORE any side effects. + if (dryRun) { + await printAndExitDryRun('Starlight', 'starlight-backup', docmdConfig); + return; + } + + await fs.ensureDir(backupDir); + await moveFilesToBackup(backupDir); + TUI.step('Created backup directory', 'DONE'); + + const backupDocsDir = path.resolve(backupDir, 'src/content/docs'); + const newDocsDir = path.resolve(CWD, 'docs'); + + if (nativeFs.existsSync(backupDocsDir)) { + await fs.copy(backupDocsDir, newDocsDir); + TUI.step('Migrated documentation content', 'DONE'); + } else { + await fs.ensureDir(newDocsDir); + TUI.step('Created new docs directory', 'DONE'); + } + + await nativeFs.promises.writeFile(path.resolve(CWD, 'docmd.config.js'), serializeConfig(docmdConfig)); + TUI.step('Generated docmd.config.js', 'DONE'); + + TUI.footer(); + TUI.success('Astro Starlight migration complete.'); + TUI.info(`Original files moved to: ${TUI.cyan('starlight-backup/')}`); + TUI.info(`Run ${TUI.cyan('docmd dev')} to preview your site.`); + } else if (options.upgrade) { + TUI.section('Upgrading Configuration'); + + const jsonPath = path.resolve(CWD, 'docmd.config.json'); + const jsPath = path.resolve(CWD, 'docmd.config.js'); + const tsPath = path.resolve(CWD, 'docmd.config.ts'); + + let activePath = ''; + let format: 'json' | 'js' | 'ts' = 'json'; + + if (nativeFs.existsSync(jsonPath)) { + activePath = jsonPath; + format = 'json'; + } else if (nativeFs.existsSync(jsPath)) { + activePath = jsPath; + format = 'js'; + } else if (nativeFs.existsSync(tsPath)) { + activePath = tsPath; + format = 'ts'; + } + + if (!activePath) { + TUI.error('Upgrade Failed', 'No docmd configuration file (docmd.config.json/js/ts) found in current directory.'); + // Phase 3 PR 3.A (F6): exit 1 so CI pipelines can gate on it. + process.exit(1); + } + + TUI.step(`Found configuration: ${TUI.cyan(path.basename(activePath))}`, 'WAIT'); + + try { + const raw = await nativeFs.promises.readFile(activePath, 'utf8'); + let configObj: any = {}; + let isUpgraded = false; + + if (format === 'json') { + configObj = JSON.parse(raw); + } else { + // Dynamic import to read current exported config values + const module = await import(`file://${activePath}`); + configObj = module.default || {}; + } + + // 1. Upgrade legacy top-level 'projects' to 'workspace.projects' + if (configObj.projects && Array.isArray(configObj.projects) && !configObj.workspace) { + configObj.workspace = { + projects: configObj.projects, + switcher: { + enabled: true, + position: 'sidebar-top' + } + }; + delete configObj.projects; + isUpgraded = true; + TUI.step('Upgraded legacy top-level "projects" to "workspace" schema.', 'DONE'); + } + + // 2. Upgrade legacy 'siteTitle' to 'title' + if (configObj.siteTitle && !configObj.title) { + configObj.title = configObj.siteTitle; + delete configObj.siteTitle; + isUpgraded = true; + TUI.step('Upgraded "siteTitle" to "title".', 'DONE'); + } + + // 3. Upgrade legacy 'siteUrl' / 'baseUrl' to 'url' + if (configObj.siteUrl && !configObj.url) { + configObj.url = configObj.siteUrl; + delete configObj.siteUrl; + isUpgraded = true; + TUI.step('Upgraded "siteUrl" to "url".', 'DONE'); + } + if (configObj.baseUrl && !configObj.url) { + configObj.url = configObj.baseUrl; + delete configObj.baseUrl; + isUpgraded = true; + TUI.step('Upgraded "baseUrl" to "url".', 'DONE'); + } + + // 4. Upgrade legacy 'srcDir' to 'src' + if (configObj.srcDir && !configObj.src) { + configObj.src = configObj.srcDir; + delete configObj.srcDir; + isUpgraded = true; + TUI.step('Upgraded "srcDir" to "src".', 'DONE'); + } + + // 5. Upgrade legacy 'outputDir' to 'out' + if (configObj.outputDir && !configObj.out) { + configObj.out = configObj.outputDir; + delete configObj.outputDir; + isUpgraded = true; + TUI.step('Upgraded "outputDir" to "out".', 'DONE'); + } + + // 6. Upgrade legacy 'defaultLocale' to 'i18n.default' + if (configObj.defaultLocale) { + configObj.i18n = configObj.i18n || {}; + configObj.i18n.default = configObj.defaultLocale; + delete configObj.defaultLocale; + isUpgraded = true; + TUI.step('Upgraded "defaultLocale" to "i18n.default".', 'DONE'); + } + + // N-4: extend the legacy-key map with the remaining common keys. + // The previous upgrade covered siteTitle/siteUrl/baseUrl/srcDir/ + // outputDir/defaultLocale/projects but left several documented + // legacy keys untouched. These are the keys the build-time + // loader used in 0.7.x and earlier. + + // 7. 'source' (older alias for 'src') + if (configObj.source && !configObj.src) { + configObj.src = configObj.source; + delete configObj.source; + isUpgraded = true; + TUI.step('Upgraded "source" to "src".', 'DONE'); + } + + // 8. 'outDir' (older alias for 'out') + if (configObj.outDir && !configObj.out) { + configObj.out = configObj.outDir; + delete configObj.outDir; + isUpgraded = true; + TUI.step('Upgraded "outDir" to "out".', 'DONE'); + } + + // 9. 'nav' (legacy sidebar structure) โ†’ 'navigation' + if (configObj.nav && !configObj.navigation) { + configObj.navigation = configObj.nav; + delete configObj.nav; + isUpgraded = true; + TUI.step('Upgraded "nav" to "navigation".', 'DONE'); + } + + // 10. Top-level 'search' boolean โ†’ 'plugins.search' + if (typeof configObj.search === 'boolean' && !configObj.plugins?.search) { + configObj.plugins = configObj.plugins || {}; + configObj.plugins.search = configObj.search === true ? {} : { enabled: false }; + delete configObj.search; + isUpgraded = true; + TUI.step('Upgraded top-level "search" to "plugins.search".', 'DONE'); + } + + // 11. Top-level 'sidebar' โ†’ 'layout.sidebar' + if (configObj.sidebar && !configObj.layout?.sidebar) { + configObj.layout = configObj.layout || {}; + configObj.layout.sidebar = configObj.sidebar; + delete configObj.sidebar; + isUpgraded = true; + TUI.step('Upgraded top-level "sidebar" to "layout.sidebar".', 'DONE'); + } + + // 12. 'theme.enableModeToggle' โ†’ 'optionsMenu.components.themeSwitch' + if (configObj.theme?.enableModeToggle !== undefined) { + configObj.optionsMenu = configObj.optionsMenu || {}; + configObj.optionsMenu.components = configObj.optionsMenu.components || {}; + configObj.optionsMenu.components.themeSwitch = configObj.theme.enableModeToggle !== false; + delete configObj.theme.enableModeToggle; + isUpgraded = true; + TUI.step('Upgraded "theme.enableModeToggle" to "optionsMenu.components.themeSwitch".', 'DONE'); + } + + // 13. 'theme.positionMode' โ†’ 'optionsMenu.position' + if (configObj.theme?.positionMode && !configObj.optionsMenu?.position) { + configObj.optionsMenu = configObj.optionsMenu || {}; + configObj.optionsMenu.position = configObj.theme.positionMode === 'bottom' ? 'sidebar-bottom' : 'sidebar-top'; + delete configObj.theme.positionMode; + isUpgraded = true; + TUI.step('Upgraded "theme.positionMode" to "optionsMenu.position".', 'DONE'); + } + + // 14. 'theme.defaultMode' โ†’ 'theme.appearance' + if (configObj.theme?.defaultMode && !configObj.theme?.appearance) { + configObj.theme.appearance = configObj.theme.defaultMode; + delete configObj.theme.defaultMode; + isUpgraded = true; + TUI.step('Upgraded "theme.defaultMode" to "theme.appearance".', 'DONE'); + } + + if (!isUpgraded) { + TUI.footer(); + TUI.success('Configuration is already up to date with the latest schema.'); + return; + } + + // N-3: dry-run prints the upgraded config and exits 0 without writing. + if (dryRun) { + TUI.section('Dry run: config upgrade'); + TUI.item('Config path', activePath); + TUI.item('Upgraded config', JSON.stringify(configObj, null, 2)); + TUI.footer(); + TUI.info('No changes made. Re-run without --dry-run to apply.'); + return; + } + + // Write upgraded config back + if (format === 'json') { + await nativeFs.promises.writeFile(activePath, JSON.stringify(configObj, null, 2) + '\n'); + } else { + let content = serializeConfig(configObj); + if (format === 'ts') { + content = `import { UserConfig } from '@docmd/api';\n\nconst config: UserConfig = ${JSON.stringify(configObj, null, 2).replace(/"([^"]+)":/g, '$1:')};\n\nexport default config;\n`; + } + await nativeFs.promises.writeFile(activePath, content); + } + + TUI.footer(); + TUI.success(`Successfully upgraded config file to modern schema.`); + } catch (error: any) { + TUI.error('Upgrade Error', `Failed to parse or write config file: ${error.message}`); + // Phase 3 PR 3.A (F6): exit 1 so CI pipelines can gate on it. + process.exit(1); + } + } +} diff --git a/packages/core/src/commands/stop.ts b/packages/core/src/commands/stop.ts new file mode 100644 index 0000000..7c1c734 --- /dev/null +++ b/packages/core/src/commands/stop.ts @@ -0,0 +1,182 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { execSync } from 'child_process'; +import { TUI } from '@docmd/api'; + +// M-11: how long to wait after SIGTERM before escalating to SIGKILL. +// Docmd's dev server installs a graceful-shutdown handler on SIGTERM +// (closes watchers, the http server, the WebSocket server, and the +// worker pool). `docmd stop` waits this long for the process to exit +// on its own before sending the uncatchable SIGKILL. +const SIGTERM_GRACE_MS = 5000; + +/** + * Poll `pid` until it has exited or `timeoutMs` has elapsed. + * Returns `true` if the process exited within the window, `false` + * if it was still alive at the timeout (caller should escalate to + * SIGKILL). Polls every 100ms to keep the perceived latency low. + */ +export async function waitForExit(pid: number, timeoutMs: number): Promise { + const deadline = Date.now() + timeoutMs; + while (Date.now() < deadline) { + try { + // signal 0 = existence check; throws ESRCH if the pid is gone + process.kill(pid, 0); + } catch (err: any) { + if (err && err.code === 'ESRCH') return true; + // EPERM means the process exists but we can't signal it โ€” treat + // as still alive and let the outer catch handle escalation. + return false; + } + await new Promise((r) => setTimeout(r, 100)); + } + return false; +} + +/** + * find and kill running docmd processes + * If port is provided, only kill the process listening on that port. + * If force is true, also kill serve processes on common docmd ports. + */ +export async function stopServer(port: any, force: boolean = false) { + // Common ports used by docmd dev server + const commonPorts = [3000, 3001, 8080, 8081]; + + if (port) { + TUI.section(`Stopping port ${port}`); + try { + // Try lsof first + let pid = ''; + try { + pid = execSync(`lsof -t -i:${port}`).toString().trim(); + } catch { + // Fallback to fuser if lsof fails + try { + pid = execSync(`fuser -k ${port}/tcp 2>/dev/null`).toString().trim(); + } catch { + // Fallback to netstat + const netstat = execSync(`netstat -anp tcp 2>/dev/null | grep LISTEN | grep ${port}`).toString(); + const match = netstat.match(/(\d+)\/\w+/); + if (match) pid = match[1]; + } + } + if (pid) { + TUI.step(`Found process ${pid} on port ${port}`, 'WAIT'); + const pidNum = Number(pid); + // M-11: send SIGTERM first, wait up to SIGTERM_GRACE_MS for the + // process to exit on its own (the dev server installs a + // graceful shutdown handler), and only then escalate to SIGKILL. + try { + process.kill(pidNum, 'SIGTERM'); + } catch (err: any) { + TUI.step(`Failed to send SIGTERM to PID ${pid}: ${err.message}`, 'FAIL', TUI.red); + } + if (await waitForExit(pidNum, SIGTERM_GRACE_MS)) { + TUI.footer(); + TUI.success(`Docmd instance on port ${port} stopped gracefully.`); + return; + } + try { + process.kill(pidNum, 'SIGKILL'); + } catch (err: any) { + TUI.step(`Failed to send SIGKILL to PID ${pid}: ${err.message}`, 'FAIL', TUI.red); + } + TUI.footer(); + TUI.success(`Docmd instance on port ${port} has been stopped.`); + return; + } + } catch { + // No process found + } + TUI.step(`No instance found on port ${port}`, 'SKIP'); + TUI.footer(); + return; + } + + TUI.section('Stopping all instances'); + + try { + // Get all processes with PIDs and full command lines + // We filter for docmd but exclude the grep itself and the current process + const currentPid = process.pid; + + // Use ps to list processes. -ax to see all, -o pid,command for details. + const output = execSync('ps -ax -o pid,command').toString(); + const lines = output.split('\n'); + + const targets = []; + + for (const line of lines) { + const trimmed = line.trim(); + if (!trimmed) continue; + + const [pidStr, ...cmdParts] = trimmed.split(/\s+/); + const pid = parseInt(pidStr, 10); + const command = cmdParts.join(' '); + + // Check if it's a docmd process (dev or live) but not the current one + // We look for 'docmd dev', 'docmd live', or direct bin/docmd.js execution + const isDocmd = command.includes('docmd dev') || + command.includes('docmd live') || + command.includes('bin/docmd.js'); + + // With --force, also detect 'serve' processes on common docmd ports + let isServe = false; + if (force) { + isServe = (command.includes('serve ') || command.includes('serve -p')) && + commonPorts.some(p => command.includes(`-p ${p}`) || command.includes(`--port ${p}`)); + } + + const isNotCurrent = pid !== currentPid && command.indexOf('stop') === -1; + + if ((isDocmd || isServe) && isNotCurrent) { + targets.push({ pid, command, type: isServe ? 'serve' : 'docmd' }); + } + } + + if (targets.length === 0) { + TUI.step('No running docmd instances found', 'SKIP'); + TUI.footer(); + return; + } + + for (const target of targets) { + try { + TUI.step(`Stopping ${target.type} PID ${target.pid} (SIGTERM)`, 'WAIT'); + process.kill(target.pid, 'SIGTERM'); + } catch { + // If SIGTERM fails, skip the graceful wait + } + // M-11: give the graceful-shutdown handler time to run before + // escalating to SIGKILL. + if (!(await waitForExit(target.pid, SIGTERM_GRACE_MS))) { + try { + process.kill(target.pid, 'SIGKILL'); + TUI.step(`Killed ${target.type} PID ${target.pid} (SIGKILL after grace)`, 'DONE'); + } catch (err2: any) { + TUI.step(`Failed to kill PID ${target.pid}: ${err2.message}`, 'FAIL', TUI.red); + } + } else { + TUI.step(`Stopped ${target.type} PID ${target.pid} gracefully`, 'DONE'); + } + } + + TUI.footer(); + TUI.success('All docmd instances have been stopped.'); + + } catch (error: any) { + TUI.error('Error during stop', error.message); + } +} \ No newline at end of file diff --git a/packages/core/src/commands/validate.ts b/packages/core/src/commands/validate.ts new file mode 100644 index 0000000..eb48ba9 --- /dev/null +++ b/packages/core/src/commands/validate.ts @@ -0,0 +1,64 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { TUI } from '@docmd/api'; +import { loadConfig } from '../utils/config-loader.js'; +import { validateLinks } from './mcp.js'; +import path from 'path'; +import fs from 'fs'; + +export async function validateProject(options: { json?: boolean } = {}) { + let config: any; + try { + config = await loadConfig('docmd.config.js', { quiet: true }); + } catch { + config = { src: 'docs' }; + } + + const docsDir = path.resolve(process.cwd(), config.src || 'docs'); + + if (!fs.existsSync(docsDir)) { + if (options.json) { + console.log(JSON.stringify({ error: `Docs directory not found at ${docsDir}`, errors: [] })); + } else { + TUI.error('Validation Error', `Docs directory not found: ${docsDir}`); + } + process.exit(1); + } + + const errors = validateLinks(docsDir); + + if (options.json) { + // Phase 3 PR 3.A (M-12): even when JSON output is requested, the + // process MUST exit 1 if any errors were found. CI pipelines + // (`docmd validate --json | jq .errors | if [ $(. | length) -gt 0 ]; then exit 1`) + // rely on the exit code, not the JSON payload, to gate merges. + console.log(JSON.stringify({ errors })); + if (errors.length > 0) { + process.exit(1); + } + } else { + TUI.section('Documentation Validation'); + if (errors.length === 0) { + TUI.success('All internal links and references are valid!'); + } else { + TUI.error('Validation Failed', `Found ${errors.length} broken links:`); + errors.forEach(e => { + TUI.item(`[${e.file}:${e.line}]`, `${e.link} -> ${e.error}`); + }); + TUI.footer(); + process.exit(1); + } + } +} \ No newline at end of file diff --git a/packages/core/src/engine/assets.ts b/packages/core/src/engine/assets.ts new file mode 100644 index 0000000..72ecaa3 --- /dev/null +++ b/packages/core/src/engine/assets.ts @@ -0,0 +1,133 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import { fsUtils as fs } from '@docmd/utils'; +import esbuild from 'esbuild'; +import { createRequire } from 'module'; +import nativeFs from 'fs'; + +const _require = createRequire(import.meta.url); +import * as themes from '@docmd/themes'; +import * as ui from '@docmd/ui'; + +const pkgUrl = new URL('../../package.json', import.meta.url); +const pkg = JSON.parse(nativeFs.readFileSync(pkgUrl, 'utf8')); + +const COPYRIGHT_BANNER = `/*! + * docmd (v${pkg.version}) + * Copyright (c) 2025-present docmd.io + * License: MIT + */`; + +export async function findFilesRecursive(dir: string, extensions: string[]): Promise { + let files: string[] = []; + if (!await fs.exists(dir)) return []; + const items = await nativeFs.promises.readdir(dir, { withFileTypes: true }); + for (const item of items) { + // Explicitly ignore system files, git, and node_modules to prevent duplicate ID crashes + if (item.name === 'node_modules' || item.name.startsWith('.') || item.name === 'site') continue; + + const fullPath = path.join(dir, item.name); + if (item.isDirectory()) { + files = files.concat(await findFilesRecursive(fullPath, extensions)); + } else if (item.isFile()) { + if (!extensions || extensions.includes(path.extname(item.name))) { + files.push(fullPath); + } + } + } + return files; +} + +export async function prepareAssets(config: any, outputDir: string, options: any = {}) { + const CWD = process.cwd(); + + // 1. Core UI Assets + const uiAssets = ui.getAssetsDir(); + if (await fs.exists(uiAssets)) await fs.copy(uiAssets, path.join(outputDir, 'assets')); + + // 2. Theme Assets + const themesDir = themes.getThemesDir(); + if (await fs.exists(themesDir)) await fs.copy(themesDir, path.join(outputDir, 'assets/css')); + + // 3. User Assets (Root) + const userAssets = path.resolve(CWD, 'assets'); + if (await fs.exists(userAssets)) await fs.copy(userAssets, path.join(outputDir, 'assets')); + + // 3.5. User Assets (Docs Dir) + if (config.src) { + const srcAssets = path.resolve(CWD, config.src, 'assets'); + if (await fs.exists(srcAssets)) await fs.copy(srcAssets, path.join(outputDir, 'assets')); + } + + // 4. Minification (Production only) + if (config.minify !== false && !options.isDev) { + await minifyDir(path.join(outputDir, 'assets')); + } +} + +// --------------------------------------------------------------------------- +// Template Assets (new in 0.8.7) +// Templates ship their own CSS/JS bundles. We copy them into +// `assets/template/` so they survive minification and +// can be referenced with a stable URL. +// --------------------------------------------------------------------------- +export async function prepareTemplateAssets(config: any, outputDir: string) { + // The hooks object is exported by @docmd/api. We import lazily to avoid + // a hard build-time cycle between @docmd/core โ†” @docmd/api. + const { hooks } = await import('@docmd/api'); + if (!hooks || !Array.isArray(hooks.templateAssets) || hooks.templateAssets.length === 0) return; + + const templateDir = path.join(outputDir, 'assets', 'template'); + await fs.ensureDir(templateDir); + + for (const asset of hooks.templateAssets) { + if (!asset || !asset.path || !asset.type) continue; + if (asset.type !== 'css' && asset.type !== 'js') continue; + if (!await fs.exists(asset.path)) { + // Don't crash the build โ€” the resolver already warned at render time. + continue; + } + const dest = path.join(templateDir, path.basename(asset.path)); + await fs.copy(asset.path, dest); + } +} + +async function minifyDir(dir: string) { + const assets = await findFilesRecursive(dir, ['.css', '.js']); + for (const file of assets) { + if (file.endsWith('.min.js') || file.endsWith('.min.css')) continue; + try { + const ext = path.extname(file); + const content = await nativeFs.promises.readFile(file, 'utf8'); + const result = await esbuild.transform(content, { + loader: ext.slice(1) as any, + minify: true, + legalComments: 'none' + }); + await nativeFs.promises.writeFile(file, COPYRIGHT_BANNER + '\n' + result.code); + } catch { + // Ignore errors for non-standard files or mixed content + } + } +} + +// Generate HTML Tag Helper +export function generateAssetTag(pathOrUrl: string, type: string, attributes: any = {}) { + const attrs = Object.entries(attributes).map(([k, v]) => v === true ? k : `${k}="${v}"`).join(' '); + if (type === 'css') return ``; + if (type === 'js') return ``; + return ''; +} \ No newline at end of file diff --git a/packages/core/src/engine/generator.ts b/packages/core/src/engine/generator.ts new file mode 100644 index 0000000..ed1c8ef --- /dev/null +++ b/packages/core/src/engine/generator.ts @@ -0,0 +1,837 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import { fsUtils as fs } from '@docmd/utils'; +import { createRequire } from 'module'; +import { execSync } from 'child_process'; + +/** + * Convert every segment of a relative file path to a URL-safe slug, + * mirroring the slugifySegment logic in auto-router.ts. + * This ensures the output path written to disk matches the URL that + * buildAutoNav generates for the same file. + * + * Example: "SA/folder with space/page with space" + * โ†’ "SA/folder-with-space/page-with-space" + */ +function slugifyOutputPath(p: string): string { + return p + .split('/') + .map(seg => + seg + .replace(/\s+/g, '-') + .replace(/[^a-zA-Z0-9\-_.~]/g, '-') + .replace(/-{2,}/g, '-') + .replace(/^-+|-+$/g, '') + || seg + ) + .join('/'); +} +import { generateAssetTag, findFilesRecursive } from './assets.js'; +import { generateHreflangTags } from './i18n.js'; +import nativeFs from 'fs'; + +const _require = createRequire(import.meta.url); +import * as parser from '@docmd/parser'; +import { TUI } from '@docmd/tui'; +import { findPageNeighbors, findBreadcrumbs, normalizeNavPaths, createUrlContext, buildContextualUrl, computePageUrls, buildAbsoluteUrl, sanitizeUrl } from '@docmd/parser'; +import * as ui from '@docmd/ui'; + + + +/* โ”€โ”€ Core package version (for ) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ +const _pkgUrl = new URL('../../package.json', import.meta.url); +const _pkg = JSON.parse(nativeFs.readFileSync(_pkgUrl, 'utf8')) as { version: string }; +const CORE_VERSION: string = _pkg.version; + +/* โ”€โ”€ Constants โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +/** Number of pages to process concurrently in each batch. */ +const BATCH_SIZE = 64; + +/** Number of pages to write to disk concurrently. */ +const WRITE_BATCH_SIZE = 128; + +/* โ”€โ”€ Git Root Detection (for edit links) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +/** Cached git root path (null = not yet detected, '' = not a git repo). */ +let _cachedGitRoot: string | null = null; + +/** + * Detect the git repository root for the current working directory. + * Returns the absolute path to the git root, or null if not in a git repo. + * Result is cached per build (cache resets when cwd changes). + */ +function getGitRoot(): string | null { + if (_cachedGitRoot !== null) { + return _cachedGitRoot || null; + } + try { + _cachedGitRoot = execSync('git rev-parse --show-toplevel', { + cwd: process.cwd(), + stdio: 'pipe', + encoding: 'utf8' + }).trim(); + return _cachedGitRoot; + } catch { + _cachedGitRoot = ''; + return null; + } +} + +/* โ”€โ”€ Types โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +interface RenderPagesOptions { + config: any; + srcDir: string; + fallbackSrcDir: string | null; + outputDir: string; + hooks: any; + buildHash: string; + options: any; + outputPrefix?: string; + /** docmd core version (e.g. "0.8.7"). Used for the tag. */ + coreVersion?: string; + /** Progress callback: (current, total) called after each batch completes. */ + onProgress?: (current: number, total: number) => void; + /** Optional: only render specific files (relative to srcDir). Used for incremental dev rebuilds. */ + targetFiles?: string[]; +} + +export async function renderPages({ config, srcDir, fallbackSrcDir, outputDir, hooks, buildHash, options, outputPrefix = '', coreVersion, onProgress, targetFiles }: RenderPagesOptions) { + // Reset git root cache (cwd may have changed between workspace builds) + _cachedGitRoot = null; + + // Load Translations for the active locale + const localeId = config._activeLocale?.id || null; + const pluginTranslations = hooks.translations + ? await hooks.translations.reduce(async (accP: any, fn: any) => ({ ...(await accP), ...(await fn(localeId)) }), {}) + : {}; + + // Merge: system translations โ†’ plugin translations โ†’ user-provided locale translations + const userLocaleTranslations = config._activeLocale?.translations || {}; + const strings = ui.loadTranslations(localeId, { ...pluginTranslations, ...userLocaleTranslations }); + const t = ui.createT(strings); + + // Resolve locale-specific navigation.json + // Each locale dir has its own navigation.json; fall back to default locale's navigation + if (config.i18n && config._activeLocale) { + const localeNavPath = path.join(srcDir, 'navigation.json'); + try { + if (nativeFs.existsSync(localeNavPath)) { + const rawNav = await nativeFs.promises.readFile(localeNavPath, 'utf8'); + const parsedNav = JSON.parse(rawNav); + normalizeNavPaths(parsedNav); + config = { ...config, navigation: parsedNav }; + } else if (fallbackSrcDir) { + // Fall back to default locale's navigation.json + const fallbackNavPath = path.join(fallbackSrcDir, 'navigation.json'); + if (nativeFs.existsSync(fallbackNavPath)) { + const rawNav = await nativeFs.promises.readFile(fallbackNavPath, 'utf8'); + const parsedNav = JSON.parse(rawNav); + normalizeNavPaths(parsedNav); + config = { ...config, navigation: parsedNav }; + } + } + } catch { + TUI.warn(`Failed to parse locale navigation: ${localeNavPath}`); + } + } + + // Pass UI strings to the markdown processor (for locale-aware aria-labels etc.) + const configWithStrings = { ...config, _uiStrings: strings }; + const mdProcessor = parser.createMarkdownProcessor(configWithStrings, (md: any) => hooks.markdownSetup.forEach((hook: any) => hook(md))); + + // Load Layout Templates + const templates = { + layout: await nativeFs.promises.readFile(ui.getTemplatePath('layout'), 'utf8'), + noStyle: await nativeFs.promises.readFile(ui.getTemplatePath('no-style'), 'utf8'), + navigation: await nativeFs.promises.readFile(ui.getTemplatePath('navigation'), 'utf8'), + 'docmd-search': await nativeFs.promises.readFile(ui.getTemplatePath('docmd-search'), 'utf8'), + }; + + // Load Partials + const themeInitPath = path.join(ui.getTemplatesDir(), 'partials', 'theme-init.js'); + const themeInitScript = (await fs.exists(themeInitPath)) + ? `` + : ''; + + // Footer Processing + const footerHtml = config.footer?.content ? mdProcessor.renderInline(config.footer.content) : ''; + + // --- 1. Identify Assets (Plugin + Template Injection) --- + // Each entry is `{ priority, gen }` so we can sort by load order: + // 0 = base (docmd-main.css) + // 5 = theme colour overlay (docmd-theme-sky.css etc.) + // 10 = template structure (NEW in 0.8.7) + // 15 = user customCss (always wins) + // 20 = other plugins + // Within the same priority, the order of registration is preserved. + // + // Assets fall into two buckets per position: + // - `commonXxx` โ€” emitted on EVERY page (legacy behaviour) + // - `condXxx` โ€” gated by an AssetCondition; evaluated per page + type AssetEntry = { priority: number; gen: (rel: string) => string; condition?: any }; + const assetTags: { head: AssetEntry[]; body: AssetEntry[] } = { + head: [], + body: [], + }; + + // Theme CSS (priority 5 โ€” overrides base, overridden by template & customCss) + // Skipped when: + // - name is 'default' (no overlay) or 'none' (explicitly disabled) + // - name was promoted to a template name (see config-schema ยง4.0) + // - the template opted out of CSS overlay via _noCssOverlay + const themeName = config.theme.name; + const themeIsTemplate = config.theme._noCssOverlay === true; + if (themeName && themeName !== 'default' && themeName !== 'none' && !themeIsTemplate) { + assetTags.head.push({ + priority: 5, + gen: (rel: string) => generateAssetTag(`${rel}assets/css/docmd-theme-${themeName}.css?v=${buildHash}`, 'css'), + }); + } + // Lightbox (priority 20 โ€” always last, no theme/template should override it) + assetTags.body.push({ + priority: 20, + gen: (rel: string) => generateAssetTag(`${rel}assets/js/docmd-image-lightbox.js?v=${buildHash}`, 'js'), + }); + + // Template assets (priority 10 by default โ€” overrides theme, overridden by customCss) + if (hooks.templateAssets && Array.isArray(hooks.templateAssets)) { + for (const asset of hooks.templateAssets) { + if (!asset || !asset.path || (asset.type !== 'css' && asset.type !== 'js')) continue; + const baseName = path.basename(asset.path); + const position = (asset.position || (asset.type === 'css' ? 'head' : 'body')) as 'head' | 'body'; + const priority = typeof asset.priority === 'number' ? asset.priority : 10; + const bucket = position === 'head' ? assetTags.head : assetTags.body; + // The URL is computed per-page (relativePathToRoot varies by depth). + bucket.push({ + priority, + gen: (rel: string) => generateAssetTag(`${rel}assets/template/${baseName}?v=${buildHash}`, asset.type), + }); + } + } + + // Plugin Assets + if (hooks.assets) { + for (const getAssetsFn of hooks.assets) { + // hooks.assets entries are async wrappers; missing the await here + // would make `assets` a Promise and silently skip the whole tag + // generation loop (Array.isArray(Promise) === false). The + // user-visible symptom is "plugin tag) because no regex can + // reliably distinguish a trusted analytics script from a malicious one. + const fullHeadHtml = [ + headInjections.join('\n'), + assetHeadHtml, + generateHreflangTags(config, page.outputPath) + ].join('\n'); + + const fullBodyHtml = [ + assetBodyHtml, + bodyInjections.join('\n') + ].join('\n'); + + // Source file path relative to srcDir + const sourceRelative = path.relative(process.cwd(), page.sourcePath).replace(/\\/g, '/'); + + // Compute edit URL from git plugin config (preferred) or legacy config.editLink + let editUrl = null; + const editLinkText = config.plugins?.git?.editLinkText || config.editLink?.text || t('editThisPage'); + const gitPluginConfig = config.plugins?.git; + + if (gitPluginConfig?.repo && gitPluginConfig?.editLink !== false) { + // Git plugin config (modern approach) + const gitRoot = getGitRoot(); + const editRelative = gitRoot + ? path.relative(gitRoot, page.sourcePath).replace(/\\/g, '/') + : sourceRelative; + const repo = gitPluginConfig.repo.replace(/\/$/, ''); + const branch = gitPluginConfig.branch || 'main'; + const editPath = gitPluginConfig.editPath || 'edit'; + editUrl = `${repo}/${editPath}/${branch}/${editRelative}`; + } else if (config.editLink?.enabled && config.editLink?.baseUrl) { + // Legacy fallback + const cleanBase = config.editLink.baseUrl.replace(/\/$/, ''); + const gitRoot = getGitRoot(); + const editRelative = gitRoot + ? path.relative(gitRoot, page.sourcePath).replace(/\\/g, '/') + : path.relative(path.resolve(process.cwd(), config.src || '.'), page.sourcePath).replace(/\\/g, '/'); + editUrl = `${cleanBase}/${editRelative}`; + } + + // Navigation HTML + const navigationHtml = await parser.renderTemplateAsync(templates.navigation, { + config, + navItems: config.navigation, + currentPagePath: navPath, + relativePathToRoot, + outputPrefix, + isOfflineMode: options.offline, + buildRelativeUrl, + t + }, { filename: ui.getTemplatePath('navigation') }); + + // Render Full Page + // Template selection (new in 0.8.7): resolveTemplate() honours + // frontmatter.template > config.templates[glob] > config.theme.template > default + // and falls back to the default layout if the resolved file is missing. + // noStyle pages (no chrome) continue to use templates.noStyle as before. + let templateString = templates.layout; + let resolvedTemplateInfo: any = null; + if (page.frontmatter.noStyle) { + templateString = templates.noStyle; + } else { + try { + const resolved = ui.resolveTemplate({ + type: 'layout', + pagePath: page.outputPath, + frontmatter: page.frontmatter, + config, + localeId: config._activeLocale?.id, + versionId: config._activeVersion?.id, + }); + if (resolved && resolved.templatePath) { + templateString = await nativeFs.promises.readFile(resolved.templatePath, 'utf8'); + resolvedTemplateInfo = resolved; + } + } catch (e: any) { + TUI.warn(`Template resolver failed for "${page.outputPath}" โ€” falling back to default. ${e.message}`); + } + } + let fullHtml = await parser.renderTemplateAsync(templateString, { + content: page.htmlContent, + rawMarkdown: page.rawMarkdown || '', + frontmatter: page.frontmatter, + headings: page.headings, + config, + buildHash, + coreVersion: coreVersion || CORE_VERSION, + siteTitle: config.title, + pageTitle: page.frontmatter.title, + description: page.frontmatter.description || '', + appearance: config.theme?.appearance || config.theme?.defaultMode || 'system', + defaultMode: config.theme?.appearance || config.theme?.defaultMode || 'system', + relativePathToRoot, + isOfflineMode: options.offline, + buildRelativeUrl, + navigationHtml, + prevPage: fixNeighbor(prevPage), + nextPage: fixNeighbor(nextPage), + logo: config.logo, + theme: config.theme, + + headerConfig: config.header, + sidebarConfig: config.sidebar, + footerConfig: config.footer, + menubarConfig: config.menubar, + optionsMenu: config.optionsMenu, + + customCssFiles: config.theme.customCss || [], + customJsFiles: config.customJs || [], + + pluginHeadScriptsHtml: fullHeadHtml, + pluginBodyScriptsHtml: fullBodyHtml, + + faviconLinkHtml: config.favicon ? `` : '', + themeInitScript, + footerHtml, + isActivePage: page.htmlContent && page.htmlContent.trim().length > 0, + editUrl, + editLinkText, + breadcrumbs, + sourceFile: sourceRelative, + activeLocale: config._activeLocale || null, + allLocales: config._allLocales || null, + builtLocales: config._builtLocales ? [...config._builtLocales] : null, + defaultLocale: config._defaultLocale || null, + i18nInPlace: config.i18n?.inPlace || false, + i18nStringMode: config.i18n?.stringMode || false, + localePrefix: config._localeOutputPrefix || '', + currentPagePath: navPath, + outputPrefix, + siteRootAbs: (() => { + let root = '/'; + if (config._activePrefix && config._activePrefix !== '/') { + root = config._activePrefix; + } else if (config.base && config.base !== '/') { + root = config.base; + } + if (root !== '/' && !root.endsWith('/')) root += '/'; + return root; + })(), + t, + buildAbsoluteUrl, + sanitizeUrl, + workspace: config._workspace, + themeCssLinkHtml: '', + metaTagsHtml: '', + pluginStylesHtml: '', + // New in 0.8.7: resolved template metadata, available to the + // template if it needs to know which template handled this page. + _template: resolvedTemplateInfo, + }, { filename: ui.getTemplatePath('layout') }); + + const pageObj = { + html: fullHtml, + frontmatter: page.frontmatter, + outputPath: page.outputPath, + sourcePath: page.sourcePath, + urls: pageUrls, + urlContext, + config + }; + + for (const fn of hooks.onPageReady) { + await fn(pageObj); + } + + fullHtml = pageObj.html; + + // Queue the write + writeQueue.push({ finalPath, html: fullHtml }); + (page as any).urls = pageUrls; + })); + } + + // --- 4. Parallel file writes โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + // Write all rendered HTML files in batches for maximum I/O throughput + for (let i = 0; i < writeQueue.length; i += WRITE_BATCH_SIZE) { + const writeBatch = writeQueue.slice(i, i + WRITE_BATCH_SIZE); + await Promise.all( + writeBatch.map(async ({ finalPath, html }) => { + await fs.ensureDir(path.dirname(finalPath)); + await nativeFs.promises.writeFile(finalPath, html); + }) + ); + } + + return pages; +} \ No newline at end of file diff --git a/packages/core/src/engine/i18n.ts b/packages/core/src/engine/i18n.ts new file mode 100644 index 0000000..1c58095 --- /dev/null +++ b/packages/core/src/engine/i18n.ts @@ -0,0 +1,456 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import { TUI } from '@docmd/tui'; +import nativeFs from 'fs'; +import { fsUtils as fs } from '@docmd/utils'; +import { renderPages } from './generator.js'; +import { buildVersions, filterGhostVersions } from './versioning.js'; +import { sanitizeUrl } from '@docmd/parser'; +import { findFilesRecursive } from './assets.js'; + +/** + * Pre-count total pages across all locale ร— version passes. + * Fast scan (just directory walks, no file reads) so the progress bar + * knows the exact denominator from the very first page. + */ +export async function preCountPages(config: any, CWD: string, targetFiles?: string[] | null): Promise { + if (targetFiles && targetFiles.length > 0) return targetFiles.length; + const locales = getLocales(config); + const isStringMode = config.i18n?.stringMode === true; + let total = 0; + + for (const locale of locales) { + const localeId = locale ? locale.id : null; + const isDefault = localeId ? localeId === config.i18n.default : false; + if (isStringMode && localeId && !isDefault) continue; + + const localeConfig = createLocaleConfig(config, locale); + const versions = localeConfig.versions?.all?.length > 0 + ? localeConfig.versions.all + : [null]; + + for (const v of versions) { + const baseSrcDir = v + ? path.resolve(CWD, v.dir) + : path.resolve(CWD, localeConfig.src); + + const localeSrcDir = resolveLocaleSrcDir(baseSrcDir, localeConfig); + const fallbackSrcDir = resolveFallbackSrcDir(baseSrcDir, localeConfig); + + // Match the skip logic from buildVersions (line 164-169) and buildLocales (line 271-274): + // If the locale-specific dir doesn't exist, only the default locale processes. + if (!nativeFs.existsSync(localeSrcDir)) { + if (!isDefault && localeId) continue; // non-default locale: skip + // Default locale: try the base dir directly (old versions without locale dirs) + if (v && nativeFs.existsSync(baseSrcDir)) { + const files = await findFilesRecursive(baseSrcDir, ['.md', '.markdown', '.ejs']); + total += files.length; + } + continue; + } + + // Scan fallback dir when set (non-default locale uses default locale as canonical list) + const scanDir = fallbackSrcDir || localeSrcDir; + if (!nativeFs.existsSync(scanDir)) continue; + + const files = await findFilesRecursive(scanDir, ['.md', '.markdown', '.ejs']); + total += files.length; + } + } + + return total; +} + +/** + * Prepare locale context to inject into config for a build pass. + * When locale is null (i18n disabled), returns the config unchanged. + * + * Design: every locale lives in its own subdirectory inside the src dir: + * docs/en/ docs/hi/ docs/zh/ + * + * The default locale renders at root (no URL prefix), + * non-default locales render at /{locale}/. + * Fallback: if a page doesn't exist in a non-default locale dir, + * the engine falls back to the default locale's version of that page. + */ +export function createLocaleConfig(config: any, locale: any): any { + if (!locale) return config; + const isDefault = locale.id === config.i18n.default; + return { + ...config, + _activeLocale: locale, + _allLocales: config.i18n.locales, + _defaultLocale: config.i18n.default, + _localeOutputPrefix: isDefault ? '' : locale.id + '/' + }; +} + +/** + * Resolve the source directory for a given locale. + * When i18n is enabled with directory mode, each locale gets its own subdirectory: {baseSrcDir}/{localeId}/ + * When stringMode is enabled, all locales use the same root source directory. + * When i18n is disabled, returns baseSrcDir unchanged. + */ +export function resolveLocaleSrcDir(baseSrcDir: string, config: any): string { + if (!config._activeLocale) return baseSrcDir; + if (config.i18n?.stringMode) return baseSrcDir; + return path.join(baseSrcDir, config._activeLocale.id); +} + +/** + * Resolve the fallback source directory (the default locale's dir). + * Used when a non-default locale is missing a page - falls back to the default locale. + * Returns null if current locale IS the default (no fallback needed). + * Returns null in stringMode (all locales share the same source). + */ +export function resolveFallbackSrcDir(baseSrcDir: string, config: any): string | null { + if (!config._activeLocale || !config._defaultLocale) return null; + if (config.i18n?.stringMode) return null; + if (config._activeLocale.id === config._defaultLocale) return null; + return path.join(baseSrcDir, config._defaultLocale); +} + +/** + * Get the list of locales to iterate over. + * Returns [null] when i18n is disabled (single pass, no locale prefix). + */ +export function getLocales(config: any): any[] { + return config.i18n && config.i18n.locales ? config.i18n.locales : [null]; +} + +/** + * Build all locales - the outer loop of the build pipeline. + * For each locale, runs the versioning loop (or standard build) inside it. + * + * The default locale builds directly into rootOutputDir (no prefix). + * Non-default locales build into rootOutputDir/{locale}/. + */ +export async function buildLocales({ + config, + rootOutputDir, + hooks, + buildHash, + options, + CWD, + onProgress, + targetFiles, + coreVersion +}: { + config: any; + rootOutputDir: string; + hooks: any; + buildHash: string; + options: any; + CWD: string; + onProgress?: (current: number, total: number) => void; + targetFiles?: string[]; + coreVersion?: string; +}): Promise { + const allGeneratedPages = []; + + // Filter ghost versions once before any locale pass + await filterGhostVersions(config, CWD, options.isDev); + + const locales = getLocales(config); + const isStringMode = config.i18n?.stringMode === true; + + // Pre-scan which locale directories actually exist so the language switcher + // can disable unavailable locales during rendering (before pages are built). + // The default locale is always "available" since it renders at root. + if (config.i18n && config.i18n.locales) { + const baseSrcDir = path.resolve(CWD, config.src); + const availableLocaleIds = new Set(); + + for (const loc of config.i18n.locales) { + if (loc.id === config.i18n.default) { + availableLocaleIds.add(loc.id); + continue; + } + if (isStringMode) { + // stringMode: all locales are available (they clone the default) + availableLocaleIds.add(loc.id); + continue; + } + + // Check for locale directory - handle both versioned and non-versioned structures + // Non-versioned: baseSrcDir/{localeId}/ + // Versioned: baseSrcDir/{versionDir}/{localeId}/ + const locDir = path.join(baseSrcDir, loc.id); + if (nativeFs.existsSync(locDir)) { + availableLocaleIds.add(loc.id); + continue; + } + + // Check versioned structure: look in the current version's directory + if (config.versions?.all?.length > 0) { + const currentVersion = config.versions.all.find((v: any) => v.id === config.versions.current); + if (currentVersion) { + const versionedLocDir = path.join(baseSrcDir, currentVersion.dir, loc.id); + if (nativeFs.existsSync(versionedLocDir)) { + availableLocaleIds.add(loc.id); + } + } + } + } + config._builtLocales = availableLocaleIds; + } + + // In stringMode, build the default locale first (or single pass), + // then clone its output with server-side string replacements for other locales. + let defaultPassPages: any[] | null = null; + + for (const locale of locales) { + const localeId = locale ? locale.id : null; + const isDefault = localeId ? localeId === config.i18n.default : false; + const localeConfig = createLocaleConfig(config, locale); + + // We pass the rootOutputDir so that path.rel() accurately maps back to root. + // The nesting is handled purely by the string pathPrefix. + const pathPrefix = (localeId && !isDefault) ? localeId + '/' : ''; + + if (isStringMode && localeId && !isDefault) { + // stringMode: clone default locale output with string replacements + if (!defaultPassPages) { + TUI.warn(`stringMode: no default locale pages to clone for ${localeId}. Skipping...`); + continue; + } + + const assetsDir = config.assets || 'assets'; + const strings = await loadStringModeTranslations(CWD, assetsDir, localeId); + const localeDir = locale?.dir || 'ltr'; + + if (Object.keys(strings).length === 0) { + TUI.warn(`No string translations found for ${localeId} (assets/i18n/${localeId}.json). Rendering default language.`); + } + + for (const page of defaultPassPages) { + // Re-read the rendered default HTML and apply string replacements + const defaultOutputPath = path.join(rootOutputDir, page.outputPath); + if (!nativeFs.existsSync(defaultOutputPath)) continue; + + const defaultHtml = await nativeFs.promises.readFile(defaultOutputPath, 'utf8'); + const translatedHtml = applyStringModeReplacements(defaultHtml, strings, localeId, localeDir); + + // Write to the locale-prefixed output path + const localeOutputPath = path.join(rootOutputDir, pathPrefix, page.outputPath); + await fs.ensureDir(path.dirname(localeOutputPath)); + await nativeFs.promises.writeFile(localeOutputPath, translatedHtml); + + allGeneratedPages.push({ ...page, outputPath: pathPrefix + page.outputPath }); + } + continue; + } + + if (localeConfig.versions?.all?.length > 0) { + // Versioned build within this locale + const pages = await buildVersions({ + config: localeConfig, + outputDir: rootOutputDir, + hooks, + buildHash, + options, + CWD, + pathPrefix, + onProgress, + targetFiles, + coreVersion + }); + allGeneratedPages.push(...pages); + if (isStringMode && isDefault) defaultPassPages = pages; + + } else { + // Standard build (no versioning) within this locale + const baseSrcDir = path.resolve(CWD, localeConfig.src); + const localeSrcDir = resolveLocaleSrcDir(baseSrcDir, localeConfig); + const fallbackSrcDir = resolveFallbackSrcDir(baseSrcDir, localeConfig); + + // The locale dir must exist (or fall back to base when no i18n) + if (!await fs.exists(localeSrcDir)) { + if (localeConfig._activeLocale && !isStringMode) { + TUI.warn(`Locale directory missing: ${localeSrcDir}. Skipping ${localeConfig._activeLocale.id}...`); + continue; + } else if (!localeConfig._activeLocale) { + throw new Error(`Source directory not found: ${localeSrcDir}`); + } + } + + const pages = await renderPages({ + config: localeConfig, + srcDir: localeSrcDir, + fallbackSrcDir, + outputDir: rootOutputDir, + hooks, + buildHash, + options, + outputPrefix: pathPrefix, + onProgress, + targetFiles, + coreVersion + }); + allGeneratedPages.push(...pages); + if (isStringMode && (isDefault || !localeId)) defaultPassPages = pages; + } + } + + return allGeneratedPages; +} + +/** + * Generate the root redirect page for i18n sites. + * + * Since the default locale now renders at root, the redirect is only needed + * if the user's browser locale matches a non-default locale. The redirect + * page is written as a lightweight JS snippet that checks localStorage โ†’ + * navigator.language; if it matches a non-default locale, it redirects. + * Otherwise, the root content (default locale) is already there. + * + * Note: This is now a no-op because the default locale is at root. + * Users browsing to / get the default locale directly. The language + * switcher handles navigation to non-default locales. + */ +export async function generateLocaleRedirect(config: any, _rootOutputDir: string): Promise { + // Default locale is at root - no redirect needed. + // The language switcher provides navigation to /hi/, /zh/, etc. + if (!config.i18n?.locales) return; + return; +} + +/** + * Generate hreflang link tags for a page across all locales. + * Used by the generator to inject into . + * + * Default locale pages are at root (no prefix). + * Non-default locale pages are at /{locale}/path. + */ +export function generateHreflangTags(config: any, pageOutputPath: string): string { + if (!config._allLocales) return ''; + + const base = config.base && config.base !== '/' ? config.base.replace(/\/$/, '') : ''; + let pagePath = pageOutputPath.replace(/index\.html$/, '').replace(/\\/g, '/'); + + // Strip the current locale prefix from pagePath if present. + // pageOutputPath may be "hi/guide/index.html" - we need just "guide/". + const defaultLocale = config._defaultLocale; + for (const loc of config._allLocales) { + if (loc.id !== defaultLocale && pagePath.startsWith(loc.id + '/')) { + pagePath = pagePath.slice(loc.id.length + 1); + break; + } + } + + return config._allLocales.map((loc: any) => { + const isDefault = loc.id === config._defaultLocale; + // Default locale โ†’ root path, non-default โ†’ /{locale}/path + // Use sanitizeUrl to ensure no double slashes + const href = sanitizeUrl(isDefault + ? `${base}/${pagePath}` + : `${base}/${loc.id}/${pagePath}`); + let tags = ``; + if (isDefault) { + tags += `\n`; + } + return tags; + }).join('\n'); +} + +/** + * Load string-mode translations from assets/i18n/{localeId}.json. + * Returns an empty object if the file doesn't exist (graceful fallback). + */ +export async function loadStringModeTranslations( + CWD: string, + assetsDir: string, + localeId: string +): Promise> { + const filePath = path.join(CWD, assetsDir, 'i18n', `${localeId}.json`); + try { + if (nativeFs.existsSync(filePath)) { + const raw = await nativeFs.promises.readFile(filePath, 'utf8'); + return JSON.parse(raw); + } + } catch (e: any) { + TUI.warn(`Failed to load string-mode translations: ${filePath} - ${e.message}`); + } + return {}; +} + +/** + * Apply server-side string replacement on rendered HTML. + * Resolves data-i18n, data-i18n-html, and data-i18n-{attr} attributes + * using the provided translations object. + * + * This is the build-time equivalent of docmd-i18n-strings.js - it produces + * fully translated HTML that search engines can index. + */ +export function applyStringModeReplacements(html: string, strings: Record, localeId: string, localeDir?: string): string { + if (!strings || Object.keys(strings).length === 0) return html; + + // 1. data-i18n="key" โ†’ replace textContent + // Match: content + html = html.replace( + /(<[^>]+\sdata-i18n="([^"]+)"[^>]*>)([\s\S]*?)(<\/[a-zA-Z][a-zA-Z0-9]*>)/g, + (match, openTag, key, _content, closeTag) => { + if (strings[key] !== undefined) { + return openTag + strings[key] + closeTag; + } + return match; + } + ); + + // 2. data-i18n-html="key" โ†’ replace innerHTML + html = html.replace( + /(<[^>]+\sdata-i18n-html="([^"]+)"[^>]*>)([\s\S]*?)(<\/[a-zA-Z][a-zA-Z0-9]*>)/g, + (match, openTag, key, _content, closeTag) => { + if (strings[key] !== undefined) { + return openTag + strings[key] + closeTag; + } + return match; + } + ); + + // 3. data-i18n-{attr}="key" โ†’ replace the target attribute value + // e.g. data-i18n-placeholder="search.placeholder" placeholder="Search..." + html = html.replace( + /(<[^>]+)\sdata-i18n-(?!html)([a-zA-Z][\w-]*)="([^"]+)"([^>]*>)/g, + (match, before, targetAttr, key, after) => { + if (strings[key] !== undefined) { + // Replace the target attribute's value + const attrRegex = new RegExp(`(${targetAttr})="[^"]*"`); + const fullTag = before + ' data-i18n-' + targetAttr + '="' + key + '"' + after; + if (attrRegex.test(fullTag)) { + return fullTag.replace(attrRegex, `$1="${strings[key]}"`); + } + } + return match; + } + ); + + // 4. Update to the target locale + html = html.replace(/ { + const newItem = { ...item }; + + if (newItem.children) { + newItem.children = filterNavForVersion(newItem.children, vSrcDir, fallbackSrcDir); + } + + if (newItem.path && !newItem.path.startsWith('http') && !newItem.external) { + let relativeFilePath = newItem.path.replace(/^\//, ''); + // Reverse clean-URL normalisation to find the source file + if (relativeFilePath.endsWith('/') || relativeFilePath === '') { + // Trailing slash (or root) โ†’ could be folder/index.md or folder/README.md or file.md + const dir = relativeFilePath.replace(/\/$/, ''); + const fileCandidate = dir ? dir + '.md' : ''; + const indexCandidates = dir + ? [dir + '/index.md', dir + '/README.md', dir + '/readme.md', fileCandidate] + : ['index.md', 'README.md', 'readme.md']; + + const found = indexCandidates.find(c => { + if (!c) return false; + const abs = path.join(vSrcDir, c); + if (nodeFs.existsSync(abs)) return true; + if (fallbackSrcDir && nodeFs.existsSync(path.join(fallbackSrcDir, c))) return true; + return false; + }); + relativeFilePath = found || (dir ? dir + '/index.md' : 'index.md'); + } else if (!relativeFilePath.endsWith('.md')) { + relativeFilePath += '.md'; + } + + const absoluteFilePath = path.join(vSrcDir, relativeFilePath); + try { + if (!nodeFs.existsSync(absoluteFilePath)) { + // If a fallback dir exists, check there too before removing + if (fallbackSrcDir) { + const fallbackFilePath = path.join(fallbackSrcDir, relativeFilePath); + try { + if (!nodeFs.existsSync(fallbackFilePath)) return acc; + } catch { return acc; } + } else { + return acc; + } + } + } catch { return acc; } + } + + acc.push(newItem); + return acc; + }, []); +} + +/** + * Resolve the active navigation for a version - checks for navigation.json (Nav V2), + * then per-version config override, then falls back to the global config navigation. + */ +export function resolveVersionNav(v: any, vSrcDir: string, configNavigation: any): any { + let activeNav = configNavigation; + + try { + const navJsonPath = path.join(vSrcDir, 'navigation.json'); + if (nodeFs.existsSync(navJsonPath)) { + const rawNav = nodeFs.readFileSync(navJsonPath, 'utf-8'); + activeNav = JSON.parse(rawNav); + } else if (v.navigation) { + activeNav = v.navigation; + } + } catch (err) { + TUI.warn(`Failed to parse navigation.json in ${vSrcDir}: ${err.message}`); + activeNav = v.navigation || configNavigation; + } + + // Clone activeNav before mutating to avoid modifying global config + activeNav = JSON.parse(JSON.stringify(activeNav)); + normalizeNavPaths(activeNav); + + return activeNav; +} + +/** + * Build all versions for a given base config and output directory. + * Returns pages array with output paths prefixed for non-current versions. + */ +export async function buildVersions({ + config, + outputDir, + hooks, + buildHash, + options, + CWD, + pathPrefix = '', + onProgress, + targetFiles, + coreVersion +}: { + config: any; + outputDir: string; + hooks: any; + buildHash: string; + options: any; + CWD: string; + pathPrefix?: string; + onProgress?: (current: number, total: number) => void; + targetFiles?: string[]; + coreVersion?: string; +}): Promise { + const allPages = []; + + // Pre-scan: determine which versions have i18n support for the current locale + const versionI18nMap: Record = {}; + for (const v of config.versions.all) { + const baseSrcDir = path.resolve(CWD, v.dir); + const localeSrcDir = resolveLocaleSrcDir(baseSrcDir, config); + versionI18nMap[v.id] = await fs.exists(localeSrcDir); + } + config._versionI18nMap = versionI18nMap; + + for (const v of config.versions.all) { + const isCurrent = v.id === config.versions.current; + const baseSrcDir = path.resolve(CWD, v.dir); + + // When i18n is enabled, resolve to the locale-specific subdirectory + // e.g., docs/ โ†’ docs/en/ for English locale + // Graceful fallback: if the locale subdir doesn't exist but the base dir does, + // use the base dir directly (supports old versions without locale dirs) + let vSrcDir = resolveLocaleSrcDir(baseSrcDir, config); + let fallbackSrcDir = resolveFallbackSrcDir(baseSrcDir, config); + let versionHasI18n = true; + + if (!await fs.exists(vSrcDir) && await fs.exists(baseSrcDir)) { + // Locale subdir doesn't exist but base dir does - this version has no i18n structure + versionHasI18n = false; + if (config._activeLocale && config._activeLocale.id !== config._defaultLocale) { + // Non-default locale: skip entirely (no translations for this version) + continue; + } + // Default locale: use the base dir directly (backward compat for old versions) + vSrcDir = baseSrcDir; + fallbackSrcDir = null; + } + + if (!await fs.exists(vSrcDir)) { + if (!options.isDev) TUI.warn(`Version directory missing: ${v.dir}. Skipping ${v.id}...`); + continue; + } + + // Determine the full output prefix for this version combining locale prefix + version prefix + // Only non-current versions get a version prefix. + const versionPrefixSegment = isCurrent ? '' : v.id + '/'; + const combinedOutputPrefix = pathPrefix + versionPrefixSegment; + + const activeNav = resolveVersionNav(v, vSrcDir, config.navigation); + const cleanedNav = filterNavForVersion(activeNav, vSrcDir, fallbackSrcDir); + + const versionedConfig = { + ...config, + _activeVersion: v, + _versionHasI18n: versionHasI18n, + navigation: cleanedNav + }; + + const pages = await renderPages({ + config: versionedConfig, + srcDir: vSrcDir, + fallbackSrcDir, + outputDir, // We always pass root outputDir so relativePathToRoot computes perfectly + hooks, + buildHash, + options, + outputPrefix: combinedOutputPrefix, + onProgress, + targetFiles, + coreVersion + }); + + allPages.push(...pages); + } + + return allPages; +} \ No newline at end of file diff --git a/packages/core/src/engine/worker-parser.ts b/packages/core/src/engine/worker-parser.ts new file mode 100644 index 0000000..12302c8 --- /dev/null +++ b/packages/core/src/engine/worker-parser.ts @@ -0,0 +1,170 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * -------------------------------------------------------------------- + */ + +/** + * Worker-thread parser + * ==================== + * + * Each docmd worker thread runs an independent copy of this module โ€” + * Node.js `worker_threads` load modules per worker, so `mdProcessor`, + * `hooks`, and `config` below are PER-WORKER state, not shared across + * threads. Phase 2 (F1โ€“F5) requires that two workers given the same + * input produce byte-identical HTML; the determinism contract is + * enforced by: + * + * 1. `mdProcessor` is instantiated inside `init()` on this worker, + * never imported from the main thread. + * 2. `hooks` are loaded on this worker via `loadPlugins(config, ...)`. + * No plugin module is cached across workers. + * 3. `config` is the structured-clone snapshot from `workerData` โ€” + * no live reference to the main-thread config object. + * 4. The container normaliser (`@docmd/parser/utils/container-normaliser`) + * is a pure function of its input โ€” no `Date.now()`, no + * `Math.random()`, no module-level mutable state. The determinism + * test fixture at `packages/parser/test/container-normaliser.test.js` + * verifies this empirically (100-way concurrency + cross-worker). + * 5. `verifyDeterminismAtBoot()` runs a known input through the + * freshly-built processor at the end of `init()` and asserts the + * output matches the snapshot. Any future regression that breaks + * determinism crashes the worker before the first message is + * processed. + * + * If you add any module-level mutable state to this file or to the + * parser pipeline, the boot-time self-test will fail and the worker + * will refuse to start. That is the structural fence. + */ + +import { parentPort, workerData } from 'node:worker_threads'; +import { loadPlugins } from '@docmd/api'; +import { createMarkdownProcessor, processContentAsync } from '@docmd/parser'; +import * as ui from '@docmd/ui'; + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// Per-worker state โ€” `let` is intentional; these are populated by +// `init()` and frozen-equivalent after that point. +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +let mdProcessor: any; +let hooks: any; +let config: any; + +/** + * Determinism snapshot. Two workers given the same input MUST produce + * the same HTML. We assert this at boot by parsing a known input and + * comparing the output to this frozen string. Any future code change + * that introduces non-determinism (Date.now, Math.random, shared + * module-level state, etc.) crashes the worker before it processes + * its first real message. + * + * The snapshot is intentionally a small, isolated example โ€” a balanced + * callout with a self-closing tag โ€” that exercises the normaliser + * (no warnings expected), the depth tracker, the renderer pipeline, + * and the heading ID plugin. + */ +const DETERMINISM_SNAPSHOT_INPUT = '# Hi\n\n::: callout info "T"\nbody\n:::\n'; +const DETERMINISM_SNAPSHOT_OUTPUT = '

Hi

\n
T
\n

body

\n
\n'; + +async function init() { + config = workerData.config; + const cwd = workerData.cwd; + + // 1. Re-hydrate hooks by loading plugins within the worker boundary. + hooks = await loadPlugins(config, { resolvePaths: [cwd] }); + + // 2. Re-hydrate UI strings for the markdown processor (for heading anchors, etc.) + const localeId = config._activeLocale?.id || null; + const pluginTranslations = hooks.translations + ? await hooks.translations.reduce(async (accP: any, fn: any) => ({ ...(await accP), ...(await fn(localeId)) }), {}) + : {}; + const userLocaleTranslations = config._activeLocale?.translations || {}; + const strings = ui.loadTranslations(localeId, { ...pluginTranslations, ...userLocaleTranslations }); + const configWithStrings = { ...config, _uiStrings: strings }; + + // 3. Instantiate the exact same Markdown-It pipeline as the main thread + mdProcessor = createMarkdownProcessor(configWithStrings, (md: any) => { + hooks.markdownSetup.forEach((hook: any) => hook(md)); + }); + + // 4. Boot-time determinism self-test. Crashes the worker if the + // parser output diverges from the snapshot, which means the + // parser is no longer deterministic and parallel workers may + // produce different HTML for the same input. + await verifyDeterminismAtBoot(); +} + +/** + * Boot-time determinism check. Parses `DETERMINISM_SNAPSHOT_INPUT` + * through the freshly-built processor and asserts the output equals + * `DETERMINISM_SNAPSHOT_OUTPUT`. If it doesn't, this is a regression + * โ€” the worker crashes with a clear error message before processing + * any real message. + */ +async function verifyDeterminismAtBoot(): Promise { + const result = await processContentAsync( + DETERMINISM_SNAPSHOT_INPUT, + mdProcessor, + config, + { filePath: '' }, + hooks + ); + if (result.htmlContent !== DETERMINISM_SNAPSHOT_OUTPUT) { + throw new Error( + '[docmd] Parser determinism regression detected at worker boot.\n' + + ' Expected:\n' + JSON.stringify(DETERMINISM_SNAPSHOT_OUTPUT) + '\n' + + ' Actual:\n' + JSON.stringify(result.htmlContent) + '\n' + + ' This means two worker threads given the same input may now\n' + + ' produce different HTML โ€” the parser pipeline is no longer\n' + + ' deterministic. Audit `packages/parser/src/` for any new\n' + + ' module-level mutable state, Date.now, Math.random, or\n' + + ' non-pure helpers.' + ); + } +} + +// Start initialization immediately upon worker thread spawn +const initPromise = init(); + +parentPort?.on('message', async (task) => { + try { + // Ensure the worker is fully initialized before processing any task + await initPromise; + + // Support generic tasks for plugins leveraging the WorkerPool + if (task.payload && task.payload.type === 'plugin-task') { + const { modulePath, functionName, args } = task.payload; + const mod = await import(modulePath); + const result = await mod[functionName](...args); + parentPort?.postMessage({ + taskId: task.id, + success: true, + data: result + }); + return; + } + + const { rawContent, env } = task.payload; + + // Process the content (includes frontmatter extraction, hooks execution, and HTML rendering) + const processed = await processContentAsync(rawContent, mdProcessor, config, env, hooks); + + parentPort?.postMessage({ + taskId: task.id, + success: true, + data: processed + }); + } catch (error: any) { + parentPort?.postMessage({ + taskId: task.id, + success: false, + error: error.message || String(error) + }); + } +}); \ No newline at end of file diff --git a/packages/core/src/engine/workspace.ts b/packages/core/src/engine/workspace.ts new file mode 100644 index 0000000..ccb387e --- /dev/null +++ b/packages/core/src/engine/workspace.ts @@ -0,0 +1,768 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * Workspace Handler. + * + * Enables a single docmd instance to build multiple independent + * documentation projects under one domain. + * + * Root config: + * workspace: { + * projects: [ + * { prefix: '/', src: 'docmd-main' }, + * { prefix: '/search', src: 'docmd-search' } + * ] + * } + * + * Each project folder has its own docmd.config.json with its own + * title, versions, i18n, plugins, navigation, etc. + * + * Output merges into a single site/ directory: + * site/ โ† root project + * site/search/ โ† prefixed project + * + * Assets: + * - Root-level assets/ are shared across all projects + * - Each project can have its own assets/ that override shared ones + */ + +import path from 'path'; +import { fsUtils as fs, FileSignatureTracker } from '@docmd/utils'; +import nativeFs from 'fs'; +import { TUI } from '@docmd/tui'; +import { loadConfig } from '../utils/config-loader.js'; +import { buildSite } from '../commands/build.js'; +import { createOriginVerify } from '../utils/ws-origin-guard.js'; + +/* โ”€โ”€ Types โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +export interface ProjectEntry { + /** URL prefix. '/' for root, '/search' for subpath. */ + prefix: string; + /** Source directory relative to CWD (contains the project's docmd.config.js). */ + src: string; + /** Optional: Display title for the project switcher. */ + title?: string; +} + +export interface WorkspaceConfig { + /** The list of projects in the workspace. */ + projects: ProjectEntry[]; + /** Project switcher configuration. */ + switcher?: { + enabled?: boolean; + position?: 'sidebar-top' | 'sidebar-bottom' | 'options-menu'; + }; +} + +export interface WorkspaceRootConfig { + /** The workspace configuration. */ + workspace?: WorkspaceConfig; + /** Legacy projects array (deprecated, maps to workspace.projects). */ + projects?: ProjectEntry[]; + /** Shared output directory. Default: 'site' */ + out?: string; + /** Internal: Absolute path to the config file itself. Used for hot-reloading. */ + _resolvedPath?: string; + /** Internal: Any other root keys act as global defaults. */ + [key: string]: any; +} + +/* โ”€โ”€ Detection โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +/** + * Check if a raw config object is a workspace config. + */ +export function isWorkspace(rawConfig: any): rawConfig is WorkspaceRootConfig { + if (!rawConfig) return false; + + // New 'workspace' schema + if (rawConfig.workspace && Array.isArray(rawConfig.workspace.projects)) { + return rawConfig.workspace.projects.every((p: any) => + typeof p.prefix === 'string' && typeof p.src === 'string' + ); + } + + // Legacy 'projects' schema (for backward compatibility) + if (Array.isArray(rawConfig.projects) && rawConfig.projects.length > 0) { + return rawConfig.projects.every((p: any) => + typeof p.prefix === 'string' && typeof p.src === 'string' + ); + } + + return false; +} + +/** + * Load the raw config file without normalization to check for workspace settings. + */ +export async function detectWorkspace(configPathOption: string): Promise { + const CWD = process.cwd(); + let absolutePath = path.resolve(CWD, configPathOption); + + if (configPathOption === 'docmd.config.js') { + const candidates = [ + 'docmd.config.json', + 'docmd.config.ts', + 'docmd.config.js', + 'docmd.config.mjs', + 'config.js' + ]; + let found = false; + for (const c of candidates) { + const p = path.resolve(CWD, c); + if (nativeFs.existsSync(p)) { + absolutePath = p; + found = true; + break; + } + } + if (!found) return null; + } else if (!nativeFs.existsSync(absolutePath)) { + return null; + } + + try { + let rawConfig: any; + + if (absolutePath.endsWith('.json')) { + rawConfig = JSON.parse(nativeFs.readFileSync(absolutePath, 'utf-8')); + } else { + // Polyfill defineConfig + (global as any).defineConfig = (config: any) => config; + + const ts = Date.now(); + const ext = path.extname(absolutePath); + const tempPath = absolutePath.replace(new RegExp(`\\${ext}$`), `-${ts}${ext}`); + nativeFs.copyFileSync(absolutePath, tempPath); + + const { pathToFileURL } = await import('url'); + const configUrl = pathToFileURL(tempPath).href; + const rawModule = await import(configUrl); + rawConfig = rawModule.default || rawModule; + + nativeFs.unlinkSync(tempPath); + delete (global as any).defineConfig; + } + + if (isWorkspace(rawConfig)) { + rawConfig._resolvedPath = absolutePath; + + // Internal normalization: map legacy 'projects' to 'workspace.projects' + if (!rawConfig.workspace && rawConfig.projects) { + rawConfig.workspace = { + projects: rawConfig.projects, + switcher: { enabled: true, position: 'sidebar-top' } + }; + } else if (rawConfig.workspace) { + // Ensure default switcher settings + rawConfig.workspace.switcher = { + enabled: true, + position: 'sidebar-top', + ...rawConfig.workspace.switcher + }; + } + + // Return workspace config only if it has workspace settings + // This prevents false positives when a config has a 'workspace' field but no projects + if (rawConfig.workspace && rawConfig.workspace.projects) { + return rawConfig as WorkspaceRootConfig; + } + + return null; + } + return null; + } catch { + delete (global as any).defineConfig; + return null; + } +} + +/* โ”€โ”€ Validation โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +function validateProjects(projects: ProjectEntry[]): void { + const prefixes = new Set(); + let hasRoot = false; + + for (const project of projects) { + // Normalize prefix + const prefix = project.prefix === '/' ? '/' : project.prefix.replace(/\/$/, ''); + + if (prefixes.has(prefix)) { + throw new Error(`Duplicate project prefix: "${prefix}"`); + } + prefixes.add(prefix); + + if (prefix === '/') hasRoot = true; + + // Verify source directory exists + const srcPath = path.resolve(process.cwd(), project.src); + if (!nativeFs.existsSync(srcPath)) { + throw new Error(`Project source directory not found: ${project.src}`); + } + } + + if (!hasRoot) { + throw new Error( + 'Workspace configuration must include a root project with prefix "/".\n' + + 'Each workspace needs one project that owns the site root, with the others mounted under their own prefixes.\n' + + 'Example:\n' + + ' {\n' + + ' "workspace": {\n' + + ' "projects": [\n' + + ' { "name": "main", "src": "./docs", "prefix": "/" },\n' + + ' { "name": "api", "src": "./api-docs", "prefix": "/api/" }\n' + + ' ]\n' + + ' }\n' + + ' }\n' + + 'See https://docs.docmd.io/configuration/workspaces/ for the full layout guide.' + ); + } + + // Check for potential conflicts + const rootProject = projects.find(p => p.prefix === '/'); + if (rootProject) { + const rootSrcPath = path.resolve(process.cwd(), rootProject.src); + for (const project of projects) { + if (project.prefix === '/') continue; + const prefixName = project.prefix.replace(/^\//, ''); + const conflictPath = path.join(rootSrcPath, prefixName); + if (nativeFs.existsSync(conflictPath)) { + TUI.warn(`Potential conflict: Root project has "${prefixName}/" folder which may conflict with project prefix "${project.prefix}".`); + TUI.warn(`Content at "${rootProject.src}/${prefixName}/" will be overwritten by project "${project.src}".`); + } + } + } +} + +/* โ”€โ”€ Build โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +/** + * Build all projects in a workspace. + */ +export async function buildWorkspace( + workspaceConfig: WorkspaceRootConfig, + opts: { isDev?: boolean; offline?: boolean; quiet?: boolean; verbose?: boolean } = {} +): Promise { + const CWD = process.cwd(); + const rootOutDir = path.resolve(CWD, workspaceConfig.out || 'site'); + const totalElapsed = TUI.timer(); + + const workspace = workspaceConfig.workspace!; + validateProjects(workspace.projects); + + // Extract global defaults + const globalDefaults: Record = {}; + const skipKeys = ['workspace', 'projects', 'out', '_resolvedPath']; + for (const key of Object.keys(workspaceConfig)) { + if (!skipKeys.includes(key) && !key.startsWith('_')) { + globalDefaults[key] = workspaceConfig[key]; + } + } + + // Sort: root project first, then alphabetical + const sorted = [...workspace.projects].sort((a, b) => { + if (a.prefix === '/') return -1; + if (b.prefix === '/') return 1; + return a.prefix.localeCompare(b.prefix); + }); + + if (!opts.quiet) { + TUI.section(`Workspace Build (${sorted.length} projects)`); + } + + // Ensure clean output directory + await fs.ensureDir(rootOutDir); + + // Copy shared assets first + const sharedAssetsDir = path.resolve(CWD, 'assets'); + if (nativeFs.existsSync(sharedAssetsDir)) { + if (!opts.quiet) { + TUI.item('Shared assets', path.relative(CWD, sharedAssetsDir), TUI.dim, TUI.cyan); + } + } + + if (!opts.quiet) { + TUI.footer(TUI.cyan); + } + + for (const project of sorted) { + const prefix = project.prefix === '/' ? '/' : project.prefix.replace(/\/$/, ''); + const projectSrcDir = path.resolve(CWD, project.src); + + const candidates = ['docmd.config.json', 'docmd.config.ts', 'docmd.config.js', 'docmd.config.mjs', 'config.js']; + let resolvedConfigName: string | null = null; + for (const c of candidates) { + if (nativeFs.existsSync(path.join(projectSrcDir, c))) { + resolvedConfigName = c; + break; + } + } + const hasProjectConfig = resolvedConfigName !== null; + const configFileToUse = resolvedConfigName || 'docmd.config.js'; + + const projectOutDir = prefix === '/' + ? rootOutDir + : path.join(rootOutDir, prefix.replace(/^\//, '')); + + const label = prefix === '/' ? `/ (root)` : prefix; + + if (!opts.quiet) { + TUI.section(`Building Project: ${label}`); + + const originalCwdCheck = process.cwd(); + process.chdir(projectSrcDir); + try { + const childConfig = await loadConfig(configFileToUse, { isDev: opts.isDev, quiet: true }); + const childDetails = TUI.extractProjectDetails(childConfig, projectOutDir, CWD); + TUI.projectDetails({ + engine: childConfig.engine && childConfig.engine !== 'js' ? childConfig.engine : undefined, + source: `${project.src}/`, + output: `${path.relative(CWD, projectOutDir)}/`, + versions: childDetails.versions, + locales: childDetails.locales, + }); + } catch { + TUI.item('Source', `${project.src}/`, TUI.dim, TUI.cyan); + TUI.item('Output', `${path.relative(CWD, projectOutDir)}/`, TUI.dim, TUI.cyan); + } finally { + process.chdir(originalCwdCheck); + } + + if (!hasProjectConfig) { + TUI.item('Config', 'zero-config (no docmd.config.json found)', TUI.dim, TUI.cyan); + } + } + + const originalCwd = process.cwd(); + process.chdir(projectSrcDir); + + try { + process.env.DOCMD_PROJECT_OUT = projectOutDir; + process.env.DOCMD_PROJECT_PREFIX = prefix; + + if (nativeFs.existsSync(sharedAssetsDir)) { + await fs.ensureDir(path.join(projectOutDir, 'assets')); + await fs.copy(sharedAssetsDir, path.join(projectOutDir, 'assets')); + } + + await buildSite(configFileToUse, { + isDev: opts.isDev || false, + offline: opts.offline || false, + // Pass through quiet so the first build (quiet:false) shows git/search + // indexing progress. Live-reload rebuilds always arrive with quiet:true + // from buildWorkspaceProject, so they stay silent. + quiet: opts.quiet || false, + // Forward --verbose so the per-project normaliser prints every + // container issue (unclosed ::: card, stray :::, etc.). Without + // this, `docmd build --verbose` on a workspace config silently + // drops the flag and only the aggregate error count is shown. + verbose: opts.verbose || false, + _globalDefaults: globalDefaults, + _workspace: workspace, + _activePrefix: prefix + }); + + if (!opts.quiet) { + TUI.footer(TUI.cyan); + } + + } catch (err: any) { + if (!opts.quiet) { + TUI.step(`Project ${label} build failed`, 'FAIL', TUI.cyan); + TUI.footer(TUI.cyan); + } + TUI.error(`Build failed for ${label}`, err.message); + if (!opts.isDev) process.exit(1); + } finally { + process.chdir(originalCwd); + delete process.env.DOCMD_PROJECT_OUT; + delete process.env.DOCMD_PROJECT_PREFIX; + } + } + + if (!opts.quiet) { + const totalSize = await getDirectorySize(rootOutDir); + TUI.success(`Workspace build complete. ${sorted.length} projects โ†’ ${path.relative(CWD, rootOutDir)}/ (${formatBytes(totalSize)}) in ${totalElapsed()}.\n`); + } +} + +/* โ”€โ”€ Single Project Build โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +async function buildWorkspaceProject( + project: ProjectEntry, + workspaceConfig: WorkspaceRootConfig, + opts: { isDev?: boolean; offline?: boolean; quiet?: boolean; verbose?: boolean; targetFiles?: string[] } = {} +): Promise { + const CWD = process.cwd(); + const rootOutDir = path.resolve(CWD, workspaceConfig.out || 'site'); + const workspace = workspaceConfig.workspace!; + const prefix = project.prefix === '/' ? '/' : project.prefix.replace(/\/$/, ''); + const projectSrcDir = path.resolve(CWD, project.src); + + const candidates = ['docmd.config.json', 'docmd.config.ts', 'docmd.config.js', 'docmd.config.mjs', 'config.js']; + let resolvedConfigName: string | null = null; + for (const c of candidates) { + if (nativeFs.existsSync(path.join(projectSrcDir, c))) { + resolvedConfigName = c; + break; + } + } + const configFileToUse = resolvedConfigName || 'docmd.config.js'; + + const projectOutDir = prefix === '/' + ? rootOutDir + : path.join(rootOutDir, prefix.replace(/^\//, '')); + + const label = prefix === '/' ? '/ (root)' : prefix; + + const originalCwd = process.cwd(); + process.chdir(projectSrcDir); + + try { + process.env.DOCMD_PROJECT_OUT = projectOutDir; + process.env.DOCMD_PROJECT_PREFIX = prefix; + + const sharedAssetsDir = path.resolve(CWD, 'assets'); + if (nativeFs.existsSync(sharedAssetsDir)) { + await fs.ensureDir(path.join(projectOutDir, 'assets')); + await fs.copy(sharedAssetsDir, path.join(projectOutDir, 'assets')); + } + + const globalDefaults: Record = {}; + const skipKeys = ['workspace', 'projects', 'out', '_resolvedPath']; + for (const key of Object.keys(workspaceConfig)) { + if (!skipKeys.includes(key) && !key.startsWith('_')) { + globalDefaults[key] = workspaceConfig[key]; + } + } + + await buildSite(configFileToUse, { + isDev: opts.isDev || false, + offline: opts.offline || false, + quiet: true, + // Forward --verbose to the per-project build so container + // normaliser issues are listed per file in verbose mode. + verbose: opts.verbose || false, + targetFiles: opts.targetFiles, + _globalDefaults: globalDefaults, + _workspace: workspace, + _activePrefix: prefix + }); + + } catch (err: any) { + TUI.error(`Build failed for ${label}`, err.message); + throw err; + } finally { + process.chdir(originalCwd); + delete process.env.DOCMD_PROJECT_OUT; + delete process.env.DOCMD_PROJECT_PREFIX; + } +} + +/* โ”€โ”€ Dev Server Wrapper โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +/** + * Start dev server for workspace mode. + */ +export async function devWorkspace( + workspaceConfig: WorkspaceRootConfig, + opts: { port?: string; preserve?: boolean } = {} +): Promise { + try { + await buildWorkspace(workspaceConfig, { isDev: true }); + } catch (err: any) { + TUI.error('Initial build failed', err.message); + } + + const CWD = process.cwd(); + const rootOutDir = path.resolve(CWD, workspaceConfig.out || 'site'); + + const { serveStatic, findAvailablePort, formatPathForDisplay, getNetworkIp, openBrowser } = await import('../utils/dev-utils.js'); + const http = await import('http'); + const { WebSocketServer, WebSocket } = await import('ws'); + + const state = { outputDir: rootOutDir }; + const server = http.createServer((req: any, res: any) => serveStatic(req, res, state.outputDir)); + + const PORT = parseInt(opts.port || process.env.PORT || '3000', 10); + const port = await findAvailablePort(PORT); + + let wss: any; + + function broadcastReload() { + if (wss) { + wss.clients.forEach((client: any) => { + if (client.readyState === WebSocket.OPEN) client.send('reload'); + }); + } + } + + // Phase 1.D: default to loopback. Set DOCMD_HOST=0.0.0.0 to expose on LAN + // (with the verifyClient callback below still guarding the Origin header). + const BIND_HOST = process.env.DOCMD_HOST || '127.0.0.1'; + + server.listen(port, BIND_HOST, () => { + if (BIND_HOST !== '127.0.0.1' && BIND_HOST !== '::1' && BIND_HOST !== 'localhost') { + TUI.warn(`Workspace dev server bound to ${BIND_HOST} (LAN). verifyClient guards Origin.`); + } + const networkIp = getNetworkIp(); + // Phase 1.D: CWE-1385 CSWSH fix (N-S1). Even when bound to LAN, the + // verifyClient callback rejects any Origin that isn't loopback or the + // LAN IP returned by getNetworkIp(). + wss = new WebSocketServer({ + server, + verifyClient: createOriginVerify(networkIp ? [networkIp] : []), + }); + wss.on('error', (e: any) => TUI.error('WebSocket Error', e.message)); + + const localUrl = `http://127.0.0.1:${port}`; + const networkUrl = networkIp ? `http://${networkIp}:${port}` : null; + + TUI.section('Workspace Dev Server Running', TUI.green); + TUI.item('', '', TUI.dim, TUI.green); + TUI.item('Local Access', localUrl, TUI.bold, TUI.green); + if (networkUrl) { + TUI.item('Network Access', networkUrl, TUI.bold, TUI.green); + } + TUI.item('Serving from', formatPathForDisplay(rootOutDir, CWD), TUI.dim, TUI.green); + TUI.item('', '', TUI.dim, TUI.green); + + const workspace = workspaceConfig.workspace!; + for (const project of workspace.projects) { + const pfx = project.prefix === '/' ? '/' : project.prefix; + TUI.item('Project', localUrl + pfx, TUI.dim, TUI.green); + } + TUI.item('', '', TUI.dim, TUI.green); + TUI.footer(TUI.green); + + // Auto-launch localhost URL in default browser + openBrowser(localUrl); + }); + + let isRebuilding = false; + let rebuildTimeout: any = null; + let lastContentRebuildAt = 0; + let lastConfigRebuildAt = 0; + // Quiet windows after a rebuild to absorb phantom fs.watch events macOS + // emits for newly-written nearby files. The primary defence is the + // content-signature check (FileSignatureTracker) below; these are + // secondary cushions. + // - 1000ms after a content rebuild + // - 2500ms after a full workspace config rebuild (cascades everywhere) + const CONTENT_QUIET_MS = 1000; + const CONFIG_QUIET_MS = 2500; + // Tracks each watched file's mtime+size signature so phantom fs.watch + // events that don't actually mutate the file are silently ignored. + const signatureTracker = new FileSignatureTracker(); + + const workspace = workspaceConfig.workspace!; + for (const project of workspace.projects) { + const projectSrcDir = path.resolve(CWD, project.src); + + if (!nativeFs.existsSync(projectSrcDir)) continue; + + nativeFs.watch(projectSrcDir, { recursive: true }, (event, filename) => { + if (!filename) return; + + // Post-rebuild quiet period + if (Date.now() - lastContentRebuildAt < CONTENT_QUIET_MS) return; + if (Date.now() - lastConfigRebuildAt < CONFIG_QUIET_MS) return; + + if (filename.includes('.git') || filename.includes('node_modules') || + filename.includes('.DS_Store') || filename.startsWith('.') || + filename.includes('docmd.config-') || filename.endsWith('.js.bak')) return; + + // Exclude build output + const resolvedOut = path.resolve(CWD, workspaceConfig.out || 'site'); + const filePath = path.resolve(projectSrcDir, filename); + if (filePath.startsWith(resolvedOut + path.sep) || filePath === resolvedOut) return; + + // Content-signature gate: ignore phantom events that don't actually + // mutate the file (Spotlight reindex, iCloud sync, etc.). + if (!signatureTracker.hasChanged(filePath)) return; + + if (rebuildTimeout) clearTimeout(rebuildTimeout); + rebuildTimeout = setTimeout(async () => { + if (isRebuilding) return; + isRebuilding = true; + + const isConfigUpdate = (filename.includes('docmd.config') && !filename.includes('docmd.config-')) || filename.includes('navigation.json'); + const label = project.prefix === '/' ? '/' : project.prefix; + const displayPath = filename.replace(/^[^/]+\//, ''); + const rebuildElapsed = TUI.timer(); + + if (isConfigUpdate) { + TUI.step(`Reloading config and rebuilding [${label}]`, 'WAIT', TUI.blue, true); + } else { + TUI.step(`Rebuilding [${label}] ${displayPath}`, 'WAIT', TUI.blue, true); + } + + try { + const fullChangedPath = path.resolve(projectSrcDir, filename); + await buildWorkspaceProject(project, workspaceConfig, { + isDev: true, + targetFiles: isConfigUpdate ? undefined : [fullChangedPath] + }); + if (isConfigUpdate) { + lastConfigRebuildAt = Date.now(); + signatureTracker.reset(); + } else { + lastContentRebuildAt = Date.now(); + } + broadcastReload(); + TUI.step(`Rebuilt [${label}] ${isConfigUpdate ? 'with new config' : displayPath} in ${rebuildElapsed()}`, 'DONE', TUI.blue, true); + } catch (err: any) { + TUI.step(`Rebuild [${label}] ${displayPath}`, 'FAIL', TUI.blue, true); + TUI.error('Rebuild failed', err.message); + } finally { + isRebuilding = false; + } + }, 600); // 600ms idle: rebuild only after user stops saving + }); + } + + if (workspaceConfig._resolvedPath && nativeFs.existsSync(workspaceConfig._resolvedPath)) { + let rootConfigDebounce: any = null; + // Watch the parent directory rather than the file directly โ€” far more + // stable on macOS, where direct-file fs.watch fires phantom events from + // Spotlight / iCloud / Time Machine. + const rootConfigPath = workspaceConfig._resolvedPath; + const rootConfigDir = path.dirname(rootConfigPath); + const rootConfigBaseName = path.basename(rootConfigPath); + + nativeFs.watch(rootConfigDir, (event, filename) => { + if (!filename) return; + if (filename !== rootConfigBaseName) return; + + // Post-rebuild quiet period + if (Date.now() - lastConfigRebuildAt < CONFIG_QUIET_MS) return; + + // Content-signature gate: ignore phantom events that don't actually + // mutate the file. + if (!signatureTracker.hasChanged(rootConfigPath)) return; + + if (rootConfigDebounce) clearTimeout(rootConfigDebounce); + rootConfigDebounce = setTimeout(async () => { + rootConfigDebounce = null; + if (isRebuilding) return; + isRebuilding = true; + + const rebuildElapsed = TUI.timer(); + TUI.step('Reloading workspace config...', 'WAIT', TUI.blue, true); + + try { + const { detectWorkspace } = await import('./workspace.js'); + const newWorkspaceConfig = await detectWorkspace(rootConfigBaseName); + if (newWorkspaceConfig) { + Object.assign(workspaceConfig, newWorkspaceConfig); + await buildWorkspace(newWorkspaceConfig, { isDev: true, quiet: true }); + lastConfigRebuildAt = Date.now(); + signatureTracker.reset(); + broadcastReload(); + TUI.step(`Rebuilt entire workspace with new config in ${rebuildElapsed()}`, 'DONE', TUI.blue, true); + } + } catch (err: any) { + TUI.step('Workspace Rebuild', 'FAIL', TUI.blue, true); + TUI.error('Rebuild failed', err.message); + } finally { + isRebuilding = false; + } + }, 500); + }); + } + + if (nativeFs.existsSync(path.resolve(CWD, 'assets'))) { + const sharedAssetsDir = path.resolve(CWD, 'assets'); + nativeFs.watch(sharedAssetsDir, { recursive: true }, (event, filename) => { + if (!filename) return; + // Post-rebuild quiet period + if (Date.now() - lastContentRebuildAt < CONTENT_QUIET_MS) return; + if (Date.now() - lastConfigRebuildAt < CONFIG_QUIET_MS) return; + + // Content-signature gate: ignore phantom events that don't actually + // mutate the file. + const filePath = path.resolve(sharedAssetsDir, filename); + if (!signatureTracker.hasChanged(filePath)) return; + + if (rebuildTimeout) clearTimeout(rebuildTimeout); + rebuildTimeout = setTimeout(async () => { + if (isRebuilding) return; + isRebuilding = true; + + const rebuildElapsed = TUI.timer(); + TUI.step('Shared assets changed โ€” rebuilding all', 'WAIT', TUI.blue, true); + + try { + await buildWorkspace(workspaceConfig, { isDev: true, quiet: true }); + lastContentRebuildAt = Date.now(); + broadcastReload(); + TUI.step(`All projects rebuilt in ${rebuildElapsed()}`, 'DONE', TUI.blue, true); + } catch (err: any) { + TUI.step('Rebuild all projects', 'FAIL', TUI.blue, true); + TUI.error('Rebuild failed', err.message); + } finally { + isRebuilding = false; + } + }, 600); // 600ms idle: rebuild only after user stops saving + }); + } + + if (process.stdin.isTTY) { + process.stdin.setRawMode(true); + process.stdin.resume(); + process.stdin.on('data', (data) => { + if (data[0] === 0x03) { + process.emit('SIGINT' as any); + } + }); + } + + let isShuttingDown = false; + process.on('SIGINT', () => { + if (isShuttingDown) return; + isShuttingDown = true; + if (process.stdin.isTTY) process.stdin.setRawMode(false); + TUI.success('Shutting down workspace dev server...\n'); + server.close(); + if (wss) wss.close(); + process.exit(0); + }); +} + +/* โ”€โ”€ Helpers โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +async function getDirectorySize(dir: string): Promise { + let total = 0; + try { + const entries = await nativeFs.promises.readdir(dir, { withFileTypes: true }); + for (const entry of entries) { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + total += await getDirectorySize(fullPath); + } else { + const stat = await nativeFs.promises.stat(fullPath); + total += stat.size; + } + } + } catch { /* ignore */ } + return total; +} + +function formatBytes(bytes: number): string { + if (bytes < 1024) return `${bytes} B`; + if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`; + return `${(bytes / (1024 * 1024)).toFixed(1)} MB`; +} \ No newline at end of file diff --git a/packages/core/src/env.d.ts b/packages/core/src/env.d.ts new file mode 100644 index 0000000..f20e73d --- /dev/null +++ b/packages/core/src/env.d.ts @@ -0,0 +1,5 @@ +declare module '@docmd/parser'; +declare module '@docmd/plugin-installer'; +declare module '@docmd/themes'; +declare module '@docmd/ui'; +declare module 'ws'; \ No newline at end of file diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts new file mode 100644 index 0000000..24e9b07 --- /dev/null +++ b/packages/core/src/index.ts @@ -0,0 +1,50 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +export function defineConfig(config: any): any { + return config; +} + +export { buildSite as build } from './commands/build.js'; +export { startDevServer as dev } from './commands/dev.js'; +export { buildLive } from './commands/live.js'; + +// D-H2: re-export the workspace helpers under their documented names. +// The skill/docs reference `buildWorkspace`, `detectWorkspace`, and +// `isWorkspace` directly; previously only `build` (= buildSite) was +// exposed from the package root and consumers got `SyntaxError: +// does not provide an export named 'buildWorkspace'` at import time. +export { buildWorkspace, detectWorkspace, isWorkspace } from './engine/workspace.js'; + +// Re-export from @docmd/api for backward compatibility +// These modules have moved to @docmd/api as of 0.7.1. +// Direct imports from @docmd/core continue to work but consumers +// are encouraged to migrate to @docmd/api. +export { createActionDispatcher, safePath, createSourceTools } from '@docmd/api'; + +// Plugin API types (re-exported from @docmd/api) +export type { + ActionContext, + ActionHandler, + EventHandler, + DispatchResult, + PluginModule, + PluginDescriptor, + PluginHooks, + Capability, + SourceTools, + BlockInfo, + InlineSegment, + TextLocation, +} from '@docmd/api'; \ No newline at end of file diff --git a/packages/core/src/utils/auto-router.ts b/packages/core/src/utils/auto-router.ts new file mode 100644 index 0000000..1aa700d --- /dev/null +++ b/packages/core/src/utils/auto-router.ts @@ -0,0 +1,153 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import fs from 'fs'; +import path from 'path'; +import { normalizeInternalHref } from '@docmd/parser'; + +/** + * Convert a file/folder name to a URL-safe slug. + * Replaces spaces and URL-unsafe characters with hyphens so that the + * generated nav link, the output file path, and the browser URL all agree. + * + * Examples: + * "folder with space" โ†’ "folder-with-space" + * "my file (draft)" โ†’ "my-file-draft" + * "already-slug_ok" โ†’ "already-slug_ok" (no change) + */ +function slugifySegment(name: string): string { + return name + .replace(/\s+/g, '-') // spaces โ†’ hyphens + .replace(/[^a-zA-Z0-9\-_.~]/g, '-') // unsafe URL chars โ†’ hyphens + .replace(/-{2,}/g, '-') // collapse consecutive hyphens + .replace(/^-+|-+$/g, '') // strip leading/trailing hyphens + || name; // fallback: keep original if result is empty +} + +// Extract title from Frontmatter or H1 without loading heavy parsers +function extractTitleFromFile(filePath: string, filename: string) { + try { + const content = fs.readFileSync(filePath, 'utf8'); + + // 1. Try YAML frontmatter title + const fmMatch = content.match(/^---\n([\s\S]*?)\n---/); + if (fmMatch) { + const titleMatch = fmMatch[1].match(/^title:\s*"?([^"\n]+)"?/m); + if (titleMatch) return titleMatch[1].trim(); + } + + // 2. Try H1 + const h1Match = content.match(/^#\s+(.*)/m); + if (h1Match) return h1Match[1].trim(); + + } catch { /* ignore parser errors */ } + + // 3. Fallback: Prettify Filename + // "index copy.md" -> "Index Copy" + const cleanName = filename.replace(/\.(md|ejs)$/i, ''); + // Capitalize first letter of each word + return cleanName.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase()); +} + +/** + * Recursively builds the navigation array for Zero Config mode. + */ +export function buildAutoNav(dir: string, basePath = '/'): any[] { // Default base path is root '/' + const items = fs.readdirSync(dir, { withFileTypes: true }); + const nav: any[] = []; + + // Handle index.md/index.ejs (or README.md if no index.md) -> maps to the folder root + const hasIndex = items.some(i => /^index\.(md|ejs)$/i.test(i.name)); + const hasReadme = items.some(i => i.name.toLowerCase() === 'readme.md'); + const indexExists = hasIndex || hasReadme; + + for (const item of items) { + // Skip hidden files, node_modules, and typical output/asset dirs + if ( + item.name.startsWith('.') || + item.name === '_playground' || + item.name === 'node_modules' || + item.name === 'assets' || + item.name === 'site' || + item.name === 'dist' || + item.name === 'bin' || + item.name === 'src' || + item.name === 'lib' || + item.name === 'test' || + item.name === 'tests' || + item.name === 'coverage' || + item.name === 'scripts' || + item.name === 'temp' || + item.name === 'tmp' || + item.name === 'build' || + item.name === 'vendor' + ) continue; + + const fullPath = path.join(dir, item.name); + + // Construct URL path: basePath + slugified filename. + // Slugify so that spaces and URL-unsafe characters are replaced with hyphens, + // keeping the nav link, output file path, and browser URL consistent. + const safeBase = basePath.endsWith('/') ? basePath : basePath + '/'; + const relPath = safeBase + slugifySegment(item.name); + + if (item.isDirectory()) { + const children = buildAutoNav(fullPath, relPath); + if (children.length > 0) { + const title = item.name.replace(/[-_]/g, ' ').replace(/\b\w/g, l => l.toUpperCase()); + nav.push({ + title, + collapsible: true, + children + }); + } + } else if (item.isFile() && /\.(md|ejs)$/i.test(item.name)) { + const title = extractTitleFromFile(fullPath, item.name); + + let linkPath = relPath; + + const isIndex = /^index\.(md|ejs)$/i.test(item.name); + const isReadme = item.name.toLowerCase() === 'readme.md'; + + if (isIndex || (isReadme && !hasIndex)) { + linkPath = basePath === '/' ? '/' : basePath; + } else { + // Use centralised normaliser for clean URLs with trailing slash + linkPath = normalizeInternalHref(linkPath); + } + + nav.push({ title, path: linkPath }); + } + } + + // Sort: Put index.md (Home) at the top, then sort alphabetically + return nav.sort((a, b) => { + // Check if path effectively points to current folder root + const aIsRoot = a.path === basePath || a.path === basePath + '/'; + const bIsRoot = b.path === basePath || b.path === basePath + '/'; + + if (aIsRoot && !bIsRoot) return -1; + if (!aIsRoot && bIsRoot) return 1; + + // Folders usually come after files in some docs, or before. + // Let's standard: Files (Home) -> Folders -> Other Files + const aIsDir = !!a.children; + const bIsDir = !!b.children; + + if (aIsDir && !bIsDir) return 1; + if (!aIsDir && bIsDir) return -1; + + return a.title.localeCompare(b.title); + }); +} \ No newline at end of file diff --git a/packages/core/src/utils/config-loader.ts b/packages/core/src/utils/config-loader.ts new file mode 100644 index 0000000..926eec7 --- /dev/null +++ b/packages/core/src/utils/config-loader.ts @@ -0,0 +1,447 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import fs from 'fs'; +import { validateConfig } from '@docmd/parser'; +import { normalizeConfig } from './config-schema.js'; +import { buildAutoNav } from './auto-router.js'; +import { pathToFileURL } from 'url'; +import { TUI } from '@docmd/api'; + +function hasMarkdownFiles(dir: string, maxDepth = 2, currentDepth = 0): boolean { + if (currentDepth > maxDepth) return false; + try { + const entries = fs.readdirSync(dir, { withFileTypes: true }); + for (const entry of entries) { + if (entry.name === 'node_modules' || entry.name.startsWith('.') || entry.name === 'site' || entry.name === 'dist' || entry.name === 'out') continue; + if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.markdown') || entry.name.endsWith('.ejs'))) return true; + if (entry.isDirectory()) { + if (hasMarkdownFiles(path.join(dir, entry.name), maxDepth, currentDepth + 1)) return true; + } + } + } catch { /* ignore */ } + return false; +} + +function detectHeuristics(cwd: string, srcDir: string) { + const absSrcDir = path.join(cwd, srcDir); + let items: any[] = []; + try { + items = fs.readdirSync(absSrcDir, { withFileTypes: true }); + } catch { + return { versions: null, i18n: null }; + } + + const versionFolders: string[] = []; + const localeFolders: string[] = []; + + const langMap: Record = { + en: 'English', + de: 'Deutsch', + zh: '็ฎ€ไฝ“ไธญๆ–‡', + fr: 'Franรงais', + ja: 'ๆ—ฅๆœฌ่ชž', + es: 'Espaรฑol', + ru: 'ะ ัƒััะบะธะน', + it: 'Italiano', + pt: 'Portuguรชs' + }; + + const isVersion = (name: string) => /^v\d/i.test(name); + const isLocale = (name: string) => /^[a-z]{2}(-[A-Z]{2})?$/i.test(name); + + for (const item of items) { + if (!item.isDirectory()) continue; + if (item.name.startsWith('.') || item.name === 'node_modules') continue; + + if (isVersion(item.name)) { + versionFolders.push(item.name); + } else if (isLocale(item.name)) { + localeFolders.push(item.name); + } + } + + // Sort versions descending (v0.8, v0.7, etc.) + versionFolders.sort((a, b) => b.localeCompare(a, undefined, { numeric: true, sensitivity: 'base' })); + + let finalVersions: any = null; + let finalI18n: any = null; + + if (versionFolders.length > 0) { + finalVersions = { + all: versionFolders.map(v => ({ + id: v, + dir: path.join(srcDir, v), + label: v + })), + current: versionFolders[0] + }; + + // Check if the current/first version contains locales + const currentVerDir = path.join(absSrcDir, versionFolders[0]); + if (fs.existsSync(currentVerDir)) { + try { + const verItems = fs.readdirSync(currentVerDir, { withFileTypes: true }); + const verLocales = verItems + .filter(item => item.isDirectory() && isLocale(item.name)) + .map(item => item.name); + + if (verLocales.length > 0) { + const defaultLoc = verLocales.includes('en') ? 'en' : verLocales[0]; + finalI18n = { + default: defaultLoc, + locales: verLocales.map(loc => ({ + id: loc, + label: langMap[loc.toLowerCase()] || loc.toUpperCase() + })) + }; + } + } catch { /* ignore read errors */ } + } + } else if (localeFolders.length > 0) { + const defaultLoc = localeFolders.includes('en') ? 'en' : localeFolders[0]; + finalI18n = { + default: defaultLoc, + locales: localeFolders.map(loc => ({ + id: loc, + label: langMap[loc.toLowerCase()] || loc.toUpperCase() + })) + }; + } + + return { versions: finalVersions, i18n: finalI18n }; +} + +async function buildZeroConfig(cwd: string, isDev = false, quiet = false, options: any = {}) { + + if (isDev && !quiet) { + if (!(global as any).__DOCMD_ZERO_LOGGED) { + TUI.info('Zero-Config mode activated. Analyzing directory...'); + (global as any).__DOCMD_ZERO_LOGGED = true; + } + } + + // Detect if there's a specific docs folder, otherwise use root + const candidates = ['docs', 'src/docs', 'documentation', 'content']; + let srcDir: string | null = null; + for (const c of candidates) { + if (fs.existsSync(path.join(cwd, c)) && hasMarkdownFiles(path.join(cwd, c), 2)) { + srcDir = c; + break; + } + } + + if (!srcDir) { + // Check if the root directory itself has markdown files + if (hasMarkdownFiles(cwd, 1)) { + srcDir = '.'; + } + } + + if (!srcDir) { + TUI.error('Configuration Error', 'No documentation directory or files found.'); + TUI.info(`Zero-Config expects one of: ${candidates.join(', ')} or markdown files in the project root.`); + TUI.info('Create one of these folders, place markdown files in the root, or provide a docmd.config.json file.'); + + const err: any = new Error('No candidate documentation directory or files found.'); + err.silent = true; + throw err; + } + + const absSrcDir = path.join(cwd, srcDir); + + if (!hasMarkdownFiles(absSrcDir, 2)) { + TUI.warn(`No documentation content found in ${absSrcDir}`); + TUI.info('docmd expects markdown files in the source folder.'); + + const err: any = new Error('No content found for documentation.'); + err.silent = true; + throw err; + } + + // Try extracting defaults from package.json + let autoTitle = path.basename(cwd) || 'Documentation'; + let autoDesc = ''; + try { + const pkgPath = path.join(cwd, 'package.json'); + if (fs.existsSync(pkgPath)) { + const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); + if (pkg.name) { + autoTitle = pkg.name.replace(/^@[^/]+\//, '').split('-').map((w: string) => w.charAt(0).toUpperCase() + w.slice(1)).join(' '); + } + if (pkg.description) autoDesc = pkg.description; + } + } catch { /* ignore */ } + + const { versions, i18n } = detectHeuristics(cwd, srcDir); + + // Dynamically build the navigation tree only if we do not have versions/locales at root + // (otherwise navigation is handled at version/locale level) + const autoNav = (!versions && !i18n) ? buildAutoNav(absSrcDir) : null; + + const autoConfig: any = { + title: autoTitle, + description: autoDesc, + src: srcDir, + out: 'site', + layout: { spa: true }, + theme: { name: 'default', appearance: 'system' } + }; + + if (autoNav) { + autoConfig.navigation = autoNav; + } + if (versions) { + autoConfig.versions = versions; + } + if (i18n) { + autoConfig.i18n = i18n; + } + + // Merge with global defaults + const merged = { ...(options._globalDefaults || {}), ...autoConfig }; + + return normalizeConfig(merged); +} + +export async function loadConfig(configPath: string, options: any = {}) { + // D-H1: honour an explicit `cwd` option (used by build.ts when the + // caller passes --config from a foreign working dir). Falls + // back to `process.cwd()` so existing callers continue to work. + const cwd = options.cwd || process.cwd(); + + let absoluteConfigPath = path.resolve(cwd, configPath); + + if (configPath === 'docmd.config.js') { + const candidates = [ + 'docmd.config.json', + 'docmd.config.ts', + 'docmd.config.js', + 'docmd.config.mjs', + 'config.js' + ]; + let found = false; + for (const c of candidates) { + const p = path.resolve(cwd, c); + if (fs.existsSync(p)) { + absoluteConfigPath = p; + found = true; + break; + } + } + + if (!found) { + // Check if we have docs directory with markdown files or if root has them. + // If we don't even have a docs directory, or if it's empty, auto-run init: + const docCandidates = ['docs', 'src/docs', 'documentation', 'content']; + let hasDocs = false; + for (const d of docCandidates) { + const dp = path.join(cwd, d); + if (fs.existsSync(dp) && hasMarkdownFiles(dp, 2)) { + hasDocs = true; + break; + } + } + + if (!hasDocs && hasMarkdownFiles(cwd, 1)) { + hasDocs = true; + } + + if (!hasDocs) { + if (process.argv.includes('--json') || options.quiet) { + throw new Error('No documentation directory or configuration found.'); + } + TUI.warn('No documentation or configuration found. Initializing new project...'); + const { initProject } = await import('../commands/init.js'); + await initProject(); + + // Re-check config candidates + for (const c of candidates) { + const p = path.resolve(cwd, c); + if (fs.existsSync(p)) { + absoluteConfigPath = p; + found = true; + break; + } + } + } + + if (!found) { + // Fallback to Zero-Config if nothing is found to prevent crashing! + if (!(global as any).__DOCMD_NO_CONFIG_LOGGED && !options.quiet) { + TUI.warn('No config found. Running in auto mode. Run `docmd init` to create one.'); + (global as any).__DOCMD_NO_CONFIG_LOGGED = true; + } + const autoConfig = await buildZeroConfig(cwd, options.isDev, options.quiet, options); + return JSON.parse(JSON.stringify(autoConfig)); + } + } + } else if (!fs.existsSync(absoluteConfigPath)) { + throw new Error(`Config file not found: ${absoluteConfigPath}`); + } + + // Cleanup any orphaned temp config files from previous failed reloads + try { + const configDir = path.dirname(absoluteConfigPath); + const baseName = path.basename(absoluteConfigPath).split('.')[0]; + const files = fs.readdirSync(configDir); + for (const file of files) { + if (file.startsWith(`${baseName}-`) && (file.endsWith('.js') || file.endsWith('.mjs'))) { + const fullPath = path.join(configDir, file); + // If it has a timestamp-like suffix, it's one of ours + if (/-[0-9]{13}\.(js|mjs)$/.test(file)) { + fs.unlinkSync(fullPath); + } + } + } + } catch { /* ignore cleanup errors */ } + + try { + // Polyfill defineConfig globally so the config file works + // even if @docmd/core isn't installed locally in the target project. + (global as any).defineConfig = (config: any) => config; + + // Use a timestamp to bypass ESM cache if file is likely changed + const ts = Date.now(); + let configUrl = pathToFileURL(absoluteConfigPath).href + '?t=' + ts; + let tempConfigPath: string | null = null; + let rawConfig: any; + + try { + if (absoluteConfigPath.endsWith('.json')) { + rawConfig = JSON.parse(fs.readFileSync(absoluteConfigPath, 'utf-8')); + } else { + if (absoluteConfigPath.endsWith('.ts')) { + const esbuild = await import('esbuild'); + tempConfigPath = absoluteConfigPath.replace(/\.ts$/, `-${ts}.mjs`); + await esbuild.build({ + entryPoints: [absoluteConfigPath], + outfile: tempConfigPath, + format: 'esm', + bundle: true, + packages: 'external', + platform: 'node', + target: 'node18' + }); + configUrl = pathToFileURL(tempConfigPath).href; + } else if (absoluteConfigPath.endsWith('.js') || absoluteConfigPath.endsWith('.mjs')) { + // Copy to a temp file to guarantee cache bypass (query strings + // are not always reliable for ESM cache busting in all Node versions) + const ext = path.extname(absoluteConfigPath); + tempConfigPath = absoluteConfigPath.replace(new RegExp(`\\${ext}$`), `-${ts}${ext}`); + fs.copyFileSync(absoluteConfigPath, tempConfigPath); + configUrl = pathToFileURL(tempConfigPath).href; + } + + const rawModule = await import(configUrl); + rawConfig = rawModule.default || rawModule; + } + + // If user has 'search' or 'theme' at root, but no 'layout' object, they are legacy. + const isLegacy = !rawConfig.layout && ( + rawConfig.search !== undefined || + (rawConfig.theme && rawConfig.theme.enableModeToggle !== undefined) || + rawConfig.sponsor + ); + + if (isLegacy) { + TUI.error('Legacy Configuration Detected', 'Your docmd.config uses an outdated structure.'); + TUI.info(`Run ${TUI.cyan('docmd migrate')} to automatically upgrade your configuration.`); + } + + validateConfig(rawConfig); + const hasExplicitNav = 'navigation' in rawConfig; + + // Merge with global defaults: root project config overrides global defaults + const mergedConfig = { ...(options._globalDefaults || {}), ...rawConfig }; + + const normalized = normalizeConfig(mergedConfig); + + if (normalized._baseAutoDerived) { + TUI.info(`${TUI.dim('base auto-derived from url:')} ${TUI.cyan(normalized._baseAutoDerived)}`); + } + + // Navigation Handling: Prioritize local navigation.json in the project folder + let navScanDir = path.resolve(cwd, normalized.srcDir); + let localNavPath = path.join(navScanDir, 'navigation.json'); + + // Adjust navScanDir if i18n is enabled to check in the default locale folder + if (normalized.i18n?.default) { + const localeScanDir = path.join(navScanDir, normalized.i18n.default); + if (fs.existsSync(localeScanDir)) { + navScanDir = localeScanDir; + localNavPath = path.join(navScanDir, 'navigation.json'); + } + } + + // If navigation.json exists locally, it ALWAYS wins over inherited global navigation + if (fs.existsSync(localNavPath)) { + try { + normalized.navigation = JSON.parse(fs.readFileSync(localNavPath, 'utf-8')); + } catch (e: any) { + TUI.error('Navigation Error', `Failed to parse ${localNavPath}: ${e.message}`); + } + } + // Otherwise, if we still don't have any navigation (not from global, not from config, not from JSON), + // check for localized/versioned nav or fallback to auto-nav + else if (!normalized.navigation || (normalized.navigation.length === 0 && !hasExplicitNav)) { + let hasNavInSubdirs = false; + + if (normalized.i18n?.default) { + // Check if any locale dir has navigation.json + hasNavInSubdirs = (normalized.i18n.locales || []).some((l: any) => + fs.existsSync(path.join(path.resolve(cwd, normalized.srcDir), l.id, 'navigation.json')) + ); + } + + // Check if any version dir has navigation.json + if (!hasNavInSubdirs && normalized.versions?.all?.length > 0) { + hasNavInSubdirs = normalized.versions.all.some((v: any) => { + const vDir = path.resolve(cwd, v.dir); + if (fs.existsSync(path.join(vDir, 'navigation.json'))) return true; + if (normalized.i18n?.default) { + return fs.existsSync(path.join(vDir, normalized.i18n.default, 'navigation.json')); + } + return false; + }); + } + + if (!hasNavInSubdirs) { + if (!options.quiet && !(global as any).__DOCMD_ZERO_NAV_LOGGED) { + TUI.info('No navigation settings found. Auto-generating with Zero-Config...'); + if (options.isDev) (global as any).__DOCMD_ZERO_NAV_LOGGED = true; + } + normalized.navigation = buildAutoNav(navScanDir); + } + } + + normalized._resolvedPath = absoluteConfigPath; + + // Ensure the final configuration object is completely JSON-serialisable + // This is crucial for passing the config to worker threads in the new multi-threaded build engine + return JSON.parse(JSON.stringify(normalized)); + } finally { + if (tempConfigPath && fs.existsSync(tempConfigPath)) { + fs.unlinkSync(tempConfigPath); + } + // Clean up global to avoid pollution + delete (global as any).defineConfig; + } + + } catch (e: any) { + if (e.message === 'Invalid configuration file.') throw e; + throw new Error(`Error parsing config file: ${e.message}`); + } +} \ No newline at end of file diff --git a/packages/core/src/utils/config-schema.ts b/packages/core/src/utils/config-schema.ts new file mode 100644 index 0000000..3090789 --- /dev/null +++ b/packages/core/src/utils/config-schema.ts @@ -0,0 +1,421 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { normalizeNavPaths, normalizeMenubarPaths } from '@docmd/parser'; + +/** + * CSS themes shipped with @docmd/themes. Any other value of `theme.name` + * is treated as a template name (see Section 4.0 of normalizeConfig). + * + * The "none" sentinel value suppresses the CSS overlay entirely. + */ +const KNOWN_CSS_THEMES: ReadonlySet = new Set([ + 'default', + 'sky', + 'ruby', + 'retro', + 'none', +]); + +/** + * Hardcoded English defaults for the 404 page. These are intentionally + * NOT injected into `config.notFound` during normalisation โ€” if we did, + * the build site's `|| t('pageNotFound')` fallback would never fire + * (the user-supplied English string would shadow it), and a site with + * default locale = 'zh' would still render "404 : Page Not Found" in + * English. + * + * Instead, the build command resolves the actual title/content at + * render-time using this priority chain: + * 1. config.notFound.title / config.notFound.content (user override) + * 2. t('pageNotFound') / t('pageNotFoundMsg') (translated to default locale) + * 3. NOT_FOUND_DEFAULTS.title / content (this constant, English) + * + * Exported here so the defaults live next to the rest of the config + * schema rather than buried in the build command. + */ +export const NOT_FOUND_DEFAULTS = { + title: 'Page Not Found', + content: 'The page youโ€™re looking for doesnโ€™t exist or has moved.' +}; + +/** + * Normalizes user config to ensure all required nested objects exist. + * Handles legacy backward compatibility transparently. + */ +export function normalizeConfig(userConfig: any) { + const config = { ...userConfig }; + + // --- 1. Modern Syntax Standard (V3) --- + // New labels are the source of truth. Fallback to legacy labels if present. + // Every field MUST have a default here so no consumer needs its own fallback chain. + config.title = config.title || config.siteTitle || 'Documentation'; + config.url = config.url || config.siteUrl || config.baseUrl || ''; + config.src = config.src || config.srcDir || config.source || 'docs'; + config.out = process.env.DOCMD_PROJECT_OUT || config.out || config.outDir || config.outputDir || 'site'; + + // Track whether the user explicitly set base (vs. the default '/'). + // The env var (DOCMD_PROJECT_PREFIX) counts as explicit; only a truly + // absent base triggers auto-derivation from url below. + const _userSetBaseExplicitly = !!process.env.DOCMD_PROJECT_PREFIX || userConfig.base !== undefined; + config.base = process.env.DOCMD_PROJECT_PREFIX || config.base || '/'; + + // --- 1.1 Normalise base slashes + auto-derive from URL --- + // + // DESIGN PRINCIPLE: `base` is an internal implementation detail. Users + // should NEVER have to think about it. They set `url` (the canonical + // production URL) and docmd derives everything else. The only time + // `base` is needed is the rare case where the deployment path differs + // from the URL path (e.g. a CDN that strips a prefix). + // + // What this block does, in order: + // 1. If the user explicitly set base, normalise its slashes: + // "repo" โ†’ "/repo/", "/repo" โ†’ "/repo/", "repo/" โ†’ "/repo/". + // Users should not have to remember whether slashes are needed. + // 2. If base was NOT explicitly set, derive it from url's pathname. + // This handles GitHub Pages project sites and any subpath deploy + // where the user set url to match their deployment. + // 3. If neither base nor url is informative, default to "/". + // + // The derivation is slash-tolerant on url too: + // url = "https://user.github.io/repo" โ†’ base = "/repo/" + // url = "https://user.github.io/repo/" โ†’ base = "/repo/" + // url = "https://docs.example.com" โ†’ base = "/" + // url = "https://example.com/docs/" โ†’ base = "/docs/" + // + // If derivation cannot fire (no url, or url is a root), base stays "/" + // and the build will warn if assets turn out to be unreachable. + if (_userSetBaseExplicitly && config.base !== '/') { + // User set base explicitly: fix the slashes for them. + let b = config.base.trim(); + if (!b.startsWith('/')) b = '/' + b; // "repo" โ†’ "/repo" + if (!b.endsWith('/')) b = b + '/'; // "/repo" โ†’ "/repo/" + // Collapse accidental double slashes (e.g. "//repo///" โ†’ "/repo/"). + b = b.replace(/([^:])\/{2,}/g, '$1/'); + if (b !== config.base) config._baseNormalised = config.base; + config.base = b; + } else if (!_userSetBaseExplicitly && config.url) { + // Derive base from url. Slash-tolerant on both ends. + try { + const parsedUrl = new URL(config.url); + // Strip trailing slashes to get a clean path, then re-add one. + // Empty or "/" โ†’ root deployment, base stays "/". + const pathname = parsedUrl.pathname.replace(/\/+$/, ''); + if (pathname && pathname !== '/') { + const derivedBase = pathname + '/'; + config.base = derivedBase; + config._baseAutoDerived = derivedBase; + } + } catch { + // Invalid url (placeholder, typo, empty-ish) โ€” leave base as "/". + // The build will surface a clear warning if assets end up missing. + } + } + // Top-level QoL defaults โ€” opt out by setting `false`. + if (config.pageNavigation === undefined) config.pageNavigation = true; + if (config.copyCode === undefined) config.copyCode = true; + if (config.autoTitleFromH1 === undefined) config.autoTitleFromH1 = true; + + // --- 1.5 Security defaults (Phase 0.D, new in v0.8.8) --- + // Controls how the markdown parser handles raw HTML in user content. + // 'allow' - raw HTML passes through to the rendered output (UNSAFE) + // 'escape' - raw HTML is HTML-escaped and shown as text (default) + // 'strip' - raw HTML blocks are removed from the rendered output + // The default flips from allow to escape in v0.8.8 to mitigate S-2 and S-7. + const VALID_HTML_POLICIES = new Set(['allow', 'escape', 'strip']); + const userHtmlPolicy = config.security && config.security.html; + config.security = { + html: VALID_HTML_POLICIES.has(userHtmlPolicy) ? userHtmlPolicy : 'escape', + }; + + // Failsafe: Keep legacy keys attached for older plugins (SEO, Sitemap) to prevent breakage during transition. + config.siteTitle = config.title; + config.siteUrl = config.url; + config.srcDir = config.src; + config.outputDir = config.out; + + // --- Logo Normalization + if (typeof config.logo === 'string') { + config.logo = { + light: config.logo, + dark: config.logo, + alt: config.title || 'Logo' + }; + } + + // --- 2. Layout Structure (V2 Schema) --- + const userLayout = config.layout || {}; + + config.layout = { + spa: true, + breadcrumbs: true, + ...userLayout + }; + + config.header = { + enabled: true, + ...(userLayout.header || config.header || {}) + }; + + // Legacy Mapping: Sidebar + const legacySidebar = config.sidebar || {}; + config.sidebar = { + enabled: true, + collapsible: true, + defaultCollapsed: false, + position: 'left', + ...(userLayout.sidebar || legacySidebar) + }; + + // Legacy Mapping: Footer + const legacyFooter = config.footer; + config.footer = { + copyright: `ยฉ ${new Date().getFullYear()}`, + style: 'minimal', + content: typeof legacyFooter === 'string' ? legacyFooter : null, + branding: true, + ...(userLayout.footer || (typeof legacyFooter === 'object' ? legacyFooter : {})) + }; + + if (config.footer.columns && Array.isArray(config.footer.columns)) { + for (const col of config.footer.columns) { + if (col.links && Array.isArray(col.links)) { + normalizeMenubarPaths(col.links); + } + } + } + + // --- 3. Options Menu (Search, Theme, Sponsor) --- + config.optionsMenu = { + position: 'header', + components: { + search: true, + themeSwitch: true, + sponsor: null + }, + ...(userLayout.optionsMenu || config.optionsMenu || {}) + }; + + // --- 3.1. Site-wide Banner (new in 0.8.7) --- + // Sits above the menubar. Opt-in โ€” defaults to null (no banner rendered). + if (config.layout?.banner) { + const ub = config.layout.banner; + config.layout.banner = { + content: typeof ub === 'string' ? ub : (ub.content || ub.html || ''), + html: typeof ub === 'object' && ub.html ? ub.html : undefined, + type: (typeof ub === 'object' && ub.type) ? ub.type : 'info', + dismissible: typeof ub === 'object' && ub.dismissible === false ? false : true, + link: typeof ub === 'object' && ub.link && ub.link.url ? ub.link : null, + icon: typeof ub === 'object' && ub.icon ? ub.icon : null, + }; + // If only a string was passed, `ub` is a string and `content` is the string. + // If it's an object, ensure `content` and `html` are mutually consistent. + if (config.layout.banner.html && !config.layout.banner.content) { + config.layout.banner.content = config.layout.banner.html; + } + } else { + config.layout.banner = null; + } + + // --- Menubar (Top Navigation Bar) --- + const userMenubar = userLayout.menubar || config.menubar; + if (userMenubar) { + const isArray = Array.isArray(userMenubar); + config.menubar = { + enabled: true, + position: (!isArray && userMenubar.position) ? userMenubar.position : 'top', + left: isArray ? userMenubar : (Array.isArray(userMenubar.left) ? userMenubar.left : []), + right: (!isArray && Array.isArray(userMenubar.right)) ? userMenubar.right : [], + ...(!isArray ? userMenubar : {}) + }; + normalizeMenubarPaths(config.menubar.left); + normalizeMenubarPaths(config.menubar.right); + } else { + config.menubar = null; + } + + // --> Legacy Adapter: Sponsor + if (config.sponsor) { + if (typeof config.sponsor === 'object' && config.sponsor.enabled && config.sponsor.link) { + config.optionsMenu.components.sponsor = config.sponsor.link; + } else if (typeof config.sponsor === 'string') { + config.optionsMenu.components.sponsor = config.sponsor; + } + } + + // --> Legacy Adapter: Search (Boolean) + if (typeof config.search === 'boolean') { + config.optionsMenu.components.search = config.search; + } + + // --> Legacy Adapter: Theme Switch & Position + if (config.theme) { + if (config.theme.enableModeToggle === false) { + config.optionsMenu.components.themeSwitch = false; + } + if (config.theme.positionMode === 'bottom') { + config.optionsMenu.position = 'sidebar-bottom'; + } else if (config.theme.positionMode === 'top') { + config.optionsMenu.position = 'header'; + } + } + + // --- 4. Theme & Branding --- + config.theme = { + name: 'default', + appearance: 'system', + customCss: [], + codeHighlight: true, + ...(config.theme || {}) + }; + + // Legacy Support: Map defaultMode to appearance if appearance isn't explicitly set + if (config.theme.defaultMode && !userConfig.theme?.appearance) { + config.theme.appearance = config.theme.defaultMode; + } + + // Ensure defaultMode is still available for legacy templates/plugins + config.theme.defaultMode = config.theme.appearance; + + // --- 4.0. Theme name โ†’ Template auto-promotion (new in 0.8.7) --- + // The CSS themes shipped with @docmd/themes are a known, short list. + // Any other value in `theme.name` is treated as a template name (so + // users only need to learn ONE key: `theme.name`). + // Explicit `theme.template` always wins. + if (config.theme.name && !config.theme.template && !KNOWN_CSS_THEMES.has(config.theme.name)) { + config.theme.template = config.theme.name; + // Keep `theme.name` so the original intent is preserved, but + // mark the theme as "no CSS overlay" so the generator does not + // try to load `docmd-theme-${name}.css` (which would 404). + config.theme._noCssOverlay = true; + } + + // --- 4.1. Cookie Consent (new in 0.8.7) --- + // Opt-in. Users add `"cookie": { ... }` to enable the consent dialog. + // Defaults are kept conservative; templates can ship their own defaults + // by reading config.cookie and supplying a copy in their template's + // onboarding step. The user is always in control. + if (config.cookie) { + const uc = config.cookie; + if (uc === true) { + config.cookie = { enabled: true }; + } else if (typeof uc === 'object') { + config.cookie = { + enabled: uc.enabled !== false, + message: uc.message || null, + acceptText: uc.acceptText || null, + declineText: uc.declineText || null, + policyUrl: uc.policyUrl || null, + position: ['bottom', 'bottom-left', 'bottom-right', 'center'].includes(uc.position) ? uc.position : 'bottom', + dismissible: uc.dismissible !== false, + expiryDays: typeof uc.expiryDays === 'number' && uc.expiryDays > 0 ? uc.expiryDays : 180, + }; + } else { + config.cookie = null; + } + } else { + config.cookie = null; + } + + config.customJs = config.customJs || []; + + // Normalize Navigation + config.navigation = Array.isArray(config.navigation) ? config.navigation : []; + normalizeNavPaths(config.navigation); + + // Aliasing for Menubar items (title -> text, path -> url) + if (config.menubar) { + const normalizeItems = (items: any[]) => { + items.forEach(item => { + if (item.title && !item.text) item.text = item.title; + if (item.path && !item.url) item.url = item.path; + if (item.items) normalizeItems(item.items); + }); + }; + if (config.menubar.left) normalizeItems(config.menubar.left); + if (config.menubar.right) normalizeItems(config.menubar.right); + } + + // --- 5. Plugins --- + config.hasExplicitPlugins = 'plugins' in userConfig; + config.plugins = config.plugins || {}; + + // --- 6. Versioning Engine --- + // M-6: accept `config.versions.list` as an alias for `config.versions.all`. + // The original audit reported "i18n + explicit versions: 0 pages (silent)" + // โ€” turns out the actual cause was a typo: users wrote `list` (a + // common shape for "list of versions") but the schema only accepted + // `all`, so the config branch was never entered and zero pages got + // built. Aliasing `list` to `all` here restores the user's config + // without changing the canonical key. + if (config.versions && Array.isArray(config.versions.list) && !Array.isArray(config.versions.all)) { + config.versions.all = config.versions.list; + } + if (config.versions && Array.isArray(config.versions.all)) { + if (!config.versions.current) { + config.versions.current = config.versions.all[0]?.id || 'main'; + } + config.versions.position = config.versions.position || 'sidebar-top'; + config.versions.all = config.versions.all.map((v: any) => { + return { + id: v.id, + dir: v.dir || `docs-${v.id}`, + label: v.label || v.id, + navigation: v.navigation || null + }; + }); + } else { + config.versions = false; + } + + // --- 7. SEO Redirects & 404 --- + // config.notFound is normalised to an empty object here so build + // commands can read `config.notFound?.title` / `content` without + // optional-chaining every access. The English defaults live in the + // exported NOT_FOUND_DEFAULTS constant and are applied at render + // time (NOT pre-injected into config.notFound โ€” that would shadow + // the translation fallback chain in the build command). + config.redirects = config.redirects || {}; + config.notFound = config.notFound || {}; + + // --- 8. Internationalisation (i18n) --- + if (config.i18n && config.i18n.locales && Array.isArray(config.i18n.locales) && config.i18n.locales.length > 0) { + config.i18n = { + default: config.i18n.default || config.i18n.locales[0].id || 'en', + position: config.i18n.position || 'options-menu', + stringMode: config.i18n.stringMode || false, + inPlace: config.i18n.inPlace || false, + locales: config.i18n.locales.map((loc: any) => ({ + id: loc.id, + label: loc.label || loc.id, + dir: loc.dir || 'ltr', + translations: loc.translations || {} + })) + }; + } else { + config.i18n = false; + } + + // --- 9. OptionsMenu Fallbacks --- + if (config.optionsMenu.position === 'menubar' && (!config.menubar || config.menubar.enabled === false)) { + config.optionsMenu.position = 'sidebar-top'; + } else if (config.optionsMenu.position === 'header' && (!config.header || config.header.enabled === false)) { + config.optionsMenu.position = 'sidebar-top'; + } + + return config; +} + +// Re-export for backward compatibility (used by generator.ts, versioning.ts) +export { normalizeNavPaths, normalizeMenubarPaths } from '@docmd/parser'; \ No newline at end of file diff --git a/packages/core/src/utils/dev-utils.ts b/packages/core/src/utils/dev-utils.ts new file mode 100644 index 0000000..93b3e16 --- /dev/null +++ b/packages/core/src/utils/dev-utils.ts @@ -0,0 +1,257 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import http from 'http'; +import os from 'os'; +import path from 'path'; +import crypto from 'crypto'; +import { execSync, spawn } from 'child_process'; +import { fileURLToPath } from 'url'; +import { fsUtils as fs, safePath, asUserPath } from '@docmd/utils'; + + + +// MIME types for static file serving +export const MIME_TYPES: Record = { + '.html': 'text/html', + '.js': 'text/javascript', + '.css': 'text/css', + '.json': 'application/json', + '.png': 'image/png', + '.jpg': 'image/jpg', + '.jpeg': 'image/jpg', + '.gif': 'image/gif', + '.svg': 'image/svg+xml', + '.ico': 'image/x-icon', + '.woff': 'application/font-woff', + '.woff2': 'font/woff2', + '.ttf': 'application/font-ttf', + '.txt': 'text/plain', +}; + +/** + * Format an absolute path for display relative to CWD. + */ +export function formatPathForDisplay(absolutePath: string, cwd: string): string { + const relativePath = path.relative(cwd, absolutePath); + if (!relativePath.startsWith('..') && !path.isAbsolute(relativePath)) { + return `./${relativePath}`; + } + return relativePath; +} + +/** + * Get the first non-internal IPv4 network address. + */ +export function getNetworkIp(): string | null { + const interfaces = os.networkInterfaces(); + for (const name of Object.keys(interfaces)) { + for (const iface of interfaces[name]!) { + if (iface.family === 'IPv4' && !iface.internal) { + return iface.address; + } + } + } + return null; +} + +/** + * Read git user.name and user.email, compute Gravatar URL. + * Lazy-initialized on first call. + */ +let _gitDevInfoCache: { name: string; email: string; gravatarUrl: string } | null = null; +export function getGitDevInfo() { + if (_gitDevInfoCache) return _gitDevInfoCache; + let name = ''; + let email = ''; + try { name = execSync('git config user.name', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim(); } catch { /* git not configured */ } + try { email = execSync('git config user.email', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim(); } catch { /* git not configured */ } + const gravatarUrl = email + ? `https://gravatar.com/avatar/${crypto.createHash('md5').update(email.toLowerCase().trim()).digest('hex')}?s=80&d=mp` + : ''; + _gitDevInfoCache = { name, email, gravatarUrl }; + return _gitDevInfoCache; +} + +export function getDevInfoScript(): string { + return ``; +} + +/** + * Serve static files from rootDir with live-reload injection. + */ +export async function serveStatic(req: any, res: any, rootDir: string) { + // Serve dev-only API script + if (req.url === '/__dev/docmd-api.js') { + try { + const apiScriptPath = path.resolve( + fileURLToPath(import.meta.url), + '../../../../ui/assets/js/docmd-api.js' + ); + const apiScript = await fs.readFile(apiScriptPath, 'utf-8'); + res.writeHead(200, { 'Content-Type': 'text/javascript' }); + res.end(apiScript); + } catch { + res.writeHead(404); + res.end('Not found'); + } + return; + } + + const url = new URL(req.url || '/', 'http://localhost'); + const pathname = decodeURIComponent(url.pathname); + const rootAbs = path.resolve(rootDir); + // Security (Phase 1.A: CWE-22 fix). Use safePath() to enforce the boundary. + // + // The previous `filePath.startsWith(rootAbs)` check was the outlier in the + // repo: it did not append `path.sep`, so a sibling directory whose name + // started with rootDir's name (e.g. rootDir=`/x/site`, sibling=`/x/site-private`) + // passed the check, and a URL like `/..%2fsite-private/secret.txt` resolved + // to the sibling. safePath() enforces the strict `root + path.sep` boundary + // and throws on escape. + // + // Note: URL pathnames always start with `/` (e.g. `/index.html`). We + // strip the leading slash before passing to safePath() so the second + // argument is treated as a *relative* path. `path.resolve` (which + // safePath uses internally) treats `/index.html` as absolute and would + // bypass the boundary check; `path.join`-style resolution is the + // correct semantic for "join this to the root". + let filePath: string; + try { + const safeRelative = pathname.replace(/^\/+/, '') || '.'; + filePath = safePath(rootAbs, asUserPath(safeRelative)); + } catch (_e: any) { + res.writeHead(403); + res.end('Forbidden'); + return; + } + + try { + let stats; + try { + stats = await fs.stat(filePath); + } catch (e) { + if (path.extname(filePath) === '') { + filePath += '.html'; + stats = await fs.stat(filePath); + } else { + throw e; + } + } + + if (stats.isDirectory()) { + if (!req.url.split('?')[0].endsWith('/')) { + res.writeHead(301, { 'Location': req.url + '/' }); + res.end(); + return; + } + filePath = path.join(filePath, 'index.html'); + await fs.stat(filePath); + } + + const ext = path.extname(filePath).toLowerCase(); + const contentType = MIME_TYPES[ext] || 'application/octet-stream'; + const content = await fs.readFile(filePath); + + if (contentType === 'text/html') { + res.writeHead(200, { 'Content-Type': contentType, 'Cache-Control': 'no-cache' }); + const htmlStr = content.toString('utf-8'); + const liveReloadScript = `${getDevInfoScript()}`; + res.end(htmlStr.replace('', liveReloadScript)); + } else { + res.writeHead(200, { 'Content-Type': contentType }); + res.end(content); + } + + } catch (err: any) { + if (err.code === 'ENOENT') { + const custom404Path = path.join(rootDir, '404.html'); + try { + const content = await fs.readFile(custom404Path); + res.writeHead(404, { 'Content-Type': 'text/html' }); + const htmlStr = content.toString('utf-8'); + const liveReloadScript = `${getDevInfoScript()}`; + res.end(htmlStr.replace('', liveReloadScript)); + } catch { + res.writeHead(404, { 'Content-Type': 'text/html' }); + res.end(` +
+

404 Not Found

+

The requested URL ${req.url} was not found.

+

(docmd dev server)

+
+ `); + } + } else { + res.writeHead(500); + res.end(`Server Error: ${err.code}`); + } + } +} + +/** + * Check if a port is in use. + */ +export function checkPortInUse(port: number): Promise { + // The probe binds to 127.0.0.1, not 0.0.0.0, so it only checks whether + // the loopback interface has the port. Binding to all interfaces here + // was unnecessary (we just need to know if "our" port is taken) and + // briefly exposed the probe socket to the LAN. + return new Promise((resolve) => { + const tester = http.createServer() + .once('error', (err: any) => resolve(err.code === 'EADDRINUSE')) + .once('listening', () => tester.close(() => resolve(false))) + .listen(port, '127.0.0.1'); + }); +} + +/** + * Find the next available port starting from startPort. + */ +export async function findAvailablePort(startPort: number): Promise { + let port = startPort; + while (await checkPortInUse(port)) { + port++; + } + return port; +} + +/** + * Open a URL in the user's default browser. Best-effort: failures are + * swallowed so the dev server is never taken down by a missing `xdg-open` + * (e.g. inside the official Docker image, where the binary is not + * installed). The call is also skipped entirely when running inside a + * container โ€” the official image sets DOCMD_CONTAINER=true for this. + */ +export function openBrowser(url: string): void { + if (process.env.DOCMD_CONTAINER === 'true') return; + + let command = 'xdg-open'; + let args = [url]; + + if (process.platform === 'darwin') { + command = 'open'; + } else if (process.platform === 'win32') { + command = 'cmd'; + args = ['/c', 'start', '""', url]; + } + + try { + const child = spawn(command, args, { stdio: 'ignore', detached: true }); + child.on('error', () => { /* missing browser binary โ€” ignore */ }); + child.unref(); + } catch { + /* never let a browser-launch failure crash the dev server */ + } +} \ No newline at end of file diff --git a/packages/core/src/utils/exit.ts b/packages/core/src/utils/exit.ts new file mode 100644 index 0000000..c60b3d0 --- /dev/null +++ b/packages/core/src/utils/exit.ts @@ -0,0 +1,94 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * Phase 3 PR 3.A โ€” Exit-code contract. + * + * Every `docmd ` that hits a documented error path MUST exit + * with a non-zero code so CI pipelines can gate on it. Historically we + * had several `TUI.error(...); return;` patterns that printed the + * message but left the process at exit code 0, silently passing broken + * builds (see `unified-issues.md` ยงF6 / ยงM-12). + * + * These helpers centralise the contract: + * + * - `exitCodeFor(err)` returns a numeric exit code. Today this is + * always 1 (operational error), but the indirection lets us + * introduce code-2 for usage errors, code-3 for config errors, + * etc. without rewriting every call site. + * + * - `exitWithError(err, opts?)` calls `TUI.error(...)` (or prints + * JSON when `opts.json === true`) and then `process.exit(code)`. + * The `quiet` option suppresses the error print when the caller + * has already surfaced the error. + * + * - `failWith(message, opts?)` is the convenience wrapper for the + * common "no extra Error object, just a message" case. + * + * Every CLI command that previously did `TUI.error(...); return;` + * should be ported to `exitWithError(...)`. The Phase 3 PR 3.A brute- + * test scenario asserts that every documented failure case exits 1. + */ + +import { TUI } from '@docmd/api'; + +/** + * Map any thrown or constructed value to a numeric exit code. + * + * Reserved codes (matches common CLI conventions): + * 0 โ€” success + * 1 โ€” operational error (default for any thrown value) + * + * Future expansion: discriminate on `err.code` or `err.name` to + * return 2 (usage), 3 (config), 4 (network), 5 (I/O), 6 (plugin). + */ +export function exitCodeFor(_err: unknown): number { + // Reserved for future discrimination on err.code / err.name. Today every + // error maps to 1 (operational). The parameter is part of the contract. + void _err; + return 1; +} + +/** + * Print an error and exit with the code returned by `exitCodeFor`. + * Never returns โ€” the function always terminates the process. + * + * exitWithError(new Error('Plugin not found: foo')); + * exitWithError('Build failed: ...', { json: true }); + * exitWithError('Missing configuration', { quiet: true }); + */ +export function exitWithError( + err: unknown, + opts: { json?: boolean; quiet?: boolean; section?: string } = {} +): never { + const message = err instanceof Error ? err.message : String(err); + const code = exitCodeFor(err); + + if (!opts.quiet) { + if (opts.json) { + console.log(JSON.stringify({ error: message, exitCode: code })); + } else { + TUI.error(opts.section || 'Command failed', message); + } + } + process.exit(code); +} + +/** + * Convenience wrapper when the caller has a plain message string and + * no Error object. Same as `exitWithError(new Error(message), opts)`. + */ +export function failWith(message: string, opts: { json?: boolean; section?: string } = {}): never { + exitWithError(new Error(message), opts); +} diff --git a/packages/core/src/utils/ws-origin-guard.ts b/packages/core/src/utils/ws-origin-guard.ts new file mode 100644 index 0000000..78622d3 --- /dev/null +++ b/packages/core/src/utils/ws-origin-guard.ts @@ -0,0 +1,62 @@ +/** + * Origin-allowlist verifyClient callback factory for the dev-server + * WebSocketServers. Used by packages/core/src/commands/dev.ts and + * packages/core/src/engine/workspace.ts. Mitigates CSWSH + * (Cross-Site WebSocket Hijacking, CWE-1385). See + * DEVELOPMENT-BENCHMARK.md ยงS3. + */ + +import type { IncomingMessage } from 'node:http'; + +const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']); + +/** + * Extract the hostname (lowercased) from an Origin URL header value. + * Returns null if the value cannot be parsed. + */ +function originHost(originHeader: string | undefined | null): string | null { + if (!originHeader) return null; + try { + const u = new URL(originHeader); + return u.hostname.toLowerCase(); + } catch { + return null; + } +} + +export interface VerifyClientInfo { + origin?: string; + req: IncomingMessage; + secure: boolean; +} + +/** + * Build a verifyClient callback that allows loopback origins plus an + * optional list of explicit additional hosts (e.g. a known LAN IP). + * The port portion of the origin is intentionally ignored โ€” we only + * gate by hostname, because the dev server's port may vary per run. + */ +export function createOriginVerify(extraAllowedHosts: string[] = []) { + const allowed = new Set([...LOOPBACK_HOSTS]); + for (const h of extraAllowedHosts) { + if (h) allowed.add(h.toLowerCase()); + } + + return function verifyClient( + info: VerifyClientInfo, + callback: (allowed: boolean, code?: number, message?: string) => void + ): void { + const originHeader = info.origin || (info.req.headers.origin as string | undefined); + const host = originHost(originHeader); + if (!host) { + // No Origin header at all (direct script / curl) โ€” reject for safety. + callback(false, 403, 'Origin header required'); + return; + } + if (allowed.has(host)) { + callback(true); + return; + } + callback(false, 403, `Origin ${host} not in allowlist`); + }; +} \ No newline at end of file diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.json new file mode 100644 index 0000000..9635ce4 --- /dev/null +++ b/packages/core/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/deployer/LICENSE b/packages/deployer/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/deployer/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/deployer/README.md b/packages/deployer/README.md new file mode 100644 index 0000000..2ba7697 --- /dev/null +++ b/packages/deployer/README.md @@ -0,0 +1,78 @@ +# @docmd/deployer + +Deployment configuration generator for **[docmd](https://github.com/docmd-io/docmd)** - the zero-config documentation engine. + +Generates production-ready deployment files from your `docmd.config.json`. All outputs are personalised to your project; no generic copy-paste templates. + +## Supported Targets + +### Self-hosted + +| Flag | Output | +|------|--------| +| `--docker` | `Dockerfile` + `.dockerignore` | +| `--nginx` | Production-hardened `nginx.conf` | +| `--caddy` | HTTPS-ready `Caddyfile` | + +### Cloud & CI + +| Flag | Output | +|------|--------| +| `--github-pages` | `.github/workflows/deploy.yml` (GitHub Actions) | +| `--vercel` | `vercel.json` | +| `--netlify` | `netlify.toml` | + +## Usage + +This package is invoked via the `docmd` CLI. You do not need to import it directly. + +```bash +# Self-hosted +docmd deploy --docker +docmd deploy --nginx +docmd deploy --caddy + +# Cloud / CI +docmd deploy --github-pages +docmd deploy --vercel +docmd deploy --netlify + +# Combine targets +docmd deploy --docker --nginx +``` + +Every run reads your `docmd.config.json` and regenerates the files to match. Zero-config projects use the same defaults as `docmd build`. + +## Architecture + +``` +@docmd/deployer + src/ + context.ts Shared DeployContext type + index.ts Orchestrator - resolves options, writes files + providers/ + docker.ts Dockerfile + .dockerignore + nginx.ts nginx.conf + caddy.ts Caddyfile + github-pages.ts GitHub Actions deploy workflow + vercel.ts vercel.json + netlify.ts netlify.toml +``` + +Each provider is a pure function `(ctx: DeployContext) => string` - no side effects, no I/O. File writing is handled by the orchestrator. Adding a new provider is a single file with no changes to other providers. + +**Dependency graph (no cycles):** + +``` +@docmd/core โ†’ @docmd/deployer โ†’ @docmd/api +``` + +Config resolution (`loadConfig`, `normalizeConfig`) stays in `@docmd/core` to keep `@docmd/deployer` free of any dependency on its parent package. + +## Documentation + +See **[docmd.io/deployment](https://docmd.io/deployment)** for detailed, service-specific guides. + +## License + +MIT - Copyright (c) 2025-present docmd.io \ No newline at end of file diff --git a/packages/deployer/package.json b/packages/deployer/package.json new file mode 100644 index 0000000..efe5f63 --- /dev/null +++ b/packages/deployer/package.json @@ -0,0 +1,50 @@ +{ + "name": "@docmd/deployer", + "version": "0.8.12", + "description": "Deployment configuration generator for docmd - Docker, Nginx, Caddy, GitHub Pages, Vercel, and Netlify.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "scripts": { + "build": "tsc" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "dependencies": { + "@docmd/api": "workspace:*" + }, + "devDependencies": { + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "deployer", + "docker", + "nginx", + "caddy", + "github-pages", + "vercel", + "netlify", + "deployment", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/deployer/src/context.ts b/packages/deployer/src/context.ts new file mode 100644 index 0000000..1d73320 --- /dev/null +++ b/packages/deployer/src/context.ts @@ -0,0 +1,24 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/deployer + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** Normalised project context shared across all deployment providers. */ +export interface DeployContext { + title: string; + outDir: string; + siteUrl: string | null; + hostname: string; + isSpa: boolean; + configFile: string | null; + version: string; +} \ No newline at end of file diff --git a/packages/deployer/src/index.ts b/packages/deployer/src/index.ts new file mode 100644 index 0000000..a50e604 --- /dev/null +++ b/packages/deployer/src/index.ts @@ -0,0 +1,99 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/deployer + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import fs from 'node:fs/promises'; +import { readFileSync } from 'node:fs'; +import { resolve } from 'node:path'; +import { TUI } from '@docmd/api'; + +import type { DeployContext } from './context.js'; +import { generateDocker } from './providers/docker.js'; +import { generateNginx } from './providers/nginx.js'; +import { generateCaddy } from './providers/caddy.js'; +import { generateGithubPages } from './providers/github-pages.js'; +import { generateVercel } from './providers/vercel.js'; +import { generateNetlify } from './providers/netlify.js'; + +const pkgUrl = new URL('../package.json', import.meta.url); +const { version } = JSON.parse(readFileSync(pkgUrl, 'utf-8')); + +export interface DeployOpts { + docker?: boolean; + nginx?: boolean; + caddy?: boolean; + githubPages?: boolean; + vercel?: boolean; + netlify?: boolean; + force?: boolean; +} + +async function write(filePath: string, content: string, label: string, force?: boolean) { + // N-2: when --force is not set, do not overwrite an existing file. + // The deploy command was silently clobbering existing Docker / nginx / + // vercel / etc. configs on every run. The fix: skip with a clear + // TUI line and the existing content is preserved. Pass --force to + // overwrite. This makes the existing `--force` flag meaningful. + if (await fileExists(filePath) && !force) { + TUI.step(`${label} (already exists, skipped โ€” use --force to overwrite)`, 'SKIP', TUI.yellow); + return; + } + await fs.writeFile(filePath, content, 'utf8'); + TUI.step(label, 'DONE'); +} + +async function fileExists(filePath: string): Promise { + try { await fs.access(filePath); return true; } catch { return false; } +} + +export async function generateDeployConfigs(ctx: DeployContext, opts: DeployOpts): Promise { + const cwd = process.cwd(); + const force = opts.force === true; + + TUI.section('Deployment Context'); + TUI.item('Project', ctx.title); + TUI.item('Output', `${ctx.outDir}/`); + if (ctx.hostname) TUI.item('Host', ctx.hostname); + TUI.footer(); + + if (opts.docker) { + const hasNginxConf = opts.nginx || await fileExists(resolve(cwd, 'nginx.conf')); + const { dockerfile, dockerignore } = await generateDocker(ctx); + const df = hasNginxConf + ? dockerfile.replace('FROM nginx:alpine', 'FROM nginx:alpine\nCOPY nginx.conf /etc/nginx/conf.d/default.conf') + : dockerfile; + await write(resolve(cwd, 'Dockerfile'), df, 'Dockerfile', force); + await write(resolve(cwd, '.dockerignore'), dockerignore, '.dockerignore', force); + } + + if (opts.nginx) { + await write(resolve(cwd, 'nginx.conf'), generateNginx(ctx), 'nginx.conf', force); + } + + if (opts.caddy) { + await write(resolve(cwd, 'Caddyfile'), generateCaddy(ctx), 'Caddyfile', force); + } + + if (opts.githubPages) { + await fs.mkdir(resolve(cwd, '.github', 'workflows'), { recursive: true }); + await write(resolve(cwd, '.github', 'workflows', 'deploy.yml'), generateGithubPages(ctx), '.github/workflows/deploy.yml', force); + } + + if (opts.vercel) { + await write(resolve(cwd, 'vercel.json'), generateVercel(ctx), 'vercel.json', force); + } + + if (opts.netlify) { + await write(resolve(cwd, 'netlify.toml'), generateNetlify(ctx), 'netlify.toml', force); + } +} \ No newline at end of file diff --git a/packages/deployer/src/providers/caddy.ts b/packages/deployer/src/providers/caddy.ts new file mode 100644 index 0000000..aa56d90 --- /dev/null +++ b/packages/deployer/src/providers/caddy.ts @@ -0,0 +1,64 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/deployer + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import type { DeployContext } from '../context.js'; + +export function generateCaddy(ctx: DeployContext): string { + const caddyAddress = ctx.hostname || ':80'; + const spaCaddyLine = ctx.isSpa + ? ' try_files {path} {path}/ /index.html' + : ' try_files {path} {path}/'; + + return `# --------------------------------------------------- +# Caddyfile generated by docmd v${ctx.version} +# Project: ${ctx.title} +# https://docmd.io/deployment/caddy +# --------------------------------------------------- + +${caddyAddress} { + root * ./${ctx.outDir} + file_server + + # SPA Routing Fallback +${spaCaddyLine} + + # Security headers + header { + X-Content-Type-Options "nosniff" + X-Frame-Options "SAMEORIGIN" + X-XSS-Protection "1; mode=block" + Referrer-Policy "strict-origin-when-cross-origin" + Permissions-Policy "camera=(), microphone=(), geolocation=()" + # HSTS (1 year). Only enable after verifying HTTPS works end-to-end. + # Strict-Transport-Security "max-age=31536000; includeSubDomains" + # CSP โ€” adjust if you embed third-party widgets or analytics. + Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self'; frame-ancestors 'self'" + -Server + } + + # Custom 404 + handle_errors { + rewrite * /404.html + file_server + } + + # Cache Static Assets (6 months) + @static { + file + path *.ico *.css *.js *.gif *.jpg *.jpeg *.png *.webp *.avif *.svg *.woff *.woff2 *.eot *.ttf *.otf + } + header @static Cache-Control "public, max-age=15552000, immutable" +} +`; +} \ No newline at end of file diff --git a/packages/deployer/src/providers/docker.ts b/packages/deployer/src/providers/docker.ts new file mode 100644 index 0000000..11f0b2d --- /dev/null +++ b/packages/deployer/src/providers/docker.ts @@ -0,0 +1,64 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/deployer + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import type { DeployContext } from '../context.js'; + +export async function generateDocker(ctx: DeployContext): Promise<{ dockerfile: string; dockerignore: string }> { + const buildCmd = ctx.configFile ? `docmd build --config ${ctx.configFile}` : 'docmd build'; + + const dockerfile = `# --------------------------------------------------- +# Dockerfile generated by docmd v${ctx.version} +# Project: ${ctx.title} +# https://docmd.io/deployment/docker +# --------------------------------------------------- + +# Stage 1: Build the docmd site +FROM node:22-alpine AS builder +WORKDIR /app + +# Copy dependency manifests first for optimal layer caching +COPY package*.json ./ +RUN if [ -f package.json ]; then npm install --ignore-scripts; fi + +# Copy the rest of the project +COPY . . + +# Install the exact docmd core version used to configure this deployment +RUN npm install -g @docmd/core@${ctx.version} + +# Build the site +RUN ${buildCmd} + +# Stage 2: Serve with nginx +FROM nginx:alpine +COPY --from=builder /app/${ctx.outDir} /usr/share/nginx/html +EXPOSE 80 +CMD ["nginx", "-g", "daemon off;"] +`; + + const dockerignore = `node_modules +${ctx.outDir} +dist +.git +.gitignore +.env +.env.* +*.md +!docs/**/*.md +.DS_Store +Thumbs.db +`; + + return { dockerfile, dockerignore }; +} \ No newline at end of file diff --git a/packages/deployer/src/providers/github-pages.ts b/packages/deployer/src/providers/github-pages.ts new file mode 100644 index 0000000..a1457a0 --- /dev/null +++ b/packages/deployer/src/providers/github-pages.ts @@ -0,0 +1,80 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/deployer + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import type { DeployContext } from '../context.js'; + +export function generateGithubPages(ctx: DeployContext): string { + const buildCmd = ctx.configFile ? `docmd build --config ${ctx.configFile}` : 'docmd build'; + + return `# --------------------------------------------------- +# GitHub Pages Deployment Workflow +# Generated by docmd v${ctx.version} +# Project: ${ctx.title} +# https://docmd.io/deployment/github-pages +# --------------------------------------------------- + +name: Deploy to GitHub Pages + +on: + push: + branches: + - main + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: "20" + + - name: Install dependencies + run: npm install + + - name: Install docmd + run: npm install -g @docmd/core@${ctx.version} + + - name: Build site + run: ${buildCmd} + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./${ctx.outDir} + + deploy: + environment: + name: github-pages + url: \${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 +`; +} \ No newline at end of file diff --git a/packages/deployer/src/providers/netlify.ts b/packages/deployer/src/providers/netlify.ts new file mode 100644 index 0000000..048bf2c --- /dev/null +++ b/packages/deployer/src/providers/netlify.ts @@ -0,0 +1,64 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/deployer + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import type { DeployContext } from '../context.js'; + +export function generateNetlify(ctx: DeployContext): string { + // T-Z9: do NOT emit a `[[redirects]] from = "/*" status = 200` block. + // docmd generates real HTML files for every route (SPA mode is a thin + // client-side layer on top of pre-rendered HTML, not a single-page + // app served from /). A catch-all to /index.html with status 200 + // makes missing routes return 200 with the home page content โ€” a + // soft-404 that hides errors, hurts SEO, and creates a URL + // enumeration surface. Without the redirect, Netlify serves the + // generated file if it exists, or the bundled 404.html (with 404 + // status) if not. + return `# --------------------------------------------------- +# netlify.toml generated by docmd v${ctx.version} +# Project: ${ctx.title} +# https://docmd.io/deployment/netlify +# --------------------------------------------------- + +[build] + command = "npm install -g @docmd/core@${ctx.version} && docmd build" + publish = "${ctx.outDir}" + +[build.environment] + NODE_VERSION = "20" + +# Security headers applied to every response. +# HSTS is commented out โ€” enable it after verifying HTTPS works end-to-end. +# CSP: adjust default-src if you embed third-party widgets or analytics. +[[headers]] + for = "/*" + [headers.values] + X-Content-Type-Options = "nosniff" + X-Frame-Options = "SAMEORIGIN" + X-XSS-Protection = "1; mode=block" + Referrer-Policy = "strict-origin-when-cross-origin" + Permissions-Policy = "camera=(), microphone=(), geolocation=()" + Content-Security-Policy = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self'; frame-ancestors 'self'" + # Strict-Transport-Security = "max-age=31536000; includeSubDomains" + +[[headers]] + for = "/assets/*" + [headers.values] + Cache-Control = "public, max-age=15552000, immutable" + +[[headers]] + for = "/*.html" + [headers.values] + Cache-Control = "public, max-age=0, must-revalidate" +`; +} \ No newline at end of file diff --git a/packages/deployer/src/providers/nginx.ts b/packages/deployer/src/providers/nginx.ts new file mode 100644 index 0000000..973bf51 --- /dev/null +++ b/packages/deployer/src/providers/nginx.ts @@ -0,0 +1,81 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/deployer + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import type { DeployContext } from '../context.js'; + +export function generateNginx(ctx: DeployContext): string { + const serverName = ctx.hostname || 'localhost'; + const spaBlock = ctx.isSpa ? ` + # SPA Routing Fallback + location / { + try_files $uri $uri/ /index.html; + } +` : ` + location / { + try_files $uri $uri/ =404; + } +`; + + return `# --------------------------------------------------- +# nginx.conf generated by docmd v${ctx.version} +# Project: ${ctx.title} +# https://docmd.io/deployment/nginx +# --------------------------------------------------- + +server { + listen 80; + server_name ${serverName}; + root /usr/share/nginx/html; + index index.html; + + # Security headers + server_tokens off; + add_header X-Content-Type-Options "nosniff" always; + add_header X-Frame-Options "SAMEORIGIN" always; + add_header X-XSS-Protection "1; mode=block" always; + add_header Referrer-Policy "strict-origin-when-cross-origin" always; + add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always; + # HSTS (1 year). Only enable after verifying HTTPS works end-to-end. + # add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + # CSP โ€” adjust 'default-src' if you embed third-party widgets or analytics. + add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self'; frame-ancestors 'self'" always; + + # GZIP Compression + gzip on; + gzip_vary on; + gzip_proxied any; + gzip_min_length 256; + gzip_types + text/plain + text/css + application/json + application/javascript + text/xml + application/xml + application/xml+rss + text/javascript + image/svg+xml; +${spaBlock} + # Custom 404 + error_page 404 /404.html; + + # Cache Control for Static Assets + location ~* \\.(?:ico|css|js|gif|jpe?g|png|webp|avif|woff2?|eot|ttf|otf|svg)$ { + expires 6M; + access_log off; + add_header Cache-Control "public, immutable"; + } +} +`; +} \ No newline at end of file diff --git a/packages/deployer/src/providers/vercel.ts b/packages/deployer/src/providers/vercel.ts new file mode 100644 index 0000000..5930466 --- /dev/null +++ b/packages/deployer/src/providers/vercel.ts @@ -0,0 +1,60 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/deployer + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import type { DeployContext } from '../context.js'; + +export function generateVercel(ctx: DeployContext): string { + const routes = ctx.isSpa + ? ` "routes": [ + { "handle": "filesystem" }, + { "src": "/(.*)", "dest": "/index.html" } + ]` + : ` "cleanUrls": true, + "trailingSlash": false`; + + return `{ + "$schema": "https://openapi.vercel.sh/vercel.json", + "buildCommand": "docmd build", + "outputDirectory": "${ctx.outDir}", + "installCommand": "npm install && npm install -g @docmd/core@${ctx.version}", + "framework": null, + "headers": [ + { + "source": "/(.*)", + "headers": [ + { "key": "X-Content-Type-Options", "value": "nosniff" }, + { "key": "X-Frame-Options", "value": "SAMEORIGIN" }, + { "key": "X-XSS-Protection", "value": "1; mode=block" }, + { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }, + { "key": "Permissions-Policy", "value": "camera=(), microphone=(), geolocation=()" }, + { "key": "Content-Security-Policy", "value": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self'; frame-ancestors 'self'" } + ] + }, + { + "source": "/assets/(.*)", + "headers": [ + { "key": "Cache-Control", "value": "public, max-age=15552000, immutable" } + ] + }, + { + "source": "/(.*).html", + "headers": [ + { "key": "Cache-Control", "value": "public, max-age=0, must-revalidate" } + ] + } + ], +${routes} +} +`; +} \ No newline at end of file diff --git a/packages/deployer/tsconfig.json b/packages/deployer/tsconfig.json new file mode 100644 index 0000000..4dcf19b --- /dev/null +++ b/packages/deployer/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} \ No newline at end of file diff --git a/packages/engines/js/LICENSE b/packages/engines/js/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/engines/js/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/engines/js/README.md b/packages/engines/js/README.md new file mode 100644 index 0000000..26630f1 --- /dev/null +++ b/packages/engines/js/README.md @@ -0,0 +1,39 @@ +# @docmd/engine-js + +Default JavaScript engine for docmd using Node.js worker threads and native async I/O. Works everywhere without any native dependencies. + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Usage + +This engine is used by default when no `engine` configuration is specified: + +```javascript +// docmd.config.js +export default { + // No engine specified = uses 'js' engine +}; +``` + +Explicitly select the JS engine: + +```javascript +export default { + engine: 'js' +}; +``` + +## Capabilities + +- **file-discovery**: Parallel file system traversal +- **file-read-batch**: Batched file reading +- **git-log**: Git history extraction via `git` CLI +- **search-index**: Search index building with MiniSearch + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/engines/js/package.json b/packages/engines/js/package.json new file mode 100644 index 0000000..4c78eff --- /dev/null +++ b/packages/engines/js/package.json @@ -0,0 +1,51 @@ +{ + "name": "@docmd/engine-js", + "version": "0.8.12", + "description": "Default JavaScript engine for docmd using Node.js native APIs.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } + }, + "scripts": { + "build": "tsc" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "devDependencies": { + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "engine", + "javascript", + "nodejs", + "minimalist", + "zero-config", + "site-generator", + "documentation", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/engines/js/src/index.ts b/packages/engines/js/src/index.ts new file mode 100644 index 0000000..a3ef7f0 --- /dev/null +++ b/packages/engines/js/src/index.ts @@ -0,0 +1,300 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import * as fs from 'fs/promises'; +import * as path from 'path'; +import { execFile } from 'child_process'; +import { promisify } from 'util'; + +const execFileAsync = promisify(execFile); + +// --------------------------------------------------------------------------- +// Types - self-contained, no external dependencies +// --------------------------------------------------------------------------- + +export interface EngineTask { + type: string; + payload: any; + timeout?: number; +} + +export interface EngineResult { + success: boolean; + data?: T; + error?: string; + duration?: number; +} + +export interface Engine { + readonly name: string; + readonly version: string; + run(task: EngineTask): Promise>; + supports?(taskType: string): boolean; +} + +// --------------------------------------------------------------------------- +// Task Handlers +// --------------------------------------------------------------------------- + +type TaskHandler = (payload: any) => Promise; + +const SKIP_DIRS = new Set(['node_modules', '.git', '.docmd', 'dist', 'site']); + +const handlers: Record = { + + // --- File Operations --- + + 'file:discover': async ({ dir, extensions, exclude }) => { + const results: Array<{ path: string; size: number; mtimeMs: number }> = []; + const extSet = extensions ? new Set(extensions) : null; + const skipSet: Set = exclude ? new Set([...SKIP_DIRS, ...exclude]) : SKIP_DIRS; + + async function walk(currentDir: string): Promise { + let entries; + try { + entries = await fs.readdir(currentDir, { withFileTypes: true }); + } catch { + return; + } + await Promise.all(entries.map(async (entry) => { + const fullPath = path.join(currentDir, entry.name); + if (entry.isDirectory()) { + if (!skipSet.has(entry.name)) await walk(fullPath); + } else if (entry.isFile()) { + const ext = path.extname(entry.name).toLowerCase(); + if (!extSet || extSet.has(ext) || extSet.has(entry.name)) { + try { + const stat = await fs.stat(fullPath); + results.push({ path: fullPath, size: stat.size, mtimeMs: stat.mtimeMs }); + } catch { /* skip inaccessible files */ } + } + } + })); + } + + await walk(dir); + return results; + }, + + 'file:read': async ({ path: filePath }) => { + return fs.readFile(filePath, 'utf-8'); + }, + + 'file:readBatch': async ({ paths }) => { + const results: Record = {}; + await Promise.all((paths as string[]).map(async (p) => { + try { + results[p] = await fs.readFile(p, 'utf-8'); + } catch { + results[p] = ''; + } + })); + return results; + }, + + 'file:write': async ({ path: filePath, content }) => { + await fs.mkdir(path.dirname(filePath), { recursive: true }); + await fs.writeFile(filePath, content, 'utf-8'); + return { success: true }; + }, + + 'file:exists': async ({ path: filePath }) => { + try { + await fs.access(filePath); + return true; + } catch { + return false; + } + }, + + // --- Git Operations --- + + 'git:log': async ({ filePaths, maxCommits = 6 }) => { + const results: Record = {}; + await Promise.all((filePaths as string[]).map(async (filePath) => { + try { + const { stdout } = await execFileAsync('git', [ + 'log', '--follow', '-n', String(maxCommits), + '--format=%H|%h|%an|%ae|%at|%s', '--', filePath, + ], { cwd: process.cwd() }); + results[filePath] = stdout.trim() + ? stdout.trim().split('\n').map((line) => { + const [hash, shortHash, author, email, timestamp, ...msg] = line.split('|'); + return { hash, shortHash, author, email, timestamp: parseInt(timestamp, 10) * 1000, message: msg.join('|') }; + }) + : []; + } catch { + results[filePath] = []; + } + })); + return results; + }, + + 'git:status': async () => { + try { + const { stdout } = await execFileAsync('git', ['status', '--porcelain'], { cwd: process.cwd() }); + return stdout.trim().split('\n').filter(Boolean).map((line) => ({ + status: line.slice(0, 2).trim(), + path: line.slice(3), + })); + } catch { + return []; + } + }, + + // --- Search Operations --- + + 'search:index': async ({ documents }) => { + const index = { + documents: (documents as any[]).map((doc) => ({ + id: doc.id, + title: (doc.title as string).toLowerCase(), + content: (doc.content as string).toLowerCase().slice(0, 5000), + path: doc.path, + locale: doc.locale, + version: doc.version, + })), + builtAt: Date.now(), + }; + return JSON.stringify(index); + }, + + // โ”€โ”€ docmd-search semantic tasks โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + + /** + * search:chunk โ€” Split a document into overlapping chunks by heading + word count. + * payload: { text, file, chunkSize?, chunkOverlap? } + * returns: Array<{ file, heading?, text, range: [start, end] }> + */ + 'search:chunk': async ({ text, file, chunkSize = 256, chunkOverlap = 32 }) => { + const chunks: Array<{ file: string; heading?: string; text: string; range: [number, number] }> = []; + let currentHeading: string | undefined; + let currentWords: string[] = []; + let currentStart = 0; + let bytePos = 0; + + for (const line of (text as string).split('\n')) { + const lineBytes = line.length + 1; + + if (/^#{1,6}\s/.test(line)) { + // Flush current chunk before heading + if (currentWords.length > 0) { + chunks.push({ file, heading: currentHeading, text: currentWords.join(' '), range: [currentStart, bytePos] }); + currentWords = currentWords.slice(-chunkOverlap); + currentStart = bytePos; + } + currentHeading = line.replace(/^#+\s*/, '').trim(); + } else { + const words = line.split(/\s+/).filter(Boolean); + currentWords.push(...words); + + if (currentWords.length >= chunkSize) { + chunks.push({ file, heading: currentHeading, text: currentWords.join(' '), range: [currentStart, bytePos + lineBytes] }); + currentWords = currentWords.slice(-chunkOverlap); + currentStart = bytePos; + } + } + + bytePos += lineBytes; + } + + if (currentWords.length > 0) { + chunks.push({ file, heading: currentHeading, text: currentWords.join(' '), range: [currentStart, bytePos] }); + } + + return chunks; + }, + + /** + * search:quantize โ€” Float32 โ†’ Int8 per-vector quantization. + * payload: { vectors: number[][], dimensions: number } + * returns: { quantized: number[][], mins: number[], ranges: number[] } + */ + 'search:quantize': async ({ vectors, dimensions = 384 }) => { + const quantized: number[][] = []; + const mins: number[] = []; + const ranges: number[] = []; + + for (const vec of (vectors as number[][])) { + const v = vec.length === dimensions ? vec : Array.from({ length: dimensions }, (_, i) => vec[i] ?? 0); + const min = Math.min(...v); + const max = Math.max(...v); + const range = Math.abs(max - min) < 1e-10 ? 1.0 : max - min; + + const q = v.map(x => Math.round(((x - min) / range) * 255 - 128)); + quantized.push(q); + mins.push(min); + ranges.push(range); + } + + return { quantized, mins, ranges }; + }, + + /** + * search:cosine โ€” Batch cosine similarity between a query vector and a corpus. + * payload: { query: number[], vectors: number[][], topK?: number } + * returns: Array<{ index: number, score: number }> + */ + 'search:cosine': async ({ query, vectors, topK = 10 }) => { + const q = query as number[]; + const qNorm = Math.sqrt(q.reduce((s: number, v: number) => s + v * v, 0)); + if (qNorm < 1e-10) return []; + + const scores = (vectors as number[][]).map((vec, idx) => { + const dot = q.reduce((s: number, v: number, i: number) => s + v * (vec[i] ?? 0), 0); + const vNorm = Math.sqrt(vec.reduce((s: number, v: number) => s + v * v, 0)); + const sim = vNorm < 1e-10 ? 0 : dot / (qNorm * vNorm); + return { index: idx, score: sim }; + }); + + return scores.sort((a, b) => b.score - a.score).slice(0, topK); + }, +}; + +// --------------------------------------------------------------------------- +// Engine Factory +// --------------------------------------------------------------------------- + +/** + * Create a JavaScript engine instance. + * + * The JS engine uses only Node.js built-in APIs โ€” no external dependencies, + * no native binaries. Works on every platform and Node.js version docmd supports. + */ +export function createJsEngine(): Engine { + return { + name: 'js', + version: '0.8.12', + + supports(taskType: string): boolean { + return taskType in handlers; + }, + + async run(task: EngineTask): Promise> { + const start = Date.now(); + try { + const handler = handlers[task.type]; + if (!handler) { + return { success: false, error: `Unknown task type: '${task.type}'`, duration: Date.now() - start }; + } + const data = await handler(task.payload); + return { success: true, data, duration: Date.now() - start }; + } catch (error) { + return { success: false, error: (error as Error).message, duration: Date.now() - start }; + } + }, + }; +} + +// Engine, EngineTask, and EngineResult are declared above as exported interfaces. diff --git a/packages/engines/js/tsconfig.json b/packages/engines/js/tsconfig.json new file mode 100644 index 0000000..3b7bf53 --- /dev/null +++ b/packages/engines/js/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "dist", + "declaration": true, + "declarationMap": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} \ No newline at end of file diff --git a/packages/engines/rust-binaries/LICENSE b/packages/engines/rust-binaries/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/engines/rust-binaries/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/engines/rust-binaries/README.md b/packages/engines/rust-binaries/README.md new file mode 100644 index 0000000..9159b95 --- /dev/null +++ b/packages/engines/rust-binaries/README.md @@ -0,0 +1,55 @@ +# @docmd/engine-rust-binaries + +**Maintainer-only package.** Contains the Rust source code and pre-built native binaries for the docmd Rust engine. + +## Structure + +``` +native/ + Cargo.toml - Rust crate definition + build.rs - napi-rs build script + src/lib.rs - All Rust engine capabilities (edit this to add features) + +bin/ + docmd-engine-darwin-arm64.node - macOS Apple Silicon (753KB) + docmd-engine-darwin-x64.node - macOS Intel + docmd-engine-linux-x64.node - Linux x64 + docmd-engine-linux-arm64.node - Linux ARM64 + docmd-engine-win32-x64.node - Windows x64 +``` + +## For Maintainers + +### Adding new capabilities + +1. Edit `native/src/lib.rs` - add your new task handler +2. Run `pnpm --filter @docmd/engine-rust-binaries run build` +3. Commit the updated binary in `bin/` +4. The new capability is now available to all users + +### Building binaries + +```bash +# Build for current platform +pnpm --filter @docmd/engine-rust-binaries run build + +# You need to build on each platform: +# - macOS ARM64 (Apple Silicon Mac) +# - macOS x64 (Intel Mac) +# - Linux x64 +# - Linux ARM64 +# - Windows x64 +``` + +### How users get the binaries + +Users install `@docmd/engine-rust` (not this package). At install time, it downloads the appropriate binary from this repo's `bin/` directory on GitHub. + +## Not published to npm + +This package is `"private": true`. It exists only to: +1. Hold the Rust source code +2. Hold the pre-built binaries (committed to git) +3. Provide a build script for maintainers + +Users never install or interact with this package directly. diff --git a/packages/engines/rust-binaries/bin/docmd-engine-darwin-arm64.node b/packages/engines/rust-binaries/bin/docmd-engine-darwin-arm64.node new file mode 100755 index 0000000000000000000000000000000000000000..5218260e5909874773b6c442870bfa910b341e22 GIT binary patch literal 771536 zcmc${33yah((r$7ca}~91jq&i$%0D)2r2@JB&L&~gk@Yp6qlJvLS#%p!2m81H65a_ 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

Z-?Dn| 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

RihRbw9NPQuJ0jeTn|nx*pwY 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�Q^8IC=a=++f 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

Q`hjF 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 z%0A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 fs.existsSync(f)); + +if (!builtFile) { + console.error(`Could not find compiled library in ${releaseDir}`); + process.exit(1); +} + +fs.mkdirSync(binDir, { recursive: true }); +fs.copyFileSync(builtFile, outputPath); + +const size = (fs.statSync(outputPath).size / 1024).toFixed(0); +console.log(`โœ“ Built: bin/${outputName} (${size}KB)`); +console.log(`\nCommit this file to the repo. Users will download it at install time.`); diff --git a/packages/engines/rust-binaries/native/Cargo.lock b/packages/engines/rust-binaries/native/Cargo.lock new file mode 100644 index 0000000..7a1df15 --- /dev/null +++ b/packages/engines/rust-binaries/native/Cargo.lock @@ -0,0 +1,362 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "aho-corasick" +version = "1.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301" +dependencies = [ + "memchr", +] + +[[package]] +name = "bitflags" +version = "2.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3" + +[[package]] +name = "bytes" +version = "1.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33" + +[[package]] +name = "cfg-if" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" + +[[package]] +name = "convert_case" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec182b0ca2f35d8fc196cf3404988fd8b8c739a4d270ff118a398feb0cbec1ca" +dependencies = [ + "unicode-segmentation", +] + +[[package]] +name = "ctor" +version = "0.2.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a2785755761f3ddc1492979ce1e48d2c00d09311c39e4466429188f3dd6501" +dependencies = [ + "quote", + "syn", +] + +[[package]] +name = "docmd-engine" +version = "0.8.12" +dependencies = [ + "napi", + "napi-build", + "napi-derive", + "serde", + "serde_json", + "tokio", +] + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "libc" +version = "0.2.186" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66" + +[[package]] +name = "libloading" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55" +dependencies = [ + "cfg-if", + "windows-link", +] + +[[package]] +name = "memchr" +version = "2.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79" + +[[package]] +name = "mio" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1" +dependencies = [ + "libc", + "wasi", + "windows-sys", +] + +[[package]] +name = "napi" +version = "2.16.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "55740c4ae1d8696773c78fdafd5d0e5fe9bc9f1b071c7ba493ba5c413a9184f3" +dependencies = [ + "bitflags", + "ctor", + "napi-derive", + "napi-sys", + "once_cell", + "tokio", +] + +[[package]] +name = "napi-build" +version = "2.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d376940fd5b723c6893cd1ee3f33abbfd86acb1cd1ec079f3ab04a2a3bc4d3b1" + +[[package]] +name = "napi-derive" +version = "2.16.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7cbe2585d8ac223f7d34f13701434b9d5f4eb9c332cccce8dee57ea18ab8ab0c" +dependencies = [ + "cfg-if", + "convert_case", + "napi-derive-backend", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "napi-derive-backend" +version = "1.0.75" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1639aaa9eeb76e91c6ae66da8ce3e89e921cd3885e99ec85f4abacae72fc91bf" +dependencies = [ + "convert_case", + "once_cell", + "proc-macro2", + "quote", + "regex", + "semver", + "syn", +] + +[[package]] +name = "napi-sys" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "427802e8ec3a734331fec1035594a210ce1ff4dc5bc1950530920ab717964ea3" +dependencies = [ + "libloading", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "proc-macro2" +version = "1.0.106" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "regex" +version = "1.12.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "regex-automata" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a" + +[[package]] +name = "semver" +version = "1.0.28" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd" + +[[package]] +name = "serde" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.228" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "serde_json" +version = "1.0.149" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + +[[package]] +name = "syn" +version = "2.0.117" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "tokio" +version = "1.52.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe" +dependencies = [ + "bytes", + "libc", + "mio", + "pin-project-lite", + "signal-hook-registry", + "tokio-macros", + "windows-sys", +] + +[[package]] +name = "tokio-macros" +version = "2.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "unicode-ident" +version = "1.0.24" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" + +[[package]] +name = "unicode-segmentation" +version = "1.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9629274872b2bfaf8d66f5f15725007f635594914870f65218920345aa11aa8c" + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "zmij" +version = "1.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa" diff --git a/packages/engines/rust-binaries/native/Cargo.toml b/packages/engines/rust-binaries/native/Cargo.toml new file mode 100644 index 0000000..3013274 --- /dev/null +++ b/packages/engines/rust-binaries/native/Cargo.toml @@ -0,0 +1,32 @@ +[package] +name = "docmd-engine" +version = "0.8.12" +edition = "2021" +description = "Native Node.js addon for the docmd Rust engine" +license = "MIT" + +# napi-rs builds a cdylib (.node file loaded by Node.js via require()) +[lib] +crate-type = ["cdylib"] + +[dependencies] +# napi-rs: Rust โ†” Node.js bridge (N-API, ABI-stable across Node versions) +napi = { version = "2", features = ["async", "napi4"] } +napi-derive = "2" + +# Async runtime โ€” tokio powers all async tasks inside the addon +tokio = { version = "1", features = ["rt-multi-thread", "fs", "process", "macros"] } + +# Serialisation โ€” tasks arrive as JSON strings, results leave as JSON strings +serde = { version = "1", features = ["derive"] } +serde_json = "1" + +[build-dependencies] +napi-build = "2" + +# Release profile: optimise for speed and small binary size +[profile.release] +lto = true +codegen-units = 1 +opt-level = 3 +strip = true \ No newline at end of file diff --git a/packages/engines/rust-binaries/native/build.rs b/packages/engines/rust-binaries/native/build.rs new file mode 100644 index 0000000..52e917c --- /dev/null +++ b/packages/engines/rust-binaries/native/build.rs @@ -0,0 +1,17 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + + fn main() { + napi_build::setup(); +} \ No newline at end of file diff --git a/packages/engines/rust-binaries/native/src/lib.rs b/packages/engines/rust-binaries/native/src/lib.rs new file mode 100644 index 0000000..a6741dd --- /dev/null +++ b/packages/engines/rust-binaries/native/src/lib.rs @@ -0,0 +1,236 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +use napi_derive::napi; +use serde::{Deserialize, Serialize}; +use serde_json::Value; +use std::collections::HashMap; +use std::path::Path; +use tokio::process::Command; + +type TaskResult = Result; + +// --------------------------------------------------------------------------- +// Entry point +// --------------------------------------------------------------------------- + +#[napi] +pub async fn run_task(task_type: String, payload_json: String) -> napi::Result { + let payload: Value = serde_json::from_str(&payload_json) + .map_err(|e| napi::Error::from_reason(format!("Invalid payload JSON: {e}")))?; + + let result: TaskResult = dispatch(&task_type, payload).await; + + match result { + Ok(data) => serde_json::to_string(&data) + .map_err(|e| napi::Error::from_reason(format!("Failed to serialise: {e}"))), + Err(msg) => Ok(format!(r#"{{"error":"{}"}}"#, msg.replace('"', "\\\""))), + } +} + +async fn dispatch(task_type: &str, payload: Value) -> TaskResult { + match task_type { + "file:discover" => file_discover(payload).await, + "file:read" => file_read(payload).await, + "file:readBatch" => file_read_batch(payload).await, + "file:write" => file_write(payload).await, + "file:exists" => file_exists(payload).await, + "git:log" => git_log(payload).await, + "git:status" => git_status(payload).await, + "search:index" => search_index(payload).await, + other => Err(format!("Unknown task type: '{other}'")), + } +} + +// --------------------------------------------------------------------------- +// file:discover +// --------------------------------------------------------------------------- + +#[derive(Serialize)] +struct FileEntry { path: String, size: u64, #[serde(rename = "mtimeMs")] mtime_ms: u64 } + +const SKIP_DIRS: &[&str] = &["node_modules", ".git", ".docmd", "dist", "site"]; + +async fn file_discover(payload: Value) -> TaskResult { + let dir = payload["dir"].as_str().ok_or_else(|| "file:discover: missing 'dir'".to_string())?; + let extensions: Option> = payload["extensions"].as_array() + .map(|a| a.iter().filter_map(|v| v.as_str().map(String::from)).collect()); + let exclude: Vec = payload["exclude"].as_array() + .map(|a| a.iter().filter_map(|v| v.as_str().map(String::from)).collect()) + .unwrap_or_default(); + + let mut results: Vec = Vec::new(); + walk_dir(Path::new(dir), &extensions, &exclude, &mut results).map_err(|e| format!("file:discover: {e}"))?; + serde_json::to_value(results).map_err(|e| e.to_string()) +} + +fn walk_dir(dir: &Path, extensions: &Option>, extra_skip: &[String], results: &mut Vec) -> std::io::Result<()> { + let entries = match std::fs::read_dir(dir) { Ok(e) => e, Err(_) => return Ok(()) }; + for entry in entries.flatten() { + let path = entry.path(); + let name_str = entry.file_name().to_string_lossy().to_string(); + if path.is_dir() { + if !SKIP_DIRS.contains(&name_str.as_str()) && !extra_skip.iter().any(|s| s == &name_str) { + walk_dir(&path, extensions, extra_skip, results)?; + } + } else if path.is_file() { + let include = match extensions { + None => true, + Some(exts) => { + let ext = path.extension().map(|e| format!(".{}", e.to_string_lossy())).unwrap_or_default(); + exts.iter().any(|e| e == &ext || e == &name_str) + } + }; + if include { + if let Ok(meta) = entry.metadata() { + let mtime_ms = meta.modified().ok().and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok()).map(|d| d.as_millis() as u64).unwrap_or(0); + results.push(FileEntry { path: path.to_string_lossy().into_owned(), size: meta.len(), mtime_ms }); + } + } + } + } + Ok(()) +} + +// --------------------------------------------------------------------------- +// file:read +// --------------------------------------------------------------------------- + +async fn file_read(payload: Value) -> TaskResult { + let file_path = payload["path"].as_str().ok_or_else(|| "file:read: missing 'path'".to_string())?; + let content = tokio::fs::read_to_string(file_path).await.map_err(|e| format!("file:read: {e}"))?; + Ok(Value::String(content)) +} + +// --------------------------------------------------------------------------- +// file:readBatch +// --------------------------------------------------------------------------- + +async fn file_read_batch(payload: Value) -> TaskResult { + let paths: Vec = payload["paths"].as_array() + .ok_or_else(|| "file:readBatch: missing 'paths'".to_string())? + .iter().filter_map(|v| v.as_str().map(String::from)).collect(); + + let mut handles = Vec::with_capacity(paths.len()); + for p in paths { + handles.push(tokio::spawn(async move { + let content = tokio::fs::read_to_string(&p).await.unwrap_or_default(); + (p, content) + })); + } + + let mut map = HashMap::new(); + for h in handles { + let (p, c) = h.await.map_err(|e| format!("file:readBatch: {e}"))?; + if !c.is_empty() { map.insert(p, c); } + } + serde_json::to_value(map).map_err(|e| e.to_string()) +} + +// --------------------------------------------------------------------------- +// file:write +// --------------------------------------------------------------------------- + +async fn file_write(payload: Value) -> TaskResult { + let file_path = payload["path"].as_str().ok_or_else(|| "file:write: missing 'path'".to_string())?; + let content = payload["content"].as_str().ok_or_else(|| "file:write: missing 'content'".to_string())?; + if let Some(parent) = Path::new(file_path).parent() { + tokio::fs::create_dir_all(parent).await.map_err(|e| format!("file:write mkdir: {e}"))?; + } + tokio::fs::write(file_path, content).await.map_err(|e| format!("file:write: {e}"))?; + Ok(serde_json::json!({ "success": true })) +} + +// --------------------------------------------------------------------------- +// file:exists +// --------------------------------------------------------------------------- + +async fn file_exists(payload: Value) -> TaskResult { + let file_path = payload["path"].as_str().ok_or_else(|| "file:exists: missing 'path'".to_string())?; + Ok(Value::Bool(tokio::fs::metadata(file_path).await.is_ok())) +} + +// --------------------------------------------------------------------------- +// git:log +// --------------------------------------------------------------------------- + +#[derive(Serialize)] +struct GitEntry { hash: String, #[serde(rename = "shortHash")] short_hash: String, author: String, email: String, timestamp: u64, message: String } + +async fn git_log(payload: Value) -> TaskResult { + let file_paths: Vec = payload["filePaths"].as_array() + .ok_or_else(|| "git:log: missing 'filePaths'".to_string())? + .iter().filter_map(|v| v.as_str().map(String::from)).collect(); + let max_commits = payload["maxCommits"].as_u64().unwrap_or(6); + + let mut handles = Vec::with_capacity(file_paths.len()); + for fp in file_paths { + let n = max_commits; + handles.push(tokio::spawn(async move { + let out = Command::new("git").args(["log", "--follow", "-n", &n.to_string(), "--format=%H|%h|%an|%ae|%at|%s", "--", &fp]).output().await; + let entries: Vec = match out { + Ok(o) if o.status.success() => { + String::from_utf8_lossy(&o.stdout).trim().lines().filter(|l| !l.is_empty()).map(|line| { + let parts: Vec<&str> = line.splitn(6, '|').collect(); + let ts = parts.get(4).and_then(|s| s.parse::().ok()).unwrap_or(0); + GitEntry { hash: parts.first().unwrap_or(&"").to_string(), short_hash: parts.get(1).unwrap_or(&"").to_string(), author: parts.get(2).unwrap_or(&"").to_string(), email: parts.get(3).unwrap_or(&"").to_string(), timestamp: ts * 1000, message: parts.get(5).unwrap_or(&"").to_string() } + }).collect() + } + _ => vec![], + }; + (fp, entries) + })); + } + + let mut map: HashMap> = HashMap::new(); + for h in handles { + let (fp, entries) = h.await.map_err(|e| format!("git:log: {e}"))?; + map.insert(fp, entries); + } + serde_json::to_value(map).map_err(|e| e.to_string()) +} + +// --------------------------------------------------------------------------- +// git:status +// --------------------------------------------------------------------------- + +async fn git_status(_payload: Value) -> TaskResult { + let out = Command::new("git").args(["status", "--porcelain"]).output().await.map_err(|e| format!("git:status: {e}"))?; + let entries: Vec = String::from_utf8_lossy(&out.stdout).lines().filter(|l| !l.is_empty()).map(|line| { + let status = if line.len() >= 2 { line[..2].trim() } else { "" }; + let path = if line.len() > 3 { &line[3..] } else { "" }; + serde_json::json!({ "status": status, "path": path }) + }).collect(); + Ok(Value::Array(entries)) +} + +// --------------------------------------------------------------------------- +// search:index +// --------------------------------------------------------------------------- + +#[derive(Deserialize)] +struct SearchDoc { id: String, title: String, content: String, path: String, locale: Option, version: Option } + +#[derive(Serialize)] +struct IndexedDoc { id: String, title: String, content: String, path: String, #[serde(skip_serializing_if = "Option::is_none")] locale: Option, #[serde(skip_serializing_if = "Option::is_none")] version: Option } + +async fn search_index(payload: Value) -> TaskResult { + let docs: Vec = serde_json::from_value(payload["documents"].clone()).map_err(|e| format!("search:index: {e}"))?; + let indexed: Vec = docs.into_iter().map(|doc| IndexedDoc { + id: doc.id, title: doc.title.to_lowercase(), content: doc.content.to_lowercase().chars().take(5000).collect(), path: doc.path, locale: doc.locale, version: doc.version, + }).collect(); + let result = serde_json::json!({ "documents": indexed, "builtAt": std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_millis() as u64).unwrap_or(0) }); + let s = serde_json::to_string(&result).map_err(|e| e.to_string())?; + Ok(Value::String(s)) +} \ No newline at end of file diff --git a/packages/engines/rust-binaries/package.json b/packages/engines/rust-binaries/package.json new file mode 100644 index 0000000..db05018 --- /dev/null +++ b/packages/engines/rust-binaries/package.json @@ -0,0 +1,41 @@ +{ + "name": "@docmd/engine-rust-binaries", + "version": "0.8.12", + "description": "Pre-built Rust binaries for the docmd engine. All platforms bundled.", + "scripts": { + "build": "node build.js" + }, + "files": [ + "bin" + ], + "engines": { + "node": ">=18" + }, + "keywords": [ + "docmd", + "engine", + "rust", + "binaries", + "native", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "documentation", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/engines/rust/LICENSE b/packages/engines/rust/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/engines/rust/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/engines/rust/README.md b/packages/engines/rust/README.md new file mode 100644 index 0000000..d565bf3 --- /dev/null +++ b/packages/engines/rust/README.md @@ -0,0 +1,54 @@ +# @docmd/engine-rust + +Rust-accelerated engine for docmd with native I/O and parallel processing. Provides significant performance improvements for large documentation sites. + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Installation + +The Rust engine is optional and installed on-demand. To use it: + +```javascript +// docmd.config.js +export default { + engine: 'rust' +}; +``` + +On first run, docmd will prompt you to install the appropriate native binary for your platform. + +## Supported Platforms + +| Platform | Package | +|----------|---------| +| macOS (ARM64) | `@docmd/engine-rust-darwin-arm64` | +| macOS (x64) | `@docmd/engine-rust-darwin-x64` | +| Linux (x64, glibc) | `@docmd/engine-rust-linux-x64-gnu` | +| Linux (ARM64, glibc) | `@docmd/engine-rust-linux-arm64-gnu` | +| Windows (x64) | `@docmd/engine-rust-win32-x64-msvc` | + +## Capabilities + +- **file-discovery**: Parallel directory traversal with native filesystem APIs +- **file-read-batch**: Memory-mapped file reading for large batches +- **git-log**: Direct libgit2 integration (no git CLI required) +- **search-index**: SIMD-accelerated text processing + +## When to Use + +The Rust engine is recommended for: + +- Large documentation sites (1000+ pages) +- Projects with extensive Git history +- Multi-project monorepo builds +- CI/CD pipelines where build time is critical + +For smaller sites or development mode, the default JS engine may be more convenient. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/engines/rust/package.json b/packages/engines/rust/package.json new file mode 100644 index 0000000..1434b01 --- /dev/null +++ b/packages/engines/rust/package.json @@ -0,0 +1,56 @@ +{ + "name": "@docmd/engine-rust", + "version": "0.8.12", + "description": "Rust-accelerated engine for docmd. The postinstall script downloads a pre-built platform binary from npm CDN (unpkg/jsdelivr). No code is executed beyond copying the .node file. Source: https://github.com/docmd-io/docmd", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } + }, + "scripts": { + "build": "tsc", + "postinstall": "node scripts/postinstall.cjs" + }, + "files": [ + "dist", + "scripts", + "bin" + ], + "engines": { + "node": ">=18" + }, + "devDependencies": { + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "engine", + "rust", + "native", + "performance", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "documentation", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/engines/rust/scripts/postinstall.cjs b/packages/engines/rust/scripts/postinstall.cjs new file mode 100644 index 0000000..b061f08 --- /dev/null +++ b/packages/engines/rust/scripts/postinstall.cjs @@ -0,0 +1,118 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +'use strict'; + +const https = require('https'); +const fs = require('fs'); +const path = require('path'); + +const PLATFORM_MAP = { + 'darwin-arm64': 'docmd-engine-darwin-arm64.node', + 'darwin-x64': 'docmd-engine-darwin-x64.node', + 'linux-x64': 'docmd-engine-linux-x64.node', + 'linux-arm64': 'docmd-engine-linux-arm64.node', + 'win32-x64': 'docmd-engine-win32-x64.node', +}; + +const platformId = `${process.platform}-${process.arch}`; +const binaryName = PLATFORM_MAP[platformId]; + +// This script only downloads a pre-built .node binary from npm CDN +// (unpkg / jsdelivr) for your platform. Source: https://github.com/docmd-io/docmd +// You can safely approve it with: npm approve-scripts @docmd/engine-rust +if (!binaryName) { + console.warn(`[@docmd/engine-rust] Unsupported platform: ${platformId}`); + console.warn(`Supported: ${Object.keys(PLATFORM_MAP).join(', ')}`); + console.warn(`The JS engine will be used as fallback.`); + process.exit(0); +} + +const pkgDir = path.join(__dirname, '..'); +const binDir = path.join(pkgDir, 'bin'); +const binaryPath = path.join(binDir, binaryName); + +// Get version from this package's package.json +const version = require(path.join(pkgDir, 'package.json')).version; + +// Skip if already present +if (fs.existsSync(binaryPath)) { + console.log(`[@docmd/engine-rust] Binary already present: ${binaryName}`); + process.exit(0); +} + +// Download URLs with exact version (npm CDNs) +const URLS = [ + // unpkg (npm CDN) - exact version + `https://unpkg.com/@docmd/engine-rust-binaries@${version}/bin/${binaryName}`, + // jsdelivr (npm CDN) - exact version + `https://cdn.jsdelivr.net/npm/@docmd/engine-rust-binaries@${version}/bin/${binaryName}`, +]; + +function download(url) { + return new Promise((resolve, reject) => { + const follow = (url, redirects = 0) => { + if (redirects > 5) return reject(new Error('Too many redirects')); + + const proto = url.startsWith('https') ? https : require('http'); + proto.get(url, { headers: { 'User-Agent': 'docmd-engine-rust' } }, (res) => { + if (res.statusCode === 301 || res.statusCode === 302 || res.statusCode === 307) { + return follow(res.headers.location, redirects + 1); + } + if (res.statusCode !== 200) { + res.resume(); + return reject(new Error(`HTTP ${res.statusCode}`)); + } + + fs.mkdirSync(binDir, { recursive: true }); + const tmp = binaryPath + '.tmp'; + const out = fs.createWriteStream(tmp); + + res.pipe(out); + out.on('finish', () => { + fs.renameSync(tmp, binaryPath); + fs.chmodSync(binaryPath, 0o755); + resolve(); + }); + out.on('error', (err) => { + fs.rmSync(tmp, { force: true }); + reject(err); + }); + }).on('error', reject); + }; + follow(url); + }); +} + +async function main() { + console.log(`[@docmd/engine-rust] Downloading ${binaryName} (v${version})โ€ฆ`); + + for (const url of URLS) { + try { + await download(url); + const size = (fs.statSync(binaryPath).size / 1024).toFixed(0); + console.log(`[@docmd/engine-rust] โœ“ Downloaded (${size}KB)`); + return; + } catch (err) { + // Try next URL + } + } + + console.warn(`[@docmd/engine-rust] Could not download binary for v${version}.`); + console.warn(`This version may not be published yet.`); + console.warn(`The JS engine will be used as fallback.`); + // Exit 0 so pnpm install doesn't fail +} + +main(); diff --git a/packages/engines/rust/src/index.ts b/packages/engines/rust/src/index.ts new file mode 100644 index 0000000..752b93a --- /dev/null +++ b/packages/engines/rust/src/index.ts @@ -0,0 +1,155 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { createRequire } from 'module'; +import * as path from 'path'; +import * as fs from 'fs'; +import { fileURLToPath } from 'url'; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const require = createRequire(import.meta.url); + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +export interface EngineTask { + type: string; + payload: any; + timeout?: number; +} + +export interface EngineResult { + success: boolean; + data?: T; + error?: string; + duration?: number; +} + +export interface Engine { + readonly name: string; + readonly version: string; + run(task: EngineTask): Promise>; + supports?(taskType: string): boolean; +} + +// --------------------------------------------------------------------------- +// Platform Detection +// --------------------------------------------------------------------------- + +type PlatformId = 'darwin-arm64' | 'darwin-x64' | 'linux-x64' | 'linux-arm64' | 'win32-x64'; + +const SUPPORTED: PlatformId[] = ['darwin-arm64', 'darwin-x64', 'linux-x64', 'linux-arm64', 'win32-x64']; + +const BINARY_NAMES: Record = { + 'darwin-arm64': 'docmd-engine-darwin-arm64.node', + 'darwin-x64': 'docmd-engine-darwin-x64.node', + 'linux-x64': 'docmd-engine-linux-x64.node', + 'linux-arm64': 'docmd-engine-linux-arm64.node', + 'win32-x64': 'docmd-engine-win32-x64.node', +}; + +function detectPlatform(): PlatformId | null { + const id = `${process.platform}-${process.arch}` as PlatformId; + return SUPPORTED.includes(id) ? id : null; +} + +// --------------------------------------------------------------------------- +// Binary Loading +// --------------------------------------------------------------------------- + +function resolveBinaryPath(platformId: PlatformId): string { + const name = BINARY_NAMES[platformId]; + // bin/ is sibling to dist/ (both under package root) + const pkgRoot = path.join(__dirname, '..'); + const binaryPath = path.join(pkgRoot, 'bin', name); + + if (!fs.existsSync(binaryPath)) { + throw new Error( + `Rust engine binary not found: ${binaryPath}\n\n` + + `Run: pnpm --filter @docmd/engine-rust run postinstall\n` + + `Or the JS engine will be used as fallback.` + ); + } + + return binaryPath; +} + +interface NativeBindings { + runTask(taskType: string, payloadJson: string): Promise; +} + +let _binding: NativeBindings | null = null; + +function loadBinding(platformId: PlatformId): NativeBindings { + if (_binding) return _binding; + const binaryPath = resolveBinaryPath(platformId); + _binding = require(binaryPath) as NativeBindings; + return _binding; +} + +// --------------------------------------------------------------------------- +// Public API +// --------------------------------------------------------------------------- + +export function isRustEngineAvailable(): boolean { + const platformId = detectPlatform(); + if (!platformId) return false; + try { + const name = BINARY_NAMES[platformId]; + const pkgRoot = path.join(__dirname, '..'); + return fs.existsSync(path.join(pkgRoot, 'bin', name)); + } catch { + return false; + } +} + +export function createRustEngine(): Engine { + const platformId = detectPlatform(); + + if (!platformId) { + throw new Error( + `Rust engine not supported on ${process.platform}-${process.arch}.\n` + + `Supported: ${SUPPORTED.join(', ')}` + ); + } + + const binding = loadBinding(platformId); + + return { + name: 'rust', + version: '0.8.12', + + supports(_taskType: string): boolean { + return true; + }, + + async run(task: EngineTask): Promise> { + const start = Date.now(); + try { + const raw = await binding.runTask(task.type, JSON.stringify(task.payload)); + const data = JSON.parse(raw) as T; + + // Check if Rust returned an error object + if (data && typeof data === 'object' && 'error' in data) { + return { success: false, error: (data as any).error, duration: Date.now() - start }; + } + + return { success: true, data, duration: Date.now() - start }; + } catch (error) { + return { success: false, error: (error as Error).message, duration: Date.now() - start }; + } + }, + }; +} diff --git a/packages/engines/rust/tsconfig.json b/packages/engines/rust/tsconfig.json new file mode 100644 index 0000000..3b7bf53 --- /dev/null +++ b/packages/engines/rust/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "dist", + "declaration": true, + "declarationMap": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +} \ No newline at end of file diff --git a/packages/legacy/doc.md/LICENSE b/packages/legacy/doc.md/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/legacy/doc.md/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/legacy/doc.md/README.md b/packages/legacy/doc.md/README.md new file mode 100644 index 0000000..6cdd8f1 --- /dev/null +++ b/packages/legacy/doc.md/README.md @@ -0,0 +1,21 @@ +# doc.md + +> **This package has moved.** Use **[@docmd/core](https://www.npmjs.com/package/@docmd/core)** for all future updates. + +This is a legacy wrapper that forwards commands to `@docmd/core` to avoid breaking existing CI/CD pipelines. This package will not receive new features or updates. + +## Migration + +```bash +# Remove the old package +npm uninstall -g doc.md + +# Install the current package +npm install -g @docmd/core +``` + +See **[docmd.io](https://docmd.io)** for full documentation. + +## License + +MIT \ No newline at end of file diff --git a/packages/legacy/doc.md/bin/docmd.js b/packages/legacy/doc.md/bin/docmd.js new file mode 100644 index 0000000..0463b5b --- /dev/null +++ b/packages/legacy/doc.md/bin/docmd.js @@ -0,0 +1,24 @@ +#!/usr/bin/env node + +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +const pkgName = (() => { try { return require('../package.json').name; } catch { return 'this package'; } })(); +console.error('\x1b[33m%s\x1b[0m', 'โš ๏ธ DEPRECATION NOTICE:'); +console.error('\x1b[33m%s\x1b[0m', ` You are using the legacy package "${pkgName}".`); +console.error('\x1b[33m%s\x1b[0m', ' Please uninstall it and install "@docmd/core" for future updates.'); +console.error('\x1b[33m%s\x1b[0m', ' Redirecting to new engine...\n'); + +// Pass control to the core binary +require('@docmd/core/bin/docmd.js'); \ No newline at end of file diff --git a/packages/legacy/doc.md/package.json b/packages/legacy/doc.md/package.json new file mode 100644 index 0000000..1f296a1 --- /dev/null +++ b/packages/legacy/doc.md/package.json @@ -0,0 +1,47 @@ +{ + "name": "doc.md", + "version": "0.8.12", + "description": "Discontinued. Legacy wrapper for docmd. Please use @docmd/core.", + "bin": { + "docmd": "bin/docmd.js" + }, + "engines": { + "node": ">=18" + }, + "dependencies": { + "@docmd/core": "workspace:*" + }, + "keywords": [ + "docmd", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "documentation", + "typescript", + "javascript", + "nodejs", + "browser", + "website", + "generator", + "hosted", + "cli", + "ssg", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/legacy/mgks/LICENSE b/packages/legacy/mgks/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/legacy/mgks/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/legacy/mgks/README.md b/packages/legacy/mgks/README.md new file mode 100644 index 0000000..c50d3ea --- /dev/null +++ b/packages/legacy/mgks/README.md @@ -0,0 +1,21 @@ +# @mgks/docmd + +> **This package has moved.** Use **[@docmd/core](https://www.npmjs.com/package/@docmd/core)** for all future updates. + +This is a legacy wrapper that forwards commands to `@docmd/core` to avoid breaking existing CI/CD pipelines. This package will not receive new features or updates. + +## Migration + +```bash +# Remove the old package +npm uninstall -g @mgks/docmd + +# Install the current package +npm install -g @docmd/core +``` + +See **[docs.docmd.io](https://docs.docmd.io)** for full documentation. + +## License + +MIT \ No newline at end of file diff --git a/packages/legacy/mgks/bin/docmd.js b/packages/legacy/mgks/bin/docmd.js new file mode 100755 index 0000000..0463b5b --- /dev/null +++ b/packages/legacy/mgks/bin/docmd.js @@ -0,0 +1,24 @@ +#!/usr/bin/env node + +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +const pkgName = (() => { try { return require('../package.json').name; } catch { return 'this package'; } })(); +console.error('\x1b[33m%s\x1b[0m', 'โš ๏ธ DEPRECATION NOTICE:'); +console.error('\x1b[33m%s\x1b[0m', ` You are using the legacy package "${pkgName}".`); +console.error('\x1b[33m%s\x1b[0m', ' Please uninstall it and install "@docmd/core" for future updates.'); +console.error('\x1b[33m%s\x1b[0m', ' Redirecting to new engine...\n'); + +// Pass control to the core binary +require('@docmd/core/bin/docmd.js'); \ No newline at end of file diff --git a/packages/legacy/mgks/package.json b/packages/legacy/mgks/package.json new file mode 100644 index 0000000..aee9655 --- /dev/null +++ b/packages/legacy/mgks/package.json @@ -0,0 +1,47 @@ +{ + "name": "@mgks/docmd", + "version": "0.8.12", + "description": "Discontinued. Legacy wrapper for docmd. Please use @docmd/core.", + "bin": { + "docmd": "bin/docmd.js" + }, + "engines": { + "node": ">=18" + }, + "dependencies": { + "@docmd/core": "workspace:*" + }, + "keywords": [ + "docmd", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "documentation", + "typescript", + "javascript", + "nodejs", + "browser", + "website", + "generator", + "hosted", + "cli", + "ssg", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/live/LICENSE b/packages/live/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/live/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/live/README.md b/packages/live/README.md new file mode 100644 index 0000000..40855c7 --- /dev/null +++ b/packages/live/README.md @@ -0,0 +1,28 @@ +# @docmd/live + +The browser-based bundle that powers the docmd Live Editor - packages the core parser, UI, and themes into a single standalone script that renders documentation client-side without a Node.js server. + +**Live demo:** **[live.docmd.io](https://live.docmd.io)** + +## Quick start + +```bash +# Run the editor locally +docmd live +``` + +```js +// Embed the editor engine in your own tooling +import { buildLive } from '@docmd/core'; +await buildLive(); +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/live/bin/docmd-live.js b/packages/live/bin/docmd-live.js new file mode 100755 index 0000000..1270b63 --- /dev/null +++ b/packages/live/bin/docmd-live.js @@ -0,0 +1,18 @@ +#!/usr/bin/env node + +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { start } from '../dist/index.js'; +start(); \ No newline at end of file diff --git a/packages/live/package.json b/packages/live/package.json new file mode 100644 index 0000000..2697262 --- /dev/null +++ b/packages/live/package.json @@ -0,0 +1,68 @@ +{ + "name": "@docmd/live", + "version": "0.8.12", + "description": "Browser-based editor engine for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": "./dist/index.js" + }, + "bin": { + "docmd-live": "bin/docmd-live.js" + }, + "scripts": { + "build": "tsc && node ./dist/build.js" + }, + "files": [ + "bin", + "dist", + "public", + "src" + ], + "engines": { + "node": ">=18" + }, + "dependencies": { + "@docmd/parser": "workspace:*", + "@docmd/plugin-math": "workspace:*", + "@docmd/plugin-mermaid": "workspace:*", + "@docmd/themes": "workspace:*", + "@docmd/tui": "workspace:*", + "@docmd/ui": "workspace:*", + "buffer": "^6.0.3", + "esbuild": "^0.28.1", + "katex": "^0.17.0", + "markdown-it-texmath": "^1.0.0" + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "editor", + "browser", + "live", + "parser", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/live/src/browser-entry.ts b/packages/live/src/browser-entry.ts new file mode 100644 index 0000000..9c690f0 --- /dev/null +++ b/packages/live/src/browser-entry.ts @@ -0,0 +1,132 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { createMarkdownProcessor, processContent } from '@docmd/parser/dist/markdown-processor.js'; +import texmath from 'markdown-it-texmath'; +import katex from 'katex'; +// @ts-expect-error virtual module +import templates from 'virtual:docmd-templates'; + +// Expose the compile function to the window.docmd global +async function compile(markdown: string, config: any = {}) { + const defaults: any = { + siteTitle: 'Live Preview', + theme: { appearance: 'light', name: 'default', codeHighlight: true }, + layout: { spa: false }, + ...config + }; + + // 1. Process Markdown with Plugin Support + const md = createMarkdownProcessor(defaults, (parser) => { + // Math (KaTeX) + parser.use(texmath, { engine: katex, delimiters: 'dollars' }); + + // Mermaid fence override + const defaultFence = parser.renderer.rules.fence; + parser.renderer.rules.fence = (tokens, idx, options, env, self) => { + const info = tokens[idx].info.trim(); + if (info === 'mermaid') { + return `

${parser.utils.escapeHtml(tokens[idx].content)}
\n`; + } + return defaultFence(tokens, idx, options, env, self); + }; + }); + const result = processContent(markdown, md, defaults); + + if (!result) return '

Error parsing markdown

'; + + // Since we are in the browser, we assume assets are served at ./assets/ + const assetsRoot = './assets'; + const appearance = defaults.theme.appearance || 'light'; + + // Theme init script โ€” handles DOCMD_APPEARANCE + safe localStorage + const themeInitScript = templates['partials/theme-init.js'] || ''; + + // KaTeX stylesheet (theme tokens come from docmd-main.css) + const katexCss = ``; + + // Mermaid init โ€” runs in the preview iframe, picks up the current theme + const mermaidScript = ` + + `; + + // Minimal interactivity for the preview iframe. docmd-main.js is not + // loaded here (we stripped the chrome), so tab switching has to be + // wired here. Collapsibles use native
, so they need no JS. + const interactivityScript = ` + + + + + ${katexCss} + + + +${result.htmlContent} +${interactivityScript} +${mermaidScript} + +`; +} + +export { compile }; \ No newline at end of file diff --git a/packages/live/src/build.ts b/packages/live/src/build.ts new file mode 100644 index 0000000..82b960e --- /dev/null +++ b/packages/live/src/build.ts @@ -0,0 +1,188 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import fs from 'fs/promises'; +import esbuild from 'esbuild'; +import * as ui from '@docmd/ui'; +import * as themes from '@docmd/themes'; +import { fileURLToPath } from 'url'; +import { createRequire } from 'module'; +import { TUI } from '@docmd/tui'; + +const require = createRequire(import.meta.url); +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); + +// Path Constants +const PKG_ROOT = path.resolve(__dirname, '..'); +const PUBLIC_DIR = path.join(PKG_ROOT, 'public'); + +// Asset Discovery +const SOURCE_ASSETS_DIR = (async () => { + const srcPath = path.join(PKG_ROOT, 'src'); + try { + await fs.access(srcPath); + return srcPath; + } catch { + return __dirname; + } +})(); + +async function build(outputPath?: string) { + const elapsed = TUI.timer(); + const sp = TUI.spinner('Building Live Editor'); + + const finalOutputDir = outputPath ? path.join(outputPath, 'dist') : PUBLIC_DIR; + + try { + // 1. Prepare Dist + await fs.rm(finalOutputDir, { recursive: true, force: true }); + await fs.mkdir(finalOutputDir, { recursive: true }); + + // 2. Generate Shims + const assetsDir = await SOURCE_ASSETS_DIR; + const shimPath = path.join(__dirname, 'shims.js'); + await fs.writeFile(shimPath, `import { Buffer } from 'buffer'; globalThis.Buffer = Buffer;`); + + // 3. Template Plugin + const templatePlugin = { + name: 'docmd-templates', + setup(build) { + build.onResolve({ filter: /^virtual:docmd-templates$/ }, args => ({ + path: args.path, namespace: 'docmd-templates-ns', + })); + build.onLoad({ filter: /.*/, namespace: 'docmd-templates-ns' }, async () => { + const templatesDir = ui.getTemplatesDir(); + const templates = {}; + const tryRead = async (f) => { + const p = path.join(templatesDir, f); + try { return await fs.readFile(p, 'utf8'); } catch { return null; } + }; + const files = await fs.readdir(templatesDir); + for (const file of files) { + if (file.endsWith('.ejs')) templates[file] = await tryRead(file); + } + try { + const partialsDir = path.join(templatesDir, 'partials'); + const partials = await fs.readdir(partialsDir); + for (const file of partials) { + if (file.endsWith('.ejs') || file.endsWith('.js')) { + templates[`partials/${file}`] = await tryRead(`partials/${file}`); + } + } + } catch { /* Ignore missing partials */ } + return { contents: `export default ${JSON.stringify(templates)};`, loader: 'js' }; + }); + }, + }; + + // 4. Node Shim Plugin + const nodeShimPlugin = { + name: 'node-deps-shim', + setup(build) { + build.onResolve({ filter: /^(node:)?path$/ }, args => ({ path: args.path, namespace: 'path-shim' })); + build.onLoad({ filter: /.*/, namespace: 'path-shim' }, () => ({ + contents: ` + export const join = (...a) => a.filter(Boolean).join('/'); + export const resolve = (...a) => '/' + a.filter(Boolean).join('/'); + export const basename = (p) => p ? p.split(/[\\\\/]/).pop() : ''; + export const dirname = (p) => p ? p.split(/[\\\\/]/).slice(0, -1).join('/') || '.' : '.'; + export const extname = (p) => p ? '.' + p.split('.').pop() : ''; + export const sep = '/'; + export default { join, resolve, basename, dirname, extname, sep }; + `, loader: 'js' + })); + build.onResolve({ filter: /^(node:)?fs(\/promises)?|fs-extra$/ }, args => ({ path: args.path, namespace: 'fs-shim' })); + build.onLoad({ filter: /.*/, namespace: 'fs-shim' }, () => ({ + contents: ` + export const promises = {}; + export const existsSync = () => false; + export default { promises, existsSync }; + `, loader: 'js' + })); + } + }; + + // 5. Bundle JS + await esbuild.build({ + entryPoints: [path.join(assetsDir, 'browser-entry.ts')], + bundle: true, + outfile: path.join(finalOutputDir, 'docmd-live.js'), + platform: 'browser', + format: 'iife', + globalName: 'docmd', + minify: true, + define: { 'process.env.NODE_ENV': '"production"' }, + inject: [shimPath], + plugins: [templatePlugin, nodeShimPlugin] + }); + + // 6. Copy Static Assets + await fs.copyFile(path.join(assetsDir, 'index.html'), path.join(finalOutputDir, 'index.html')); + await fs.copyFile(path.join(assetsDir, 'docmd-live.css'), path.join(finalOutputDir, 'docmd-live.css')); + + const cssDest = path.join(finalOutputDir, 'assets/css'); + const jsDest = path.join(finalOutputDir, 'assets/js'); + await fs.mkdir(cssDest, { recursive: true }); + await fs.mkdir(jsDest, { recursive: true }); + await fs.copyFile(path.join(assetsDir, 'docmd-live-preview.css'), path.join(cssDest, 'docmd-live-preview.css')); + + const copy = async (src, destName) => { + try { + await fs.copyFile(src, path.join(path.extname(destName) === '.js' ? jsDest : cssDest, destName)); + } catch { + TUI.warn(`Missing asset: ${path.basename(src)}`); + } + }; + + await copy(path.join(ui.getAssetsDir(), 'css/docmd-main.css'), 'docmd-main.css'); + await copy(path.join(ui.getAssetsDir(), 'css/docmd-highlight-light.css'), 'docmd-highlight-light.css'); + await copy(path.join(ui.getAssetsDir(), 'css/docmd-highlight-dark.css'), 'docmd-highlight-dark.css'); + await copy(path.join(ui.getAssetsDir(), 'js/docmd-main.js'), 'docmd-main.js'); + + const mermaidPkgPath = require.resolve('@docmd/plugin-mermaid/package.json'); + const mermaidDir = path.dirname(mermaidPkgPath); + const mermaidSrc = path.join(mermaidDir, 'dist', 'init-mermaid.js'); + await fs.copyFile(mermaidSrc, path.join(jsDest, 'init-mermaid.js')); + + const themesDir = themes.getThemesDir(); + const themeFiles = await fs.readdir(themesDir); + for (const t of themeFiles) { + if (t.endsWith('.css')) { + const cleanName = t.replace('docmd-theme-', ''); + await copy(path.join(themesDir, t), `docmd-theme-${cleanName}`); + } + } + + try { + await fs.copyFile(path.join(ui.getAssetsDir(), 'favicon.ico'), path.join(finalOutputDir, 'favicon.ico')); + } catch { + TUI.warn('Missing Favicon'); + } + + const relPath = path.relative(process.cwd(), finalOutputDir); + sp.done(`Live Editor built in ./${relPath} (${elapsed()})`); + } catch (e) { + sp.fail('Live build failed'); + TUI.error('Live build failed', e.message); + process.exit(1); + } +} + +export { build }; + +if (process.argv[1].endsWith('build.js')) { + build(); +} \ No newline at end of file diff --git a/packages/live/src/docmd-live-preview.css b/packages/live/src/docmd-live-preview.css new file mode 100644 index 0000000..7a8c496 --- /dev/null +++ b/packages/live/src/docmd-live-preview.css @@ -0,0 +1,56 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +.toc-sidebar, +.page-footer-actions, +.sidebar-header h1 { + display: none !important; +} + +body { + display: flex; + flex-direction: column; + min-height: 100vh; +} + +.main-content-wrapper { + display: flex; + flex-direction: column; + flex: 1; +} + +.content-area { + flex: 1; + min-height: 80vh; +} + +.content-layout { + display: block !important; +} + +@media (max-width: 768px) { + .sidebar { + display: none !important; + } + + .main-content-wrapper { + margin-left: 0 !important; + } +} + +@media (max-width: 768px) { + .sidebar-toggle-button { + display: none !important; + } +} \ No newline at end of file diff --git a/packages/live/src/docmd-live.css b/packages/live/src/docmd-live.css new file mode 100644 index 0000000..6cd06a8 --- /dev/null +++ b/packages/live/src/docmd-live.css @@ -0,0 +1,371 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + + :root { + --header-height: 50px; + --border-color: #e0e0e0; + --bg-color: #f9fafb; + --primary-color: #007bff; + --resizer-width: 8px +} + +body { + margin: 0; + height: 100vh; + display: flex; + flex-direction: column; + font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; + overflow: hidden +} + +.top-bar { + height: var(--header-height); + background: #fff; + border-bottom: 1px solid var(--border-color); + display: flex; + align-items: center; + justify-content: space-between; + padding: 0 1rem; + flex-shrink: 0 +} + +.logo { + font-weight: 700; + font-size: 1.1rem; + display: flex; + align-items: center; + gap: 12px +} + +.logo span { + background: var(--primary-color); + color: #fff; + padding: 2px 6px; + border-radius: 4px; + font-size: .75rem; + text-transform: uppercase +} + +.back-link { + display: flex; + width: 24px; + height: 24px; + background-color: #f0f0f0; + border-radius: 100%; + align-items: center; + justify-content: center; + color: #666; + transition: color 0.2s, transform .2s; + text-decoration: none; + padding: 4px; +} + +.back-link:hover { + color: var(--primary-color); + background: #f0f0f0; + transform: translateX(-2px) +} + +.logo .docmd-logo { + color: inherit; + text-decoration: none; + transition: .5s; +} + +.logo .docmd-logo:hover { + color: var(--primary-color); +} + +.view-switcher { + display: flex; + background: #f0f0f0; + padding: 3px; + border-radius: 8px; + gap: 0; +} + +.view-btn { + border: none; + background: transparent; + padding: 6px 12px; + border-radius: 6px; + cursor: pointer; + font-size: 0.85rem; + color: #666; + font-weight: 500; + transition: background 0.15s, color 0.15s; +} + +.view-btn:hover { + color: #333; +} + +.view-btn.active { + background: #fff; + color: #000; + box-shadow: 0 1px 3px #0000001a; + font-weight: 600; +} + +.workspace { + flex: 1; + display: flex; + position: relative; + overflow: hidden +} + +.pane { + height: 100%; + display: flex; + flex-direction: column; + min-width: 300px; + background: #fff +} + +.pane-header { + padding: 0 16px; + height: 40px; + font-size: .75rem; + font-weight: 600; + text-transform: uppercase; + color: #888; + background: var(--bg-color); + border-bottom: 1px solid var(--border-color); + flex-shrink: 0; + display: flex; + align-items: center; + justify-content: space-between; +} + +/* Light/dark toggle in the preview pane header. Sits on the right via + the .pane-header's space-between layout. Sun icon shows in dark + mode (clicking returns to light), moon icon shows in light mode. */ +.preview-theme-toggle { + display: inline-flex; + align-items: center; + justify-content: center; + width: 26px; + height: 26px; + border-radius: 4px; + color: #888; + background: transparent; + border: none; + cursor: pointer; + transition: background 0.15s ease, color 0.15s ease; +} + +.preview-theme-toggle:hover { + background: rgba(0, 0, 0, 0.06); + color: #333; +} + +.preview-theme-toggle svg { + width: 15px; + height: 15px; + stroke-width: 2; +} + +.preview-theme-toggle .icon-sun { display: none; } +.preview-theme-toggle .icon-moon { display: inline-block; } +[data-theme="dark"] .preview-theme-toggle .icon-sun { display: inline-block; } +[data-theme="dark"] .preview-theme-toggle .icon-moon { display: none; } + +.editor-pane { + width: 50% +} + +.presets-bar { + display: flex; + gap: 6px; + overflow-x: auto; + white-space: nowrap; + scrollbar-width: none; +} + +.presets-bar::-webkit-scrollbar { + display: none; +} + +.presets-bar button { + background: #eef2f5; + border: 1px solid #e0e0e0; + border-radius: 12px; + padding: 2px 10px; + font-size: 10px; + color: #666; + cursor: pointer; + text-transform: uppercase; + font-weight: 600; + transition: all 0.2s; + flex-shrink: 0; +} + +.presets-bar button:hover, +.presets-bar button.active { + background: #fff; + border-color: var(--primary-color); + color: var(--primary-color); +} + +textarea#input { + flex: 1; + border: none; + resize: none; + padding: 20px; + font-family: 'JetBrains Mono', 'Fira Code', Consolas, monospace; + font-size: 14px; + line-height: 1.6; + outline: none; + background: var(--bg-color) +} + +.preview-pane { + flex: 1; + background: #fff +} + +.iframe-wrapper { + width: 100%; + height: 100%; + background: #fff; + position: relative; +} + +iframe#preview { + width: 100%; + height: 100%; + border: none; + display: block; + transition: opacity 0.15s ease-in-out; + opacity: 1; +} + +.iframe-wrapper.rendering iframe { + opacity: 0.6; + filter: grayscale(0.5); +} + +.resizer { + width: var(--resizer-width); + background: var(--bg-color); + border-left: 1px solid var(--border-color); + border-right: 1px solid var(--border-color); + cursor: col-resize; + display: flex; + align-items: center; + justify-content: center; + transition: background .2s; + z-index: 10 +} + +.resizer:hover, +.resizer.resizing { + background: #e0e0e0 +} + +.resizer::after { + content: "||"; + color: #aaa; + font-size: 10px; + letter-spacing: 1px +} + +body.mode-single .resizer { + display: none +} + +body.mode-single .pane { + width: 100% !important; + min-width: 0 +} + +body.mode-single .editor-pane { + display: none +} + +body.mode-single .preview-pane { + display: none +} + +body.mode-single.show-editor .editor-pane { + display: flex +} + +body.mode-single.show-preview .preview-pane { + display: flex +} + +@media (max-width: 768px) { + .desktop-only { + display: none !important + } + + .resizer { + display: none !important + } + + .pane { + width: 100% !important + } + + .editor-pane { + display: none + } + + .preview-pane { + display: none + } + + body.mobile-tab-editor .editor-pane { + display: flex + } + + body.mobile-tab-preview .preview-pane { + display: flex + } + + .mobile-tabs { + display: flex !important; + position: fixed; + bottom: 0; + left: 0; + right: 0; + height: 50px; + background: #fff; + border-top: 1px solid var(--border-color); + z-index: 100 + } + + .mobile-tab-btn { + flex: 1; + border: none; + background: transparent; + font-weight: 600; + color: #888; + cursor: pointer + } + + .mobile-tab-btn.active { + color: var(--primary-color); + border-top: 2px solid var(--primary-color) + } + + .workspace { + padding-bottom: 50px + } +} + +.mobile-tabs { + display: none +} \ No newline at end of file diff --git a/packages/live/src/index.html b/packages/live/src/index.html new file mode 100644 index 0000000..f5c9e0b --- /dev/null +++ b/packages/live/src/index.html @@ -0,0 +1,233 @@ + + + + + + + + + + Docmd Live Editor + + + + + + + + + + + + +
+ + + +
+ + + +
+
+ + +
+ +
+
+ Markdown +
+ + + + + + +
+
+ +
+ + +
+ + +
+
+ Preview + +
+ +
+
+ + +
+ + +
+ + + + \ No newline at end of file diff --git a/packages/live/src/index.ts b/packages/live/src/index.ts new file mode 100644 index 0000000..000d189 --- /dev/null +++ b/packages/live/src/index.ts @@ -0,0 +1,178 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import http from 'http'; +import fs from 'fs/promises'; +import { fileURLToPath } from 'node:url'; +import { build } from './build.js'; +import { TUI } from '@docmd/tui'; +import { safePath as canonicalSafePath } from '@docmd/api'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); + +const MIME_TYPES = { + '.html': 'text/html', + '.js': 'text/javascript', + '.css': 'text/css', + '.json': 'application/json', + '.png': 'image/png', + '.jpg': 'image/jpg', + '.svg': 'image/svg+xml', + '.ico': 'image/x-icon' +}; + +function checkPortInUse(port: number): Promise { + // Probe binds to 127.0.0.1 only. We just need to know if the loopback + // interface has the port โ€” binding to 0.0.0.0 briefly exposed the probe + // socket to the LAN. + return new Promise((resolve) => { + const tester = http.createServer() + .once('error', (err: any) => resolve(err.code === 'EADDRINUSE')) + .once('listening', () => tester.close(() => resolve(false))) + .listen(port, '127.0.0.1'); + }); +} + +async function findAvailablePort(startPort: number): Promise { + let port = startPort; + while (await checkPortInUse(port)) { + port++; + } + return port; +} + +async function start() { + // Resolution logic: index.js is in dist/, public/ is its sibling at root + const publicDir = path.resolve(__dirname, '..', 'public'); + const initialPort = parseInt(process.env.PORT || '3000', 10); + const port = await findAvailablePort(initialPort); + + // 2. Native HTTP Server + const server = http.createServer(async (req, res) => { + // Normalize path and prevent directory traversal attacks + let safePath = path.normalize(req.url!).replace(/^(\.\.[\/\\])+/, '').split('?')[0].split('#')[0]; + if (safePath === '/' || safePath === '\\') safePath = 'index.html'; + + // D-H6: use the canonical safePath from @docmd/api to resolve the + // requested path against the public dir, instead of relying on + // path.join + the ad-hoc `../` stripper. The ad-hoc stripper + // happened to be safe for `..` and absolute paths, but the canonical + // helper has explicit tests for both and throws with a clear + // message instead of returning a wrong-path silently. This + // change keeps the existing behaviour for in-bounds paths and + // upgrades the security check to the one the rest of the project + // uses. + let filePath: string; + try { + filePath = canonicalSafePath(publicDir, safePath); + } catch (e) { + res.writeHead(403, { 'Content-Type': 'text/plain' }); + res.end('Forbidden'); + return; + } + + // Dynamic routing for project-local user assets (bypassing the precompiled bundle) + if (safePath.startsWith('assets/')) { + const userAssetPath = path.join(process.cwd(), safePath); + try { + await fs.stat(userAssetPath); + filePath = userAssetPath; + } catch { + // fallback to bundled assets if not found locally + } + } + + try { + const stats = await fs.stat(filePath); + + // If it's a directory, serve its index.html + if (stats.isDirectory()) { + filePath = path.join(filePath, 'index.html'); + await fs.stat(filePath); + } + + const ext = path.extname(filePath).toLowerCase(); + const contentType = MIME_TYPES[ext] || 'application/octet-stream'; + const content = await fs.readFile(filePath); + + res.writeHead(200, { 'Content-Type': contentType }); + res.end(content); + + } catch (err) { + if (err.code === 'ENOENT') { + res.writeHead(404, { 'Content-Type': 'text/plain' }); + res.end('404 Not Found'); + } else { + res.writeHead(500); + res.end(`Server Error: ${err.code}`); + } + } + }); + + // 3. Start Listening + // Security: default to loopback. Set DOCMD_HOST=0.0.0.0 to expose on the + // LAN. The Live editor serves the built site + the project's `assets/` + // directory, so LAN exposure is opt-in only โ€” same model as the main + // dev server (packages/core/src/commands/dev.ts). + const BIND_HOST = process.env.DOCMD_HOST || '127.0.0.1'; + if (BIND_HOST !== '127.0.0.1' && BIND_HOST !== '::1' && BIND_HOST !== 'localhost') { + TUI.warn( + `Live editor bound to ${BIND_HOST} (LAN). Any host able to reach this port ` + + `can browse the served site.` + ); + } + server.listen(port, BIND_HOST, () => { + TUI.section('Live Editor Running', TUI.green); + TUI.item('', '', TUI.dim, TUI.green); + TUI.item('Local Access', `http://localhost:${port}`, TUI.bold, TUI.green); + if (BIND_HOST !== '127.0.0.1' && BIND_HOST !== '::1' && BIND_HOST !== 'localhost') { + TUI.item('LAN Access', `http://${BIND_HOST}:${port}`, TUI.bold, TUI.yellow); + } + TUI.item('Serving from', path.relative(process.cwd(), publicDir) || '.', TUI.dim, TUI.green); + TUI.item('', '', TUI.dim, TUI.green); + TUI.footer(TUI.green); + }); + + server.on('error', (err: any) => { + TUI.error('Live server error', err.message); + process.exit(1); + }); + + // Graceful shutdown - suppress ^C display + if (process.stdin.isTTY) { + process.stdin.setRawMode(true); + process.stdin.resume(); + process.stdin.on('data', (data) => { + if (data[0] === 0x03) { + process.emit('SIGINT' as any); + } + }); + } + + let isShuttingDown = false; + process.on('SIGINT', () => { + if (isShuttingDown) return; + isShuttingDown = true; + + if (process.stdin.isTTY) process.stdin.setRawMode(false); + + TUI.success('Shutting down Live Editor...'); + server.close(); + process.exit(0); + }); +} + +export { start, build }; \ No newline at end of file diff --git a/packages/live/src/shims.js b/packages/live/src/shims.js new file mode 100644 index 0000000..66aa6a6 --- /dev/null +++ b/packages/live/src/shims.js @@ -0,0 +1,15 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { Buffer } from 'buffer'; globalThis.Buffer = Buffer; \ No newline at end of file diff --git a/packages/live/src/shims.ts b/packages/live/src/shims.ts new file mode 100644 index 0000000..66aa6a6 --- /dev/null +++ b/packages/live/src/shims.ts @@ -0,0 +1,15 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { Buffer } from 'buffer'; globalThis.Buffer = Buffer; \ No newline at end of file diff --git a/packages/live/tsconfig.json b/packages/live/tsconfig.json new file mode 100644 index 0000000..9635ce4 --- /dev/null +++ b/packages/live/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/parser/LICENSE b/packages/parser/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/parser/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/parser/README.md b/packages/parser/README.md new file mode 100644 index 0000000..9f23964 --- /dev/null +++ b/packages/parser/README.md @@ -0,0 +1,13 @@ +# @docmd/parser + +The isomorphic Markdown engine that powers docmd - parses Markdown to HTML with support for callouts, tabs, steps, and changelogs, and runs identically in Node.js and the browser. + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/parser/package.json b/packages/parser/package.json new file mode 100644 index 0000000..7bb91bb --- /dev/null +++ b/packages/parser/package.json @@ -0,0 +1,66 @@ +{ + "name": "@docmd/parser", + "version": "0.8.12", + "description": "Pure Markdown parsing engine for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "scripts": { + "build": "tsc", + "test": "node --test 'test/**/*.test.js'" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "dependencies": { + "@docmd/tui": "workspace:*", + "@docmd/utils": "workspace:*", + "embed-lite": "^0.1.4", + "lite-hl": "^0.1.2", + "lite-matter": "^0.1.1", + "lite-template": "^0.1.2", + "lucide-static": "^0.577.0", + "markdown-it": "^14.3.0", + "markdown-it-abbr": "^1.0.4", + "markdown-it-attrs": "^4.5.0", + "markdown-it-deflist": "^2.1.0", + "markdown-it-emoji": "^2.0.2", + "markdown-it-footnote": "^3.0.3", + "markdown-it-task-lists": "^2.1.1" + }, + "keywords": [ + "docmd", + "parser", + "utils", + "tools", + "containers", + "markdown-it", + "markdown", + "markdown-processor", + "icon-renderer", + "renderer", + "validator", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/parser/src/features/basics.ts b/packages/parser/src/features/basics.ts new file mode 100644 index 0000000..c202017 --- /dev/null +++ b/packages/parser/src/features/basics.ts @@ -0,0 +1,43 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +export default { + name: 'basics', + setup(md) { + // 1. Custom Image Renderer + const defaultImageRenderer = md.renderer.rules.image || function (tokens, idx, options, env, self) { + return self.renderToken(tokens, idx, options); + }; + + md.renderer.rules.image = function (tokens, idx, options, env, self) { + const renderedImage = defaultImageRenderer(tokens, idx, options, env, self); + const nextToken = tokens[idx + 1]; + + // Look ahead for attributes syntax { .class } immediately after image + if (nextToken && nextToken.type === 'attrs_block') { + // markdown-it-attrs usually handles this, but if we need specific logic for + // aligning images that don't use standard attributes, we do it here. + } + return renderedImage; + }; + + // 2. Table Wrapper (Horizontal Scroll) + md.renderer.rules.table_open = (tokens, idx, options, env, self) => { + return '
' + self.renderToken(tokens, idx, options); + }; + md.renderer.rules.table_close = (tokens, idx, options, env, self) => { + return self.renderToken(tokens, idx, options) + '
'; + }; + } +}; \ No newline at end of file diff --git a/packages/parser/src/features/buttons.ts b/packages/parser/src/features/buttons.ts new file mode 100644 index 0000000..13615b6 --- /dev/null +++ b/packages/parser/src/features/buttons.ts @@ -0,0 +1,106 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { renderIcon } from '../utils/icon-renderer.js'; +import { resolveHref } from '../utils/normalize-href.js'; + +function buttonRule(state, startLine, endLine, silent) { + const start = state.bMarks[startLine] + state.tShift[startLine]; + const max = state.eMarks[startLine]; + const lineContent = state.src.slice(start, max).trim(); + + // Regex matches: ::: button "Text" Link [color] or :::button (spaceless) + const match = lineContent.match(/^:::\s*button\s+(?:["'](.*?)["']|(\S+))\s+(.*)$/); + + if (!match) return false; + if (silent) return true; + + // Extract Data + // Group 1 is quoted text, Group 2 is single-word text + let text = match[1] || match[2] || 'Button'; + // Replace underscores only if it was a single word (legacy support) + if (match[2]) text = text.replace(/_/g, ' '); + + const rest = match[3].trim(); + + // Parse Link and Options + // We look for the first string as the link, rest as options + const parts = rest.split(/\s+/); + const rawLink = parts[0]; + let color = ''; + let icon = ''; + + // Look for options in remaining parts + for (let i = 1; i < parts.length; i++) { + if (parts[i].startsWith('color:')) { + color = parts[i].replace('color:', ''); + } else if (parts[i].startsWith('icon:')) { + icon = parts[i].replace('icon:', ''); + } + } + + // Resolve link through the unified normaliser + const result = resolveHref(rawLink); + let href = result.href; + + // Clean URL depth adjustment for non-index pages + if (!result.isRaw && !result.isExternal && !href.startsWith('#')) { + let hashPart = ''; + let pathPart = href; + const hashIdx = href.indexOf('#'); + if (hashIdx >= 0) { + hashPart = href.substring(hashIdx); + pathPart = href.substring(0, hashIdx); + } + + const isProtocol = pathPart.match(/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i); + if (!isProtocol && !pathPart.startsWith('/') && state.env && state.env.isIndex === false) { + if (pathPart.startsWith('./')) { + pathPart = '../' + pathPart.substring(2); + } else if (pathPart !== '') { + pathPart = '../' + pathPart; + } + } + + href = pathPart + hashPart; + } + + // Generate Token + const token = state.push('html_inline', '', 0); + + let styleAttr = ''; + if (color) { + // Basic validation to prevent CSS injection if needed, or allow flexibility + styleAttr = ` style="background-color: ${color}; border-color: ${color}; color: #fff;"`; + } + + const targetAttr = result.isExternal ? ' target="_blank" rel="noopener noreferrer"' : ''; + + let iconHtml = ''; + if (icon) { + iconHtml = renderIcon(icon, { class: 'button-icon' }); + } + + token.content = `${iconHtml}${state.md.renderInline(text)}`; + + state.line = startLine + 1; + return true; +} + +export default { + name: 'buttons', + setup(md) { + md.block.ruler.before('paragraph', 'docmd_button', buttonRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] }); + } +}; \ No newline at end of file diff --git a/packages/parser/src/features/changelog.ts b/packages/parser/src/features/changelog.ts new file mode 100644 index 0000000..41ba2c2 --- /dev/null +++ b/packages/parser/src/features/changelog.ts @@ -0,0 +1,163 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +function smartDedent(str) { + const lines = str.split('\n'); + let minIndent = Infinity; + lines.forEach(line => { + if (line.trim().length === 0) return; + const match = line.match(/^ */); + if (match[0].length < minIndent) minIndent = match[0].length; + }); + if (minIndent === Infinity) return str; + return lines.map(line => line.trim().length ? line.substring(minIndent) : '').join('\n'); +} + +function parseQuotedTitle(info) { + if (!info) return ''; + const match = info.match(/"([^"]*)"/); + return match ? match[1] : info.trim(); +} + +function changelogRule(state, startLine, endLine, silent) { + const start = state.bMarks[startLine] + state.tShift[startLine]; + const max = state.eMarks[startLine]; + const lineContent = state.src.slice(start, max).trim(); + + // Support both '::: changelog' and ':::changelog' (spaceless) + if (lineContent !== '::: changelog' && lineContent !== ':::changelog') return false; + if (silent) return true; + + let nextLine = startLine; + let found = false; + let depth = 1; + let fenceMarker = null; + + while (nextLine < endLine) { + nextLine++; + if (nextLine >= endLine) break; + + const nextStart = state.bMarks[nextLine] + state.tShift[nextLine]; + const nextMax = state.eMarks[nextLine]; + const nextContent = state.src.slice(nextStart, nextMax).trim(); + + if (!fenceMarker) { + const match = nextContent.match(/^(`{3,}|~{3,})/); + if (match) fenceMarker = match[1]; + } else if (nextContent.startsWith(fenceMarker)) { + fenceMarker = null; + } + + if (!fenceMarker) { + if (nextContent.match(/^:::\s*[a-zA-Z]/) && !nextContent.match(/^:::\s*button/)) { + depth++; + } else if (nextContent.match(/^:::\s*$/)) { + depth--; + if (depth === 0) { + found = true; + break; + } + } + } + } + + if (!found) return false; + + // Extract content block + let content = ''; + for (let i = startLine + 1; i < nextLine; i++) { + const lineStart = state.bMarks[i]; + const lineEnd = state.eMarks[i]; + content += state.src.slice(lineStart, lineEnd) + '\n'; + } + + // Parse "== Date" entries + const lines = content.split('\n'); + const entries = []; + let currentEntry = null; + let currentContentLines = []; + + for (let i = 0; i < lines.length; i++) { + const rawLine = lines[i]; + const trimmedLine = rawLine.trim(); + const markerMatch = trimmedLine.match(/^==\s+(.+)$/); + + if (markerMatch) { + if (currentEntry) { + currentEntry.content = smartDedent(currentContentLines.join('\n')); + entries.push(currentEntry); + } + currentEntry = { meta: parseQuotedTitle(markerMatch[1]), content: '' }; + currentContentLines = []; + } else if (currentEntry) { + currentContentLines.push(rawLine); + } + } + if (currentEntry) { + currentEntry.content = smartDedent(currentContentLines.join('\n')); + entries.push(currentEntry); + } + + state.push('changelog_open', 'div', 1); + + // Slugify a changelog entry's meta string into a URL-safe id. Mirrors + // the Unicode-aware rules used by the parser-side heading slug + // generator (see markdown-processor.ts) so anchors for non-ASCII + // dates work the same as anchors for non-ASCII headings. + const slugifyMeta = (text: string): string => + text.toLowerCase() + .trim() + .replace(/\s+/g, '-') + .replace(/[^\p{L}\p{N}-]+/gu, '') + .replace(/--+/g, '-') + .replace(/^-+/, '') + .replace(/-+$/, '') || 'entry'; + + // Lucide `link-2` icon โ€” same SVG used by .heading-anchor and + // .step-permalink so all three permalink affordances are visually + // identical. + const PERMALINK_SVG = ''; + + entries.forEach((entry, idx) => { + // We render HTML blocks directly for the timeline structure + const slug = `changelog-${slugifyMeta(entry.meta || String(idx))}`; + const permalink = `${PERMALINK_SVG}`; + const entryOpen = state.push('html_block', '', 0); + entryOpen.content = `
+
${state.md.renderInline(entry.meta)}${permalink}
+
`; + + // Recurse render the markdown inside the entry + entryOpen.content += state.md.render(entry.content, state.env); + + const entryClose = state.push('html_block', '', 0); + entryClose.content = `
`; + }); + + state.push('changelog_close', 'div', -1); + state.line = nextLine + 1; + return true; +} + +export default { + name: 'changelog', + setup(md) { + // Register Rule + md.block.ruler.before('fence', 'changelog_timeline', changelogRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] }); + + // Register Container Renderer + md.renderer.rules.changelog_open = () => '
'; + md.renderer.rules.changelog_close = () => '
'; + } +}; \ No newline at end of file diff --git a/packages/parser/src/features/common-containers.ts b/packages/parser/src/features/common-containers.ts new file mode 100644 index 0000000..d9894e2 --- /dev/null +++ b/packages/parser/src/features/common-containers.ts @@ -0,0 +1,270 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { renderIcon } from '../utils/icon-renderer.js'; +import { parseTitleAndIcon } from '../utils/container-helper.js'; +import { normaliseContainers } from '../utils/container-normaliser.js'; + +function smartDedent(str) { + const lines = str.split('\n'); + + while (lines.length && lines[0].trim() === '') lines.shift(); + while (lines.length && lines[lines.length - 1].trim() === '') lines.pop(); + + let minIndent = Infinity; + for (const line of lines) { + if (!line.trim()) continue; + const indent = line.match(/^ */)[0].length; + minIndent = Math.min(minIndent, indent); + } + + if (!isFinite(minIndent) || minIndent === 0) return lines.join('\n'); + + return lines.map(line => + line.startsWith(' '.repeat(minIndent)) ? line.slice(minIndent) : line + ).join('\n'); +} + +/** + * Creates a depth-tracking container block rule for markdown-it. + * Handles arbitrary nesting of `:::` containers by tracking open/close depth. + * + * @example + * ```ts + * import { createDepthTrackingContainer } from '@docmd/parser'; + * + * createDepthTrackingContainer(md, 'note', + * (tokens, idx) => `
\n`, + * () => '
\n' + * ); + * ``` + * + * @param md - The markdown-it instance + * @param name - Container name (matched after `:::`) + * @param renderOpen - Renderer for the opening token + * @param renderClose - Renderer for the closing token + */ +export function createDepthTrackingContainer(md: any, name: string, renderOpen: any, renderClose: any) { + md.block.ruler.before('fence', `custom_${name}`, (state, startLine, endLine, silent) => { + const start = state.bMarks[startLine] + state.tShift[startLine]; + const max = state.eMarks[startLine]; + const lineContent = state.src.slice(start, max).trim(); + + // Match opening tag e.g., `::: callout info Title` or `:::callout info Title` (spaceless) + const regex = new RegExp(`^:::\\s*${name}(?:\\s+(.*))?$`); + const match = lineContent.match(regex); + if (!match) return false; + if (silent) return true; + + let nextLine = startLine; + let found = false; + let depth = 1; + let fenceMarker = null; + + while (nextLine < endLine) { + nextLine++; + if (nextLine >= endLine) break; + + const nextStart = state.bMarks[nextLine] + state.tShift[nextLine]; + const nextMax = state.eMarks[nextLine]; + const nextContent = state.src.slice(nextStart, nextMax).trim(); + + if (!fenceMarker) { + const match = nextContent.match(/^(`{3,}|~{3,})/); + if (match) fenceMarker = match[1]; + } else if (nextContent.startsWith(fenceMarker)) { + fenceMarker = null; + } + + if (!fenceMarker) { + if (nextContent.match(/^:::\s*[a-zA-Z]/) && !nextContent.match(/^:::\s*(button|embed|tag)\b/)) { + depth++; + } else if (nextContent.match(/^:::\s*$/)) { + depth--; + if (depth === 0) { + found = true; + break; + } + } + } + } + + if (!found) return false; + + const info = match[1] || ''; + + // Extract raw content lines and dedent to reset indentation, + // then re-render recursively so nested containers parse correctly. + let rawContent = ''; + for (let i = startLine + 1; i < nextLine; i++) { + const lineStart = state.bMarks[i]; + const lineEnd = state.eMarks[i]; + rawContent += state.src.slice(lineStart, lineEnd) + '\n'; + } + + // Phase 2 (F1): re-run the container normaliser on the extracted body + // BEFORE smartDedent. The top-level normaliser balances the OUTER + // container's open/close depth, but inside a recursive render of the + // extracted body the depth-tracker is ambiguous again (e.g. nested + // grids with one close per inner card). Normalising here inserts the + // missing closes inside the body so the recursive grid/card rule sees + // balanced input. + const normalisedBody = normaliseContainers(rawContent, { + sourcePath: `<${name}-body@L${startLine + 1}>` + }); + const innerContent = smartDedent(normalisedBody.source); + + const openToken = state.push(`custom_${name}_open`, 'div', 1); + openToken.info = info; + + if (innerContent) { + // Flag the environment so the inner heading plugin skips generating permalinks & IDs + const oldIsInsideContainer = state.env.isInsideContainer; + state.env.isInsideContainer = true; + + const renderedContent = state.md.render(innerContent, state.env); + + state.env.isInsideContainer = oldIsInsideContainer; + + const htmlToken = state.push('html_block', '', 0); + htmlToken.content = renderedContent; + } + + state.push(`custom_${name}_close`, 'div', -1); + + state.line = nextLine + 1; + return true; + }, { alt: ['paragraph', 'reference', 'blockquote', 'list'] }); + + // Register Renderers + md.renderer.rules[`custom_${name}_open`] = renderOpen; + md.renderer.rules[`custom_${name}_close`] = renderClose; +} + +export default { + name: 'common-containers', + setup(md: any) { + + // 1. Callout + createDepthTrackingContainer(md, 'callout', (tokens, idx) => { + const info = tokens[idx].info.trim(); + const parts = info.split(' '); + const type = parts[0] || 'info'; + + // Support ::: callout type "Title" or ::: callout type Title + let title = ''; + let icon = ''; + const remaining = parts.slice(1).join(' ').trim(); + if (remaining) { + const parsed = parseTitleAndIcon(remaining); + title = parsed.title; + icon = parsed.icon; + } + + const renderedTitle = title ? md.renderInline(title) : ''; + const iconHtml = icon ? renderIcon(icon, { class: 'callout-icon-heading' }) : ''; + const safeType = md.utils.escapeHtml(type); + + return `
${renderedTitle || iconHtml ? `
${iconHtml}${renderedTitle}
` : ''}
\n`; + }, () => '
\n'); + + // 2. Card + createDepthTrackingContainer(md, 'card', (tokens, idx) => { + const { title, icon } = parseTitleAndIcon(tokens[idx].info); + const renderedTitle = title ? md.renderInline(title) : ''; + const iconHtml = icon ? renderIcon(icon, { class: 'card-icon-heading' }) : ''; + // No trailing newline after
: any inline + // markdown immediately after the ::: card opener (e.g. a callout + // block or a heading) would otherwise get a literal newline inserted + // before its first tag, which broke card layouts where the inner + // block was meant to sit flush against the card edge. + return `
${renderedTitle || iconHtml ? `
${iconHtml}${renderedTitle}
` : ''}
`; + }, () => '
'); + + // 3. Collapsible + createDepthTrackingContainer(md, 'collapsible', (tokens, idx) => { + const info = tokens[idx].info.trim(); + const isOpen = info.startsWith('open ') || info === 'open'; + const rawInfo = isOpen ? info.replace('open', '').trim() : info; + const { title, icon } = parseTitleAndIcon(rawInfo); + const displayTitle = title || 'Click to expand'; + const renderedTitle = md.renderInline(displayTitle); + const iconHtml = icon ? renderIcon(icon, { class: 'collapsible-icon-heading' }) : ''; + const safeOpen = isOpen ? ' open' : ''; + + return `
+ + ${iconHtml}${renderedTitle} + + +
\n`; + }, () => '
\n'); + + // 4. Grids + createDepthTrackingContainer(md, 'grids', () => { + return `
\n`; + }, () => '
\n'); + + // 5. Grid Item + createDepthTrackingContainer(md, 'grid', () => { + return `
\n`; + }, () => '
\n'); + + // โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + // Container Aliases (VitePress/Docusaurus compatibility) + // These allow users migrating from other documentation engines to use + // familiar syntax without modification. + // โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + + // Callout type aliases - map directly to callout variants + const calloutAliases = [ + // VitePress aliases + { name: 'tip', type: 'tip' }, + { name: 'warning', type: 'warning' }, + { name: 'danger', type: 'danger' }, + { name: 'info', type: 'info' }, + // Docusaurus aliases + { name: 'note', type: 'info' }, + { name: 'caution', type: 'warning' }, + ]; + + for (const alias of calloutAliases) { + createDepthTrackingContainer(md, alias.name, (tokens, idx) => { + const info = tokens[idx].info.trim(); + const { title, icon } = parseTitleAndIcon(info); + const renderedTitle = title ? md.renderInline(title) : ''; + const iconHtml = icon ? renderIcon(icon, { class: 'callout-icon-heading' }) : ''; + const safeType = md.utils.escapeHtml(alias.type); + return `
${renderedTitle || iconHtml ? `
${iconHtml}${renderedTitle}
` : ''}
\n`; + }, () => '
\n'); + } + + // VitePress details alias -> collapsible + createDepthTrackingContainer(md, 'details', (tokens, idx) => { + const info = tokens[idx].info.trim(); + const { title, icon } = parseTitleAndIcon(info); + const displayTitle = title || 'Details'; + const renderedTitle = md.renderInline(displayTitle); + const iconHtml = icon ? renderIcon(icon, { class: 'collapsible-icon-heading' }) : ''; + + return `
+ + ${iconHtml}${renderedTitle} + + +
\n`; + }, () => '
\n'); + + } +}; \ No newline at end of file diff --git a/packages/parser/src/features/embed.ts b/packages/parser/src/features/embed.ts new file mode 100644 index 0000000..d6e0e13 --- /dev/null +++ b/packages/parser/src/features/embed.ts @@ -0,0 +1,57 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { embed } from 'embed-lite'; + +function embedRule(state: any, startLine: number, endLine: number, silent: boolean) { + const start = state.bMarks[startLine] + state.tShift[startLine]; + const max = state.eMarks[startLine]; + const lineContent = state.src.slice(start, max).trim(); + + // Support both '::: embed' and ':::embed' (spaceless) + const match = lineContent.match(/^:::\s*embed\s+(?:\[|")?((https?:\/\/)[^\]"\s]+)(?:\]|")?$/i); + if (!match) return false; + if (silent) return true; + + const urlStr = match[1]; + let html = ''; + + try { + const embedResult = embed(urlStr, { className: 'docmd-embed' }); + if (embedResult && embedResult.html) { + // We received a valid parsed native iframe/blockquote component + html = embedResult.html; + } else { + const url = new URL(urlStr); + const hostname = url.hostname.replace('www.', ''); + html = `
Open ${hostname} link
`; + } + } catch { + // Hard fallback if string is entirely invalid URL + html = `
Open link
`; + } + + const token = state.push('html_inline', '', 0); + token.content = html; + + state.line = startLine + 1; + return true; +} + +export default { + name: 'embed', + setup(md: any) { + md.block.ruler.before('paragraph', 'docmd_embed', embedRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] }); + } +}; \ No newline at end of file diff --git a/packages/parser/src/features/hero.ts b/packages/parser/src/features/hero.ts new file mode 100644 index 0000000..d9732ab --- /dev/null +++ b/packages/parser/src/features/hero.ts @@ -0,0 +1,218 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +function smartDedent(str) { + const lines = str.split('\n'); + while (lines.length && lines[0].trim() === '') lines.shift(); + while (lines.length && lines[lines.length - 1].trim() === '') lines.pop(); + + let minIndent = Infinity; + for (const line of lines) { + if (!line.trim()) continue; + const indent = line.match(/^ */)[0].length; + minIndent = Math.min(minIndent, indent); + } + + if (!isFinite(minIndent) || minIndent === 0) return lines.join('\n'); + + return lines.map(line => + line.startsWith(' '.repeat(minIndent)) ? line.slice(minIndent) : line + ).join('\n'); +} + +function heroRule(state, startLine, endLine, silent) { + const start = state.bMarks[startLine] + state.tShift[startLine]; + const max = state.eMarks[startLine]; + const lineContent = state.src.slice(start, max).trim(); + + // Support both '::: hero' and ':::hero' (spaceless) + const regex = /^:::\s*hero(?:\s+(.*))?$/; + const match = lineContent.match(regex); + if (!match) return false; + if (silent) return true; + + const flagsStr = match[1] || ''; + const flags = { + split: flagsStr.includes('layout:split'), + slider: flagsStr.includes('layout:slider'), + glow: flagsStr.includes('glow:true') + }; + + let nextLine = startLine; + let found = false; + let depth = 1; + let fenceMarker = null; + + while (nextLine < endLine) { + nextLine++; + if (nextLine >= endLine) break; + + const nextStart = state.bMarks[nextLine] + state.tShift[nextLine]; + const nextMax = state.eMarks[nextLine]; + const nextContent = state.src.slice(nextStart, nextMax).trim(); + + if (!fenceMarker) { + const match = nextContent.match(/^(`{3,}|~{3,})/); + if (match) fenceMarker = match[1]; + } else if (nextContent.startsWith(fenceMarker)) { + fenceMarker = null; + } + + if (!fenceMarker) { + if (nextContent.match(/^:::\s*[a-zA-Z]/) && !nextContent.match(/^:::\s*(button|embed|tag)\b/)) { + depth++; + } else if (nextContent.match(/^:::\s*$/)) { + depth--; + if (depth === 0) { + found = true; + break; + } + } + } + } + if (!found) return false; + + // Extract content + let content = ''; + for (let i = startLine + 1; i < nextLine; i++) { + const lineStart = state.bMarks[i]; + const lineEnd = state.eMarks[i]; + content += state.src.slice(lineStart, lineEnd) + '\n'; + } + + const lines = content.split('\n'); + + // Handle Sections based on separators (== side or == slide) + if (flags.slider) { + const slides = []; + let currentSlide = null; + let currentLines = []; + + for (let i = 0; i < lines.length; i++) { + const rawLine = lines[i]; + const trimmed = rawLine.trim(); + if (trimmed.startsWith('== slide')) { + if (currentSlide !== null) { + slides.push(smartDedent(currentLines.join('\n'))); + } + currentSlide = true; + currentLines = []; + } else { + currentLines.push(rawLine); + } + } + if (currentSlide !== null) slides.push(smartDedent(currentLines.join('\n'))); + + const slideCount = slides.length; + // Build Tokens + const openToken = state.push('hero_open', 'div', 1); + openToken.attrs = [['class', `docmd-hero hero-slider ${flags.glow ? 'hero-glow' : ''}`.trim()]]; + + const trackToken = state.push('hero_slider_track_open', 'div', 1); + trackToken.attrs = [['class', 'hero-slider-track']]; + + slides.forEach(slideContent => { + state.push('hero_slide_open', 'div', 1); + const rendered = state.md.render(slideContent, { ...state.env, isInsideContainer: true }); + const html = state.push('html_block', '', 0); + html.content = rendered; + state.push('hero_slide_close', 'div', -1); + }); + + state.push('hero_slider_track_close', 'div', -1); + + // Inject controls (prev/next + dots) + if (slideCount > 1) { + const prevSvg = ``; + const nextSvg = ``; + const dots = slides.map((_, i) => ``).join(''); + const controls = state.push('html_block', '', 0); + controls.content = `
+ +
${dots}
+ +
\n`; + } + + state.push('hero_close', 'div', -1); + + } else if (flags.split) { + const mainContentLines = []; + const sideContentLines = []; + let foundSeparator = false; + + for (let i = 0; i < lines.length; i++) { + const rawLine = lines[i]; + if (rawLine.trim().startsWith('== side')) { + foundSeparator = true; + continue; + } + if (foundSeparator) sideContentLines.push(rawLine); + else mainContentLines.push(rawLine); + } + + const openToken = state.push('hero_open', 'div', 1); + openToken.attrs = [['class', `docmd-hero hero-split ${flags.glow ? 'hero-glow' : ''}`.trim()]]; + + // Main Section + state.push('hero_content_open', 'div', 1); + const renderedMain = state.md.render(smartDedent(mainContentLines.join('\n')), { ...state.env, isInsideContainer: true }); + const htmlMain = state.push('html_block', '', 0); + htmlMain.content = renderedMain; + state.push('hero_content_close', 'div', -1); + + // Side Section + state.push('hero_side_open', 'div', 1); + const renderedSide = state.md.render(smartDedent(sideContentLines.join('\n')), { ...state.env, isInsideContainer: true }); + const htmlSide = state.push('html_block', '', 0); + htmlSide.content = renderedSide; + state.push('hero_side_close', 'div', -1); + + state.push('hero_close', 'div', -1); + + } else { + // Normal Banner Layout + const openToken = state.push('hero_open', 'div', 1); + openToken.attrs = [['class', `docmd-hero hero-banner ${flags.glow ? 'hero-glow' : ''}`.trim()]]; + + state.push('hero_content_open', 'div', 1); + const rendered = state.md.render(smartDedent(content), { ...state.env, isInsideContainer: true }); + const htmlAt = state.push('html_block', '', 0); + htmlAt.content = rendered; + state.push('hero_content_close', 'div', -1); + + state.push('hero_close', 'div', -1); + } + + state.line = nextLine + 1; + return true; +} + +export default { + name: 'hero', + setup(md) { + md.block.ruler.before('fence', 'docmd_hero', heroRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] }); + + md.renderer.rules.hero_open = (tokens, idx) => `
`; + md.renderer.rules.hero_close = () => '
\n'; + md.renderer.rules.hero_content_open = () => '
\n'; + md.renderer.rules.hero_content_close = () => '
\n'; + md.renderer.rules.hero_side_open = () => '
\n'; + md.renderer.rules.hero_side_close = () => '
\n'; + md.renderer.rules.hero_slider_track_open = () => '
\n'; + md.renderer.rules.hero_slider_track_close = () => '
\n'; + md.renderer.rules.hero_slide_open = () => '
\n'; + md.renderer.rules.hero_slide_close = () => '
\n'; + } +}; \ No newline at end of file diff --git a/packages/parser/src/features/index.ts b/packages/parser/src/features/index.ts new file mode 100644 index 0000000..4445183 --- /dev/null +++ b/packages/parser/src/features/index.ts @@ -0,0 +1,35 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import common from './common-containers.js'; +export { createDepthTrackingContainer } from './common-containers.js'; +import tabs from './tabs.js'; +import steps from './steps.js'; +import changelog from './changelog.js'; +import buttons from './buttons.js'; +import basics from './basics.js'; +import embed from './embed.js'; +import hero from './hero.js'; + +import tags from './tags.js'; + +const FEATURES = [basics, buttons, tags, embed, common, tabs, steps, changelog, hero]; + +function registerFeatures(md) { + FEATURES.forEach(feature => { + if (feature.setup) feature.setup(md); + }); +} + +export { registerFeatures }; \ No newline at end of file diff --git a/packages/parser/src/features/steps.ts b/packages/parser/src/features/steps.ts new file mode 100644 index 0000000..cbdbaa9 --- /dev/null +++ b/packages/parser/src/features/steps.ts @@ -0,0 +1,128 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +function stepsRule(state, startLine, endLine, silent) { + const start = state.bMarks[startLine] + state.tShift[startLine]; + const max = state.eMarks[startLine]; + const lineContent = state.src.slice(start, max).trim(); + // Support both '::: steps' and ':::steps' (spaceless) + if (lineContent !== '::: steps' && lineContent !== ':::steps') return false; + if (silent) return true; + + let nextLine = startLine; + let found = false; + let depth = 1; + let fenceMarker = null; + + while (nextLine < endLine) { + nextLine++; + if (nextLine >= endLine) break; + + const nextStart = state.bMarks[nextLine] + state.tShift[nextLine]; + const nextMax = state.eMarks[nextLine]; + const nextContent = state.src.slice(nextStart, nextMax).trim(); + + if (!fenceMarker) { + const match = nextContent.match(/^(`{3,}|~{3,})/); + if (match) fenceMarker = match[1]; + } else if (nextContent.startsWith(fenceMarker)) { + fenceMarker = null; + } + + if (!fenceMarker) { + if (nextContent.match(/^:::\s*[a-zA-Z]/) && !nextContent.match(/^:::\s*button/)) { + depth++; + } else if (nextContent.match(/^:::\s*$/)) { + depth--; + if (depth === 0) { + found = true; + break; + } + } + } + } + + if (!found) return false; + + const openToken = state.push('steps_open', 'div', 1); + openToken.info = ''; + + const oldParentType = state.parentType; + const oldLineMax = state.lineMax; + state.parentType = 'container'; + state.lineMax = nextLine; + + state.md.block.tokenize(state, startLine + 1, nextLine); + + state.push('steps_close', 'div', -1); + + state.parentType = oldParentType; + state.lineMax = oldLineMax; + state.line = nextLine + 1; + return true; +} + +export default { + name: 'steps', + setup(md) { + md.block.ruler.before('fence', 'steps_container', stepsRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] }); + + // Module-level counter so each
  • gets a globally unique `id` + // (step-1, step-2, โ€ฆ) across the whole document. This matters for + // permalinks: clicking `#step-1` on a page with two step containers + // would otherwise scroll to the first match in both. + let stepIndex = 0; + + // Custom List Renderer for Steps + md.renderer.rules.steps_open = () => '
    '; + md.renderer.rules.steps_close = () => '
    '; + + // Hook into list rendering to add classes when inside steps + md.renderer.rules.ordered_list_open = function (tokens, idx, options, env, self) { + let isInSteps = false; + // Check tokens backward to see if we are inside a steps container + for (let i = idx - 1; i >= 0; i--) { + if (tokens[i].type === 'steps_open') { isInSteps = true; break; } + if (tokens[i].type === 'steps_close') break; + } + if (isInSteps) { + const start = tokens[idx].attrGet('start'); + return start ? `
      ` : '
        '; + } + return self.renderToken(tokens, idx, options); + }; + + // Lucide `link-2` icon โ€” same as the one used by .heading-anchor so the + // visual language stays consistent across the site. + const STEP_PERMALINK_SVG = ''; + + md.renderer.rules.list_item_open = function (tokens, idx, _options, _env, _self) { + let isInSteps = false; + for (let i = idx - 1; i >= 0; i--) { + if (tokens[i].type === 'steps_open') { isInSteps = true; break; } + if (tokens[i].type === 'steps_close') break; + } + if (isInSteps) { + stepIndex++; + // Render a permalink anchor that's hidden by default and revealed + // on hover. Uses `scroll-margin-top` via .step-item so jumping + // to the anchor lands just below the sticky header. + const id = `step-${stepIndex}`; + const permalink = `${STEP_PERMALINK_SVG}`; + return `
      1. ${permalink}`; + } + return '
      2. '; + }; + } +}; \ No newline at end of file diff --git a/packages/parser/src/features/tabs.ts b/packages/parser/src/features/tabs.ts new file mode 100644 index 0000000..422a2a5 --- /dev/null +++ b/packages/parser/src/features/tabs.ts @@ -0,0 +1,192 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { renderIcon } from '../utils/icon-renderer.js'; +import { parseTitleAndIcon } from '../utils/container-helper.js'; + +function smartDedent(str) { + const lines = str.split('\n'); + + // Ignore first and last blank lines (common in container blocks) + while (lines.length && lines[0].trim() === '') lines.shift(); + while (lines.length && lines[lines.length - 1].trim() === '') lines.pop(); + + let minIndent = Infinity; + + // Find minimum indentation of non-empty lines + for (const line of lines) { + if (!line.trim()) continue; + const indent = line.match(/^ */)[0].length; + minIndent = Math.min(minIndent, indent); + } + + // If no indentation to strip, return joined lines + if (!isFinite(minIndent) || minIndent === 0) return lines.join('\n'); + + // Strip exactly minIndent from each line + return lines.map(line => + line.startsWith(' '.repeat(minIndent)) + ? line.slice(minIndent) + : line + ).join('\n'); +} + +// The Parsing Rule +function tabsRule(state: any, startLine: number, endLine: number, silent: boolean) { + const start = state.bMarks[startLine] + state.tShift[startLine]; + const max = state.eMarks[startLine]; + const lineContent = state.src.slice(start, max).trim(); + + // Support both '::: tabs' and ':::tabs' (spaceless) + if (lineContent !== '::: tabs' && lineContent !== ':::tabs') return false; + if (silent) return true; + + let nextLine = startLine; + let found = false; + let depth = 1; + let fenceMarker = null; + + while (nextLine < endLine) { + nextLine++; + if (nextLine >= endLine) break; + + const nextStart = state.bMarks[nextLine] + state.tShift[nextLine]; + const nextMax = state.eMarks[nextLine]; + const nextContent = state.src.slice(nextStart, nextMax).trim(); + + if (!fenceMarker) { + const match = nextContent.match(/^(`{3,}|~{3,})/); + if (match) fenceMarker = match[1]; + } else if (nextContent.startsWith(fenceMarker)) { + fenceMarker = null; + } + + if (!fenceMarker) { + // Increment depth for block-level container openers only. + // Inline self-closing containers (tag, button, embed) must NOT affect depth + // because they have no matching closing `:::` - treating them as openers + // would make the tabs parser wait for an extra closing `:::` that never comes. + const INLINE_CONTAINERS = /^:::\s*(tag|button|embed)\b/; + if (nextContent.match(/^:::\s*[a-zA-Z]/) && !INLINE_CONTAINERS.test(nextContent)) { + depth++; + } else if (nextContent.match(/^:::\s*$/)) { + depth--; + if (depth === 0) { + found = true; + break; + } + } + } + } + if (!found) return false; + + // Extract content + let content = ''; + for (let i = startLine + 1; i < nextLine; i++) { + const lineStart = state.bMarks[i]; + const lineEnd = state.eMarks[i]; + content += state.src.slice(lineStart, lineEnd) + '\n'; + } + + // Parse "== tab" lines + const lines = content.split('\n'); + const tabs = []; + let currentTab = null; + let currentContentLines = []; + + for (let i = 0; i < lines.length; i++) { + const rawLine = lines[i]; + const trimmedLine = rawLine.trim(); + const tabMatch = trimmedLine.match(/^==\s*tab\s+(.*)/); + + if (tabMatch) { + if (currentTab) { + currentTab.content = smartDedent(currentContentLines.join('\n')); + tabs.push(currentTab); + } + const { title, icon } = parseTitleAndIcon(tabMatch[1]); + currentTab = { title, icon, content: '' }; + currentContentLines = []; + } else if (currentTab) { + currentContentLines.push(rawLine); + } + } + if (currentTab) { + currentTab.content = smartDedent(currentContentLines.join('\n')); + tabs.push(currentTab); + } + + // Generate Tokens + const openToken = state.push('tabs_open', 'div', 1); + openToken.attrs = [['class', 'docmd-tabs']]; + + state.push('tabs_nav_open', 'div', 1); + tabs.forEach((tab, index) => { + const navItemToken = state.push('tabs_nav_item', 'div', 0); + navItemToken.attrs = [['class', `docmd-tabs-nav-item ${index === 0 ? 'active' : ''}`]]; + if (tab.icon) { + navItemToken.attrs.push(['data-icon', state.md.utils.escapeHtml(tab.icon)]); + } + navItemToken.content = tab.title; + }); + state.push('tabs_nav_close', 'div', -1); + + state.push('tabs_content_open', 'div', 1); + tabs.forEach((tab, index) => { + const paneToken = state.push('tab_pane_open', 'div', 1); + paneToken.attrs = [['class', `docmd-tab-pane ${index === 0 ? 'active' : ''}`]]; + + if (tab.content) { + // Recurse parsing inside tabs and flag as inside container + const oldIsInsideContainer = state.env.isInsideContainer; + state.env.isInsideContainer = true; + + const renderedContent = state.md.render(tab.content, state.env); + + state.env.isInsideContainer = oldIsInsideContainer; + + const htmlToken = state.push('html_block', '', 0); + htmlToken.content = renderedContent; + } + state.push('tab_pane_close', 'div', -1); + }); + state.push('tabs_content_close', 'div', -1); + state.push('tabs_close', 'div', -1); + + state.line = nextLine + 1; + return true; +} + +export default { + name: 'tabs', + setup(md: any) { + md.block.ruler.before('fence', 'enhanced_tabs', tabsRule, { alt: ['paragraph', 'reference', 'blockquote', 'list'] }); + + // Register Renderers + md.renderer.rules.tabs_nav_open = () => '
        '; + md.renderer.rules.tabs_nav_close = () => '
        '; + md.renderer.rules.tabs_nav_item = (tokens, idx) => { + const iconAttr = tokens[idx].attrs.find(a => a[0] === 'data-icon'); + const icon = iconAttr ? iconAttr[1] : null; + const iconHtml = icon ? renderIcon(icon, { class: 'tab-icon' }) : ''; + const className = tokens[idx].attrs.find(a => a[0] === 'class')[1]; + return `
        ${iconHtml}${md.renderInline(tokens[idx].content)}
        `; + }; + md.renderer.rules.tabs_content_open = () => '
        '; + md.renderer.rules.tabs_content_close = () => '
        '; + md.renderer.rules.tab_pane_open = (tokens, idx) => `
        `; + md.renderer.rules.tab_pane_close = () => '
        '; + md.renderer.rules.tabs_close = () => '
    • '; + } +}; \ No newline at end of file diff --git a/packages/parser/src/features/tags.ts b/packages/parser/src/features/tags.ts new file mode 100644 index 0000000..839957c --- /dev/null +++ b/packages/parser/src/features/tags.ts @@ -0,0 +1,109 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { renderIcon } from '../utils/icon-renderer.js'; +import { resolveHref } from '../utils/normalize-href.js'; + +/** + * Strips a matched pair of surrounding quotes from a value if present. + * The tag options parser captures both quoted ("..." or '...') and + * unquoted forms in a single regex; this normalises them to a plain + * string before passing to downstream helpers like resolveHref. + */ +function unquote(value: string): string { + if (value.length >= 2) { + const first = value.charAt(0); + const last = value.charAt(value.length - 1); + if ((first === '"' && last === '"') || (first === "'" && last === "'")) { + return value.slice(1, -1); + } + } + return value; +} + +function tagInlineRule(state, silent) { + const start = state.pos; + const max = state.posMax; + + if (state.src.charCodeAt(start) !== 0x3A /* : */) return false; + if (state.src.slice(start, start + 3) !== ':::') return false; + + // We are at `:::`. Let's see if it's `::: tag` or `:::tag` (spaceless). + // + // Option values accept three forms so URLs and other values that + // contain reserved characters can be wrapped in quotes for clarity + // (matching the rule used by other docmd containers): + // - icon:check-circle (unquoted) + // - color:#ef4444 (unquoted) + // - url:"../../release.md" (double-quoted, recommended for URLs) + // - url:'../../release.md' (single-quoted) + // + // `url:` is the canonical name; `link:` is kept as an alias for + // backward compatibility with existing pages. + const match = state.src.slice(start, max).match( + /^:::\s*tag\s+(?:["']([^"']+)["']|(\S+))((?:\s+(?:icon|color|link|url):(?:"[^"]*"|'[^']*'|\S+))*)/ + ); + if (!match) return false; + + if (silent) return true; + + const text = match[1] || match[2] || 'Tag'; + const optionsStr = match[3] || ''; + + let icon = ''; + let color = ''; + let link = ''; + + const parts = optionsStr.trim().split(/\s+/); + for (const part of parts) { + if (!part) continue; + if (part.startsWith('icon:')) icon = unquote(part.substring(5)); + else if (part.startsWith('color:')) color = unquote(part.substring(6)); + else if (part.startsWith('link:')) link = unquote(part.substring(5)); + else if (part.startsWith('url:')) link = unquote(part.substring(4)); + } + + state.pos += match[0].length; + + const token = state.push('html_inline', '', 0); + + let styleAttr = ''; + if (color) { + styleAttr = ` style="--tag-color: ${color}; background-color: color-mix(in srgb, ${color} 15%, transparent); color: ${color}; border-color: color-mix(in srgb, ${color} 30%, transparent);"`; + } + + let iconHtml = ''; + if (icon) { + iconHtml = renderIcon(icon, { class: 'tag-icon', style: 'width:12px;height:12px;margin-right:4px;' }); + } + + let tagHtml = `${iconHtml}${state.md.renderInline(text)}`; + + if (link) { + const result = resolveHref(link); + const targetAttr = result.isExternal ? ' target="_blank" rel="noopener noreferrer"' : ''; + tagHtml = `${tagHtml}`; + } + + token.content = tagHtml; + + return true; +} + +export default { + name: 'tags', + setup(md) { + md.inline.ruler.before('text', 'docmd_tag_inline', tagInlineRule); + } +}; \ No newline at end of file diff --git a/packages/parser/src/html-renderer.ts b/packages/parser/src/html-renderer.ts new file mode 100644 index 0000000..a635657 --- /dev/null +++ b/packages/parser/src/html-renderer.ts @@ -0,0 +1,84 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import tpl from 'lite-template'; +import { renderIcon } from './utils/icon-renderer.js'; + +/** + * Renders an EJS template string with provided data. + * + * Injects docmd-specific context helpers (renderIcon, fixLink). + * Utilizes lite-template natively, while passing a preprocessor hook + * to automatically strip YAML frontmatter out of any recursive file includes. + */ +async function renderTemplateAsync(templateString, data, options: any = {}) { + // Inject core helpers into every template + const fullData: any = { + ...data, + renderIcon, + // Helper to fix links relative to root + fixLink: (url) => fixHtmlLinks(url, data.relativePathToRoot, data.isOfflineMode, data.config?.base) + }; + + try { + const finalOptions = { + ...options, + async: true, + preprocessor: (content) => { + // Strip frontmatter from included files - frontmatter is a docmd concern, + // not an EJS/template concern. The top-level page's frontmatter is handled + // by processContent/lite-matter, but recursive includes should not re-render it. + const fmRegex = /^(?:---[\r\n]+)([\s\S]*?)(?:[\r\n]+---(?:[\r\n]+|$))/; + const fmMatch = content.match(fmRegex); + if (fmMatch) { + return content.slice(fmMatch[0].length); + } + return content; + } + }; + + return await tpl.render(templateString, fullData, finalOptions); + } catch (e) { + throw new Error(`Template Render Error: ${e.message}`); + } +} + +function fixHtmlLinks(url, root = './', isOffline = false, base = '/') { + if (!url || url.startsWith('http') || url.startsWith('#') || url.startsWith('mailto:')) return url; + + let final = url; + + // Strip base if present + if (base !== '/' && url.startsWith(base)) { + final = '/' + url.substring(base.length); + } + + // Make relative + if (final.startsWith('/')) { + final = root + final.substring(1); + } + + // Offline adjustments + if (isOffline) { + if (!final.includes('.') && !final.endsWith('/')) final += '/index.html'; + else if (final.endsWith('/')) final += 'index.html'; + } else { + // Clean URLs + if (final.endsWith('/index.html')) final = final.substring(0, final.length - 10); + } + + return final; +} + +export { renderTemplateAsync, fixHtmlLinks }; \ No newline at end of file diff --git a/packages/parser/src/index.ts b/packages/parser/src/index.ts new file mode 100644 index 0000000..2f0a8ce --- /dev/null +++ b/packages/parser/src/index.ts @@ -0,0 +1,62 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import { createMarkdownProcessor, processContent, processContentAsync, flushNormaliserWarnings, setNormaliserVerbose } from './markdown-processor.js'; +import { renderTemplateAsync } from './html-renderer.js'; +import { renderIcon } from './utils/icon-renderer.js'; +import { validateConfig } from './utils/validator.js'; + +export { + // Logic + createMarkdownProcessor, + processContent, + processContentAsync, + renderTemplateAsync, + validateConfig, + + // Utils + renderIcon, + flushNormaliserWarnings, + setNormaliserVerbose +}; + +export { createDepthTrackingContainer } from './features/index.js'; +export { + normaliseContainers, + classifyLine, + indentOf, + SELF_CLOSING_CONTAINER_NAMES +} from './utils/container-normaliser.js'; +export type { + NormaliserWarning, + NormaliserWarningSeverity, + NormaliserResult, + NormaliserOptions +} from './utils/container-normaliser.js'; +export { findPageNeighbors, findBreadcrumbs } from './utils/navigation-helper.js'; +export { normalizeInternalHref, normalizeNavPaths, normalizeMenubarPaths, resolveHref } from './utils/normalize-href.js'; + +// Centralised URL Utilities - the single source of truth for all URL transformations. +// Plugins, templates, and engine components MUST use these instead of rolling their own. +export { + sanitizeUrl, + outputPathToSlug, + outputPathToPathname, + outputPathToCanonical, + buildContextualUrl, + createUrlContext, + computePageUrls, + buildAbsoluteUrl, +} from './utils/url-utils.js'; +export type { UrlContext, PageUrls } from './utils/url-utils.js'; \ No newline at end of file diff --git a/packages/parser/src/markdown-processor.ts b/packages/parser/src/markdown-processor.ts new file mode 100644 index 0000000..56b71cf --- /dev/null +++ b/packages/parser/src/markdown-processor.ts @@ -0,0 +1,567 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import MarkdownIt from 'markdown-it'; +import matter from 'lite-matter'; +import { highlight } from 'lite-hl'; +import { resolveHref } from './utils/normalize-href.js'; +import { attrEsc } from '@docmd/utils'; +import { + normaliseContainers, + type NormaliserWarning +} from './utils/container-normaliser.js'; +import { fixHtmlLinks } from './html-renderer.js'; + +// URL schemes that can execute code or exfiltrate data when clicked. +// Phase 1.B (T-S4 fix, defense in depth): markdown-it 14 already rejects these +// at the parser layer, but we re-check inside the link_open override so any +// future refactor of the parser pipeline cannot accidentally re-introduce them. +const DANGEROUS_URL_SCHEMES = new Set([ + 'javascript:', + 'data:text/html', + 'vbscript:', + 'file:' +]); + +function isDangerousHref(href: string): boolean { + const lower = href.trim().toLowerCase(); + for (const prefix of DANGEROUS_URL_SCHEMES) { + if (lower.startsWith(prefix)) return true; + } + return false; +} + +/** + * Phase 2 (F1โ€“F5): accumulated warnings, summarised once at the end of + * the build via `flushNormaliserWarnings()`. Per-warning logging to + * stderr is opt-in via `setNormaliserVerbose(true)` so the dev-server + * console stays clean (one summary line per build instead of one line + * per warning) while CI / verbose mode still gets the full detail. + */ +const normaliserWarnings: NormaliserWarning[] = []; +let normaliserVerbose = false; + +function emitNormaliserWarning(w: NormaliserWarning): void { + normaliserWarnings.push(w); + if (normaliserVerbose) { + console.warn(`[normaliser] ${w.severity.toUpperCase()} ${w.path}:${w.line} โ€” ${w.message}`); + } +} + +export function setNormaliserVerbose(verbose: boolean): void { + normaliserVerbose = verbose; +} + +export function flushNormaliserWarnings(): void { + if (normaliserWarnings.length === 0) return; + const errors = normaliserWarnings.filter(w => w.severity === 'error').length; + const warnings = normaliserWarnings.length - errors; + const fileCount = new Set(normaliserWarnings.map(w => w.path)).size; + const severity = errors > 0 ? 'ERROR' : 'WARN'; + const tag = errors > 0 ? '\x1b[31m' : '\x1b[33m'; + const reset = '\x1b[0m'; + console.warn( + `${tag}[normaliser] ${severity}${reset} ` + + `${normaliserWarnings.length} issue${normaliserWarnings.length === 1 ? '' : 's'} ` + + `(${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}) ` + + `across ${fileCount} file${fileCount === 1 ? '' : 's'}. ` + + `Run with --verbose to list each one.` + ); + normaliserWarnings.length = 0; +} + +/** + * Phase 2 (F1โ€“F5): run the container normaliser on the markdown body before + * it is handed to markdown-it (and before any user plugin's `onBeforeParse` + * hook so they always see balanced input). + * + * The function is allocation-only on the input โ€” no module-level state โ€” so + * output is deterministic across worker threads. + */ +function applyContainerNormaliser(markdownContent: string, env: { filePath?: string }): string { + const norm = normaliseContainers(markdownContent, { + sourcePath: env && env.filePath ? env.filePath : '', + onWarning: emitNormaliserWarning + }); + return norm.source; +} + +// Standard Plugins +import attrs from 'markdown-it-attrs'; +import footnote from 'markdown-it-footnote'; +import taskLists from 'markdown-it-task-lists'; +import abbr from 'markdown-it-abbr'; +import deflist from 'markdown-it-deflist'; +import emoji from 'markdown-it-emoji'; + +// The Feature Registry +import { registerFeatures } from './features/index.js'; + +// Custom Heading ID & Anchor Logic +const headingIdPlugin = (md, options: any = {}) => { + const uiStrings = options.uiStrings || {}; + md.core.ruler.push('heading_anchors', function (state) { + let containerDepth = 0; + const lastHeadingIds = new Array(7).fill(null); + const usedIds = new Map(); + + for (let i = 0; i < state.tokens.length; i++) { + const token = state.tokens[i]; + + // Track block-level inline containers (like steps) + if (token.type === 'steps_open' || (token.type.startsWith('custom_') && token.type.endsWith('_open'))) { + containerDepth++; + } + if (token.type === 'steps_close' || (token.type.startsWith('custom_') && token.type.endsWith('_close'))) { + containerDepth--; + } + + const inContainer = state.env.isInsideContainer || containerDepth > 0; + + if (token.type === 'heading_open') { + const level = parseInt(token.tag.slice(1), 10); + const inlineToken = state.tokens[i + 1]; + + // 1. Generate ID if not present and NOT in a container + let id = token.attrGet('id'); + if (!id && inlineToken && inlineToken.content && !inContainer) { + const slug = inlineToken.content + .toLowerCase() + .trim() + .replace(/\s+/g, '-') + .replace(/[^\p{L}\p{N}-]+/gu, '') + .replace(/--+/g, '-') + .replace(/^-+/, '') + .replace(/-+$/, ''); + + if (slug) { + // Find parent ID from previous levels + let parentId = null; + for (let j = level - 1; j >= 1; j--) { + if (lastHeadingIds[j]) { + parentId = lastHeadingIds[j]; + break; + } + } + + id = parentId ? `${parentId}-${slug}` : slug; + + // Handle hard collisions (same heading sequence twice) + if (usedIds.has(id)) { + const count = usedIds.get(id); + usedIds.set(id, count + 1); + id = `${id}-${count}`; + } else { + usedIds.set(id, 1); + } + + token.attrSet('id', id); + lastHeadingIds[level] = id; + // Clear deeper levels to prevent wrong parent nesting on backtrack + for (let j = level + 1; j <= 6; j++) lastHeadingIds[j] = null; + } + } + + // If we are in a container, strip existing IDs so they don't break the TOC parsing + if (inContainer) { + if (token.attrs) { + token.attrs = token.attrs.filter(a => a[0] !== 'id'); + } + id = null; + } + + // 2. Inject Hover Anchor as an HTML Token (for H1, H2, H3, H4) + if (id && level >= 1 && level <= 4 && !inContainer) { + const existingClass = token.attrGet('class') || ''; + token.attrSet('class', `${existingClass} docmd-heading`.trim()); + + if (inlineToken && inlineToken.children) { + const anchorToken = new state.Token('html_inline', '', 0); + const anchorLabel = uiStrings.permalinkToSection || 'Permalink to this section'; + anchorToken.content = ``; + + // Insert the anchor at the beginning of the heading text + inlineToken.children.unshift(anchorToken); + } + } + } + } + }); +}; + +// Main Factory Function to Create a Markdown Processor +function createMarkdownProcessor(config: any = {}, pluginsCallback: any) { + // HTML policy from config (Phase 0.D, default 'escape'). + // 'allow' -> markdown-it html: true (raw HTML passes through, UNSAFE) + // 'escape' -> markdown-it html: false (HTML escaped and shown as text) + // 'strip' -> html: false + disable html_block/html_inline rules (HTML removed) + const htmlPolicy = (config && config.security && config.security.html) || 'escape'; + const mdOptions: any = { + html: htmlPolicy === 'allow', + linkify: true, + typographer: true, + breaks: config.markdown?.breaks ?? true, + }; + + // Syntax Highlighting (title extraction is handled separately in the fence renderer) + const highlightFn = (str, lang) => { + if (lang === 'mermaid') { + return `
    ${new MarkdownIt().utils.escapeHtml(str)}
    `; + } + const highlighted = highlight(str, { language: lang, mimicHljs: true }).value; + // Tag the code with language-xxx so consumers (e.g. the summer + // template's codeblock title bar) can pick up the language. + const langAttr = lang ? ` class="language-${lang}"` : ''; + return `
    ${highlighted}
    `; + }; + + mdOptions.highlight = config.theme?.codeHighlight !== false ? highlightFn : (str: any, lang: any) => { + if (lang === 'mermaid') return `
    ${new MarkdownIt().utils.escapeHtml(str)}
    `; + const langAttr = lang ? ` class="language-${lang}"` : ''; + return `
    ${new MarkdownIt().utils.escapeHtml(str)}
    `; + }; + + const md = new MarkdownIt(mdOptions); + + // 'strip' policy: drop html_block and html_inline rules entirely so HTML + // tokens are never emitted. Distinct from 'escape' which keeps tokens and + // HTML-escapes their content. + if (htmlPolicy === 'strip') { + md.disable(['html_block', 'html_inline']); + } + + // Core Plugins + md.use(attrs, { leftDelimiter: '{', rightDelimiter: '}' }); + md.use(footnote); + md.use(taskLists); + md.use(abbr); + md.use(deflist); + md.use(emoji); + md.use(headingIdPlugin, { uiStrings: config._uiStrings || {} }); + + // Register Built-in Features + registerFeatures(md); + + // External Plugins Hook + if (typeof pluginsCallback === 'function') { + pluginsCallback(md); + } + + // Custom Fence Renderer: Extracts title from token.info (e.g., ```js "filename.js") + // markdown-it only passes the first word as `lang` to highlight(), so the title + // in quotes never reaches the highlight function. We intercept it here instead. + const defaultFence = md.renderer.rules.fence.bind(md.renderer.rules); + md.renderer.rules.fence = function (tokens, idx, options, env, self) { + const token = tokens[idx]; + const info = (token.info || '').trim(); + + // Match: language "title" or language 'title' + const titleMatch = info.match(/^[a-zA-Z0-9+#*-]*\s+["']([^"']+)["']/); + + // Get the default rendered output (which includes the highlighted code) + const rendered = defaultFence(tokens, idx, options, env, self); + + if (titleMatch) { + const title = titleMatch[1]; + return `
    ${title}
    ${rendered}
    `; + } + + return rendered; + }; + + const defaultLinkOpen = md.renderer.rules.link_open || function (tokens, idx, options, env, self) { + return self.renderToken(tokens, idx, options); + }; + + md.renderer.rules.link_open = function (tokens, idx, options, env, self) { + const token = tokens[idx]; + const hrefIndex = token.attrIndex('href'); + + if (hrefIndex >= 0) { + const href = token.attrs[hrefIndex][1]; + + // Phase 1.B (T-S4 fix): drop dangerous schemes. The link is rendered as + // a safe hash-anchor instead so the surrounding text still appears as a + // clickable (but inert) element. + if (isDangerousHref(href)) { + token.attrs[hrefIndex][1] = '#'; + return self.renderToken(tokens, idx, options); + } + + const isHashOnly = href.startsWith('#'); + const isAsset = href.match(/(^|\/)assets\//); + + if (!isHashOnly && !isAsset) { + const result = resolveHref(href); + + if (!result.isRaw) { + let pathPart = result.href; + let hashPart = ''; + const hi = pathPart.indexOf('#'); + if (hi >= 0) { + hashPart = pathPart.substring(hi); + pathPart = pathPart.substring(0, hi); + } + + // Depth adjustment for clean URLs (non-index pages are shifted into subfolders) + const isProtocol = pathPart.match(/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i); + if (!isProtocol && !pathPart.startsWith('/') && env && env.isIndex === false) { + if (pathPart.startsWith('./')) { + pathPart = '../' + pathPart.substring(2); + } else if (pathPart !== '') { + pathPart = '../' + pathPart; + } + } + + token.attrs[hrefIndex][1] = pathPart + hashPart; + } else { + token.attrs[hrefIndex][1] = result.href; + } + + // Apply external attributes + if (result.isExternal) { + token.attrSet('target', '_blank'); + token.attrSet('rel', 'noopener noreferrer'); + } + } + } + return defaultLinkOpen(tokens, idx, options, env, self); + }; + + return md; +} + +function stripHtml(html) { + if (!html) return ''; + return html.replace(/<[^>]*>?/gm, ''); +} + +function decodeHtmlEntities(str: string): string { + if (!str) return ''; + return str + .replace(/&/g, '&') + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/"/g, '"') + .replace(/'/g, "'") + .replace(/'/g, "'") + .replace(/’/g, "'") + .replace(/‘/g, "'") + .replace(/”/g, '"') + .replace(/“/g, '"') + .replace(/ /g, ' '); +} + +function extractHeadings(html) { + const headings = []; + // Require non-empty ID match to exclude stripped container headings: "([^"]+)" + const regex = /]*?id="([^"]+)"[^>]*?>([\s\S]*?)<\/h\1>/g; + let match; + while ((match = regex.exec(html)) !== null) { + const rawText = match[3].replace(/<\/?[^>]+(>|$)/g, '').trim(); + headings.push({ + level: parseInt(match[1], 10), + id: match[2], + text: decodeHtmlEntities(rawText) + }); + } + return headings; +} + +function processContent(rawString, mdInstance, config, env = {}) { + let frontmatter, markdownContent; + + try { + const parsed = matter(rawString); + frontmatter = parsed.data; + markdownContent = parsed.content; + } catch (e) { + console.error('Error parsing frontmatter:', e.message); + return null; + } + + if (!frontmatter.title && config.autoTitleFromH1 !== false) { + const h1Match = markdownContent.match(/^#\s+(.*)/m); + if (h1Match) frontmatter.title = h1Match[1].trim(); + } + + // Phase 2 (F1โ€“F5): rewrite unbalanced `:::` containers so the existing + // depth-tracking block rule in features/common-containers.ts always sees + // a matching close. + markdownContent = applyContainerNormaliser(markdownContent, env); + + const htmlContent = mdInstance.render(markdownContent, env); + const headings = extractHeadings(htmlContent); + + let searchData = null; + if (!frontmatter.noindex) { + searchData = { + title: frontmatter.title || 'Untitled', + content: stripHtml(htmlContent).slice(0, 5000), + headings: headings.map(h => ({ id: h.id, text: h.text })) + }; + } + + return { frontmatter, htmlContent, headings, searchData }; +} + +async function processContentAsync(rawString: string, mdInstance: any, config: any, env: any = {}, hooks: any = null) { + let frontmatter, markdownContent; + + try { + const parsed = matter(rawString); + frontmatter = parsed.data; + markdownContent = parsed.content; + } catch (e) { + console.error('Error parsing frontmatter:', e.message); + return null; + } + + // Phase 2 (F1โ€“F5): rewrite unbalanced `:::` containers BEFORE user plugins + // so they always see balanced input, and BEFORE markdown-it so the + // depth-tracking block rule can match every container it sees. + markdownContent = applyContainerNormaliser(markdownContent, env); + + if (hooks && hooks.onBeforeParse) { + for (const fn of hooks.onBeforeParse) { + // D-H7: previously a throw from any plugin's onBeforeParse would + // either propagate up (abort the file) or, after the safeCall + // wrapper landed, leave `markdownContent` set to `undefined` and + // crash the next iteration. We now catch each plugin's throw + // locally, log it via TUI, and keep walking the chain so plugins + // B, C, ... still see input (even if A's contribution is lost). + try { + const next = await fn(markdownContent, frontmatter, env.filePath); + // Only adopt the plugin's output if it returned a string. + // Plugins that want to "skip" should return undefined (we keep + // the previous markdown) rather than returning null. + if (typeof next === 'string') { + markdownContent = next; + } + } catch (err: any) { + const msg = err && err.message ? err.message : String(err); + console.error(`[parser] onBeforeParse plugin threw: ${msg}`); + } + } + } + + if (!frontmatter.title && config.autoTitleFromH1 !== false) { + const h1Match = markdownContent.match(/^#\s+(.*)/m); + if (h1Match) frontmatter.title = h1Match[1].trim(); + } + + let htmlContent = mdInstance.render(markdownContent, env); + if (env) { + htmlContent = stripDefaultLocalePrefix(htmlContent, env.defaultLocale, env.allLocales, env.relativePathToRoot || './'); + if (env.isOfflineMode === true) { + htmlContent = rewriteInternalHrefsForOffline(htmlContent, env.relativePathToRoot || './', env.config?.base || '/'); + } else { + // M-5 also affects online builds: `fr/index.html` linking to + // `/en/` is a 404 on HTTP servers too, not just file://. Run the + // same fixHtmlLinks pass (without the offline-specific `index.html` + // suffix) so cross-locale paths stay clean and correct. + htmlContent = fixHtmlLinks(htmlContent, env.relativePathToRoot || './', env.config?.base || '/'); + } + } + + if (hooks && hooks.onAfterParse) { + for (const fn of hooks.onAfterParse) { + htmlContent = await fn(htmlContent, frontmatter, env.filePath); + } + } + + const headings = extractHeadings(htmlContent); + + let searchData = null; + if (!frontmatter.noindex) { + searchData = { + title: frontmatter.title || 'Untitled', + content: stripHtml(htmlContent).slice(0, 5000), + headings: headings.map((h: any) => ({ id: h.id, text: h.text })) + }; + } + + return { frontmatter, htmlContent, headings, searchData }; +} + +/** + * M-5: strip the default-locale prefix from absolute hrefs in the rendered + * HTML. The default locale lives at root, not under its own prefix, so a + * link like `/en/foo` from a non-default-locale page is a 404 unless the + * prefix is dropped. We only run this when the source page is in a + * non-default locale (which is when the default-locale prefix could + * actually appear in author-written links). + * + * The function only touches absolute paths under root, only when the + * first segment matches the default locale id, and never touches + * external URLs / anchors / mailto. + */ +function stripDefaultLocalePrefix(html: string, defaultLocale: string | null, allLocales: string[] | undefined, _relativePathToRoot: string): string { + if (!defaultLocale || !allLocales || allLocales.length < 2) return html; + // Escape regex special chars in the locale id (e.g. "en-us" with hyphen). + const escaped = defaultLocale.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); + // Match `` and `` where xx is the + // default locale. We do NOT touch `src=` (img) because images are + // typically under /assets/ and never locale-prefixed. We do NOT touch + // bare `/xx` at end of attribute (rare author pattern) โ€” that case is + // ambiguous and the user can write `/` instead. + const re = new RegExp(`(]*?\\bhref\\s*=\\s*)(["'])(\\/${escaped}\\/)([^"'#]*)\\2`, 'gi'); + return html.replace(re, (_full, prefix, quote, _stripped, rest) => { + return `${prefix}${quote}/${rest}${quote}`; + }); +} + +/** + * Walk every `` and `` in a piece of rendered + * HTML and rewrite internal links for offline mode. External URLs (http, + * https, mailto, tel, javascript, etc.), hash-only anchors, and asset paths + * are passed through unchanged. + * + * The function is intentionally permissive on the regex: it tolerates + * attribute ordering, single or double quotes, and surrounding whitespace. + * The result is intentionally not run through a full HTML parser because + * the document we're rewriting is the markdown-rendered fragment, not a + * full HTML page, and we don't want to introduce a new dependency. + */ +function rewriteInternalHrefsForOffline(html: string, relativePathToRoot: string, base: string): string { + // `` rewriting โ€” covers markdown link `[text](url)`. + html = html.replace( + /]*?)\bhref\s*=\s*("([^"]*)"|'([^']*)')([^>]*)>/gi, + (full, _pre, quoted, dq, sq, _post) => { + const href = dq !== undefined ? dq : sq; + const fixed = fixHtmlLinks(href, relativePathToRoot, true, base); + if (fixed === href) return full; + const originalQuote = quoted.charAt(0); + return full.replace(quoted, originalQuote + fixed + originalQuote); + } + ); + // `` rewriting โ€” covers markdown image `![alt](src)`. + // The button template goes through `fixLink`, but markdown-it emits + // `` directly without any template helper. Without this pass the + // offline HTML keeps `` which `file://` + // cannot resolve (it's an absolute path with no host). + html = html.replace( + /]*?)\bsrc\s*=\s*("([^"]*)"|'([^']*)')([^>]*)>/gi, + (full, _pre, quoted, dq, sq, _post) => { + const src = dq !== undefined ? dq : sq; + const fixed = fixHtmlLinks(src, relativePathToRoot, true, base); + if (fixed === src) return full; + const originalQuote = quoted.charAt(0); + return full.replace(quoted, originalQuote + fixed + originalQuote); + } + ); + return html; +} + +export { createMarkdownProcessor, processContent, processContentAsync }; \ No newline at end of file diff --git a/packages/parser/src/utils/container-helper.ts b/packages/parser/src/utils/container-helper.ts new file mode 100644 index 0000000..9bf50a4 --- /dev/null +++ b/packages/parser/src/utils/container-helper.ts @@ -0,0 +1,35 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * Extracts a quoted title (e.g., "My Title") and an optional icon (e.g., icon:rocket) from a string. + * This is the standard parser for docmd containers (callouts, cards, tabs, etc.) + * + * @param {string} info - The raw info string to parse + * @returns {{ title: string, icon: string }} + */ +export function parseTitleAndIcon(info) { + if (!info) return { title: '', icon: '' }; + let icon = ''; + const iconMatch = info.match(/icon:([a-zA-Z0-9-]+)/); + if (iconMatch) { + icon = iconMatch[1]; + info = info.replace(iconMatch[0], ''); + } + + const titleMatch = info.match(/"([^"]*)"/); + const title = titleMatch ? titleMatch[1] : info.trim(); + + return { title, icon }; +} \ No newline at end of file diff --git a/packages/parser/src/utils/container-normaliser.ts b/packages/parser/src/utils/container-normaliser.ts new file mode 100644 index 0000000..46b0c14 --- /dev/null +++ b/packages/parser/src/utils/container-normaliser.ts @@ -0,0 +1,314 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/parser + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * Container normaliser + * ==================== + * + * Single-pass linear scan that rewrites `:::` container markdown so that + * the existing depth-tracking block rules in `features/common-containers.ts` + * always see balanced open/close pairs. + * + * The classic bugs this addresses: + * + * F1 โ€” depth tracker is indentation-blind. + * `::: grids` + Nร—` ::: grid` + Nร—`:::` (one per card) + * leaves depth > 0 and the block rule fails to match, so the + * whole grids block is dumped as raw `

    ::: grids
    ...

    `. + * F2 โ€” `::: tag` is self-closing but the next orphan `:::` still + * decrements depth of the wrong container. + * F3 โ€” `::: callout ... ::: card ... :::` silently re-roots. + * F4 โ€” bare `:::` lines leak into the page as `

    :::

    ` paragraphs. + * F5 โ€” 5+ levels of nesting survive when opens and closes are balanced, + * but unbalanced user input collapses inner levels. + * + * The algorithm is the same one documented in + * `battle-test-reports/robust-parser-shim/index.js` (146 lines, + * dependency-free). This file is the in-tree port โ€” no plugins, no + * configuration, always-on. + * + * Output is deterministic: the function is a pure function of its input. + * Two worker threads given the same source produce byte-identical output. + * + * โ”€โ”€โ”€ DETERMINISM AUDIT โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + * Phase 2 (worker-shared-state fix). This module deliberately does NOT + * use any of the following non-deterministic primitives. Adding any of + * them is a regression and must be flagged in code review. + * + * โœ— `Date.now()` / `new Date()` โ€” wall-clock time + * โœ— `Math.random()` / `crypto.randomUUID` โ€” entropy source + * โœ— module-level `let` / `var` โ€” mutable shared state + * โœ— `console.log` from inside `normaliseContainers` (use the + * `onWarning` callback instead โ€” `console.log` does not affect + * output but `DOCMD_ROBUST_DEBUG=1` enables it for ad-hoc tracing) + * โœ— reading from `process.env` โ€” env may differ per worker + * (use `options` instead) + * + * The only module-level binding is `SELF_CLOSING_CONTAINER_NAMES`, a + * frozen `ReadonlySet` that is constructed once at module load + * and never mutated. Safe to share across workers. + * + * The empirical guarantee lives in three places: + * 1. `packages/parser/test/container-normaliser.test.js` โ€” replay + * determinism, 100-way concurrency, and cross-worker + * `node:worker_threads` determinism. + * 2. `packages/core/src/engine/worker-parser.ts` boot-time self-test + * (`verifyDeterminismAtBoot`). + * 3. The manual end-to-end check at the bottom of this file's docstring. + * โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + */ + +/** + * Container names that produce a single line (no body, no close). + * These are matched by name in the open line and the line is passed + * through unchanged; any stray `:::` that follows them is a user mistake + * (F2) and is removed. + */ +export const SELF_CLOSING_CONTAINER_NAMES: ReadonlySet = new Set([ + 'button', + 'tag', + 'embed' +]); + +/** + * Severity levels for normaliser warnings. Mirrors the three messages the + * shim emits so downstream consumers can route by severity if they want. + */ +export type NormaliserWarningSeverity = 'warning' | 'info' | 'error'; + +export interface NormaliserWarning { + /** 1-indexed line number in the original source. */ + line: number; + severity: NormaliserWarningSeverity; + /** Path of the source file (or `` when synthetic). */ + path: string; + message: string; +} + +export interface NormaliserResult { + /** Rewritten source with implicit closes added and stray closes removed. */ + source: string; + warnings: NormaliserWarning[]; +} + +export interface NormaliserOptions { + /** Path used in warning messages. Defaults to ``. */ + sourcePath?: string; + /** When true, print debug lines to stdout. Defaults to false. */ + debug?: boolean; + /** Optional sink for warnings โ€” useful for tests and structured logging. */ + onWarning?: (warning: NormaliserWarning) => void; +} + +interface ClassifiedLine { + kind: 'open' | 'close' | 'other'; + name?: string; +} + +interface OpenFrame { + name: string; + /** 1-indexed line number where this container was opened. */ + line: number; + /** Indent (in spaces) of the line that opened the container. */ + indent: number; +} + +/** + * Count the leading spaces of a line. Tabs are not interpreted โ€” markdown + * container indentation is conventionally spaces. + */ +export function indentOf(line: string): number { + const m = line.match(/^ */); + return m ? m[0].length : 0; +} + +/** + * Classify a single source line as `open`, `close`, or `other`. + * + * open โ€” `::: ...` where `` starts with a letter. + * Self-closing names (`button`, `tag`, `embed`) are still + * classified as `open` โ€” the algorithm distinguishes them via + * the SELF_CLOSING_CONTAINER_NAMES set, not here. + * close โ€” bare `:::` with optional surrounding whitespace. + * other โ€” anything else, passed through verbatim. + */ +export function classifyLine(line: string): ClassifiedLine { + if (/^\s*:::\s*[a-zA-Z]/.test(line)) { + const m = line.match(/^\s*:::\s*([a-zA-Z][\w-]*)/); + return { kind: 'open', name: m ? m[1] : undefined }; + } + if (/^\s*:::\s*$/.test(line)) { + return { kind: 'close' }; + } + return { kind: 'other' }; +} + +/** + * Rewrite a markdown source so that every `:::` block has a matching close. + * + * The function never throws; instead it returns the rewritten source plus + * an array of warnings. Callers may surface warnings through `console.warn`, + * a structured logger, or both via `options.onWarning`. + * + * The algorithm is allocation-conscious (single array of output lines, single + * stack of open frames) but readability is prioritised over micro-optimisation. + */ +export function normaliseContainers( + source: string, + options: NormaliserOptions | string = {} +): NormaliserResult { + // Allow the legacy 2-arg call signature `normaliseContainers(src, path)` so + // any in-flight plugin code keeps working. + const opts: NormaliserOptions = typeof options === 'string' + ? { sourcePath: options } + : options; + + const sourcePath = opts.sourcePath || ''; + const debug = opts.debug === true; + const onWarning = typeof opts.onWarning === 'function' ? opts.onWarning : null; + + const lines = source.split('\n'); + const out: string[] = []; + const stack: OpenFrame[] = []; + const warnings: NormaliserWarning[] = []; + + // Fenced code block tracking โ€” see the in-loop comment below. + let inFence = false; + let fenceMarker: string | null = null; + + const recordWarning = (w: NormaliserWarning): void => { + warnings.push(w); + if (onWarning) onWarning(w); + }; + + for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + const cls = classifyLine(line); + const indent = indentOf(line); + + // Fenced code block tracking. The normaliser must not interpret + // `:::` lines that appear inside a ``` fence as container opens or + // closes โ€” they are literal text in a code listing. Without this + // check, any docs page that shows a `::: card ... :::` example + // inside a markdown code fence triggers a spurious "Unclosed + // " error (the fence-opened line is classified as an open, + // pushed on the stack, and never matched because the matching ::: + // is also inside the fence and would have been the close). + // + // We track the fence by its opening marker (``` or ~~~) and close + // on the same marker at the start of a later line. Tildes are + // included because CommonMark allows ~~~ as an alternative fence. + if (inFence) { + // Pass through verbatim; only check for the matching close marker. + if (/^\s*(```+|~~~+)/.test(line) && line.trimStart().startsWith(fenceMarker!)) { + inFence = false; + fenceMarker = null; + } + out.push(line); + continue; + } + const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/); + if (fenceMatch) { + inFence = true; + fenceMarker = fenceMatch[1][0]; // '`' or '~' + out.push(line); + continue; + } + + if (cls.kind === 'open') { + // The shim's classification only tells us the line LOOKS like an open; + // the SELF_CLOSING set is the source of truth for whether the body + // exists. Without this distinction `::: tag` would corrupt depth (F2). + if (cls.name && SELF_CLOSING_CONTAINER_NAMES.has(cls.name)) { + out.push(line); + if (debug) { + console.log(`[normaliser] ${sourcePath}:${i + 1} self-close <${cls.name}>`); + } + continue; + } + + stack.push({ name: cls.name || '', line: i + 1, indent }); + out.push(line); + continue; + } + + if (cls.kind === 'close') { + // Walk the stack from innermost outward and find the first open whose + // indent is <= this close's indent. That is the container this `:::` + // logically closes โ€” anything above it was closed implicitly by the + // same user gesture. + let matchIdx = -1; + for (let j = stack.length - 1; j >= 0; j--) { + if (stack[j].indent <= indent) { + matchIdx = j; + break; + } + } + + if (matchIdx === -1) { + recordWarning({ + line: i + 1, + severity: 'warning', + path: sourcePath, + message: 'Stray `:::` removed. Common cause: `::: tag ... :::` (tag is self-closing).' + }); + continue; + } + + const closed = stack.splice(matchIdx); + const outerIndent = closed[0].indent; + + // Emit one `:::` per closed entry, all at the outer indent. The + // upstream parser's `smartDedent` collapses higher indents to the + // outer indent, so N closes at the outer indent correctly pop N + // entries from its depth counter. + for (let k = 0; k < closed.length; k++) { + out.push(' '.repeat(outerIndent) + ':::'); + } + + if (closed.length > 1) { + recordWarning({ + line: i + 1, + severity: 'info', + path: sourcePath, + message: + `Closed ${closed.length} containers implicitly (` + + closed.map((c) => `<${c.name}>`).join(' > ') + + `). Added ${closed.length - 1} explicit \`:::\` closes.` + }); + } + continue; + } + + out.push(line); + } + + // Auto-close anything still on the stack at EOF. Without this the upstream + // block rule would loop to endLine without finding a close and the whole + // container would be dropped (F1, F3). + for (let i = stack.length - 1; i >= 0; i--) { + const frame = stack[i]; + recordWarning({ + line: frame.line, + severity: 'error', + path: sourcePath, + message: `Unclosed \`<${frame.name}>\` from line ${frame.line} โ€” auto-closed at EOF.` + }); + out.push(' '.repeat(frame.indent) + ':::'); + } + + return { source: out.join('\n'), warnings }; +} + +export default normaliseContainers; \ No newline at end of file diff --git a/packages/parser/src/utils/icon-renderer.ts b/packages/parser/src/utils/icon-renderer.ts new file mode 100644 index 0000000..8ab5bf5 --- /dev/null +++ b/packages/parser/src/utils/icon-renderer.ts @@ -0,0 +1,60 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import * as lucideStatic from 'lucide-static'; + +// Convert kebab-case to PascalCase (e.g., arrow-right -> ArrowRight) +function kebabToPascal(str: string): string { + return str.split('-').map((p: string) => p.charAt(0).toUpperCase() + p.slice(1)).join(''); +} + +const exceptions: any = { + 'arrow-up-right-square': 'ExternalLink', + 'file-cog': 'Settings', + 'cloud-upload': 'UploadCloud' +}; + +function escapeHtml(str: any): string { + const s = typeof str === 'string' ? str : String(str || ''); + return s.replace(/[&<>"']/g, m => ({ + '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' + })[m] as string); +} + +function renderIcon(name: string, options: any = {}) { + if (!name) return ''; + + const key = exceptions[name] || kebabToPascal(name); + const svgData = (lucideStatic as any)[key]; + + if (!svgData) return ''; // Fail silently or warn via callback + + const escape = escapeHtml; + + // Inject attributes into the raw SVG string + const attrs = [ + `class="lucide-icon icon-${escape(name)} ${escape(options.class || '')}"`, + `width="${escape(options.width || '1em')}"`, + `height="${escape(options.height || '1em')}"`, + `stroke="${escape(options.stroke || 'currentColor')}"`, + `stroke-width="${escape(options.strokeWidth || 2)}"`, + 'fill="none"', + 'stroke-linecap="round"', + 'stroke-linejoin="round"' + ].join(' '); + + return svgData.replace(' item.canonical === currentCanonical); + + return { + prevPage: index > 0 ? flatNavigation[index - 1] : null, + nextPage: index < flatNavigation.length - 1 ? flatNavigation[index + 1] : null + }; +} + +function findBreadcrumbs(navItems, currentPagePath) { + const currentCanonical = getCanonicalPath(currentPagePath); + let breadcrumbs = []; + + function recurse(items, currentTrail = []) { + if (!items) return false; + for (const item of items) { + const trail = [...currentTrail, { title: item.title, path: item.path }]; + + if (item.path && getCanonicalPath(item.path) === currentCanonical) { + breadcrumbs = trail; + return true; + } + + if (item.children) { + if (recurse(item.children, trail)) return true; + } + } + return false; + } + + recurse(navItems); + return breadcrumbs; +} + +export { findPageNeighbors, findBreadcrumbs }; \ No newline at end of file diff --git a/packages/parser/src/utils/normalize-href.ts b/packages/parser/src/utils/normalize-href.ts new file mode 100644 index 0000000..4d8e232 --- /dev/null +++ b/packages/parser/src/utils/normalize-href.ts @@ -0,0 +1,195 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * Result of processing a href through the normaliser. + */ +export interface NormalizedHref { + /** The cleaned, SEO-safe href */ + href: string; + /** Whether the link should open in a new tab */ + isExternal: boolean; + /** Whether the link should skip normalisation (raw file reference) */ + isRaw: boolean; +} + +/** + * Centralised internal href normaliser. + * + * Converts any user-written link format into a clean, SEO-optimised URL + * that ends with a trailing slash (for directory-style pages) or is left + * untouched (for external, hash-only, or asset links). + * + * Supports special prefixes: + * - `external:` - forces the link to open in a new tab (strips prefix) + * - `raw:` - bypasses normalisation (strips prefix, keeps extension) + * + * Supported input formats (all produce the same output): + * - overview.md โ†’ overview/ + * - overview โ†’ overview/ + * - overview/ โ†’ overview/ + * - ./overview.md โ†’ ./overview/ + * - ../api/commands.md โ†’ ../api/commands/ + * - localisation/index.md โ†’ localisation/ + * - ./content/index.md โ†’ ./content/ + * - ../index.md โ†’ ../ + * - index.md โ†’ (empty string - root of current dir) + * - /absolute/path.md โ†’ /absolute/path/ + * - #section โ†’ #section (unchanged) + * - https://example.com โ†’ https://example.com (unchanged, auto-external) + * - mailto:hi@docmd.io โ†’ mailto:hi@docmd.io (unchanged) + * - external:overview.md โ†’ overview/ (opens in new tab) + * - raw:docs/readme.md โ†’ docs/readme.md (no normalisation) + * + * @param href The raw href string from a markdown link, button, or nav config. + * @returns The normalised result with external/raw flags. + */ +export function resolveHref(href: string): NormalizedHref { + if (!href) return { href, isExternal: false, isRaw: false }; + + // 1. Handle `raw:` prefix - bypass all normalisation, keep extension + if (href.startsWith('raw:')) { + return { href: href.slice(4), isExternal: false, isRaw: true }; + } + + // 2. Handle `external:` prefix - normalise but flag as external + // Users must explicitly use external: prefix to open in new tab + let isExternal = false; + if (href.startsWith('external:')) { + href = href.slice(9); + isExternal = true; + } + + // 3. Auto-detect external protocols (only for detection, not for new-tab behavior) + // This info can be used separately if needed, but we don't set isExternal here + // to give users control over their own docs links + + // 4. Pass through: all protocols (mailto:, tel:, ftp:, etc.), hash-only, asset paths + if ( + href.match(/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i) || // http:, https:, mailto:, tel:, ftp:, // + href.startsWith('#') || + href.match(/(^|\/)assets\//) + ) { + return { href, isExternal, isRaw: false }; + } + + // 5. Separate hash fragment + let hash = ''; + const hashIndex = href.indexOf('#'); + if (hashIndex >= 0) { + hash = href.substring(hashIndex); + href = href.substring(0, hashIndex); + } + + // 6. Strip .md, .html, and .ejs extensions + if (href.endsWith('.md')) { + href = href.slice(0, -3); + } else if (href.endsWith('.html')) { + href = href.slice(0, -5); + } else if (href.endsWith('.ejs')) { + href = href.slice(0, -4); + } + + // 7. Strip trailing /index or /README (the page is the folder root) + // Handles: dir/index, ./dir/index, ../dir/index, /dir/index + // And: dir/README, ./dir/README, ../dir/README, /dir/README + // Also handles bare "index" or "README" (root index) + const lowerHref = href.toLowerCase(); + if (lowerHref === 'index' || lowerHref === './index' || lowerHref === 'readme' || lowerHref === './readme') { + href = (lowerHref === 'index' || lowerHref === 'readme') ? '' : './'; + } else if (lowerHref.endsWith('/index')) { + href = href.slice(0, -5); // "dir/index" โ†’ "dir/" + } else if (lowerHref.endsWith('/readme')) { + href = href.slice(0, -6); // "dir/readme" โ†’ "dir/" + } + + // 8. Ensure trailing slash for non-empty paths + // But NOT for empty string (which represents current directory root) + if (href !== '' && !href.endsWith('/')) { + href += '/'; + } + + // 9. Collapse any accidental double slashes (preserve leading // caught above) + href = href.replace(/([^:])\/{2,}/g, '$1/'); + + return { href: href + hash, isExternal, isRaw: false }; +} + +/** + * Simplified normaliser for backward compatibility. + * Returns only the normalised href string (no external/raw flags). + * Used by navigation normalisation where external detection is handled separately. + */ +export function normalizeInternalHref(href: string): string { + return resolveHref(href).href; +} + +/** + * Recursively normalises all `path` values in a navigation tree. + * Used for nav config from `navigation.json`, `docmd.config.js`, and the auto-router. + * + * Supports the `external:` prefix as a shorthand for `external: true`: + * { "path": "external:https://github.com" } โ†’ { "path": "https://github.com", "external": true } + * + * The explicit `external: true` attribute is also supported and takes precedence. + */ +export function normalizeNavPaths(items: any[]): void { + if (!items) return; + for (const item of items) { + if (item.path && typeof item.path === 'string') { + const result = resolveHref(item.path); + item.path = result.href; + // If external: prefix was used, set the external flag (unless already explicitly set) + if (result.isExternal && item.external !== false) { + item.external = true; + } + } + if (item.children) { + normalizeNavPaths(item.children); + } + } +} + +/** + * Recursively normalises all `url` values in a menubar tree. + * Applies the same trailing-slash enforcement and external detection as Markdown links. + */ +export function normalizeMenubarPaths(items: any[]): void { + if (!items) return; + for (const item of items) { + if (item.url && typeof item.url === 'string') { + const result = resolveHref(item.url); + item.url = result.href; + if (result.isExternal) item.external = true; + } + if (item.items) { + normalizeMenubarPaths(item.items); + } + } +} + +/** + * Sanitize a URL by collapsing consecutive slashes (except after protocol). + * This is the last-resort safety net - if upstream logic is correct, this + * should be a no-op. + * + * @example + * sanitizeUrl('//docs//guide/') โ†’ '/docs/guide/' + * sanitizeUrl('https://a.com//b') โ†’ 'https://a.com/b' + */ +export function sanitizeUrl(url: string): string { + if (!url) return url; + // Collapse double+ slashes, but preserve protocol:// + return url.replace(/([^:])\/\/+/g, '$1/'); +} \ No newline at end of file diff --git a/packages/parser/src/utils/url-utils.ts b/packages/parser/src/utils/url-utils.ts new file mode 100644 index 0000000..411288e --- /dev/null +++ b/packages/parser/src/utils/url-utils.ts @@ -0,0 +1,294 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/parser + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * Centralised URL Utilities + * ========================= + * + * This module is the **single source of truth** for all URL transformations + * in the docmd ecosystem. Every plugin, template, and engine component + * MUST use these utilities instead of rolling their own URL logic. + * + * Architecture: + * + * User Input (markdown, config) + * โ”‚ + * โ–ผ + * resolveHref() โ† normalize-href.ts (user-facing href โ†’ clean path) + * โ”‚ + * โ–ผ + * Build Engine โ† generator.ts produces outputPath per page + * โ”‚ + * โ–ผ + * URL Utilities โ† THIS FILE + * โ”‚ + * โ”œโ”€โ”€ outputPathToSlug() โ†’ "guide/" + * โ”œโ”€โ”€ outputPathToCanonical() โ†’ "https://site.com/guide/" + * โ”œโ”€โ”€ buildContextualUrl() โ†’ "../de/guide/" (relative, context-aware) + * โ”œโ”€โ”€ sanitizeUrl() โ†’ collapse //, enforce trailing / + * โ””โ”€โ”€ createUrlContext() โ†’ factory for page-level context + * + * Plugins receive pre-computed URLs via the page object, OR can import + * these utilities directly for custom URL generation. + */ + +import { sanitizeUrl } from './normalize-href.js'; + +// Re-export sanitizeUrl from normalize-href for convenience +export { sanitizeUrl }; + +// โ”€โ”€โ”€ Types โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** + * Immutable context object that captures all the environmental factors + * needed to resolve a URL for a specific page render. + * + * Created once per page in generator.ts and passed to all templates + * and plugin hooks. + */ +export interface UrlContext { + /** Relative path from current page back to site root, e.g. `../../` or `./` */ + readonly relativePathToRoot: string; + /** Locale + version prefix for the current build pass, e.g. `de/v1/` or `` */ + readonly outputPrefix: string; + /** Whether we're generating for offline/file:// browsing */ + readonly offline: boolean; + /** The site base path from config, e.g. `/docs/` or `/` */ + readonly base: string; + /** The full site URL from config, e.g. `https://docmd.io` (no trailing slash) */ + readonly siteUrl: string; +} + +/** + * Pre-computed URL data attached to every page object. + * Plugins can read these directly - zero computation needed. + */ +export interface PageUrls { + /** Clean directory-style slug, e.g. `guide/` or `/` for root */ + readonly slug: string; + /** Full canonical URL, e.g. `https://docmd.io/guide/` (only if siteUrl is set) */ + readonly canonical: string; + /** Relative path from site root, e.g. `/guide/` or `/` */ + readonly pathname: string; +} + +// โ”€โ”€โ”€ Core Utilities โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +/** + * Collapse consecutive slashes (except after protocol `:`), enforce + * consistent formatting. This is the **last-resort safety net** - if + * the upstream logic is correct, this should be a no-op. + * + * Note: This function is imported from normalize-href.ts to ensure + * single source of truth for URL sanitization logic. + */ + +/** + * Convert a build-engine outputPath to a clean directory-style slug. + * + * This is the **single canonical conversion** from the internal file path + * representation to a URL path segment. Every consumer that previously + * did its own `outputPath.replace('/index.html', '/')` MUST use this. + * + * @param outputPath - e.g. `guide/index.html`, `index.html`, `de/v1/api/index.html` + * @returns Clean slug, e.g. `guide/`, `/`, `de/v1/api/` + * + * @example + * outputPathToSlug('guide/index.html') โ†’ 'guide/' + * outputPathToSlug('index.html') โ†’ '/' + * outputPathToSlug('de/v1/api/index.html') โ†’ 'de/v1/api/' + * outputPathToSlug('about.html') โ†’ 'about/' + */ +export function outputPathToSlug(outputPath: string): string { + if (!outputPath) return '/'; + + let slug = outputPath.replace(/\\/g, '/'); + + // Strip trailing index.html + if (slug === 'index.html') return '/'; + if (slug.endsWith('/index.html')) { + slug = slug.slice(0, -10); // remove 'index.html', keep trailing '/' + } else if (slug.endsWith('.html')) { + slug = slug.slice(0, -5) + '/'; + } + + // Ensure trailing slash + if (slug !== '/' && !slug.endsWith('/')) { + slug += '/'; + } + + return slug; +} + +/** + * Convert an outputPath to a root-relative pathname (always starts with `/`). + * + * @param outputPath - e.g. `guide/index.html` + * @returns e.g. `/guide/` + */ +export function outputPathToPathname(outputPath: string): string { + const slug = outputPathToSlug(outputPath); + return slug.startsWith('/') ? slug : '/' + slug; +} + +/** + * Convert an outputPath to a full canonical URL. + * + * @param outputPath - e.g. `guide/index.html` + * @param siteUrl - e.g. `https://docmd.io` (no trailing slash) + * @returns e.g. `https://docmd.io/guide/` + */ +export function outputPathToCanonical(outputPath: string, siteUrl: string): string { + if (!siteUrl) return ''; + const cleanSiteUrl = siteUrl.replace(/\/+$/, ''); + const pathname = outputPathToPathname(outputPath); + return sanitizeUrl(cleanSiteUrl + pathname); +} + +/** + * Build a context-aware relative URL from a clean href. + * + * This replaces ALL inline URL building in EJS templates and the + * `buildRelativeUrl` function in generator.ts. It is the single + * function that understands relativePathToRoot, outputPrefix, + * offline mode, and base path. + * + * @param href - A clean, normalised href (output of resolveHref), e.g. `guide/`, `#section`, `https://...` + * @param context - The UrlContext for the current page + * @returns A fully resolved relative URL safe for use in `    ` + * + * @example + * // Page at /de/v1/getting-started/index.html + * buildContextualUrl('guide/', ctx) + * // โ†’ '../../de/v1/guide/' (relative, with locale+version prefix) + * + * buildContextualUrl('#section', ctx) + * // โ†’ '#section' (hash-only, untouched) + * + * buildContextualUrl('https://github.com', ctx) + * // โ†’ 'https://github.com' (external, untouched) + */ +export function buildContextualUrl(href: string, context: UrlContext): string { + // Pass-through: empty, hash-only, external protocols, data URIs + if (!href || href === '#') return href || '#'; + // D-S2: strip the `external:` prefix defensively. Plugin callers may + // invoke this function directly without going through `resolveHref` + // first; previously `external:https://...` was treated as a literal + // path segment and got mangled into `./external:https://...`. + if (href.startsWith('external:')) { + href = href.slice('external:'.length); + } + if (href.startsWith('http') || href.startsWith('//') || href.startsWith('mailto:') || href.startsWith('tel:') || href.startsWith('data:')) { + return href; + } + // Hash-only anchors pass through unchanged. Without this guard, a + // value like `#section` falls through to the path-combining branch + // and gets prepended with the page's `relativePathToRoot`, producing + // `./#section` โ€” which a browser still resolves to the same anchor, + // but breaks expectations for callers that compare the output to the + // input hash verbatim. + if (href.startsWith('#')) return href; + + // Separate hash fragment + let hash = ''; + const hashIdx = href.indexOf('#'); + if (hashIdx >= 0) { + hash = href.substring(hashIdx); + href = href.substring(0, hashIdx); + } + + // Strip leading ./ and / to get a clean relative path + const cleanPath = href.replace(/^(\.\/|\/)+/, ''); + + // Build the prefixed path: outputPrefix (locale/version) + clean path + const prefixStr = context.outputPrefix ? context.outputPrefix.replace(/\/$/, '') : ''; + let combinedPath = prefixStr + ? (cleanPath ? prefixStr + '/' + cleanPath : prefixStr + '/') + : cleanPath; + + // Offline mode: append /index.html for file:// browsing + if (context.offline && combinedPath !== '' && !combinedPath.endsWith('.html') && !combinedPath.endsWith('/')) { + combinedPath = combinedPath + '/index.html'; + } else if (context.offline && combinedPath !== '' && combinedPath.endsWith('/')) { + combinedPath = combinedPath + 'index.html'; + } + + // Build final relative URL + const result = context.relativePathToRoot + combinedPath + hash; + return sanitizeUrl(result); +} + +/** + * Create a UrlContext for a specific page render. + * + * Called once per page in generator.ts. The resulting context is then + * passed to all templates and can be forwarded to plugin hooks. + * + * @param options - Configuration for this page's URL context + */ +export function createUrlContext(options: { + relativePathToRoot: string; + outputPrefix?: string; + offline?: boolean; + base?: string; + siteUrl?: string; +}): UrlContext { + return Object.freeze({ + relativePathToRoot: options.relativePathToRoot || './', + outputPrefix: options.outputPrefix || '', + offline: options.offline || false, + base: options.base || '/', + siteUrl: (options.siteUrl || '').replace(/\/+$/, ''), + }); +} + +/** + * Compute pre-built URL data for a page. + * + * Called once per page in generator.ts. The resulting PageUrls object + * is attached to the page object and available to all post-build plugins. + * + * @param outputPath - The page's output path, e.g. `guide/index.html` + * @param siteUrl - The site URL from config, e.g. `https://docmd.io` + */ +export function computePageUrls(outputPath: string, siteUrl: string): PageUrls { + return Object.freeze({ + slug: outputPathToSlug(outputPath), + canonical: outputPathToCanonical(outputPath, siteUrl), + pathname: outputPathToPathname(outputPath), + }); +} + +/** + * Build an absolute URL from config.base + optional locale + optional version + page path. + * + * Used by version-dropdown.ejs and language-switcher.ejs for absolute navigation. + * Replaces the inline JS computations in those templates. + * + * @param base - config.base, e.g. `/docs/` or `/` + * @param localePrefix - e.g. `de/` or `` for default locale + * @param versionPrefix - e.g. `v1/` or `` for current version + * @param pagePath - e.g. `guide/` or `` + * @returns Absolute path, e.g. `/docs/de/v1/guide/` + */ +export function buildAbsoluteUrl( + base: string, + localePrefix: string = '', + versionPrefix: string = '', + pagePath: string = '' +): string { + const normalizedBase = base.endsWith('/') ? base : base + '/'; + const result = normalizedBase + localePrefix + versionPrefix + pagePath; + return sanitizeUrl(result); +} diff --git a/packages/parser/src/utils/validator.ts b/packages/parser/src/utils/validator.ts new file mode 100644 index 0000000..b13b356 --- /dev/null +++ b/packages/parser/src/utils/validator.ts @@ -0,0 +1,125 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + + +import { TUI } from '@docmd/tui'; + +// Known configuration keys for typo detection (V2 + V3) +const KNOWN_KEYS = [ + // V3 Modern Labels + 'title', 'url', 'src', 'out', 'base', 'layout', + 'versions', 'redirects', 'notFound', 'projects', + + // Engine selection (e.g. "rust" for the rust preview engine) + 'engine', 'engines', + + // V2 Legacy Labels + 'siteTitle', 'siteUrl', 'srcDir', 'outputDir', + + // Shared Features + 'logo', 'sidebar', 'theme', 'customJs', 'autoTitleFromH1', + 'copyCode', 'plugins', 'navigation', 'footer', 'sponsor', 'favicon', + 'search', 'minify', 'editLink', 'pageNavigation', 'i18n', + + // Workspace + 'workspace' +]; + +// Common typos mapping +const TYPO_MAPPING = { + 'site_title': 'title', + 'sitetitle': 'title', + 'baseUrl': 'url', + 'source': 'src', + 'outDir': 'out', + 'customCSS': 'theme.customCss', + 'customcss': 'theme.customCss', + 'customJS': 'customJs', + 'customjs': 'customJs', + 'nav': 'navigation', + 'menu': 'navigation' +}; + +function validateConfig(config) { + const errors = []; + const warnings = []; + + // 1. Required Fields (Accept either title OR siteTitle) + // Skip for multi-project root configs - they only have projects[] + if (!config.title && !config.siteTitle && !Array.isArray(config.projects)) { + errors.push('Missing required property: "title" (or "siteTitle")'); + } + + // 2. Type Checking + if (config.navigation && !Array.isArray(config.navigation)) { + errors.push('"navigation" must be an Array'); + } + + if (config.customJs && !Array.isArray(config.customJs)) { + errors.push('"customJs" must be an Array of strings'); + } + + if (config.theme) { + if (config.theme.customCss && !Array.isArray(config.theme.customCss)) { + errors.push('"theme.customCss" must be an Array of strings'); + } + } + + if (config.versions && config.versions.all && !Array.isArray(config.versions.all)) { + errors.push('"versions.all" must be an Array'); + } + + // 3. Typos and Unknown Keys (Top Level) + // T-Z3: previously completely-unknown keys were silently ignored. We + // now warn about every unrecognised top-level key (typo suggestions + // where applicable) so misconfigurations don't ship silently. Nested + // plugin config (`plugins..*`) is intentionally NOT checked โ€” + // each plugin owns its own schema and is validated by the plugin + // loader. + Object.keys(config).forEach(key => { + // Skip checking internal keys (starting with _) + if (key.startsWith('_')) return; + + if (!KNOWN_KEYS.includes(key)) { + if (TYPO_MAPPING[key]) { + warnings.push(`Found unknown property "${key}". Did you mean "${TYPO_MAPPING[key]}"?`); + } else { + warnings.push(`Unknown property "${key}" in config โ€” ignored. (Top-level keys only; plugin-specific options belong under "plugins.".)`); + } + } + }); + + // 4. Theme specific typos + if (config.theme) { + if (config.theme.customCSS) { + warnings.push('Found "theme.customCSS". Did you mean "theme.customCss"?'); + } + } + + // Output results + if (warnings.length > 0) { + TUI.warn('Configuration Warnings:'); + warnings.forEach(w => TUI.warn(w)); + } + + if (errors.length > 0) { + TUI.error('Configuration Errors'); + errors.forEach(e => TUI.error(e)); + throw new Error('Invalid configuration file.'); + } + + return { warnings, errors }; +} + +export { validateConfig }; \ No newline at end of file diff --git a/packages/parser/test/container-normaliser.test.js b/packages/parser/test/container-normaliser.test.js new file mode 100644 index 0000000..e693e12 --- /dev/null +++ b/packages/parser/test/container-normaliser.test.js @@ -0,0 +1,814 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * Phase 2 container normaliser โ€” edge-case test fixture + * + * These tests cover the five reported F1โ€“F5 failure modes plus the + * 50+ edge cases that derive from the shim's own warning surface + * (battle-test-reports/robust-parser-shim/index.js) and the + * `normaliseContainers` algorithm. + * + * Test categories (in order): + * 1. classifyLine โ€” open / close / other classification + * 2. indentOf โ€” leading-space counting + * 3. normaliseContainers โ€” core algorithm (no warnings) + * 4. normaliseContainers โ€” warning surface + * 5. F1โ€“F5 reported failure modes + * 6. processContentAsync integration โ€” end-to-end HTML + * 7. Determinism โ€” identical output across threads / replays + * + * Run: `pnpm --filter @docmd/parser test` + * -------------------------------------------------------------------- + */ + +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { + normaliseContainers, + classifyLine, + indentOf, + SELF_CLOSING_CONTAINER_NAMES, + createMarkdownProcessor, + processContentAsync +} from '../dist/index.js'; + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// 1. classifyLine +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +test('classifyLine: `::: callout` is open with name `callout`', () => { + assert.deepEqual(classifyLine('::: callout'), { kind: 'open', name: 'callout' }); +}); + +test('classifyLine: `::: callout info "Title"` is open, name is the first word', () => { + assert.deepEqual( + classifyLine('::: callout info "Title"'), + { kind: 'open', name: 'callout' } + ); +}); + +test('classifyLine: `:::card` (no space) is still open (zero-or-more whitespace)', () => { + assert.deepEqual(classifyLine(':::card'), { kind: 'open', name: 'card' }); +}); + +test('classifyLine: `:::` is close', () => { + assert.deepEqual(classifyLine(':::'), { kind: 'close' }); +}); + +test('classifyLine: `::: ` (trailing whitespace) is close', () => { + assert.deepEqual(classifyLine('::: '), { kind: 'close' }); +}); + +test('classifyLine: ` ::: callout` (leading indent) is still open', () => { + assert.deepEqual( + classifyLine(' ::: callout'), + { kind: 'open', name: 'callout' } + ); +}); + +test('classifyLine: `:::: callout` (four colons) is NOT matched as open or close', () => { + // Three colons then a fourth colon is not whitespace, so `[a-zA-Z]` fails. + // The line passes through to the parser unchanged. + assert.equal(classifyLine(':::: callout').kind, 'other'); +}); + +test('classifyLine: `::: 123abc` (leading digit) is NOT open', () => { + // Name must start with a letter. + assert.equal(classifyLine('::: 123abc').kind, 'other'); +}); + +test('classifyLine: `:::-foo` (hyphen, not letter) is NOT open', () => { + assert.equal(classifyLine(':::-foo').kind, 'other'); +}); + +test('classifyLine: `plain text` is other', () => { + assert.equal(classifyLine('plain text').kind, 'other'); +}); + +test('classifyLine: empty string is other', () => { + assert.equal(classifyLine('').kind, 'other'); +}); + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// 2. indentOf +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +test('indentOf: empty line is 0', () => { + assert.equal(indentOf(''), 0); +}); + +test('indentOf: line with no leading spaces is 0', () => { + assert.equal(indentOf('::: callout'), 0); +}); + +test('indentOf: 4 leading spaces is 4', () => { + assert.equal(indentOf(' ::: callout'), 4); +}); + +test('indentOf: 8 leading spaces is 8', () => { + assert.equal(indentOf(' ::: card'), 8); +}); + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// 3. normaliseContainers โ€” core algorithm (no warnings expected) +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +test('normaliseContainers: empty input is unchanged', () => { + const r = normaliseContainers(''); + assert.equal(r.source, ''); + assert.deepEqual(r.warnings, []); +}); + +test('normaliseContainers: input with no `:::` is unchanged', () => { + const src = '# Title\n\nSome **bold** text.\n\n- list item\n'; + const r = normaliseContainers(src); + assert.equal(r.source, src); + assert.deepEqual(r.warnings, []); +}); + +test('normaliseContainers: balanced single callout is unchanged', () => { + const src = '::: callout info "Title"\nbody\n:::\n'; + const r = normaliseContainers(src); + assert.equal(r.source, src); + assert.deepEqual(r.warnings, []); +}); + +test('normaliseContainers: self-closing `::: button` passes through with no stack push', () => { + const src = '::: button "Click me"\n'; + const r = normaliseContainers(src); + assert.equal(r.source, src); + assert.deepEqual(r.warnings, []); +}); + +test('normaliseContainers: SELF_CLOSING_CONTAINER_NAMES has exactly button/tag/embed', () => { + // The whitelist is the source of truth for the depth counter's behaviour. + // Adding or removing names here is a parser-semantics change. + assert.deepEqual( + [...SELF_CLOSING_CONTAINER_NAMES].sort(), + ['button', 'embed', 'tag'] + ); +}); + +test('normaliseContainers: three self-closing tags then a stray `:::` removes the stray', () => { + // F2 โ€” orphan `:::` after self-closing tags must be dropped. + const src = '::: tag "a"\n::: tag "b"\n::: tag "c"\n:::\n'; + const r = normaliseContainers(src); + assert.equal(r.source, '::: tag "a"\n::: tag "b"\n::: tag "c"\n'); + assert.equal(r.warnings.length, 1); + assert.equal(r.warnings[0].severity, 'warning'); + assert.match(r.warnings[0].message, /Stray `:::`/); +}); + +test('normaliseContainers: nested callout/card with one implicit close emits 2 closes', () => { + // Inner `::: card` is at indent 4; user's `:::` is at indent 0 โ†’ the + // close at indent 0 matches the OUTER callout, and the inner card is + // closed implicitly. Algorithm emits 2 closes at indent 0 (one replaces + // the user's `:::`, one is added for the card). + const src = '::: callout\n ::: card "x"\n body\n:::\n'; + const r = normaliseContainers(src); + const lines = r.source.split('\n'); + const closeCount = lines.filter((l) => /^:::\s*$/.test(l)).length; + assert.equal(closeCount, 2, `expected 2 closes at indent 0, got ${closeCount}`); + assert.equal(r.warnings.length, 1); + assert.equal(r.warnings[0].severity, 'info'); +}); + +test('normaliseContainers: indented open matched by greater-indent close', () => { + // Open at indent 4, close at indent 8 (deeper indent). The shim's + // matching rule is `open.indent <= close.indent` so 4 <= 8 matches. + // The original `:::` is replaced with one at the open's indent. + const src = ' ::: card "x"\nbody\n :::\n'; + const r = normaliseContainers(src); + // The original close is rewritten at the open's indent (4 spaces). + assert.match(r.source, / {4}::: card "x"\n/); + assert.match(r.source, /\n {4}:::/); + // No warnings โ€” this is a balanced container. + assert.deepEqual(r.warnings, []); +}); + +test('normaliseContainers: close LESS indented than open is stray, container auto-closes at EOF', () => { + // Open at indent 4, close at indent 0. The shim's matching rule is + // `open.indent <= close.indent` so 4 <= 0 fails โ†’ stray close. The + // card then auto-closes at EOF with an ERROR (at the card's indent). + const src = ' ::: card "x"\nbody\n:::\n'; + const r = normaliseContainers(src); + // The stray close at indent 0 is removed; the card is auto-closed at + // EOF at the card's original indent (4 spaces). + assert.doesNotMatch(r.source, /\n:::\s*$/); + assert.match(r.source, /\n {4}:::\s*$/); + // Warnings: 1 stray (warning) + 1 unclosed (error). + const stray = r.warnings.find((w) => w.severity === 'warning'); + const unclosed = r.warnings.find((w) => w.severity === 'error'); + assert.ok(stray, 'expected a stray-close warning'); + assert.ok(unclosed, 'expected an unclosed-at-EOF error'); + assert.match(unclosed.message, /Unclosed ``/); +}); + +test('normaliseContainers: over-indented close is normalised, not stray', () => { + // Open at indent 0, close at indent 4 โ†’ close's indent (4) >= open's + // indent (0), so they match. The over-indented close is rewritten to + // the open's indent. This is the normaliser's signature behaviour: + // it lets users get the indent wrong without breaking the page. + const src = '::: callout\nbody\n :::\n'; + const r = normaliseContainers(src); + // The callout is closed cleanly with no warnings. + assert.equal(r.source, '::: callout\nbody\n:::\n'); + assert.deepEqual(r.warnings, []); +}); + +test('normaliseContainers: unclosed at EOF is auto-closed with an error', () => { + // F4 / F3 class โ€” file ends with an open container still on the stack. + const src = '::: callout\nbody\n'; + const r = normaliseContainers(src); + // Source ends with the auto-close at indent 0 (callout's indent). The + // original body line ended with `\n`, so there are two newlines + // between `body` and the inserted `:::`. + assert.match(r.source, /\n:::\s*$/); + assert.equal(r.warnings.length, 1); + assert.equal(r.warnings[0].severity, 'error'); + assert.match(r.warnings[0].message, /Unclosed ``/); +}); + +test('normaliseContainers: multiple unclosed at EOF each emit an error', () => { + const src = '::: callout\n::: card "x"\n'; + const r = normaliseContainers(src); + // Two auto-closes are appended, one per open frame. + assert.match(r.source, /\n:::\n:::\s*$/); + const errors = r.warnings.filter((w) => w.severity === 'error'); + assert.equal(errors.length, 2); + // Inner card is reported first (LIFO from the stack). + assert.match(errors[0].message, //); + assert.match(errors[1].message, //); +}); + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// 4. normaliseContainers โ€” warning surface +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +test('normaliseContainers: stray `:::` at top level produces a warning with the line number', () => { + const r = normaliseContainers(':::\n'); + assert.equal(r.warnings.length, 1); + assert.equal(r.warnings[0].line, 1); + assert.equal(r.warnings[0].severity, 'warning'); +}); + +test('normaliseContainers: sourcePath is reflected in warnings', () => { + const r = normaliseContainers(':::\n', { sourcePath: 'docs/page.md' }); + assert.equal(r.warnings[0].path, 'docs/page.md'); +}); + +test('normaliseContainers: sourcePath defaults to ``', () => { + const r = normaliseContainers(':::\n'); + assert.equal(r.warnings[0].path, ''); +}); + +test('normaliseContainers: onWarning callback fires alongside the returned array', () => { + const collected = []; + const r = normaliseContainers(':::\n', { onWarning: (w) => collected.push(w) }); + assert.equal(collected.length, 1); + assert.equal(collected[0].line, 1); + assert.equal(r.warnings.length, 1); + assert.equal(collected[0], r.warnings[0]); +}); + +test('normaliseContainers: legacy 2-arg signature `normaliseContainers(src, path)` works', () => { + // Used by the legacy shim-style plugin descriptor. + const r = normaliseContainers(':::\n', 'legacy/path.md'); + assert.equal(r.warnings[0].path, 'legacy/path.md'); +}); + +test('normaliseContainers: implicit multi-close info warning lists all closed containers', () => { + // Inner `::: card` at indent 4 is closed by the user's `:::` at indent 0. + // The outer `::: callout` is ALSO closed by the same `:::` because its + // indent (0) matches the close's indent (0). One user gesture closes two + // containers โ€” the algorithm emits an INFO warning naming both. + const src = '::: callout\n ::: card "x"\n body\n:::\n'; + const r = normaliseContainers(src); + const info = r.warnings.find((w) => w.severity === 'info'); + assert.ok(info, 'expected an info warning for implicit multi-close'); + assert.match(info.message, //); + assert.match(info.message, //); +}); + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// 5. F1โ€“F5 reported failure modes +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +test('F1: nested grids with one close per card โ†’ 3 outer closes at indent 0', () => { + // The user-reported "grids don't work" pattern. Cards are closed + // individually (one `:::` per card body) at indent 8; only the outer + // grids has its own `:::` at indent 0. The user's final `:::` closes + // the OUTER grids, and the inner grids (ร—2) are closed implicitly. + const src = [ + '::: grids', + ' ::: grid', + ' ::: card "Fast" icon:zap', + ' body', + ' :::', + ' ::: grid', + ' ::: card "Slow"', + ' body', + ' :::', + ':::' + ].join('\n'); + + const r = normaliseContainers(src); + + // Algorithm emits 3 closes at indent 0: 1 replaces the user's final + // `:::`, 2 are added to close the 2 inner grids. + const lines = r.source.split('\n'); + const outerCloses = lines.filter((l) => /^:::\s*$/.test(l)); + assert.equal(outerCloses.length, 3, `expected 3 outer closes, got ${outerCloses.length}`); + + // Top-level normaliser produces an info warning naming all 3 containers + // that the user's one `:::` closed implicitly. + const info = r.warnings.find((w) => w.severity === 'info'); + assert.ok(info, 'expected an info warning for implicit multi-close'); + assert.match(info.message, //); + assert.match(info.message, //); +}); + +test('F2: three `::: tag` lines plus an orphan `:::` โ†’ orphan removed, no stack pushes', () => { + const src = '::: tag "v0.8" color:blue\n::: tag "Experimental"\n::: tag "Live"\n:::\n'; + const r = normaliseContainers(src); + // All three tag lines preserved, orphan `:::` removed with a warning. + assert.match(r.source, /::: tag "v0.8"/); + assert.match(r.source, /::: tag "Experimental"/); + assert.match(r.source, /::: tag "Live"/); + assert.equal(r.source.split('\n').filter((l) => l === ':::').length, 0); + assert.equal(r.warnings.length, 1); + assert.equal(r.warnings[0].severity, 'warning'); +}); + +test('F3: `::: callout ... ::: card ... :::` mismatched close โ†’ auto-close callout', () => { + const src = '::: callout info "x"\nbody\n::: card "wrong close"\noops\n:::\n'; + const r = normaliseContainers(src); + // The callout opener stays; the card opener stays; the user's `:::` closes + // the card; the callout is then auto-closed at EOF with an error. + assert.match(r.source, /::: callout info "x"/); + assert.match(r.source, /::: card "wrong close"/); + const errors = r.warnings.filter((w) => w.severity === 'error'); + assert.equal(errors.length, 1); + assert.match(errors[0].message, /Unclosed ``/); +}); + +test('F4: triple `:::` after a balanced callout โ†’ two are removed, one closes callout', () => { + const src = '::: callout info "x"\nbody\n:::\n:::\n:::\n'; + const r = normaliseContainers(src); + // First `:::` closes callout (matching); second and third are stray. + const warnings = r.warnings.filter((w) => w.severity === 'warning'); + assert.equal(warnings.length, 2); + // Source retains exactly one `:::` (the callout close). + const closes = r.source.split('\n').filter((l) => /^:::\s*$/.test(l)); + assert.equal(closes.length, 1); +}); + +test('F5: 5-level nested callouts โ†’ already balanced, normalisation is a no-op', () => { + const src = [ + '::: callout info "l1"', + '::: callout tip "l2"', + '::: callout warning "l3"', + '::: callout danger "l4"', + '::: callout success "l5"', + 'deep', + ':::', + ':::', + ':::', + ':::', + ':::' + ].join('\n'); + const r = normaliseContainers(src); + assert.equal(r.source, src); + assert.deepEqual(r.warnings, []); +}); + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// 6. processContentAsync integration โ€” end-to-end HTML +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +// Build a fresh processor per test so module-level caches don't leak. +function freshProcessor() { + return createMarkdownProcessor({}, () => {}); +} + +test('integration: plain markdown renders unchanged', async () => { + const md = freshProcessor(); + const r = await processContentAsync('# Hello\n\nBody text.\n', md, {}, {}); + // headingIdPlugin adds id + class + permalink anchor; just check the + // h1 exists and contains the heading text. + assert.match(r.htmlContent, /]*>[\s\S]*?Hello[\s\S]*?<\/h1>/); + assert.match(r.htmlContent, /

    Body text\.<\/p>/); +}); + +test('integration: balanced single callout renders as `.callout` div', async () => { + const md = freshProcessor(); + const r = await processContentAsync( + '::: callout info "Title"\nbody\n:::\n', + md, + {}, + { filePath: 'test.md' } + ); + assert.match(r.htmlContent, /docmd-container callout callout-info/); + assert.match(r.htmlContent, /callout-title/); + assert.match(r.htmlContent, /

    body<\/p>/); +}); + +test('integration: F1 grids render correctly (no raw `

    ::: grids
    ` text)', async () => { + const md = freshProcessor(); + const src = [ + '::: grids', + ' ::: grid', + ' ::: card "Fast"', + ' body1', + ' :::', + ' ::: grid', + ' ::: card "Slow"', + ' body2', + ' :::', + ':::' + ].join('\n'); + const r = await processContentAsync(src, md, {}, { filePath: 'f1.md' }); + assert.match(r.htmlContent, /docmd-container grids/); + assert.match(r.htmlContent, /grid-item/); + assert.match(r.htmlContent, /card-title/); + // No leaked raw container text. + assert.doesNotMatch(r.htmlContent, /

    ::: grids
    { + const md = freshProcessor(); + const r = await processContentAsync( + '::: tag "v0.8" color:blue\n::: tag "Experimental"\n::: tag "Live"\n:::\n', + md, + {}, + { filePath: 'f2.md' } + ); + assert.match(r.htmlContent, /docmd-tag/); + // No leaked `

    :::

    ` orphan. + assert.doesNotMatch(r.htmlContent, /

    :::<\/p>/); +}); + +test('integration: F3 mismatched close renders callout + card correctly', async () => { + const md = freshProcessor(); + const r = await processContentAsync( + '::: callout info "x"\nbody\n::: card "wrong close"\noops\n:::\n', + md, + {}, + { filePath: 'f3.md' } + ); + assert.match(r.htmlContent, /callout-info/); + assert.match(r.htmlContent, /card-title/); + assert.match(r.htmlContent, /

    oops<\/p>/); +}); + +test('integration: F4 triple close renders callout only, no leaked `

    :::

    `', async () => { + const md = freshProcessor(); + const r = await processContentAsync( + '::: callout info "x"\nbody\n:::\n:::\n:::\n', + md, + {}, + { filePath: 'f4.md' } + ); + assert.match(r.htmlContent, /callout-info/); + assert.match(r.htmlContent, /

    body<\/p>/); + // No leaked `

    :::

    ` orphan paragraphs. + assert.doesNotMatch(r.htmlContent, /

    :::<\/p>/); +}); + +test('integration: F5 5-level nested callouts render five `

    ` levels', async () => { + const md = freshProcessor(); + const src = [ + '::: callout info "l1"', + '::: callout tip "l2"', + '::: callout warning "l3"', + '::: callout danger "l4"', + '::: callout success "l5"', + 'deep', + ':::', + ':::', + ':::', + ':::', + ':::' + ].join('\n'); + const r = await processContentAsync(src, md, {}, { filePath: 'f5.md' }); + for (const cls of ['callout-info', 'callout-tip', 'callout-warning', 'callout-danger', 'callout-success']) { + assert.match(r.htmlContent, new RegExp(cls), `expected ${cls} in HTML`); + } + assert.match(r.htmlContent, /

    deep<\/p>/); +}); + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// 7. Determinism โ€” identical output across replays / concurrent calls +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +test('determinism: normaliseContainers returns byte-identical output on replay', () => { + const src = [ + '::: grids', + ' ::: grid', + ' ::: card "x"', + ' body', + ' :::', + ':::' + ].join('\n'); + const a = normaliseContainers(src); + const b = normaliseContainers(src); + assert.equal(a.source, b.source); + assert.deepEqual(a.warnings, b.warnings); +}); + +test('determinism: 100 concurrent parses of the same source produce identical HTML', async () => { + const md = freshProcessor(); + const src = [ + '::: grids', + ' ::: grid', + ' ::: card "Fast"', + ' body1', + ' :::', + ' ::: grid', + ' ::: card "Slow"', + ' body2', + ' :::', + ':::' + ].join('\n'); + const N = 100; + const results = await Promise.all( + Array.from({ length: N }, () => processContentAsync(src, md, {}, { filePath: 'det.md' })) + ); + const first = results[0].htmlContent; + for (let i = 1; i < N; i++) { + assert.equal(results[i].htmlContent, first, `divergence at index ${i}`); + } +}); + +test('determinism: parser output is independent of `Date.now` / randomness', async () => { + // No Date.now / Math.random in the parser pipeline. Two parses made at + // very different times must produce identical HTML. + const md = freshProcessor(); + const src = '# Heading\n\n::: callout\nbody\n:::\n'; + const a = await processContentAsync(src, md, {}, { filePath: 'a.md' }); + await new Promise((r) => setTimeout(r, 10)); + const b = await processContentAsync(src, md, {}, { filePath: 'a.md' }); + assert.equal(a.htmlContent, b.htmlContent); +}); + +// Cross-thread determinism (Phase 2 commit 3). Run the same parse in a +// real worker_threads worker โ€” a different module instance, a different +// microtask queue โ€” and assert the HTML is byte-identical to the main +// thread's result. +test('determinism: parse in a worker_threads worker produces identical HTML', async () => { + const { Worker } = await import('node:worker_threads'); + const md = freshProcessor(); + const src = [ + '::: grids', + ' ::: grid', + ' ::: card "Fast"', + ' body1', + ' :::', + ' ::: grid', + ' ::: card "Slow"', + ' body2', + ' :::', + ':::' + ].join('\n') + '\n:::\n'; // trailing stray exercises the warning path + + // Main-thread parse. + const mainResult = await processContentAsync(src, md, {}, { filePath: 'det.md' }); + + // Worker-thread parse. Inline worker that imports the same dist build. + const workerCode = ` + import { parentPort, workerData } from 'node:worker_threads'; + import { createMarkdownProcessor, processContentAsync } from '${import.meta.dirname}/../dist/index.js'; + (async () => { + const md = createMarkdownProcessor({}, () => {}); + const r = await processContentAsync(workerData.src, md, {}, { filePath: workerData.filePath }); + parentPort.postMessage(r.htmlContent); + })().catch((e) => { parentPort.postMessage({ __err: e.message }); }); + `; + const workerResult = await new Promise((resolve, reject) => { + const w = new Worker(workerCode, { eval: true, workerData: { src, filePath: 'det.md' } }); + w.once('message', (msg) => { + if (msg && typeof msg === 'object' && msg.__err) reject(new Error(msg.__err)); + else resolve(msg); + }); + w.once('error', reject); + }); + assert.equal(workerResult, mainResult.htmlContent); +}); + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// 8. Edge cases that round out the fixture to 50+ assertions +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +test('edge case: empty `info` after `::: callout` is preserved through normalisation', () => { + // `::: callout` with no extra info โ†’ passes through, no warnings. + const src = '::: callout\nbody\n:::\n'; + const r = normaliseContainers(src); + assert.equal(r.source, src); + assert.deepEqual(r.warnings, []); +}); + +test('edge case: `::: callout` followed immediately by another container (no body)', () => { + // Two opens in a row โ€” the inner one is "body" of the outer. Both + // push to the stack; one close closes the outer. + const src = '::: callout\n::: card "x"\nbody\n:::\n'; + const r = normaliseContainers(src); + // The card is closed by the user's `:::`, the callout is auto-closed + // at EOF with an ERROR. + assert.equal(r.warnings.filter((w) => w.severity === 'error').length, 1); +}); + +test('edge case: CRLF line endings preserve `\r` on pass-through lines (documented behaviour)', () => { + // The algorithm splits on `\n` so `\r` ends up at the end of each + // pass-through line and is kept verbatim. The close regex `\s*$` + // still matches because `\r` is `\s`. The output replaces close lines + // with a freshly-emitted `:::` (no `\r`), so the trailing `\r` on the + // user's close line is dropped โ€” but everything else keeps its `\r`. + // This matches the legacy shim's behaviour. + const src = '::: callout\r\nbody\r\n:::\r\n'; + const r = normaliseContainers(src); + // Pass-through lines retain `\r\n`; only the emitted `:::` is clean. + assert.equal(r.source, '::: callout\r\nbody\r\n:::\n'); + assert.deepEqual(r.warnings, []); +}); + +test('edge case: multiple spaces between `:::` and the container name', () => { + const src = '::: callout info "Title"\nbody\n:::\n'; + const r = normaliseContainers(src); + assert.equal(r.source, src); + assert.deepEqual(r.warnings, []); +}); + +test('edge case: deeply nested self-closing tags do not corrupt the stack', () => { + // Many self-closing tag lines; no closes, no opens, no pushes. + const lines = Array.from({ length: 50 }, (_, i) => `::: tag "v${i}"`).join('\n'); + const r = normaliseContainers(lines + '\n'); + assert.equal(r.source, lines + '\n'); + assert.deepEqual(r.warnings, []); +}); + +test('edge case: pre-existing normaliser output is idempotent', () => { + // Running the normaliser twice must produce the same result as once + // (for already-balanced input). + const src = [ + '::: grids', + ' ::: grid', + ' ::: card "Fast"', + ' body1', + ' :::', + ' ::: grid', + ' ::: card "Slow"', + ' body2', + ' :::', + ':::' + ].join('\n'); + const once = normaliseContainers(src); + const twice = normaliseContainers(once.source); + assert.equal(twice.source, once.source); +}); + +test('edge case: warning `line` numbers are 1-indexed and stable across edits', () => { + // Insert a line at the top; the warning for the stray `:::` should + // shift from line 1 to line 2. + const r1 = normaliseContainers(':::\n'); + assert.equal(r1.warnings[0].line, 1); + const r2 = normaliseContainers('# heading\n:::\n'); + assert.equal(r2.warnings[0].line, 2); +}); + +test('edge case: `NormaliserWarning` shape is exactly { line, severity, path, message }', () => { + const r = normaliseContainers(':::\n', { sourcePath: 'p.md' }); + const w = r.warnings[0]; + assert.deepEqual(Object.keys(w).sort(), ['line', 'message', 'path', 'severity']); + assert.equal(typeof w.line, 'number'); + assert.equal(typeof w.severity, 'string'); + assert.equal(typeof w.path, 'string'); + assert.equal(typeof w.message, 'string'); +}); + +test('edge case: container aliases (`tip`, `warning`, `info`, `note`, `danger`, `caution`) are NOT self-closing', () => { + // The parser maps `tip`, `warning`, `danger`, `info`, `note`, `caution` + // to callout types. The normaliser must NOT treat them as self-closing + // even though the names match a generic pattern. Only the literal set + // { button, tag, embed } is self-closing. + for (const name of ['tip', 'warning', 'danger', 'info', 'note', 'caution']) { + assert.ok( + !SELF_CLOSING_CONTAINER_NAMES.has(name), + `${name} must NOT be self-closing (it's a callout alias)` + ); + } +}); + +test('edge case: debug mode logs self-close lines to stdout', () => { + // Capture console.log to verify the debug path fires. + const originalLog = console.log; + const captured = []; + console.log = (...args) => captured.push(args.join(' ')); + try { + normaliseContainers('::: tag "x"\n', { debug: true }); + } finally { + console.log = originalLog; + } + assert.equal(captured.length, 1); + assert.match(captured[0], /self-close /); +}); + +test('edge case: warnings preserve insertion order across severity', () => { + // Three different issues in one source, each in source order: + // L1 โ€” stray top-level `:::` (warning) + // L2โ€“L6 โ€” callout + card with one close at indent 0 โ†’ implicit multi-close (info) + // L8 โ€” `::: unclosed` never closed (error) + const src = [ + ':::', // 1: stray (warning) + '::: callout', // 2 + ' ::: card "x"', // 3 + ' body', // 4 + ':::', // 5: closes callout + card (info) + '', // 6 + '::: unclosed' // 7: unclosed at EOF (error) + ].join('\n') + '\n'; + const r = normaliseContainers(src); + const sevs = r.warnings.map((w) => w.severity); + // All three severities should appear, in source order. + assert.deepEqual(sevs, ['warning', 'info', 'error']); + assert.equal(r.warnings[0].line, 1); + assert.equal(r.warnings[1].line, 5); + assert.equal(r.warnings[2].line, 7); +}); + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// 8. Fenced code block tracking (F6 โ€” normaliser must not interpret +// `:::` lines that appear inside a ``` or ~~~ fence) +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +test('F6: ::: lines inside a ``` fence are not classified as opens/closes', () => { + // The docs site has pages that show `::: card ... :::` examples inside + // markdown code fences. Without fence tracking the normaliser treats the + // fenced `::: card` as a real open, pushes it on the stack, and reports + // a spurious "Unclosed " error when EOF arrives. + const src = [ + '# Buttons', // 1 + '', // 2 + '```markdown', // 3: fence open + '::: card "Setup"', // 4: literal text in fence + ' ::: button "Begin" ../../x', // 5: literal text in fence + ':::', // 6: literal text in fence + '```', // 7: fence close + '', // 8 + '::: callout', // 9: real open + 'body', // 10 + ':::' // 11: real close + ].join('\n') + '\n'; + const r = normaliseContainers(src); + // No warnings: the fenced ::: lines are not counted, the real callout + // at L9โ€“L11 is balanced. + assert.equal(r.warnings.length, 0); + // Output is unchanged โ€” the fence contents pass through verbatim. + assert.equal(r.source, src); +}); + +test('F6: ~~~ fences are also tracked', () => { + // CommonMark allows ~~~ as an alternative fence marker. + const src = [ + '~~~markdown', // 1: fence open + '::: card "x"', // 2: literal + ':::', // 3: literal + '~~~', // 4: fence close + '::: callout', // 5: real open + ':::' // 6: real close + ].join('\n') + '\n'; + const r = normaliseContainers(src); + assert.equal(r.warnings.length, 0); + assert.equal(r.source, src); +}); + +test('F6: a real ::: card outside a fence still reports the unclosed error', () => { + // Regression guard: fence tracking must not swallow real container errors + // that occur outside any fence. + const src = [ + '```markdown', // 1: fence open + '::: card "fenced"', // 2: literal + '```', // 3: fence close + '::: card "real"', // 4: real open, never closed + 'body' // 5 + ].join('\n') + '\n'; + const r = normaliseContainers(src); + const errors = r.warnings.filter((w) => w.severity === 'error'); + assert.equal(errors.length, 1); + assert.match(errors[0].message, /Unclosed.*card/); + assert.equal(errors[0].line, 4); +}); + +test('F6: mismatched fence markers (``` open vs ~~~ close) do not close the fence', () => { + // CommonMark says a fence closes only on the same marker that opened it. + const src = [ + '```markdown', // 1: ``` fence open + '::: card "x"', // 2: literal + '~~~', // 3: NOT a close (different marker) + '::: card "y"', // 4: literal (still inside fence) + '```' // 5: real close + ].join('\n') + '\n'; + const r = normaliseContainers(src); + assert.equal(r.warnings.length, 0); + assert.equal(r.source, src); +}); \ No newline at end of file diff --git a/packages/parser/tsconfig.json b/packages/parser/tsconfig.json new file mode 100644 index 0000000..9635ce4 --- /dev/null +++ b/packages/parser/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/plugins/analytics/LICENSE b/packages/plugins/analytics/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/analytics/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/analytics/README.md b/packages/plugins/analytics/README.md new file mode 100644 index 0000000..acbea7b --- /dev/null +++ b/packages/plugins/analytics/README.md @@ -0,0 +1,24 @@ +# @docmd/plugin-analytics + +Adds Google Analytics (GA4) to your docmd site - bundled with `@docmd/core`, zero installation required. + +```js +// docmd.config.js +module.exports = { + plugins: { + analytics: { + googleV4: { measurementId: 'G-XXXXXXXXXX' } + } + } +}; +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/analytics/package.json b/packages/plugins/analytics/package.json new file mode 100644 index 0000000..7668206 --- /dev/null +++ b/packages/plugins/analytics/package.json @@ -0,0 +1,64 @@ +{ + "name": "@docmd/plugin-analytics", + "version": "0.8.12", + "description": "Analytics injection plugin for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "docmd": { + "key": "analytics", + "kind": "plugin", + "displayName": "Analytics", + "tagline": "Analytics injection plugin for docmd.", + "capabilities": [ + "head", + "body" + ] + }, + "scripts": { + "build": "tsc" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@docmd/api": "workspace:*" + }, + "dependencies": { + "@docmd/utils": "workspace:*" + }, + "devDependencies": { + "@docmd/api": "workspace:*" + }, + "keywords": [ + "docmd", + "plugin", + "analytics", + "tracking", + "ga4", + "google-analytics", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/analytics/src/index.ts b/packages/plugins/analytics/src/index.ts new file mode 100644 index 0000000..6779620 --- /dev/null +++ b/packages/plugins/analytics/src/index.ts @@ -0,0 +1,130 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * @returns {Object} { headScriptsHtml, bodyScriptsHtml } + */ + +import type { PluginDescriptor } from '@docmd/api'; +import { scriptLiteral } from '@docmd/utils'; + +export const plugin: PluginDescriptor = { + name: 'analytics', + version: '0.8.12', + capabilities: ['head', 'body'] +}; + +// Phase 1.C (S-4 fix): format-validate the IDs before interpolation. +// GA4 measurementId is `G-XXXXXXXX` (uppercase letters and digits after the prefix). +// UA trackingId is `UA-XXXXXXX-Y`. +const GA4_ID_RE = /^G-[A-Z0-9]{6,12}$/; +const UA_ID_RE = /^UA-\d{6,12}-\d{1,3}$/; + +export function generateScripts(config: any) { + let headScriptsHtml = ''; + let bodyScriptsHtml = ''; + + const analytics = config.plugins?.analytics || {}; + + // Google Analytics 4 + if (analytics.googleV4?.measurementId) { + const id = analytics.googleV4.measurementId; + if (!GA4_ID_RE.test(id)) { + console.error(`[analytics] Invalid googleV4.measurementId: ${JSON.stringify(id)}. Expected format G-XXXXXXXX. Analytics script skipped.`); + } else { + const idLiteral = scriptLiteral(id); + headScriptsHtml += ` + + + \n`; + } + } + + // Legacy UA + if (analytics.googleUA?.trackingId) { + const id = analytics.googleUA.trackingId; + if (!UA_ID_RE.test(id)) { + console.error(`[analytics] Invalid googleUA.trackingId: ${JSON.stringify(id)}. Expected format UA-XXXXXXX-Y. Analytics script skipped.`); + } else { + const idLiteral = scriptLiteral(id); + headScriptsHtml += ` + + + \n`; + } + } + + // Auto-event Tagging (V2) + if (analytics.autoEvents !== false) { + const trackSearch = analytics.trackSearch !== false; + bodyScriptsHtml += ` + \n`; + } + + return { headScriptsHtml, bodyScriptsHtml }; +} \ No newline at end of file diff --git a/packages/plugins/analytics/tsconfig.json b/packages/plugins/analytics/tsconfig.json new file mode 100644 index 0000000..7befc89 --- /dev/null +++ b/packages/plugins/analytics/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/plugins/git/LICENSE b/packages/plugins/git/LICENSE new file mode 100644 index 0000000..f4432ba --- /dev/null +++ b/packages/plugins/git/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/plugins/git/README.md b/packages/plugins/git/README.md new file mode 100644 index 0000000..9fb9e52 --- /dev/null +++ b/packages/plugins/git/README.md @@ -0,0 +1,17 @@ +# @docmd/plugin-git + +Adds Git-based metadata to your docmd site: last-updated timestamps, contributor history, and edit links derived directly from your repository. Core plugin, already included in the core. + +```bash +docmd add git +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/git/build.js b/packages/plugins/git/build.js new file mode 100644 index 0000000..cec588e --- /dev/null +++ b/packages/plugins/git/build.js @@ -0,0 +1,39 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import fs from 'fs'; +import path from 'path'; +import { fileURLToPath } from 'url'; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const srcClientDir = path.resolve(__dirname, 'src', 'client'); +const distDir = path.resolve(__dirname, 'dist', 'client'); + +// Ensure dist/client directory exists +if (!fs.existsSync(distDir)) { + fs.mkdirSync(distDir, { recursive: true }); +} + +// Copy client files +const files = ['git-widget.js', 'git-widget.css']; +for (const file of files) { + const src = path.join(srcClientDir, file); + const dest = path.join(distDir, file); + if (fs.existsSync(src)) { + fs.copyFileSync(src, dest); + console.log(` ${file} โ†’ dist/client/`); + } +} + +console.log('โœ“ Client assets built'); \ No newline at end of file diff --git a/packages/plugins/git/i18n/de.json b/packages/plugins/git/i18n/de.json new file mode 100644 index 0000000..b404589 --- /dev/null +++ b/packages/plugins/git/i18n/de.json @@ -0,0 +1,13 @@ +{ + "lastUpdated": "Zuletzt aktualisiert", + "recentCommits": "Letzte Commits", + "viewCommitHistory": "Commit-Verlauf anzeigen", + "editOnGitHub": "Auf GitHub bearbeiten", + "editOnGitLab": "Auf GitLab bearbeiten", + "editOnBitbucket": "Auf Bitbucket bearbeiten", + "editThisPage": "Seite bearbeiten", + "justNow": "gerade eben", + "minutesAgo": "vor {n} Min.", + "hoursAgo": "vor {n} Std.", + "daysAgo": "vor {n} T." +} diff --git a/packages/plugins/git/i18n/en.json b/packages/plugins/git/i18n/en.json new file mode 100644 index 0000000..101bc20 --- /dev/null +++ b/packages/plugins/git/i18n/en.json @@ -0,0 +1,13 @@ +{ + "lastUpdated": "Last updated", + "recentCommits": "Recent commits", + "viewCommitHistory": "View commit history", + "editOnGitHub": "Edit on GitHub", + "editOnGitLab": "Edit on GitLab", + "editOnBitbucket": "Edit on Bitbucket", + "editThisPage": "Edit this page", + "justNow": "just now", + "minutesAgo": "{n}m ago", + "hoursAgo": "{n}h ago", + "daysAgo": "{n}d ago" +} \ No newline at end of file diff --git a/packages/plugins/git/i18n/ko.json b/packages/plugins/git/i18n/ko.json new file mode 100644 index 0000000..08a6c84 --- /dev/null +++ b/packages/plugins/git/i18n/ko.json @@ -0,0 +1,13 @@ +{ + "lastUpdated": "๋งˆ์ง€๋ง‰ ์—…๋ฐ์ดํŠธ", + "recentCommits": "์ตœ๊ทผ ์ปค๋ฐ‹", + "viewCommitHistory": "์ปค๋ฐ‹ ๊ธฐ๋ก ๋ณด๊ธฐ", + "editOnGitHub": "GitHub์—์„œ ํŽธ์ง‘", + "editOnGitLab": "GitLab์—์„œ ํŽธ์ง‘", + "editOnBitbucket": "Bitbucket์—์„œ ํŽธ์ง‘", + "editThisPage": "์ด ํŽ˜์ด์ง€ ํŽธ์ง‘", + "justNow": "๋ฐฉ๊ธˆ ์ „", + "minutesAgo": "{n}๋ถ„ ์ „", + "hoursAgo": "{n}์‹œ๊ฐ„ ์ „", + "daysAgo": "{n}์ผ ์ „" +} diff --git a/packages/plugins/git/i18n/zh.json b/packages/plugins/git/i18n/zh.json new file mode 100644 index 0000000..b7d0c2e --- /dev/null +++ b/packages/plugins/git/i18n/zh.json @@ -0,0 +1,13 @@ +{ + "lastUpdated": "ๆœ€ๅŽๆ›ดๆ–ฐ", + "recentCommits": "ๆœ€่ฟ‘ๆไบค", + "viewCommitHistory": "ๆŸฅ็œ‹ๆไบคๅŽ†ๅฒ", + "editOnGitHub": "ๅœจ GitHub ไธŠ็ผ–่พ‘", + "editOnGitLab": "ๅœจ GitLab ไธŠ็ผ–่พ‘", + "editOnBitbucket": "ๅœจ Bitbucket ไธŠ็ผ–่พ‘", + "editThisPage": "็ผ–่พ‘ๆญค้กต", + "justNow": "ๅˆšๅˆš", + "minutesAgo": "{n}ๅˆ†้’Ÿๅ‰", + "hoursAgo": "{n}ๅฐๆ—ถๅ‰", + "daysAgo": "{n}ๅคฉๅ‰" +} diff --git a/packages/plugins/git/package.json b/packages/plugins/git/package.json new file mode 100644 index 0000000..aae27e4 --- /dev/null +++ b/packages/plugins/git/package.json @@ -0,0 +1,76 @@ +{ + "name": "@docmd/plugin-git", + "version": "0.8.12", + "description": "Git integration plugin for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } + }, + "docmd": { + "key": "git", + "kind": "plugin", + "displayName": "Git", + "tagline": "Git integration with last-updated timestamps and commit history.", + "capabilities": [ + "init", + "build", + "body", + "assets", + "post-build", + "translations" + ] + }, + "scripts": { + "build": "tsc && node build.js" + }, + "files": [ + "dist", + "i18n" + ], + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@docmd/api": "workspace:*" + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "plugin", + "git", + "github", + "gitlab", + "last-updated", + "contributors", + "edit-link", + "markdown", + "documentation", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/git/src/client/git-widget.css b/packages/plugins/git/src/client/git-widget.css new file mode 100644 index 0000000..384d50c --- /dev/null +++ b/packages/plugins/git/src/client/git-widget.css @@ -0,0 +1,169 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/* โ”€โ”€ Wrapper โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ +.git-last-updated { + display: inline-flex; + align-items: center; + gap: 0.375rem; + color: var(--text-light); + font-size: 0.875rem; + position: relative; + cursor: default; +} + +.git-last-updated.has-history { cursor: default; } +.git-last-updated.has-history:hover, +.git-last-updated.has-history:focus-within { color: var(--link-color); } + +/* โ”€โ”€ Icon / Label / Time โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ +.git-icon, .git-label, .git-time { pointer-events: none; } +.git-icon { width: 1em; height: 1em; flex-shrink: 0; } +.git-label { opacity: 0.8; } +.git-time { font-weight: 500; } + +/* โ”€โ”€ Spacer โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ +.git-spacer { flex: 1; } + +/* โ”€โ”€ Tooltip โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ +.git-commit-tooltip { + position: absolute; + bottom: calc(100% + 10px); + left: 0; + min-width: 280px; + max-width: 360px; + background: var(--bg-color); + border: 1px solid var(--border-color); + border-radius: var(--radius-lg, 0.5rem); + box-shadow: var(--shadow-sm); + padding: 0.75rem; + z-index: 100; + opacity: 0; + visibility: hidden; + transform: translateY(4px); + transition: opacity 0.15s ease, transform 0.15s ease, visibility 0s linear 0.15s; + pointer-events: none; +} + +/* Bridge fills gap between tooltip and text - no visual appearance */ +.git-commit-tooltip::before { + content: ''; + position: absolute; + top: 100%; + left: 0; + right: 0; + height: 14px; + background: transparent; + pointer-events: auto; +} + +/* Show via CSS :hover */ +.git-last-updated.has-history:hover .git-commit-tooltip, +.git-last-updated.has-history:focus-within .git-commit-tooltip, +.git-commit-tooltip.visible { + opacity: 1; + visibility: visible; + transform: translateY(0); + transition: opacity 0.15s ease, transform 0.15s ease, visibility 0s linear 0s; + pointer-events: auto; +} + +/* Arrow points downward */ +.git-commit-tooltip::after { + content: ''; + position: absolute; + top: 100%; + left: 1.5rem; + border: 10px solid transparent; + border-top-color: var(--border-color); + pointer-events: none; +} + +/* โ”€โ”€ Tooltip Header โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ +.git-tooltip-title { + font-size: 0.75rem; + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.025em; + color: var(--text-light); + margin-bottom: 0.5rem; + /* padding-bottom: 0.5rem; */ + /* border-bottom: 1px solid var(--border-color); */ +} + +/* โ”€โ”€ Commit List โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ +.git-commit-list { list-style: none; margin: 0; padding: 0; } + +.git-commit-item { + display: flex; + align-items: flex-start; + gap: 0.625rem; + padding: 0.5rem 0; +} + +.git-commit-avatar { + width: 1.75rem; + height: 1.75rem; + border-radius: 50%; + background: var(--accent-color, #3b82f6); + color: #fff; + font-size: 0.625rem; + font-weight: 600; + display: flex; + align-items: center; + justify-content: center; + flex-shrink: 0; + overflow: hidden; +} +.git-commit-avatar img { + width: 100%; + height: 100%; + object-fit: cover; +} + +.git-commit-details { flex: 1; min-width: 0; } + +.git-commit-message { + font-size: 0.8125rem; + color: var(--text-color); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + line-height: 1.4; +} + +.git-commit-meta { + display: flex; + align-items: baseline; + gap: 0.5rem; + font-size: 0.7rem; + color: var(--text-light); + margin-top: 0.125rem; +} + +.git-commit-author { font-weight: 500; } +.git-commit-date {font-size: .8em;color: var(--sidebar-text);} + +/* โ”€โ”€ Dark mode โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ +[data-theme="dark"] .git-commit-tooltip { box-shadow: var(--shadow-lg); } + +/* โ”€โ”€ Responsive โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ +@media (max-width: 640px) { + .git-commit-tooltip { + min-width: 240px; + max-width: calc(100vw - 2rem); + left: -0.5rem; + } + .git-label { display: none; } +} \ No newline at end of file diff --git a/packages/plugins/git/src/client/git-widget.js b/packages/plugins/git/src/client/git-widget.js new file mode 100644 index 0000000..7c6bb0c --- /dev/null +++ b/packages/plugins/git/src/client/git-widget.js @@ -0,0 +1,97 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +(function () { + const i18n = window.__git_i18n || {}; + + /** + * Format a Unix ms timestamp into a human-readable relative or absolute string. + */ + function formatTime(ts) { + const config = window.__git_config || {}; + const format = config.dateFormat || 'relative'; + const dateObj = new Date(ts); + + if (format === 'iso') { + return dateObj.toISOString(); + } + + if (format === 'locale-aware') { + return dateObj.toLocaleString(document.documentElement.lang || 'en'); + } + + const diff = Date.now() - ts; + const s = Math.floor(diff / 1000); + const m = Math.floor(s / 60); + const h = Math.floor(m / 60); + const d = Math.floor(h / 24); + + if (d < 1) { + if (h >= 1) return (i18n.hoursAgo || '{n}h ago').replace('{n}', h); + if (m >= 1) return (i18n.minutesAgo || '{n}m ago').replace('{n}', m); + return i18n.justNow || 'just now'; + } + if (d < 7) return (i18n.daysAgo || '{n}d ago').replace('{n}', d); + + return dateObj.toLocaleDateString( + document.documentElement.lang || 'en', + { year: 'numeric', month: 'short', day: 'numeric' } + ); + } + + /** + * Hydrate all git [data-timestamp] elements with formatted relative time. + * Scoped to .git-last-updated and .git-commit-list to avoid collisions. + */ + function hydrateTimes() { + document.querySelectorAll('.git-last-updated [data-timestamp], .git-commit-list [data-timestamp]').forEach(function (el) { + const ts = parseInt(el.getAttribute('data-timestamp'), 10); + if (!ts || isNaN(ts)) return; + el.textContent = formatTime(ts); + }); + } + + /** + * Wire up keyboard accessibility on .git-last-updated elements. + * Tooltip visibility is handled by CSS :hover/:focus-within. + * JS only adds tabindex and aria attributes for keyboard users. + */ + function wireTooltips() { + document.querySelectorAll('.git-last-updated').forEach(function (wrapper) { + const tooltip = wrapper.querySelector('.git-commit-tooltip'); + if (!tooltip) return; + + wrapper.classList.add('has-history'); + wrapper.setAttribute('tabindex', '0'); + wrapper.setAttribute('role', 'button'); + wrapper.setAttribute('aria-label', i18n.viewCommitHistory || 'View commit history'); + }); + } + + function init() { + hydrateTimes(); + wireTooltips(); + } + + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', init); + } else { + init(); + } + + // Re-run after SPA navigation โ€” the SPA router swaps .page-footer-actions + // innerHTML on every page change, so we must re-hydrate timestamps and + // re-wire tooltip accessibility on the freshly injected elements. + document.addEventListener('docmd:page-mounted', init); +})(); \ No newline at end of file diff --git a/packages/plugins/git/src/index.ts b/packages/plugins/git/src/index.ts new file mode 100644 index 0000000..0e410b8 --- /dev/null +++ b/packages/plugins/git/src/index.ts @@ -0,0 +1,596 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import fs from 'fs'; +import os from 'os'; +import { execFile } from 'child_process'; +import { promisify } from 'util'; +import crypto from 'crypto'; + +const execFileAsync = promisify(execFile); +import { fileURLToPath } from 'url'; + +import type { PluginDescriptor, PageContext, Engine } from '@docmd/api'; + +// --------------------------------------------------------------------------- +// Engine Integration +// --------------------------------------------------------------------------- + +let _engine: Engine | null = null; +let _engineLoadAttempted = false; +let _configuredEngine: string = 'rust'; // default: prefer Rust, respected from config + +/** + * Try to load an engine based on config.engine key. + * Falls back to JS engine, then to execFile if neither is available. + */ +async function getEngine(): Promise { + if (_engineLoadAttempted) return _engine; + _engineLoadAttempted = true; + + try { + const { loadEngine } = await import('@docmd/api'); + if (_configuredEngine === 'js') { + _engine = await loadEngine('js'); + } else { + // Default: try Rust, fall back to JS + _engine = await loadEngine('rust').catch(() => loadEngine('js')); + } + return _engine; + } catch { + // No engine available โ€” will use execFile fallback + return null; + } +} + +/** + * Get git log for multiple files using the engine (batch operation). + * Returns a Map from file path to commits array. + */ +async function getGitLogViaEngine( + filePaths: string[], + maxCommits: number +): Promise | null> { + const engine = await getEngine(); + if (!engine) return null; + + try { + const result = await engine.run>({ + type: 'git:log', + payload: { filePaths, maxCommits } + }); + + if (!result.success) return null; + return new Map(Object.entries(result.data || {})); + } catch { + return null; + } +} + +// --------------------------------------------------------------------------- +// Original Implementation (fallback when engine is not available) +// --------------------------------------------------------------------------- + +const gitRootCache = new Map(); +const gitCache = new Map(); + +// Persistent disk cache for git histories +let _diskCache: Record | null = null; +let _diskCachePath: string | null = null; +let _cacheDirty = false; + +// Per-build deduplication: git indexing only needs to run once per full build. +// The in-memory gitCache stores results for all subsequent locale/version passes. +let _gitBuildId = ''; +let _gitIndexingDone = false; + +/** + * Resolve the cache directory anchored to the git root (not process.cwd()). + * This fixes multi-project builds where process.chdir() shifts per-project, + * which caused the cache to land in unpredictable subdirectories. + */ +let _configuredTmpDir: string | null = null; + +/** + * Resolve the cache directory base path. + * If config.tmp is configured, stores temporary files inside that specified path. + * Otherwise, moves them to the device's actual OS temporary folder nested by project hash + * so multiple documentations on the same device remain perfectly isolated. + */ +function resolveCacheDir(): string { + if (_configuredTmpDir) { + return path.join(path.resolve(process.cwd(), _configuredTmpDir), 'cache'); + } + + // Walk up from cwd to find the project git root, ensuring stable path resolution + let dir = process.cwd(); + for (let i = 0; i < 10; i++) { + if (fs.existsSync(path.join(dir, '.git'))) { + break; + } + const parent = path.dirname(dir); + if (parent === dir) break; + dir = parent; + } + + // Derive a consistent project identifier (remote origin URL -> directory inode -> absolute path) + // Ensures cache directory resolution remains stable across local folder moves/renames. + let identifier = dir; + try { + const gitConfigPath = path.join(dir, '.git', 'config'); + let urlFound = false; + if (fs.existsSync(gitConfigPath)) { + const content = fs.readFileSync(gitConfigPath, 'utf8'); + const match = content.match(/url\s*=\s*([^\r\n]+)/); + if (match && match[1]) { + identifier = match[1].trim(); + urlFound = true; + } + } + if (!urlFound) { + const stat = fs.statSync(dir); + if (stat && stat.ino) { + identifier = `ino:${stat.ino}`; + } + } + } catch { + try { + const stat = fs.statSync(dir); + if (stat && stat.ino) identifier = `ino:${stat.ino}`; + } catch { /* keep absolute path fallback */ } + } + + // Generate a unique hash for this stable project identifier + const hash = crypto.createHash('md5').update(identifier).digest('hex').slice(0, 12); + const baseSlug = path.basename(dir).replace(/[^a-zA-Z0-9-_]/g, ''); + return path.join(os.tmpdir(), `docmd-${baseSlug}-${hash}`, 'cache'); +} + +function initDiskCache() { + if (_diskCache !== null) return; + const cacheDir = resolveCacheDir(); + _diskCachePath = path.join(cacheDir, 'git-history.json'); + try { + if (fs.existsSync(_diskCachePath)) { + _diskCache = JSON.parse(fs.readFileSync(_diskCachePath, 'utf8')); + } else { + _diskCache = {}; + } + } catch { + _diskCache = {}; + } +} + +function saveDiskCache() { + if (!_cacheDirty || !_diskCachePath || !_diskCache) return; + try { + // Prune entries for files that no longer exist on disk + const keys = Object.keys(_diskCache); + for (const key of keys) { + try { + if (!fs.existsSync(key)) delete _diskCache[key]; + } catch { /* ignore stat errors */ } + } + + const cacheDir = path.dirname(_diskCachePath); + if (!fs.existsSync(cacheDir)) fs.mkdirSync(cacheDir, { recursive: true }); + fs.writeFileSync(_diskCachePath, JSON.stringify(_diskCache), 'utf8'); + _cacheDirty = false; + } catch { /* ignore */ } +} + + +async function resolveGitRoot(dir: string): Promise { + if (gitRootCache.has(dir)) return gitRootCache.get(dir)!; + try { + const realDir = fs.realpathSync(dir); + const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], { + cwd: realDir + }); + const result = stdout.trim(); + gitRootCache.set(dir, result); + return result; + } catch { + gitRootCache.set(dir, null); + return null; + } +} + +async function getGitFileInfo(filePath: string, maxCommits: number = 6): Promise { + if (gitCache.has(filePath)) return gitCache.get(filePath)!; + + initDiskCache(); + + let fileStat; + try { + fileStat = fs.statSync(filePath); + } catch { + return null; + } + + // Check disk cache + if (_diskCache && _diskCache[filePath] && _diskCache[filePath].mtimeMs === fileStat.mtimeMs) { + const cachedInfo = _diskCache[filePath].info; + gitCache.set(filePath, cachedInfo); + return cachedInfo; + } + + const fileDir = path.dirname(filePath); + const gitRoot = await resolveGitRoot(fileDir); + if (!gitRoot) return null; + + const normalizedRoot = fs.realpathSync(gitRoot); + const normalizedFile = fs.realpathSync(filePath); + + const relPath = path.relative(normalizedRoot, normalizedFile).replace(/\\/g, '/'); + + if (!relPath || relPath.startsWith('..') || path.isAbsolute(relPath)) return null; + + try { + const { stdout } = await execFileAsync('git', [ + 'log', + '--follow', + '-n', maxCommits.toString(), + '--format=%H|%h|%an|%ae|%at|%s', + '--', + relPath + ], { + cwd: normalizedRoot + }); + + const logOutput = stdout.trim(); + if (!logOutput) return null; + + const commits: GitCommit[] = logOutput.split('\n').filter(Boolean).map((line: string) => { + const [hash, shortHash, author, email, timestamp, ...messageParts] = line.split('|'); + const ts = parseInt(timestamp, 10) * 1000; + const hashEmail = crypto.createHash('md5').update(email.trim().toLowerCase()).digest('hex'); + return { + hash, + shortHash, + author, + email, + date: new Date(ts).toISOString(), + timestamp: ts, + message: messageParts.join('|'), + avatarUrl: `https://www.gravatar.com/avatar/${hashEmail}?d=mp&s=64` + }; + }); + + if (commits.length === 0) return null; + + const info: GitFileInfo = { + lastUpdated: commits[0]?.date || '', + lastUpdatedTimestamp: commits[0]?.timestamp || 0, + commits + }; + + gitCache.set(filePath, info); + if (_diskCache) { + _diskCache[filePath] = { mtimeMs: fileStat.mtimeMs, info }; + _cacheDirty = true; + } + return info; + } catch { + return null; + } +} + +export const plugin: PluginDescriptor = { + name: 'git', + version: '0.8.12', + capabilities: ['build', 'body', 'assets', 'translations', 'init', 'post-build'] +}; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const i18nDir = path.resolve(__dirname, '..', 'i18n'); + +export interface GitCommit { + hash: string; + shortHash: string; + author: string; + email: string; + date: string; + timestamp: number; + message: string; + avatarUrl: string; +} + +export interface GitFileInfo { + lastUpdated: string; + lastUpdatedTimestamp: number; + commits: GitCommit[]; +} + +/** + * Format a timestamp for display. + * Uses relative time for recent updates, absolute for older ones. + */ +function formatLastUpdated(timestamp: number, locale: string = 'en'): string { + const now = Date.now(); + const diff = now - timestamp; + const seconds = Math.floor(diff / 1000); + const minutes = Math.floor(seconds / 60); + const hours = Math.floor(minutes / 60); + const days = Math.floor(hours / 24); + + // For very recent updates, show relative time + if (days < 1) { + if (hours >= 1) { + return `${hours}h ago`; + } + if (minutes >= 1) { + return `${minutes}m ago`; + } + return 'just now'; + } + + if (days < 7) { + return `${days}d ago`; + } + + // For older updates, show date + const date = new Date(timestamp); + return date.toLocaleDateString(locale, { + year: 'numeric', + month: 'short', + day: 'numeric' + }); +} + +/** + * Load translation strings for a given locale. + */ +function loadPluginStrings(localeId: string): Record { + try { + const localePath = path.join(i18nDir, `${localeId}.json`); + if (fs.existsSync(localePath)) { + return JSON.parse(fs.readFileSync(localePath, 'utf8')); + } + } catch { /* fallback below */ } + try { + const enPath = path.join(i18nDir, 'en.json'); + if (fs.existsSync(enPath)) { + return JSON.parse(fs.readFileSync(enPath, 'utf8')); + } + } catch { /* silent */ } + return {}; +} + +/** + * Plugin translations hook. + */ +export function translations(localeId: string): Record { + return loadPluginStrings(localeId || 'en'); +} + +let pluginOptions: any = {}; + +export function onConfigResolved(config: any): void { + gitCache.clear(); + gitRootCache.clear(); + _gitIndexingDone = false; + _engineLoadAttempted = false; // Reset engine state for fresh builds + _engine = null; + _diskCache = null; // Reset disk cache so it re-reads from the correct path + _diskCachePath = null; + _cacheDirty = false; + _configuredEngine = config.engine || 'rust'; // Respect the config.engine key + _configuredTmpDir = config.tmp || null; // Respect the config.tmp custom path + pluginOptions = config.plugins?.git || {}; +} + +/** + * onBeforeParse: stub for future use (per-page processing). + */ +export function onBeforeParse(_ctx: any): void { + // Logic removed (moved to onConfigResolved for better performance) +} + +export async function onBeforeBuild(ctx: any): Promise { + const { pages, tui, options } = ctx; + if (!pages || pages.length === 0) return; + + // Deduplicate per build: only the FIRST locale/version pass runs git log. + // Subsequent passes pull from the in-memory gitCache, which is already warm. + const buildId = (options as any)?._buildId || ''; + if (buildId !== _gitBuildId) { + _gitBuildId = buildId; + _gitIndexingDone = false; + } + + const commitHistory = pluginOptions?.commitHistory !== false; + const maxCommits = commitHistory ? (pluginOptions?.maxCommits || 5) : 1; + const showTui = tui && !options?.quiet && !_gitIndexingDone; + + if (_gitIndexingDone) { + // Still populate frontmatter from in-memory cache for this locale's pages + for (const page of pages) { + if (page?.sourcePath && page.frontmatter) { + const cached = gitCache.get(page.sourcePath); + if (cached) { + if (!commitHistory) cached.commits = []; + page.frontmatter._git = cached; + } + } + } + return; + } + + _gitIndexingDone = true; + const total = pages.length; + + if (showTui) tui.step(`Syncing git metadata`, 'WAIT'); + + // Collect all source paths that need git info. + // Pre-warm in-memory cache from disk first so the engine is only called + // for uncached or modified files (warm builds benefit from persistence). + const pathsToFetch: string[] = []; + const pagesByPath = new Map(); + + initDiskCache(); + for (const page of pages) { + const sourcePath = page?.sourcePath; + if (sourcePath && page.frontmatter && !gitCache.has(sourcePath)) { + let fileStat: any; + try { fileStat = fs.statSync(sourcePath); } catch { /* skip */ } + // Hit disk cache if file hasn't changed since last build + if (fileStat && _diskCache && _diskCache[sourcePath] && _diskCache[sourcePath].mtimeMs === fileStat.mtimeMs) { + gitCache.set(sourcePath, _diskCache[sourcePath].info); + if (page.frontmatter) page.frontmatter._git = _diskCache[sourcePath].info; + } else { + pathsToFetch.push(sourcePath); + if (!pagesByPath.has(sourcePath)) pagesByPath.set(sourcePath, []); + pagesByPath.get(sourcePath)!.push(page); + } + } + } + + // Try to use engine for batch processing (much faster with Rust) + const engineResult = await getGitLogViaEngine(pathsToFetch, maxCommits); + + + if (engineResult && engineResult.size > 0) { + // Engine succeeded โ€” process and persist results + for (const [filePath, commits] of engineResult) { + + if (commits && commits.length > 0) { + let fileStat: any; + try { fileStat = fs.statSync(filePath); } catch { /* skip */ } + + const info: GitFileInfo = { + lastUpdated: new Date(commits[0].timestamp).toISOString(), + lastUpdatedTimestamp: commits[0].timestamp, + commits: commits.map((c: any) => { + const hashEmail = crypto.createHash('md5').update((c.email || '').trim().toLowerCase()).digest('hex'); + return { + hash: c.hash, + shortHash: c.shortHash, + author: c.author, + email: c.email, + date: new Date(c.timestamp).toISOString(), + timestamp: c.timestamp, + message: c.message, + avatarUrl: `https://www.gravatar.com/avatar/${hashEmail}?d=mp&s=64` + }; + }) + }; + + if (!commitHistory) info.commits = []; + gitCache.set(filePath, info); + + // Persist to disk cache so subsequent builds are fast (warm start) + if (_diskCache && fileStat) { + _diskCache[filePath] = { mtimeMs: fileStat.mtimeMs, info }; + _cacheDirty = true; + } + + // Update all pages with this source path + const pagesForPath = pagesByPath.get(filePath) || []; + for (const page of pagesForPath) { + if (page.frontmatter) page.frontmatter._git = info; + } + } + } + + if (showTui) tui.step(`Syncing git metadata`, 'DONE'); + } else { + // Fallback to original execFile-based implementation + let processed = 0; + const CONCURRENCY = 10; + + for (let i = 0; i < total; i += CONCURRENCY) { + const batch = pages.slice(i, i + CONCURRENCY); + await Promise.all(batch.map(async (page: any) => { + const sourcePath = page?.sourcePath; + if (sourcePath && page.frontmatter) { + const gitInfo = await getGitFileInfo(sourcePath, maxCommits); + if (gitInfo) { + if (!commitHistory) gitInfo.commits = []; + page.frontmatter._git = gitInfo; + } + } + })); + processed += batch.length; + if (showTui) tui.step(`Syncing git metadata ${processed}/${total}`, 'WAIT'); + } + + if (showTui) tui.step(`Syncing git metadata`, 'DONE'); + } + + // Also populate pages that were already in cache + for (const page of pages) { + if (page?.sourcePath && page.frontmatter && !page.frontmatter._git) { + const cached = gitCache.get(page.sourcePath); + if (cached) { + if (!commitHistory) cached.commits = []; + page.frontmatter._git = cached; + } + } + } +} + +export function onPostBuild(): void { + saveDiskCache(); +} + +/** + * Generate scripts to inject git i18n strings for the client widget. + */ +export function generateScripts(config: any, options?: any): { headScriptsHtml: string; bodyScriptsHtml: string } { + const gitConfig = { + repo: options?.repo || config.editLink?.baseUrl || null, + branch: options?.branch || 'main', + editLink: options?.editLink !== false && !!(options?.repo || config.editLink?.baseUrl), + lastUpdated: options?.lastUpdated !== false, + commitHistory: options?.commitHistory !== false, + maxCommits: options?.maxCommits || 5, + dateFormat: options?.dateFormat || 'relative' + }; + + const localeId = config._activeLocale?.id || 'en'; + const i18nStrings = JSON.stringify(loadPluginStrings(localeId)); + + return { + headScriptsHtml: '', + bodyScriptsHtml: `` + }; +} + +/** + * Provide client-side assets. + * Always returns assets - client-side JS handles graceful degradation. + */ +export function getAssets(_options?: any): any[] { + // Always include assets - client-side JS handles visibility based on git status + const distDir = path.resolve(__dirname, '..', 'dist', 'client'); + return [ + { + src: path.join(distDir, 'git-widget.js'), + dest: 'assets/js/docmd-git.js', + type: 'js', + location: 'body', + attributes: { type: 'module' } + }, + { + src: path.join(distDir, 'git-widget.css'), + dest: 'assets/css/docmd-git.css', + type: 'css', + location: 'head' + } + ]; +} + +export { getGitFileInfo, formatLastUpdated }; \ No newline at end of file diff --git a/packages/plugins/git/tsconfig.json b/packages/plugins/git/tsconfig.json new file mode 100644 index 0000000..51f4bfc --- /dev/null +++ b/packages/plugins/git/tsconfig.json @@ -0,0 +1,21 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ESNext", + "moduleResolution": "bundler", + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "outDir": "dist", + "rootDir": "src", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "resolveJsonModule": true, + "isolatedModules": true, + "types": ["node"] + }, + "include": ["src/**/*.ts"], + "exclude": ["node_modules", "dist"] +} diff --git a/packages/plugins/installer/LICENSE b/packages/plugins/installer/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/installer/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/installer/README.md b/packages/plugins/installer/README.md new file mode 100644 index 0000000..a457679 --- /dev/null +++ b/packages/plugins/installer/README.md @@ -0,0 +1,20 @@ +# @docmd/plugin-installer + +The engine behind `docmd add` and `docmd remove` - downloads plugins, resolves dependencies, and injects configuration into your `docmd.config.js` automatically. + +Bundled with `@docmd/core`. You do not need to install or configure this package directly. + +```bash +docmd add search +docmd remove search +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/installer/package.json b/packages/plugins/installer/package.json new file mode 100644 index 0000000..d7bb6b3 --- /dev/null +++ b/packages/plugins/installer/package.json @@ -0,0 +1,52 @@ +{ + "name": "@docmd/plugin-installer", + "version": "0.8.12", + "description": "Installer utility to add and remove plugins for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "scripts": { + "build": "tsc" + }, + "files": [ + "dist", + "registry" + ], + "engines": { + "node": ">=18" + }, + "dependencies": { + "@docmd/api": "workspace:*" + }, + "devDependencies": { + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "plugin", + "installer", + "cli", + "add", + "remove", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/installer/registry/plugins.json b/packages/plugins/installer/registry/plugins.json new file mode 100644 index 0000000..2cd945a --- /dev/null +++ b/packages/plugins/installer/registry/plugins.json @@ -0,0 +1,81 @@ +{ + "analytics": { + "package": "@docmd/plugin-analytics", + "description": "Analytics injection plugin for docmd", + "configKey": "analytics", + "defaultConfig": "{}" + }, + "git": { + "package": "@docmd/plugin-git", + "description": "Git integration with last-updated timestamps and commit history", + "configKey": "git", + "defaultConfig": "{}" + }, + "search": { + "package": "@docmd/plugin-search", + "description": "Local search implementation for docmd", + "configKey": "search", + "defaultConfig": "{}" + }, + "seo": { + "package": "@docmd/plugin-seo", + "description": "SEO meta tag generator for docmd", + "configKey": "seo", + "defaultConfig": "{}" + }, + "sitemap": { + "package": "@docmd/plugin-sitemap", + "description": "Sitemap generator for docmd", + "configKey": "sitemap", + "defaultConfig": "{}" + }, + "mermaid": { + "package": "@docmd/plugin-mermaid", + "description": "Mermaid.js diagram support for docmd", + "configKey": "mermaid", + "defaultConfig": "{}" + }, + "openapi": { + "package": "@docmd/plugin-openapi", + "description": "OpenAPI / Swagger spec rendering for docmd", + "configKey": "openapi", + "defaultConfig": "{}" + }, + "llms": { + "package": "@docmd/plugin-llms", + "description": "LLM integration plugin for docmd", + "configKey": "llms", + "defaultConfig": "{}" + }, + "okf": { + "package": "@docmd/plugin-okf", + "description": "Open Knowledge Format (OKF) bundle generator for AI-agent consumption", + "configKey": "okf", + "defaultConfig": "{}" + }, + "pwa": { + "package": "@docmd/plugin-pwa", + "description": "Progressive Web App support for docmd", + "configKey": "pwa", + "defaultConfig": "{}" + }, + "threads": { + "package": "@docmd/plugin-threads", + "description": "Inline discussion threads for docmd", + "configKey": "threads", + "defaultConfig": "{}" + }, + "math": { + "package": "@docmd/plugin-math", + "description": "Math rendering support for docmd using KaTeX", + "configKey": "math", + "defaultConfig": "{}" + }, + "summer": { + "package": "@docmd/template-summer", + "description": "Summer template โ€” bright, hopeful, summer-feel layout with top search bar and halo accents", + "kind": "template", + "configKey": "summer", + "templateName": "summer" + } +} \ No newline at end of file diff --git a/packages/plugins/installer/src/config-editor.ts b/packages/plugins/installer/src/config-editor.ts new file mode 100644 index 0000000..2e4150d --- /dev/null +++ b/packages/plugins/installer/src/config-editor.ts @@ -0,0 +1,382 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/plugin-installer + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * Config editor + * ============= + * + * Phase 3 PR 3.B (F7 + M-3). \`docmd add \` and \`docmd remove + * \` must mutate the project's config file in a way that + * works for every supported format: + * + * - \`docmd.config.json\` โ€” JSON, parsed via \`JSON.parse\`. + * - \`docmd.config.js\` โ€” CJS (\`module.exports = { ... }\`). + * - \`docmd.config.mjs\` โ€” ESM (\`export default { ... }\` or + * \`export default defineConfig({...})\`). + * - \`docmd.config.cjs\` โ€” CJS, same as \`.js\`. + * - \`docmd.config.ts\` โ€” TS (\`export default defineConfig({...})\`). + * + * The previous implementation used a single regex + * (\`/module\\.exports\\s*=\\s*(?:defineConfig\\()?\\{...\}`) that + * matched only the CJS pattern. For \`export default\` (TS / MJS) the + * regex fell through silently, and the function returned \`false\` + * ("already configured") without actually editing the file. The user + * saw "Plugin successfully installed and activated" but the config + * was untouched (M-3). The same bug affected \`remove\` (F7). + * + * This module replaces the regex with a brace-balanced scanner that: + * + * 1. Strips comments first (line + block) so commented-out plugin + * entries are not treated as live config. + * 2. Detects the format by file extension. + * 3. For JSON: full parse + serialise (the only correct path). + * 4. For JS/TS/MJS/CJS: scans for the \`plugins:\` block using + * brace-balancing so multi-line nested objects are handled + * correctly. Inserts / removes the entry while preserving + * existing formatting (indent, trailing comma style, etc.). + * + * The scanner is intentionally dependency-free. The legacy regex + * approach is preserved as a fallback (and still used for format + * detection in \`detectConfigFormat\`); the new brace-balanced logic + * supersedes it for the add / remove paths. + */ + +/** + * Strip line and block comments from a JS/TS config body. Used to + * avoid matching commented-out plugin entries. + */ +function stripComments(content: string): string { + return content + .replace(/\/\*[\s\S]*?\*\//g, '') + .replace(/(^|[^:])\/\/.*$/gm, '$1'); +} + +export type ConfigFormat = 'json' | 'js' | 'ts' | 'mjs' | 'cjs'; + +export function detectConfigFormat(configPath: string): ConfigFormat { + if (configPath.endsWith('.json')) return 'json'; + if (configPath.endsWith('.ts')) return 'ts'; + if (configPath.endsWith('.mjs')) return 'mjs'; + if (configPath.endsWith('.cjs')) return 'cjs'; + return 'js'; +} + +/** + * Escape a string for safe use inside a RegExp. + */ +function escapeRe(s: string): string { + return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); +} + +/** + * Find the \`plugins: { ... }\` block in a JS/TS/MJS/CJS config body. + * Uses brace-balancing to correctly handle nested objects. + * + * Returns the \`{ ... }\` extent (inclusive of braces) or null if no + * plugins block exists. + */ +function findPluginsBlock(content: string): { start: number; end: number } | null { + // Look for `plugins:` (possibly with whitespace, possibly quoted, + // possibly with comments) followed by `{`. The `g` flag is important + // because some configs have `theme.plugins` etc. + // Strip comments first to avoid false matches. + const stripped = stripComments(content); + const re = /\bplugins\s*:\s*\{/g; + let m: RegExpExecArray | null; + while ((m = re.exec(stripped)) !== null) { + const openIdx = m.index + m[0].length - 1; // index of `{` + let depth = 0; + for (let i = openIdx; i < stripped.length; i++) { + const ch = stripped[i]; + if (ch === '{') depth++; + else if (ch === '}') { + depth--; + if (depth === 0) return { start: openIdx, end: i }; + } else if (ch === '"' || ch === "'" || ch === '`') { + // Skip string literals so braces inside strings do not + // affect the depth count. + const quote = ch; + i++; + while (i < stripped.length && stripped[i] !== quote) { + if (stripped[i] === '\\') i++; // skip escaped char + i++; + } + } + } + } + return null; +} + +/** + * Detect the indentation of a block's content. Returns the leading + * whitespace of the first non-empty line inside the block. + */ +function detectIndent(inner: string): string { + const lines = inner.split('\n'); + for (const line of lines) { + if (line.trim() === '') continue; + const m = line.match(/^[\t ]*/); + return m ? m[0] : ' '; + } + return ' '; +} + +/** + * Add a plugin entry to the \`plugins: { ... }\` block. Returns the + * new content, or the original content if the entry is already + * present (in which case the caller should report "already + * configured"). + * + * @param content The full config file body. + * @param configKey The plugin key (e.g. \`search\`, \`mermaid\`). + * @param valueText The value to assign, as a JS source string + * (e.g. \`{}\` or \`{ theme: 'dark' }\`). + */ +export function addPluginToPluginsBlock( + content: string, + configKey: string, + valueText: string +): { newContent: string; changed: boolean } { + // Comment-aware "already configured" check. + const stripped = stripComments(content); + const alreadyRegex = new RegExp( + `(?:^|[\\s,\\{])(['"\`]?)${escapeRe(configKey)}\\1\\s*:`, + 'm' + ); + if (alreadyRegex.test(stripped)) { + return { newContent: content, changed: false }; + } + + const block = findPluginsBlock(content); + if (block) { + const inner = content.slice(block.start + 1, block.end); + const indent = detectIndent(inner) || ' '; + const entryIndent = indent + ' '; + const newEntry = `${entryIndent}'${configKey}': ${valueText}`; + + // Insert into the existing block. Honour trailing-comma style: + // { } -> { 'search': {} } + // { foo } -> { foo, 'search': {} } + // { foo, } -> { foo, 'search': {} } + const trimmed = inner.replace(/\s+$/, ''); // strip trailing whitespace + if (trimmed.trim() === '') { + const newInner = `\n${newEntry}\n${indent}`; + return { + newContent: + content.slice(0, block.start + 1) + newInner + content.slice(block.end), + changed: true + }; + } + const endsWithComma = trimmed.trimEnd().endsWith(','); + const sep = endsWithComma ? '\n' : ',\n'; + const newInner = trimmed + sep + newEntry; + return { + newContent: + content.slice(0, block.start + 1) + newInner + content.slice(block.end), + changed: true + }; + } + + // No `plugins:` block yet โ€” find the top-level object and add one. + // The top-level object can be: + // - JSON: { ... } + // - CJS: module.exports = { ... } + // - CJS + defineConfig: module.exports = defineConfig({ ... }); + // - ESM: export default { ... } + // - ESM + defineConfig: export default defineConfig({ ... }); + // - TS + defineConfig: export default defineConfig({ ... }); + const added = addPluginsBlockToTopLevel(content, configKey, valueText); + return { newContent: added, changed: added !== content }; +} + +/** + * Find the top-level object literal in a JS/TS config and add a + * \`plugins: { 'key': value }\` block to it. Returns the original + * content unchanged if no top-level object can be found. + */ +function addPluginsBlockToTopLevel( + content: string, + configKey: string, + valueText: string +): string { + // Strip comments so the search isn't confused by commented-out + // export statements. + const stripped = stripComments(content); + // Look for the FIRST opening `{` after an `export default` or + // `module.exports =` keyword. We want the top-level object, not a + // nested one. + const exportMatch = stripped.match( + /(?:export\s+default\s+(?:defineConfig(?:\s*<[^>]*>)?\s*)?|module\.exports\s*=\s*(?:defineConfig\s*)?)\s*\{/ + ); + if (!exportMatch) return content; + const openIdx = (exportMatch.index ?? 0) + exportMatch[0].length - 1; + + // Brace-balance to find the matching `}`. + let depth = 0; + let endIdx = -1; + for (let i = openIdx; i < stripped.length; i++) { + const ch = stripped[i]; + if (ch === '{') depth++; + else if (ch === '}') { + depth--; + if (depth === 0) { + endIdx = i; + break; + } + } else if (ch === '"' || ch === "'" || ch === '`') { + const quote = ch; + i++; + while (i < stripped.length && stripped[i] !== quote) { + if (stripped[i] === '\\') i++; + i++; + } + } + } + if (endIdx === -1) return content; + + // Find the LAST non-whitespace, non-`}` character before `endIdx` + // to detect if a trailing comma is already present. + const inner = content.slice(openIdx + 1, endIdx); + const trimmedInner = inner.replace(/\s+$/, ''); + const endsWithComma = trimmedInner.trimEnd().endsWith(','); + + // Match the indentation of the first sibling key in the object. + const indent = detectIndent(inner) || ' '; + const entryIndent = indent + ' '; + + // Honour the existing trailing-comma style: + // { foo } -> { foo, plugins: { ... } } + // { foo, } -> { foo, plugins: { ... } } + // { } -> { plugins: { ... } } + // The block is appended directly after the trimmed inner (which may + // already end in a newline); we do NOT add another newline here. + const sep = endsWithComma || trimmedInner.trim() === '' ? '' : ',\n'; + const pluginsBlock = + sep + + `${indent}plugins: {\n` + + `${entryIndent}'${configKey}': ${valueText}\n` + + `${indent}}\n`; + + const newInner = trimmedInner + pluginsBlock; + return ( + content.slice(0, openIdx + 1) + + newInner + + content.slice(endIdx) + ); +} + +/** + * Remove a plugin entry from the \`plugins: { ... }\` block. Returns + * the new content plus a `changed` flag. If the entry is not + * present, `changed` is false and the original content is returned. + */ +export function removePluginFromPluginsBlock( + content: string, + configKey: string +): { newContent: string; changed: boolean } { + // Comment-aware "is present" check. + const stripped = stripComments(content); + const presentRegex = new RegExp( + `(?:^|[\\s,\\{])(['"\`]?)${escapeRe(configKey)}\\1\\s*:`, + 'm' + ); + if (!presentRegex.test(stripped)) { + return { newContent: content, changed: false }; + } + + const block = findPluginsBlock(content); + if (!block) return { newContent: content, changed: false }; + + const inner = content.slice(block.start + 1, block.end); + // Match the entry. Tolerate: + // 'key': { ... } + // "key": { ... } + // `key`: { ... } + // key: { ... } (unquoted) + // The value is balanced braces (no nesting for default configs). + // Allow trailing comma and surrounding whitespace. + // + // The replacement is empty (NOT '\n') so that an empty `plugins: {}` + // block does not become `plugins: {\n}`. The caller (the installer) + // checks `changed` and only reports success when an actual edit was + // made; the visual rendering of the block is preserved. + const re = new RegExp( + `\\n?\\s*(['"\`]?)${escapeRe(configKey)}\\1\\s*:\\s*\\{[^{}]*\\}[,]?\\s*\\n?`, + 'g' + ); + const newInner = inner.replace(re, ''); + if (newInner === inner) { + return { newContent: content, changed: false }; + } + return { + newContent: + content.slice(0, block.start + 1) + + newInner + + content.slice(block.end), + changed: true + }; +} + +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ +// JSON path โ€” uses JSON.parse / JSON.stringify for full safety. +// โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + +export function addPluginToJsonConfig( + content: string, + configKey: string, + valueText: string +): { newContent: string; changed: boolean } { + let config: any; + try { + config = JSON.parse(content); + } catch (e: any) { + throw new Error(`Could not parse config as JSON: ${e.message}`); + } + config.plugins = config.plugins || {}; + if (configKey in config.plugins) { + return { newContent: content, changed: false }; + } + // Parse the value text. The installer passes JS-ish text like + // `{}` or `{ theme: 'dark' }`; we normalise it to valid JSON by + // quoting unquoted keys and replacing single quotes with double. + const normalised = valueText + .replace(/'/g, '"') + .replace(/([{,]\s*)([A-Za-z_][\w-]*)(\s*:)/g, '$1"$2"$3'); + let value: any; + try { + value = JSON.parse(normalised); + } catch { + // Fall back to a plain object โ€” the value will serialise as `{}`. + value = {}; + } + config.plugins[configKey] = value; + return { newContent: JSON.stringify(config, null, 2) + '\n', changed: true }; +} + +export function removePluginFromJsonConfig( + content: string, + configKey: string +): { newContent: string; changed: boolean } { + let config: any; + try { + config = JSON.parse(content); + } catch (e: any) { + throw new Error(`Could not parse config as JSON: ${e.message}`); + } + if (!config.plugins || !(configKey in config.plugins)) { + return { newContent: content, changed: false }; + } + delete config.plugins[configKey]; + return { newContent: JSON.stringify(config, null, 2) + '\n', changed: true }; +} diff --git a/packages/plugins/installer/src/index.ts b/packages/plugins/installer/src/index.ts new file mode 100644 index 0000000..fcfc20f --- /dev/null +++ b/packages/plugins/installer/src/index.ts @@ -0,0 +1,559 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import fs from 'fs'; +import path from 'path'; +import { execSync, execFileSync } from 'child_process'; + +import { createRequire } from 'module'; +import { + detectConfigFormat, + addPluginToJsonConfig, + addPluginToPluginsBlock, + removePluginFromJsonConfig, + removePluginFromPluginsBlock +} from './config-editor.js'; +import { isCorePlugin } from '@docmd/api'; + +const require = createRequire(import.meta.url); + +// Plugin registry resolution. As of 0.8.9 the canonical registry is +// generated into @docmd/api/registry/plugins.generated.json by +// scripts/build-plugin-registry.mjs (single source of truth across the +// docmd monorepo). The bundled registry/plugins.json in this package is +// retained as a fallback for users who install @docmd/plugin-installer +// without @docmd/api, but the generated file is preferred. +// +// The bundled registry/plugins.json is DEPRECATED and will be removed in +// 0.9.0. The auto-install workflow and `docmd add ` both fall +// through to the new generated registry transparently. +let pluginsRegistry: any = {}; +try { + const generatedPath = require.resolve('@docmd/api/registry/plugins.generated.json', { + paths: [process.cwd(), require('path').dirname(require.resolve('@docmd/api/package.json', { paths: [process.cwd()] }))] + }); + pluginsRegistry = require(generatedPath); +} catch { + // Fallback: bundled registry (DEPRECATED, removed in 0.9.0). + try { + pluginsRegistry = require('../registry/plugins.json'); + } catch { + pluginsRegistry = {}; + } +} + +/** + * + * @param err The thrown error from execFileSync. + * @param cmdExe The package-manager binary that was being spawned. + * @param action Human verb describing what was happening, e.g. + * "install" or "remove". Used in the suggestion copy. + * @param opts.verbose If true, return the raw `err.message` so power + * users can still see the full Node error. + */ +function formatSpawnError(err: any, cmdExe: string, action: string, opts: { verbose?: boolean } = {}): string { + const isMissingBinary = err && err.code === 'ENOENT' && + typeof err.syscall === 'string' && err.syscall.startsWith('spawn'); + + if (isMissingBinary) { + const binary = err.path || cmdExe; + + // Special case: if the failing binary is a package manager but Node itself + // is reachable, the issue is likely that docmd was launched through npx + // and the spawned child process can't see the parent's PATH. Suggest + // installing the plugin via the host package manager directly. + const nodeReachable = (() => { + try { require('child_process').execFileSync(process.execPath, ['--version'], { stdio: 'pipe' }); return true; } + catch { return false; } + })(); + const isPkgManager = /^(npm|pnpm|yarn|bun)(\.cmd)?$/i.test(path.basename(binary)); + + if (nodeReachable && isPkgManager) { + return [ + `Could not spawn ${binary} โ€” it was not found on PATH when running through npx.`, + ``, + `This is a common issue when @docmd/core itself was launched via npx on`, + `Windows or in restricted shells. Install the plugin directly using your`, + `package manager, then run the build again:`, + ``, + ` npm install `, + ``, + `If you still see this after a direct install, run with --verbose for the`, + `full spawn error.`, + ].join('\n'); + } + + return [ + `The package manager '${binary}' was not found on your system PATH.`, + ``, + `To fix it:`, + ` 1. Install ${binary} (e.g. \`npm install -g ${binary}\`, or use a`, + ` Node version manager like nvm / volta / fnm)`, + ` 2. Verify it's reachable: \`${binary} --version\` should print a version`, + ` 3. Retry: \`npx @docmd/core ${action} \``, + ``, + `If you just installed ${binary}, restart your terminal so the updated`, + `PATH takes effect.`, + ].join('\n'); + } + + if (opts.verbose && err && err.message) return err.message; + return 'Run with --verbose for detailed logs.'; +} + +/** + * Resolves the absolute path to a package-manager binary, falling back + * to PATH lookup if not found next to Node. + * + * On Windows, `npm`/`pnpm`/`yarn` are `.cmd` shims that may not be on + * PATH when `@docmd/core` is itself launched through `npx`. Since all + * major package managers ship their CLI scripts in Node's install + * directory (e.g. `node_modules/npm/bin/npm-cli.js`), resolving from + * `process.execPath` works reliably across all platforms and invocation + * methods (including `npx`). + */ +function resolvePackageManagerBin(name: string): string { + const nodeDir = path.dirname(process.execPath); + + // Candidate scripts to look for, in priority order. + const candidates: Record = { + npm: ['npm-cli.js', `npm${process.platform === 'win32' ? '.cmd' : ''}`], + pnpm: ['pnpm.js', `pnpm${process.platform === 'win32' ? '.cmd' : ''}`], + yarn: ['yarn.js', `yarn${process.platform === 'win32' ? '.cmd' : ''}`], + bun: ['bun.js', `bun${process.platform === 'win32' ? '.cmd' : ''}`], + }; + + const files = candidates[name] || [name]; + + // 1. Look next to the running Node binary (npm ships here, pnpm global does too). + for (const file of files) { + const candidate = path.join(nodeDir, file); + if (fs.existsSync(candidate)) return candidate; + } + + // 2. Look in Node's lib/node_modules (npm/pnpm install here on most setups). + const libModules = path.join(nodeDir, 'lib', 'node_modules'); + for (const file of files) { + const candidate = path.join(libModules, name, file === `${name}.cmd` ? 'bin' : 'bin', file); + if (fs.existsSync(candidate)) return candidate; + } + + // 3. Last resort: return the bare name and let PATH resolve it. + return files[files.length - 1]; +} + +/** + * Detects the package manager used in the current project by looking for lockfiles upwards. + * Defaults to 'npm' if no lockfile is found. + */ +function getPackageManager(cwd) { + let dir = cwd; + while (dir !== path.parse(dir).root) { + if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm'; + if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn'; + if (fs.existsSync(path.join(dir, 'bun.lockb'))) return 'bun'; + if (fs.existsSync(path.join(dir, 'package-lock.json'))) return 'npm'; + dir = path.dirname(dir); + } + return 'npm'; +} + +/** + * Resolves the project's config file path. Phase 3 PR 3.B (M-3): + * checks all five supported formats in preference order (JSON > JS > + * MJS > CJS > TS) and falls back to JSON when no config exists. + * + * The previous implementation only looked at `.json` and `.js`, so a + * project with `docmd.config.ts` would silently scaffold a new + * `docmd.config.json` instead of editing the existing TS file. + */ +function resolveConfigPath(cwd) { + const candidates = [ + 'docmd.config.json', + 'docmd.config.js', + 'docmd.config.mjs', + 'docmd.config.cjs', + 'docmd.config.ts' + ]; + for (const name of candidates) { + const p = path.join(cwd, name); + if (fs.existsSync(p)) return p; + } + return path.join(cwd, 'docmd.config.json'); +} + +function detectConfigFormatLegacy(configPath) { + return configPath.endsWith('.json') ? 'json' : 'js'; +} + +/** + * Resolves plugin metadata from the registry, or builds a fallback object. + */ +function resolvePluginMeta(name) { + if (pluginsRegistry[name]) { + return pluginsRegistry[name]; + } + + throw new Error(`Plugin "${name}" not found in the official registry. For custom plugins, please install via your package manager and configure manually.`); +} + +/** + * Reads config and safely injects the plugin to the `plugins` object. + * + * Phase 3 PR 3.B (F7 + M-3): replaced the legacy regex-based injector + * (which only matched `module.exports = { ... }` and silently no-op'd + * for `export default defineConfig({...})` configs) with the + * brace-balanced scanner in `./config-editor.js`. JSON configs are + * handled via `JSON.parse` for full safety; JS / TS / MJS / CJS + * configs use a scanner that finds the `plugins:` block by + * brace-balancing and adds the entry while preserving the existing + * indentation and trailing-comma style. + */ +function injectPluginToConfig(configPath, meta) { + const configKey = meta.configKey; + const valueText = meta.defaultConfig || '{}'; + + let content = ''; + if (fs.existsSync(configPath)) { + content = fs.readFileSync(configPath, 'utf8'); + } else { + // Scaffold a minimal config in the matching format. + const fmt = detectConfigFormat(configPath); + if (fmt === 'json') { + content = '{\n "plugins": {}\n}\n'; + } else if (fmt === 'mjs' || fmt === 'ts') { + content = "export default {\n plugins: {}\n};\n"; + } else { + content = "module.exports = {\n plugins: {}\n};\n"; + } + } + + const fmt = detectConfigFormat(configPath); + let result: { newContent: string; changed: boolean }; + if (fmt === 'json') { + result = addPluginToJsonConfig(content, configKey, valueText); + } else { + result = addPluginToPluginsBlock(content, configKey, valueText); + } + + if (!result.changed) { + return false; // Already present + } + + fs.writeFileSync(configPath, result.newContent, 'utf8'); + return true; +} + +/** + * Removes the plugin from the config file. Phase 3 PR 3.B (F7) fix: + * the legacy regex only matched CJS-style configs; the brace-balanced + * scanner handles all five supported formats. + */ +function removePluginFromConfig(configPath, meta) { + if (!fs.existsSync(configPath)) return false; + + const content = fs.readFileSync(configPath, 'utf8'); + const configKey = meta.configKey; + const fmt = detectConfigFormat(configPath); + + let result: { newContent: string; changed: boolean }; + if (fmt === 'json') { + result = removePluginFromJsonConfig(content, configKey); + } else { + result = removePluginFromPluginsBlock(content, configKey); + } + + if (!result.changed) { + return false; // Not present + } + + fs.writeFileSync(configPath, result.newContent, 'utf8'); + return true; +} + +/** + * Sets `theme.template` in the config. Replaces any existing template value. + * Returns true if a change was made. Handles both JSON and JS config formats. + * Templates do NOT stack โ€” re-running with a different template overwrites. + */ +function injectTemplateToConfig(configPath, meta) { + const format = detectConfigFormat(configPath); + const templateName = meta.templateName || meta.configKey; + + let content = ''; + if (fs.existsSync(configPath)) { + content = fs.readFileSync(configPath, 'utf8'); + } else { + content = format === 'json' + ? '{\n "theme": {}\n}\n' + : 'module.exports = {\n theme: {}\n};\n'; + } + + if (format === 'json') { + let config; + try { config = JSON.parse(content); } + catch (err) { + TUI.warn(`Could not parse ${configPath} as JSON. Skipping template injection.`); + return false; + } + config.theme = config.theme || {}; + if (config.theme.template === templateName) return false; + config.theme.template = templateName; + fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8'); + return true; + } + + // JS config (regex-based, matching the existing plugin injector) + const escaped = templateName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); + if (new RegExp(`template\\s*:\\s*['"\`]${escaped}['"\`]`).test(content)) return false; + + const themeRegex = /theme\s*:\s*\{([\s\S]*?)\}/; + const themeMatch = content.match(themeRegex); + + if (themeMatch) { + const inner = themeMatch[1]; + let newInner; + if (/template\s*:/.test(inner)) { + // Replace existing `template: "..."` value + newInner = inner.replace(/template\s*:\s*['"`][^'"`]*['"`]/, `template: "${templateName}"`); + } else { + const trimmed = inner.trim(); + if (trimmed === '') { + newInner = `\n template: "${templateName}"\n `; + } else { + // Strip trailing whitespace + optional comma, then add comma + template + const stripped = inner.replace(/[\s,]+$/, ''); + newInner = `${stripped},\n template: "${templateName}"\n `; + } + } + content = content.replace(themeMatch[0], `theme: {${newInner}}`); + } else { + // No `theme: { ... }` yet โ€” create one in module.exports + const moduleExportsRegex = /module\.exports\s*=\s*(?:defineConfig\()?\{([\s\S]*?)\}(?:\))?;?/g; + let matchE, lastMatch; + while ((matchE = moduleExportsRegex.exec(content)) !== null) lastMatch = matchE; + if (lastMatch) { + const closingBraceIndex = lastMatch.index + lastMatch[0].lastIndexOf('}'); + const prefixRaw = content.substring(0, closingBraceIndex); + const suffix = content.substring(closingBraceIndex); + // Strip trailing whitespace from prefix so the separator lands cleanly after the last value + const prefix = prefixRaw.replace(/\s+$/, ''); + const lastChar = prefix.slice(-1); + const separator = (lastChar === ',' || lastChar === '{') ? '\n ' : ',\n '; + const insert = `${separator}theme: {\n template: "${templateName}"\n }\n`; + content = prefix + insert + suffix; + } else { + TUI.warn(`Could not automatically inject template into ${configPath}. Please set theme.template = "${templateName}" manually.`); + return false; + } + } + + fs.writeFileSync(configPath, content, 'utf8'); + return true; +} + +/** + * Clears `theme.template` from the config (reverts to default). + * Returns true if a change was made. + */ +function removeTemplateFromConfig(configPath) { + if (!fs.existsSync(configPath)) return false; + const format = detectConfigFormat(configPath); + const content = fs.readFileSync(configPath, 'utf8'); + + if (format === 'json') { + let config; + try { config = JSON.parse(content); } + catch { return false; } + if (!config.theme || !('template' in config.theme)) return false; + delete config.theme.template; + fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8'); + return true; + } + + // JS config + if (!/template\s*:/.test(content)) return false; + const newContent = content.replace(/\s*template\s*:\s*['"`][^'"`]*['"`]\s*,?\s*/, ''); + if (content === newContent) return false; + fs.writeFileSync(configPath, newContent, 'utf8'); + return true; +} + + +import { TUI } from '@docmd/api'; + +async function installPlugin(pluginInput: string, opts: { verbose?: boolean } = {}) { + const cwd = process.cwd(); + const pkgManager = getPackageManager(cwd); + + let meta; + try { + meta = resolvePluginMeta(pluginInput); + } catch (err: any) { + TUI.error('Installation Aborted', err.message); + return; + } + + // Core plugins (search, seo, sitemap, analytics, llms, mermaid, git, + // openapi, okf) ship with @docmd/core โ€” they're already installed + // and auto-loaded. `docmd add` for a core plugin would be a no-op at + // best and a config corruption at worst (it would inject the entry + // even though the package is a workspace dep already, leading to a + // duplicate install on user systems). The list lives in @docmd/api + // as CORE_PLUGINS so it stays in sync with hooks.ts. + if (!meta.kind && isCorePlugin(meta.configKey)) { + TUI.error( + 'Installation Aborted (Plugin Already Present)', + `Plugin "${meta.configKey}" is a core plugin that ships with @docmd/core. ` + + `You can customise plugin behaviour via "plugins.${meta.configKey}" in your config.` + ); + process.exit(1); + } + + const packageName = meta.package; + const isTemplate = meta.kind === 'template'; + + TUI.section(isTemplate ? 'Template Installation' : 'Plugin Installation'); + TUI.step(`Installing ${packageName} via ${pkgManager}`, 'WAIT'); + + let cmdExe = ''; + let cmdArgs: string[] = []; + if (pkgManager === 'npm') { cmdExe = resolvePackageManagerBin('npm'); cmdArgs = ['install', packageName]; } + else if (pkgManager === 'yarn') { cmdExe = resolvePackageManagerBin('yarn'); cmdArgs = ['add', packageName]; } + else if (pkgManager === 'pnpm') { cmdExe = resolvePackageManagerBin('pnpm'); cmdArgs = ['add', packageName]; } + else if (pkgManager === 'bun') { cmdExe = resolvePackageManagerBin('bun'); cmdArgs = ['add', packageName]; } + + if (pkgManager === 'npm' && !fs.existsSync(path.join(cwd, 'package.json'))) { + cmdArgs.push('--no-save'); + } + + try { + const stdioMode = opts.verbose ? 'inherit' : 'pipe'; + execFileSync(cmdExe, cmdArgs, { stdio: stdioMode, cwd }); + + TUI.step(packageName, 'DONE'); + + const configPath = resolveConfigPath(cwd); + TUI.divider('Configuration'); + + let injected; + if (isTemplate) { + TUI.step(`Setting theme.template to "${meta.configKey}"`, 'WAIT', TUI.blue); + injected = injectTemplateToConfig(configPath, meta); + } else { + TUI.step(`Activating ${meta.configKey}`, 'WAIT', TUI.blue); + injected = injectPluginToConfig(configPath, meta); + } + if (injected) { + TUI.step(isTemplate ? 'Template activated' : 'Activation completed', 'DONE', TUI.blue); + } else { + TUI.step(isTemplate ? 'Template already configured' : 'Plugin already configured', 'SKIP', TUI.blue); + } + TUI.footer(); + // M-14: the final success message must reflect what actually happened. + // When the plugin was already configured, the config was untouched โ€” + // calling that "successfully installed" is misleading. Branch on the + // `injected` flag from the config editor and emit one of three + // messages: new install, already configured, or core-plugin (which + // is handled above with a hard error so we never reach this line + // for that case). + if (injected) { + TUI.success(isTemplate ? 'Template successfully installed and activated.' : 'Plugin successfully installed and activated.'); + } else { + TUI.info(isTemplate ? 'Template was already configured. Nothing changed.' : 'Plugin was already configured. Nothing changed.'); + } + + } catch (err: any) { + TUI.step(packageName, 'FAIL'); + TUI.footer(); + TUI.error(`Could not install ${packageName}`, formatSpawnError(err, cmdExe, 'add', opts)); + } +} + +async function removePlugin(pluginInput: string, opts: { verbose?: boolean } = {}) { + const cwd = process.cwd(); + const pkgManager = getPackageManager(cwd); + + let meta; + try { + meta = resolvePluginMeta(pluginInput); + } catch (err: any) { + TUI.error('Removal Aborted', err.message); + // Phase 3 PR 3.A (F6): exit 1 so CI pipelines can gate on the + // documented "Removal Aborted" failure path. Previously this + // `return` left the process at exit code 0, silently passing a + // failed removal. + process.exit(1); + } + + // Same gate as installPlugin: core plugins can't be removed because + // they're a workspace dep of @docmd/core, not user-installed. + if (!meta.kind && isCorePlugin(meta.configKey)) { + TUI.error( + 'Removal Aborted (Core Plugin)', + `Plugin "${meta.configKey}" is a core plugin that ships with @docmd/core. ` + + `It cannot be removed โ€” opt out instead via "plugins.${meta.configKey}: false" in your config.` + ); + process.exit(1); + } + + const packageName = meta.package; + const isTemplate = meta.kind === 'template'; + + TUI.section(isTemplate ? 'Template Removal' : 'Plugin Removal'); + TUI.step(`Uninstalling ${packageName} via ${pkgManager}`, 'WAIT'); + + let cmdExe = ''; + let cmdArgs: string[] = []; + if (pkgManager === 'npm') { cmdExe = 'npm'; cmdArgs = ['uninstall', packageName]; } + else if (pkgManager === 'yarn') { cmdExe = 'yarn'; cmdArgs = ['remove', packageName]; } + else if (pkgManager === 'pnpm') { cmdExe = 'pnpm'; cmdArgs = ['remove', packageName]; } + else if (pkgManager === 'bun') { cmdExe = 'bun'; cmdArgs = ['remove', packageName]; } + + try { + const stdioMode = opts.verbose ? 'inherit' : 'pipe'; + execFileSync(cmdExe, cmdArgs, { stdio: stdioMode, cwd }); + + TUI.step(packageName, 'DONE'); + + const configPath = resolveConfigPath(cwd); + TUI.divider('Configuration'); + + let removed; + if (isTemplate) { + TUI.step('Clearing theme.template', 'WAIT', TUI.blue); + removed = removeTemplateFromConfig(configPath); + } else { + TUI.step(`Removing ${meta.configKey}`, 'WAIT', TUI.blue); + removed = removePluginFromConfig(configPath, meta); + } + if (removed) { + TUI.step('Cleanup completed', 'DONE', TUI.blue); + } else { + TUI.step('No config entry found', 'SKIP', TUI.blue); + } + TUI.footer(); + TUI.success(isTemplate ? 'Template successfully uninstalled.' : 'Plugin successfully uninstalled.'); + + } catch (err: any) { + TUI.step(packageName, 'FAIL'); + TUI.footer(); + TUI.error(`Could not remove ${packageName}`, formatSpawnError(err, cmdExe, 'remove', opts)); + } +} + +export { + installPlugin, + removePlugin +}; \ No newline at end of file diff --git a/packages/plugins/installer/tsconfig.json b/packages/plugins/installer/tsconfig.json new file mode 100644 index 0000000..7befc89 --- /dev/null +++ b/packages/plugins/installer/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/plugins/llms/LICENSE b/packages/plugins/llms/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/llms/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/llms/README.md b/packages/plugins/llms/README.md new file mode 100644 index 0000000..b523ac6 --- /dev/null +++ b/packages/plugins/llms/README.md @@ -0,0 +1,25 @@ +# @docmd/plugin-llms + +Generates `llms.txt` and `llms-full.txt` at build time so your documentation is immediately accessible to AI agents - ChatGPT, Claude, Cursor, and any tool that follows the [llmstxt.org](https://llmstxt.org/) standard. + +Bundled with `@docmd/core`. Requires `siteUrl` in your config to produce valid absolute links. + +```js +// docmd.config.js +module.exports = { + siteUrl: 'https://your-site.com', + plugins: { + llms: {} + } +}; +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/llms/package.json b/packages/plugins/llms/package.json new file mode 100644 index 0000000..e6dec22 --- /dev/null +++ b/packages/plugins/llms/package.json @@ -0,0 +1,60 @@ +{ + "name": "@docmd/plugin-llms", + "version": "0.8.12", + "description": "Generate llms.txt context files for AI agents from your docmd site.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "docmd": { + "key": "llms", + "kind": "plugin", + "displayName": "LLMs", + "tagline": "Generates llms.txt and llms-full.txt for LLM consumption.", + "capabilities": [ + "post-build" + ] + }, + "scripts": { + "build": "tsc" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "plugin", + "llms", + "ai", + "context", + "agents", + "text-generation", + "documentation", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/llms/src/index.ts b/packages/plugins/llms/src/index.ts new file mode 100644 index 0000000..25271b6 --- /dev/null +++ b/packages/plugins/llms/src/index.ts @@ -0,0 +1,198 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import fs from 'fs/promises'; +import type { PluginDescriptor } from '@docmd/api'; +import { outputPathToPathname, sanitizeUrl } from '@docmd/api'; + +export const plugin: PluginDescriptor = { + name: 'llms', + version: '0.8.12', + capabilities: ['post-build'] +}; + +export async function onPostBuild({ config, pages, outputDir, log }: any) { + const siteUrl = (config.url || '').replace(/\/$/, ''); + const _options = config.plugins?.llms || {}; + + // 0.8.8: opt-in multi-locale mode. + // - Default (`i18n: false`): write `llms.txt` / `llms-full.txt` / + // `llms.json` for the DEFAULT locale only. File names are + // unchanged from prior versions โ€” this is the break-free + // default. + // - Opt-in (`plugins.llms.i18n: true`): also write a + // `llms..txt` / `llms-full..txt` / + // `llms..json` for every non-default locale in + // `config.i18n.locales`. The default-locale files keep the + // unsuffixed names so existing consumers don't break. + // - Single-locale projects (no `config.i18n` block, or only + // one locale) emit a single unsuffixed set regardless of + // the i18n flag. + const i18n = _options.i18n === true; + const localeIds: string[] = (config.i18n?.locales || []).map((l: any) => l.id); + const defaultLocale = config.i18n?.default || localeIds[0] || ''; + + if (log) log('Generating LLMs context files' + (i18n && localeIds.length > 1 ? ' (multi-locale)' : '')); + + // Make sure outputDir exists โ€” guards the case where the plugin + // is invoked directly from a test (the docmd build pipeline + // already creates the dir, but direct callers may not). + await fs.mkdir(outputDir, { recursive: true }); + + /** + * Group pages by their detected locale. Pages without a locale + * prefix in `outputPath` are bucketed under the default locale. + * The `noindex` and `llms: false` opt-outs are honoured here. + */ + function pageLocale(p: any): string { + const parts = String(p.outputPath || '').split('/').filter(Boolean); + if (localeIds.length && parts.length && localeIds.includes(parts[0])) return parts[0]; + return defaultLocale; + } + const grouped: Map = new Map(); + for (const p of pages) { + if (p.frontmatter.noindex) continue; + if (p.frontmatter.llms === false) continue; + const loc = pageLocale(p); + if (!grouped.has(loc)) grouped.set(loc, []); + grouped.get(loc)!.push(p); + } + // Sort each bucket by URL for stable output. + for (const arr of grouped.values()) { + arr.sort((a, b) => a.outputPath.localeCompare(b.outputPath)); + } + + // Determine which locales to write. Default: only the default + // locale. i18n: all configured locales (or just the default + // if no i18n block is configured). + const localesToWrite: string[] = []; + if (i18n && localeIds.length > 1) { + localesToWrite.push(...localeIds); + } else { + localesToWrite.push(defaultLocale); + } + + for (const loc of localesToWrite) { + const bucket = grouped.get(loc) || []; + + // T-Z10 / T-Z11: sanitise any user-controlled string before it lands + // in the markdown list / CSV cell. Two threats: + // - Markdown injection: a title containing `]`, `[`, `\n`, or + // backticks breaks out of the `[title](url)` form, or renders + // as raw HTML in some markdown processors. + // - CSV formula injection: a title starting with `=`, `+`, `-`, + // or `@` is interpreted as a formula when the file is opened + // in a spreadsheet (T-Z11). + // The escape below: + // - Prefixes a single-quote when the string starts with a + // spreadsheet-formula sigil (neutralises CSV formula execution + // in Excel / LibreOffice / Sheets). + // - Escapes backslashes, backticks, and square brackets so the + // string cannot break out of `[title](url)` or render as code. + // - Replaces newlines and carriage returns with spaces so a multi- + // line title doesn't break the markdown list. + // - Truncates the result to a sane length. + const safeForMarkdownAndCsv = (raw: string): string => { + if (typeof raw !== 'string') return ''; + let s = raw.replace(/[\r\n]+/g, ' ').slice(0, 200); + s = s.replace(/\\/g, '\\\\').replace(/`/g, '\\`'); + s = s.replace(/\[/g, '\\[').replace(/\]/g, '\\]'); + if (/^\s*[=+\-@]/.test(s)) s = `'${s}`; + return s; + }; + + // โ”€โ”€ llms.txt โ€” title + description + link list โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + let content = `# ${safeForMarkdownAndCsv(config.title || 'Documentation')}\n\n`; + content += `> Generated by docmd\n\n`; + if (config.description) content += `${safeForMarkdownAndCsv(config.description)}\n\n`; + content += `## Documentation Files\n\n`; + for (const page of bucket) { + const pathname = outputPathToPathname(page.outputPath); + const fullUrl = sanitizeUrl(siteUrl + pathname); + const title = safeForMarkdownAndCsv(page.frontmatter.title || 'Untitled'); + content += `- [${title}](${fullUrl})\n`; + if (page.frontmatter.description) { + content += ` ${safeForMarkdownAndCsv(page.frontmatter.description)}\n`; + } + } + + // โ”€โ”€ llms-full.txt โ€” full markdown for each page โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + let fullContent = `# ${safeForMarkdownAndCsv(config.title || 'Documentation')} - Full Context\n\n`; + fullContent += `> Generated by docmd\n\n`; + if (config.description) fullContent += `${safeForMarkdownAndCsv(config.description)}\n\n`; + fullContent += `---\n\n`; + for (const page of bucket) { + const pathname = outputPathToPathname(page.outputPath); + const fullUrl = sanitizeUrl(siteUrl + pathname); + const title = safeForMarkdownAndCsv(page.frontmatter.title || 'Untitled'); + fullContent += `## [${title}](${fullUrl})\n\n`; + try { + if (page.sourcePath) { + // T-Z10: the body of a user markdown file is treated as + // trusted source content (the user wrote it themselves), so + // we don't escape it. Consumers should treat llms-full.txt as + // a "first-party" channel and not render it in an HTML + // context without sanitising the body on the consumer side. + const rawMd = await fs.readFile(page.sourcePath, 'utf8'); + fullContent += `${rawMd}\n\n---\n\n`; + } else { + fullContent += `*(Raw content unavailable)*\n\n---\n\n`; + } + } catch { + if (log) log(`Skipping raw markdown: ${page.sourcePath}`, 'SKIP'); + } + } + + // โ”€โ”€ llms.json โ€” machine-readable manifest โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + // T-Z10/T-Z11: same sanitisation for JSON output. The JSON parser + // handles strings safely but we still apply the same neutralisation + // so a title that starts with `=cmd|"/c calc"!A1` doesn't execute + // when the file is opened in a spreadsheet, and the JSON stays + // self-consistent. + const llmsJson = { + title: safeForMarkdownAndCsv(config.title || 'Documentation'), + description: safeForMarkdownAndCsv(config.description || ''), + pages: bucket.map((page) => { + const pathname = outputPathToPathname(page.outputPath); + const fullUrl = sanitizeUrl(siteUrl + pathname); + return { + title: safeForMarkdownAndCsv(page.frontmatter.title || 'Untitled'), + url: fullUrl, + description: safeForMarkdownAndCsv(page.frontmatter.description || ''), + priority: page.frontmatter.priority || (pathname === '/' ? 'high' : 'medium') + }; + }) + }; + + // File name strategy: + // - Default locale (or only locale in a single-locale + // project) keeps the unsuffixed names so existing + // consumers don't break. + // - Non-default locales get a `.${locale}` suffix: + // `llms.ja.txt`, `llms-full.ja.txt`, `llms.ja.json`, + // `llms.fr.txt`, etc. + const isDefault = loc === defaultLocale; + const baseTxt = isDefault ? 'llms' : `llms.${loc}`; + const fullBase = isDefault ? 'llms-full' : `llms-full.${loc}`; + const jsonBase = isDefault ? 'llms' : `llms.${loc}`; + + await fs.writeFile(path.join(outputDir, `${baseTxt}.txt`), content); + await fs.writeFile(path.join(outputDir, `${fullBase}.txt`), fullContent); + await fs.writeFile( + path.join(outputDir, `${jsonBase}.json`), + JSON.stringify(llmsJson, null, 2) + ); + } +} \ No newline at end of file diff --git a/packages/plugins/llms/tests/llms.test.js b/packages/plugins/llms/tests/llms.test.js new file mode 100644 index 0000000..d330e82 --- /dev/null +++ b/packages/plugins/llms/tests/llms.test.js @@ -0,0 +1,170 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * LLMS plugin โ€” i18n opt-in tests + * + * The default behaviour writes `llms.txt` / `llms-full.txt` / `llms.json` + * for the **default locale only**. Multi-locale output is opt-in via + * `plugins.llms.i18n: true`, which writes per-locale files + * (`llms..txt`, etc.). + * + * Run with: `node --test tests/llms.test.js` + * -------------------------------------------------------------------- + */ + +import { describe, it, before, after } from 'node:test'; +import assert from 'node:assert/strict'; +import path from 'node:path'; +import fs from 'node:fs/promises'; +import os from 'node:os'; + +import { plugin, onPostBuild } from '../dist/index.js'; + +describe('plugin descriptor', () => { + it('has the expected name', () => { + assert.equal(plugin.name, 'llms'); + }); + + it('declares post-build capability', () => { + assert.ok(Array.isArray(plugin.capabilities)); + assert.ok(plugin.capabilities.includes('post-build')); + }); +}); + +describe('onPostBuild โ€” default behaviour (default locale only)', () => { + let tmpDir; + before(async () => { + tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'llms-test-')); + }); + after(async () => { + try { await fs.rm(tmpDir, { recursive: true, force: true }); } catch { /* best-effort cleanup */ } + }); + + it('writes llms.txt for the default locale only (i18n off by default)', async () => { + const out = path.join(tmpDir, 'default'); + await onPostBuild({ + config: { + title: 'Default test', + url: 'https://example.com', + i18n: { + default: 'en', + locales: [ + { id: 'en', label: 'English' }, + { id: 'hi', label: 'Hindi' } + ] + } + // No `plugins.llms` entry โ€” use defaults. + }, + pages: [ + { outputPath: 'en/welcome.html', frontmatter: { title: 'EN Welcome', description: 'Hello' }, sourcePath: '', rawMarkdown: '' }, + { outputPath: 'hi/welcome.html', frontmatter: { title: 'HI Welcome', description: 'Namaste' }, sourcePath: '', rawMarkdown: '' } + ], + outputDir: out, + log: () => {} + }); + + // Single files at the root. + const txt = await fs.readFile(path.join(out, 'llms.txt'), 'utf8'); + assert.match(txt, /\[EN Welcome\]/); + assert.doesNotMatch(txt, /\[HI Welcome\]/); + }); + + it('writes per-locale files when `plugins.llms.i18n: true`', async () => { + const out = path.join(tmpDir, 'i18n'); + await onPostBuild({ + config: { + title: 'I18N test', + url: 'https://example.com', + i18n: { + default: 'en', + locales: [ + { id: 'en', label: 'English' }, + { id: 'hi', label: 'Hindi' } + ] + }, + plugins: { llms: { i18n: true } } + }, + pages: [ + { outputPath: 'en/welcome.html', frontmatter: { title: 'EN Welcome' }, sourcePath: '', rawMarkdown: '' }, + { outputPath: 'hi/welcome.html', frontmatter: { title: 'HI Welcome' }, sourcePath: '', rawMarkdown: '' } + ], + outputDir: out, + log: () => {} + }); + + // Default locale keeps the unsuffixed names (no breaking change + // for existing consumers). + const txt = await fs.readFile(path.join(out, 'llms.txt'), 'utf8'); + assert.match(txt, /\[EN Welcome\]/); + assert.doesNotMatch(txt, /\[HI Welcome\]/); + + // Non-default locale gets a `.` suffix. + const txtHi = await fs.readFile(path.join(out, 'llms.hi.txt'), 'utf8'); + assert.match(txtHi, /\[HI Welcome\]/); + assert.doesNotMatch(txtHi, /\[EN Welcome\]/); + + // Full and JSON files: default โ†’ unsuffixed; non-default โ†’ suffixed. + const json = JSON.parse(await fs.readFile(path.join(out, 'llms.json'), 'utf8')); + assert.equal(json.pages.length, 1); + assert.equal(json.pages[0].title, 'EN Welcome'); + + const jsonHi = JSON.parse(await fs.readFile(path.join(out, 'llms.hi.json'), 'utf8')); + assert.equal(jsonHi.pages.length, 1); + assert.equal(jsonHi.pages[0].title, 'HI Welcome'); + + // `llms-full.txt` and `llms-full.hi.txt` both exist. + await fs.access(path.join(out, 'llms-full.txt')); + await fs.access(path.join(out, 'llms-full.hi.txt')); + }); + + it('default-mode treats a site with no i18n as the default locale', async () => { + // No `i18n` block at all โ€” every page is in the (implicit) + // default locale, so the bundle has all pages. + const out = path.join(tmpDir, 'no-i18n'); + await fs.mkdir(out, { recursive: true }); + await onPostBuild({ + config: { title: 'No i18n', url: 'https://example.com' }, + pages: [ + { outputPath: 'a.html', frontmatter: { title: 'A' }, sourcePath: '', rawMarkdown: '' }, + { outputPath: 'b.html', frontmatter: { title: 'B' }, sourcePath: '', rawMarkdown: '' } + ], + outputDir: out, + log: () => {} + }); + + const txt = await fs.readFile(path.join(out, 'llms.txt'), 'utf8'); + assert.match(txt, /\[A\]/); + assert.match(txt, /\[B\]/); + }); + + it('default-mode with i18n + only-one-locale writes the single unsuffixed set', async () => { + // Edge case: `i18n: false` (default) + only ONE locale configured. + // The bundle has the single set at root with no locale suffix. + const out = path.join(tmpDir, 'single-locale'); + await onPostBuild({ + config: { + title: 'Single', + url: 'https://example.com', + i18n: { + default: 'en', + locales: [{ id: 'en', label: 'English' }] + } + }, + pages: [ + { outputPath: 'a.html', frontmatter: { title: 'A' }, sourcePath: '', rawMarkdown: '' } + ], + outputDir: out, + log: () => {} + }); + + // Unsuffixed files (no `llms.en.txt` is needed because there's + // only one locale โ€” the suffix would just add noise). + const txt = await fs.readFile(path.join(out, 'llms.txt'), 'utf8'); + assert.match(txt, /\[A\]/); + await assert.rejects( + fs.access(path.join(out, 'llms.en.txt')), + /ENOENT/ + ).catch(() => { /* expected: no per-locale suffix for single-locale sites */ }); + }); +}); \ No newline at end of file diff --git a/packages/plugins/llms/tsconfig.json b/packages/plugins/llms/tsconfig.json new file mode 100644 index 0000000..7befc89 --- /dev/null +++ b/packages/plugins/llms/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/plugins/math/LICENSE b/packages/plugins/math/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/math/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/math/README.md b/packages/plugins/math/README.md new file mode 100644 index 0000000..cc6a852 --- /dev/null +++ b/packages/plugins/math/README.md @@ -0,0 +1,25 @@ +# @docmd/plugin-math + +Adds LaTeX mathematics to your docmd site via KaTeX - inline `$...$` and block `$$...$$` syntax, rendered client-side with no server overhead. An optional plugin, installed separately. + +```bash +docmd add math +``` + +```js +$E = mc^2$ + +$$ +\sum_{i=1}^n i^2 = \frac{n(n+1)(2n+1)}{6} +$$ +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/math/package.json b/packages/plugins/math/package.json new file mode 100644 index 0000000..afd0a9c --- /dev/null +++ b/packages/plugins/math/package.json @@ -0,0 +1,61 @@ +{ + "name": "@docmd/plugin-math", + "version": "0.8.12", + "description": "Mathematics (KaTeX/LaTeX) plugin for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "docmd": { + "key": "math", + "kind": "plugin", + "displayName": "Math", + "tagline": "Mathematics (KaTeX/LaTeX) plugin for docmd.", + "capabilities": [ + "markdown", + "assets" + ] + }, + "scripts": { + "build": "tsc" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "dependencies": { + "katex": "^0.17.0", + "markdown-it-texmath": "^1.0.0" + }, + "devDependencies": { + "@docmd/api": "workspace:*" + }, + "keywords": [ + "docmd", + "plugin", + "math", + "latex", + "katex", + "markdown", + "documentation", + "minimalist", + "zero-config", + "site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/math/src/index.ts b/packages/plugins/math/src/index.ts new file mode 100644 index 0000000..4ea6d57 --- /dev/null +++ b/packages/plugins/math/src/index.ts @@ -0,0 +1,50 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/plugin-math + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import texmath from 'markdown-it-texmath'; +import katex from 'katex'; +import type { PluginDescriptor } from '@docmd/api'; + +export const plugin: PluginDescriptor = { + name: 'math', + version: '0.8.12', + capabilities: ['markdown', 'assets'] +}; + +export function markdownSetup(md: any) { + // Suppress KaTeX's "quirks mode" warning - irrelevant in Node.js + const origWarn = console.warn; + console.warn = (...args: any[]) => { + if (typeof args[0] === 'string' && args[0].includes('quirks mode')) return; + origWarn.apply(console, args); + }; + md.use(texmath, { engine: katex, delimiters: 'dollars', katexOptions: { macros: { "\\RR": "\\mathbb{R}" } } }); + console.warn = origWarn; +} + +export function getAssets() { + return [ + { + url: 'https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css', + type: 'css', + location: 'head', + // Conditional loading (new in 0.8.7): only inject KaTeX's stylesheet + // on pages that actually have rendered math (KaTeX emits `class="katex"` + // on every formula and `class="katex-display"` on display math). On + // pages with no math the CSS request is skipped entirely, saving the + // ~30 KB katex.min.css fetch plus the render cost on mobile. + condition: { pageHtmlMatches: ['class="katex"', 'class="katex-display"'] } + } + ]; +} \ No newline at end of file diff --git a/packages/plugins/math/tsconfig.json b/packages/plugins/math/tsconfig.json new file mode 100644 index 0000000..7befc89 --- /dev/null +++ b/packages/plugins/math/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/plugins/mermaid/LICENSE b/packages/plugins/mermaid/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/mermaid/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/mermaid/README.md b/packages/plugins/mermaid/README.md new file mode 100644 index 0000000..62a0b20 --- /dev/null +++ b/packages/plugins/mermaid/README.md @@ -0,0 +1,23 @@ +# @docmd/plugin-mermaid + +Adds [Mermaid.js](https://mermaid.js.org/) diagram support to your docmd site - write flowcharts, sequence diagrams, and more directly in Markdown using a standard code fence. Bundled with `@docmd/core`. + +````md +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` +```` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/mermaid/package.json b/packages/plugins/mermaid/package.json new file mode 100644 index 0000000..2f67eb2 --- /dev/null +++ b/packages/plugins/mermaid/package.json @@ -0,0 +1,67 @@ +{ + "name": "@docmd/plugin-mermaid", + "version": "0.8.12", + "description": "Mermaid diagram support plugin for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "docmd": { + "key": "mermaid", + "kind": "plugin", + "displayName": "Mermaid", + "tagline": "Mermaid.js diagram support for docmd.", + "capabilities": [ + "markdown", + "assets" + ] + }, + "scripts": { + "build": "tsc && esbuild src/client.ts --bundle --outfile=dist/init-mermaid.js --format=esm --platform=browser --minify --external:https://*", + "test": "tsx --test tests/*.test.ts", + "test:watch": "tsx --test --watch tests/*.test.ts" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/node": "^24.13.3", + "esbuild": "^0.28.1", + "tsx": "^4.23.0" + }, + "keywords": [ + "docmd", + "plugin", + "mermaid", + "diagrams", + "flowchart", + "sequence", + "class", + "graph", + "mindmap", + "syntax", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/mermaid/src/client.ts b/packages/plugins/mermaid/src/client.ts new file mode 100644 index 0000000..edaa3d8 --- /dev/null +++ b/packages/plugins/mermaid/src/client.ts @@ -0,0 +1,271 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +// @ts-expect-error Deno/Browser compatible CDN import that TypeScript cannot natively resolve +import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; +import { fixSvgNamespaces } from './svg-utils.js'; + +(async function () { + 'use strict'; + let counter = 0; + let iconsRegistered = false; + + + function getTheme() { + return document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'default'; + } + + async function renderAll() { + if (!iconsRegistered) { + try { + mermaid.registerIconPacks([ + { + name: 'icon', + loader: () => fetch('https://unpkg.com/@iconify-json/lucide@1/icons.json').then((res) => res.json()), + }, + ]); + iconsRegistered = true; + } catch (e) { + console.warn('Mermaid icon registration failed:', e); + } + } + mermaid.initialize({ startOnLoad: false, theme: getTheme(), securityLevel: 'loose' }); + + // Ensure DOM is settled + await new Promise(resolve => requestAnimationFrame(resolve)); + + const elements = document.querySelectorAll('.mermaid:not([data-processed="true"])') as NodeListOf; + + for (const el of elements) { + if (!el.dataset.original) el.dataset.original = el.textContent || ''; + const code = el.dataset.original; + + + try { + const id = `mermaid-svg-${counter++}`; + const { svg } = await mermaid.render(id, code); + + // Apply container class first to establish styling context + el.classList.add('docmd-mermaid-container'); + el.innerHTML = ''; + + const parser = new DOMParser(); + const wrapper = document.createElement('div'); + wrapper.className = 'mermaid-wrapper'; + // Fix missing xmlns:xlink declaration โ€” mermaid.render() omits it (unlike + // mermaid.run()) causing DOMParser to return for diagrams + // that use xlink:href, most notably C4Context person icons. + const svgDoc = parser.parseFromString(fixSvgNamespaces(svg), 'image/svg+xml'); + wrapper.appendChild(svgDoc.documentElement); + + const svgEl = wrapper.querySelector('svg'); + + if (svgEl) { + // Remove natural constraints to prevent label clipping when scaled via CSS transform + svgEl.removeAttribute('style'); + svgEl.style.maxWidth = 'none'; + svgEl.style.maxHeight = 'none'; + svgEl.style.transformOrigin = 'center'; + svgEl.style.display = 'block'; + svgEl.style.margin = '0 auto'; + } + + // Control buttons - appended to the OUTER container so they stay fixed! + const controls = document.createElement('div'); + controls.className = 'mermaid-controls'; + + const btnStyle = 'background: var(--bg-color, #fff); border: 1px solid var(--border-color, #e4e4e7); border-radius: 6px; padding: 4px; cursor: pointer; display: flex; align-items: center; justify-content: center; box-shadow: 0 1px 3px rgba(0,0,0,0.08); width: 28px; height: 28px; color: var(--text-muted, #71717a);'; + + const createBtn = (title: string, svgContent: string) => { + const btn = document.createElement('button'); + btn.style.cssText = btnStyle; + btn.title = title; + const btnSvgDoc = parser.parseFromString(svgContent, 'image/svg+xml'); + btn.appendChild(btnSvgDoc.documentElement); + return btn; + }; + + const zoomInBtn = createBtn('Zoom in', ''); + const zoomOutBtn = createBtn('Zoom out', ''); + const resetBtn = createBtn('Reset view', ''); + const fullscreenBtn = createBtn('Fullscreen', ''); + const upBtn = createBtn('Pan Up', ''); + const downBtn = createBtn('Pan Down', ''); + const leftBtn = createBtn('Pan Left', ''); + const rightBtn = createBtn('Pan Right', ''); + controls.style.gap = '4px'; + + const row1 = document.createElement('div'); + row1.style.cssText = 'display: flex; gap: 4px;'; + row1.appendChild(zoomInBtn); + row1.appendChild(zoomOutBtn); + row1.appendChild(resetBtn); + row1.appendChild(fullscreenBtn); + + const row2 = document.createElement('div'); + row2.style.cssText = 'display: flex; gap: 4px;'; + row2.appendChild(upBtn); + row2.appendChild(downBtn); + row2.appendChild(leftBtn); + row2.appendChild(rightBtn); + + controls.appendChild(row1); + controls.appendChild(row2); + + wrapper.appendChild(controls); + el.appendChild(wrapper); + + let scale = 1; + let translateX = 0; + let translateY = 0; + let isDragging = false; + let startX = 0; + let startY = 0; + + const updateTransform = (skipTransition = false) => { + if (svgEl) { + svgEl.style.transform = `translate(${translateX}px, ${translateY}px) scale(${scale})`; + svgEl.style.transition = (isDragging || skipTransition) ? 'none' : 'transform 0.2s cubic-bezier(0.2, 0, 0, 1)'; + } + }; + + const initView = () => { + if (!svgEl) return; + scale = 1; + translateX = 0; + translateY = 0; + + // Let the SVG naturally size itself with max constraints + svgEl.style.width = ''; + svgEl.style.height = ''; + svgEl.style.maxWidth = '100%'; + svgEl.style.maxHeight = '420px'; + svgEl.style.transformOrigin = 'center'; + wrapper.style.height = 'auto'; // Remove any dynamic height + + updateTransform(true); + }; + + initView(); + + const pan = (dx: number, dy: number) => { + translateX += dx; + translateY += dy; + updateTransform(); + }; + + const zoom = (factor: number) => { + // Simple zoom from center + scale *= factor; + updateTransform(); + }; + + zoomInBtn.addEventListener('click', () => zoom(1.25)); + zoomOutBtn.addEventListener('click', () => zoom(1 / 1.25)); + upBtn.addEventListener('click', () => pan(0, 50)); + downBtn.addEventListener('click', () => pan(0, -50)); + leftBtn.addEventListener('click', () => pan(50, 0)); + rightBtn.addEventListener('click', () => pan(-50, 0)); + resetBtn.addEventListener('click', () => { initView(); }); + + fullscreenBtn.addEventListener('click', () => { + if (!document.fullscreenElement) { + wrapper.requestFullscreen().catch(err => console.warn(err)); + } else { + document.exitFullscreen(); + } + }); + + document.addEventListener('fullscreenchange', () => { + if (!svgEl) return; + if (document.fullscreenElement === wrapper) { + wrapper.classList.add('mermaid-fullscreen'); + svgEl.style.maxWidth = 'calc(100vw - 40px)'; + svgEl.style.maxHeight = 'calc(100vh - 40px)'; + svgEl.style.width = '100%'; + svgEl.style.height = '100%'; + scale = 1; + translateX = 0; + translateY = 0; + updateTransform(); + } else { + wrapper.classList.remove('mermaid-fullscreen'); + initView(); + } + }); + + wrapper.addEventListener('mousedown', (e) => { + isDragging = true; + startX = e.clientX - translateX; + startY = e.clientY - translateY; + wrapper.style.cursor = 'grabbing'; + }); + + window.addEventListener('mousemove', (e) => { + if (!isDragging) return; + e.preventDefault(); // Prevent text selection + translateX = e.clientX - startX; + translateY = e.clientY - startY; + updateTransform(); + }); + + const stopDrag = () => { + if (!isDragging) return; + isDragging = false; + wrapper.style.cursor = 'grab'; + updateTransform(); // Trigger transition if needed + }; + + window.addEventListener('mouseup', stopDrag); + wrapper.addEventListener('mouseleave', stopDrag); + + el.setAttribute('data-processed', 'true'); + + } catch (err) { + console.error(err); + el.setAttribute('data-processed', 'error'); + } + } + } + + // 1. Initial Load + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', renderAll); + } else { + renderAll(); + } + + // 2. SPA Navigation Load + document.addEventListener('docmd:page-mounted', renderAll); + + // 3. Render when a hidden Tab or Collapsible is opened + document.addEventListener('click', (e) => { + const target = e.target as HTMLElement | null; + if (target?.closest('.docmd-tabs-nav-item, .collapsible-summary')) { + setTimeout(renderAll, 50); + } + }); + + // 4. Theme Toggle + const themeObserver = new MutationObserver((mutations) => { + for (const m of mutations) { + if (m.attributeName === 'data-theme') { + document.querySelectorAll('.mermaid').forEach(el => el.removeAttribute('data-processed')); + renderAll(); + } + } + }); + themeObserver.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] }); + +})(); \ No newline at end of file diff --git a/packages/plugins/mermaid/src/index.ts b/packages/plugins/mermaid/src/index.ts new file mode 100644 index 0000000..c01e541 --- /dev/null +++ b/packages/plugins/mermaid/src/index.ts @@ -0,0 +1,55 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import { fileURLToPath } from 'url'; +import type { PluginDescriptor } from '@docmd/api'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); + +export const plugin: PluginDescriptor = { + name: 'mermaid', + version: '0.8.12', + capabilities: ['markdown', 'assets'] +}; + +export function markdownSetup(md: any) { + const defaultFence = md.renderer.rules.fence; + md.renderer.rules.fence = (tokens, idx, options, env, self) => { + const token = tokens[idx]; + const info = token.info.trim(); + if (info === 'mermaid') { + return `

    ${md.utils.escapeHtml(token.content)}
    \n`; + } + return defaultFence(tokens, idx, options, env, self); + }; +} + +export function getAssets() { + return [ + { + src: path.join(__dirname, 'init-mermaid.js'), + dest: 'assets/js/init-mermaid.js', + type: 'js', + location: 'body', + attributes: { type: 'module' }, + // Conditional loading (new in 0.8.7): only inject the init script on + // pages whose rendered HTML actually contains a mermaid diagram block. + // This avoids the ~500 KB mermaid library CDN fetch on every other + // page of the site. + condition: { pageHtmlMatches: 'class="mermaid"' } + } + ]; +} \ No newline at end of file diff --git a/packages/plugins/mermaid/src/svg-utils.ts b/packages/plugins/mermaid/src/svg-utils.ts new file mode 100644 index 0000000..8e1ab85 --- /dev/null +++ b/packages/plugins/mermaid/src/svg-utils.ts @@ -0,0 +1,24 @@ +/** + * SVG utility functions for the mermaid plugin client. + * Extracted for testability โ€” pure string/DOM operations, no browser globals. + */ + +/** + * Ensures an SVG string has the required XML namespace declarations + * for all namespace prefixes it uses. + * + * Problem: mermaid.render() returns SVG via innerHTML serialization which + * omits xmlns:xlink even when xlink:href attributes are present. + * DOMParser.parseFromString(svg, 'image/svg+xml') is a strict XML parser + * and fails with a on undeclared namespace prefixes. + * + * Affected diagram types: any that use xlink:href โ€” most notably C4Context, + * which always adds person icons via . + * (mermaid.run() includes xmlns:xlink; only mermaid.render() omits it.) + */ +export function fixSvgNamespaces(svg: string): string { + if (svg.includes('xlink:') && !svg.includes('xmlns:xlink')) { + return svg.replace(/( element. + * This causes C4Context diagrams to render as a blank white box. + * + * mermaid.run() (live editor) does include xmlns:xlink, so it works fine. + * Only mermaid.render() (static site via init-mermaid.js) is affected. + * + * Run with: `pnpm test` (uses tsx + node:test โ€” no vitest, no happy-dom). + * + * NOTE: The 3 DOMParser/`document` tests that were here under the + * "DOMParser integration" describe block were dropped when we moved off + * happy-dom. Their own comment already acknowledged: "happy-dom is lenient + * and parses it anyway, so we cannot replicate that specific Chrome failure + * here. The string-level tests above are the authoritative verification that + * the fix adds the declaration that Chrome requires." + */ + +import { describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import { fixSvgNamespaces } from '../src/svg-utils.js'; + +// Minimal SVG that mermaid.render() produces for a typical C4Context diagram. +// Critical detail: has xlink:href (from person icon elements) but +// NO xmlns:xlink declaration โ€” this is what mermaid.render() actually outputs. +const C4_SVG_WITHOUT_XMLNS = ` + + + + + Customer + +`; + +// Same SVG but already has xmlns:xlink โ€” should not be modified +const C4_SVG_WITH_XMLNS = ` + + + + +`; + +// Flowchart SVG โ€” no xlink: usage at all, should not be modified +const FLOWCHART_SVG_NO_XLINK = ` + + + + Start + +`; + +// Flowchart with clickable links โ€” also uses xlink:href (less common but possible) +const FLOWCHART_SVG_WITH_LINK = ` + + + +`; + +describe('fixSvgNamespaces', () => { + describe('C4Context person icon (root cause scenario)', () => { + it('adds xmlns:xlink when SVG uses xlink:href without declaration', () => { + const fixed = fixSvgNamespaces(C4_SVG_WITHOUT_XMLNS); + + assert.ok(fixed.includes('xmlns:xlink="http://www.w3.org/1999/xlink"')); + }); + + it('places xmlns:xlink inside the opening tag', () => { + const fixed = fixSvgNamespaces(C4_SVG_WITHOUT_XMLNS); + + // Must be on , not somewhere else + assert.match(fixed, /]+xmlns:xlink="http:\/\/www\.w3\.org\/1999\/xlink"/); + }); + + it('preserves all existing SVG content unchanged', () => { + const fixed = fixSvgNamespaces(C4_SVG_WITHOUT_XMLNS); + + assert.ok(fixed.includes('xlink:href="data:image/png;base64,iVBORw0KGgo="')); + assert.ok(fixed.includes('xmlns="http://www.w3.org/2000/svg"')); + assert.ok(fixed.includes('viewBox="0 0 650 400"')); + assert.ok(fixed.includes('Customer')); + }); + }); + + describe('idempotency โ€” does not break already-valid SVG', () => { + it('returns SVG unchanged when xmlns:xlink is already declared', () => { + const fixed = fixSvgNamespaces(C4_SVG_WITH_XMLNS); + + assert.equal(fixed, C4_SVG_WITH_XMLNS); + }); + + it('does not duplicate xmlns:xlink when called twice', () => { + const fixed = fixSvgNamespaces(fixSvgNamespaces(C4_SVG_WITHOUT_XMLNS)); + + const count = (fixed.match(/xmlns:xlink/g) ?? []).length; + assert.equal(count, 1); + }); + }); + + describe('non-C4 diagrams โ€” no false positives', () => { + it('returns flowchart SVG unchanged when no xlink: is used', () => { + const fixed = fixSvgNamespaces(FLOWCHART_SVG_NO_XLINK); + + assert.equal(fixed, FLOWCHART_SVG_NO_XLINK); + assert.ok(!fixed.includes('xmlns:xlink')); + }); + + it('adds xmlns:xlink for flowchart with clickable links (also uses xlink:href)', () => { + const fixed = fixSvgNamespaces(FLOWCHART_SVG_WITH_LINK); + + assert.ok(fixed.includes('xmlns:xlink="http://www.w3.org/1999/xlink"')); + }); + }); +}); diff --git a/packages/plugins/mermaid/tsconfig.json b/packages/plugins/mermaid/tsconfig.json new file mode 100644 index 0000000..16330b6 --- /dev/null +++ b/packages/plugins/mermaid/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "src/client.ts"] +} \ No newline at end of file diff --git a/packages/plugins/okf/LICENSE b/packages/plugins/okf/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/okf/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/okf/README.md b/packages/plugins/okf/README.md new file mode 100644 index 0000000..d8fe898 --- /dev/null +++ b/packages/plugins/okf/README.md @@ -0,0 +1,90 @@ +# @docmd/plugin-okf + +Generates an [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) (OKF) bundle at build time so your documentation is consumable by AI agents โ€” Gemini, Claude, GPT, Cursor, and any tool that speaks the vendor-neutral OKF spec. + +OKF represents organisational knowledge as a directory of markdown files with YAML frontmatter, plus a typed manifest (`okf.yaml`), an interactive graph viewer, and a machine-readable bundle summary. The bundle sits next to your site (e.g. `site/okf/`) so agents can be pointed at it directly. + +```js +// docmd.config.json + +{ + "plugins": { + "okf": { + // config options, okf is enabled by default + } + } +} +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Output structure + +``` +site/okf/ # Always emitted +โ”œโ”€โ”€ okf.yaml # Typed manifest (bundle summary) +โ”œโ”€โ”€ index.md # Karpathy-style catalog grouped by type +โ”œโ”€โ”€ concepts/ +โ”‚ โ””โ”€โ”€ .md # One markdown file per page +โ””โ”€โ”€ _meta/ + โ”œโ”€โ”€ bundle.json # JSON mirror of okf.yaml + โ””โ”€โ”€ lint-report.txt # Warnings produced during generation + +# Emitted only when `plugins.okf.graph: true` +โ”œโ”€โ”€ graph/ # Interactive viewer (open /okf/graph/) +โ”‚ โ”œโ”€โ”€ index.html # Force-directed graph viewer +โ”‚ โ”œโ”€โ”€ graph.json # Graph data (nodes + edges) +โ”‚ โ”œโ”€โ”€ graph.js # Viewer runtime (vanilla, no CDN deps) +โ”‚ โ””โ”€โ”€ graph.css # Viewer styles (theme-aware) +``` + +Each concept file carries the OKF-required `type` field in frontmatter plus the original markdown body verbatim, so an agent can both navigate the manifest and read full pages. + +## Options + +| Option | Type | Default | Description | +|---|---|---|---| +| `outputDir` | `string` | `'okf'` | Bundle directory, relative to the site output. | +| `bundleName` | `string` | slugified `config.title` | Name used inside `okf.yaml` and the graph viewer title. | +| `defaultType` | `string` | `'concept'` | Type assigned to pages with no explicit type. | +| `typeField` | `string` | `'type'` | Frontmatter field name for OKF type. | +| `warnOnMissingType` | `boolean` | `true` | Emit a TUI warning for pages that fell back to `defaultType`. | +| `includeFullMarkdown` | `boolean` | `true` | Copy raw `.md` body into each concept file. | +| `graph` | `boolean` | `false` | Emit a `graph/` subdirectory containing `index.html` + `graph.js` + `graph.css` + `graph.json`. Opt-in since 0.8.8 โ€” the OKF spec does not require a viewer, and shipping extra files by default adds noise to a clean bundle. The viewer is reachable at `/okf/graph/` without a custom filename, and fetches `graph.json` from the same directory at runtime, so `file://` also works. | +| `localeStrategy` | `'default-only' \| 'folders' \| 'mixed' \| 'latest-only'` | `'default-only'` | Single-locale by default (the bundle contains only pages in the default locale). Set to `'folders'` to nest concepts by locale id when i18n is enabled, or `'mixed'` / `'latest-only'` for the other strategies. | +| `versionStrategy` | `'folders' \| 'mixed' \| 'latest-only'` | `'latest-only'` | Nest concepts by version id when versioning is enabled. | +| `excludePatterns` | `string[]` | `[]` | Additional glob patterns to skip on top of `frontmatter.noindex` / `frontmatter.okf === false`. | + +### Per-page opt-out + +Pages can opt out of the OKF bundle in two ways: + +```markdown +--- +noindex: true # also excludes from sitemap, llms.txt, etc. +--- + +--- +okf: false # only excludes from the OKF bundle +--- +``` + +### Type resolution precedence + +For every page the plugin picks a type with this precedence: + +1. `frontmatter.okf.type` (nested) +2. `frontmatter.type` (top-level) +3. `frontmatter.okfType` (legacy) +4. Path-prefix inference (e.g. `/guides/foo` โ†’ `guide`) +5. `defaultType` (with a warning if `warnOnMissingType`) + +The path-prefix map covers `guides/`, `api/`, `reference/`, `concepts/`, `runbooks/`, `datasets/`, `metrics/`, and `tables/`. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/okf/package.json b/packages/plugins/okf/package.json new file mode 100644 index 0000000..64640ba --- /dev/null +++ b/packages/plugins/okf/package.json @@ -0,0 +1,63 @@ +{ + "name": "@docmd/plugin-okf", + "version": "0.8.12", + "description": "Generate an Open Knowledge Format (OKF) bundle from your docmd site for AI agent consumption.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "docmd": { + "key": "okf", + "kind": "plugin", + "displayName": "OKF", + "tagline": "Open Knowledge Format (OKF) bundle generator for AI-agent consumption.", + "capabilities": [ + "post-build" + ] + }, + "scripts": { + "build": "tsc -p tsconfig.build.json", + "test": "tsx --test tests/*.test.ts" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/node": "^24.13.3", + "tsx": "^4.23.0" + }, + "keywords": [ + "docmd", + "plugin", + "okf", + "open-knowledge-format", + "ai", + "agents", + "google", + "knowledge-graph", + "documentation", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/okf/src/content.ts b/packages/plugins/okf/src/content.ts new file mode 100644 index 0000000..28ef8b0 --- /dev/null +++ b/packages/plugins/okf/src/content.ts @@ -0,0 +1,100 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + * + * Concept-type resolution + content scanning helpers used during the + * OKF bundle build. + * + * `resolveType` decides what OKF type a page belongs to: + * 1. Explicit `okf.type` in frontmatter (nested OKF block) + * 2. Top-level `type` (or a custom field set via `typeField` config) + * 3. `okfType` (legacy alias kept for back-compat) + * 4. Path-based inference (e.g. `/api/...` โ†’ 'api') + * 5. The configured `defaultType` (with `fallback: true` so the + * caller can warn that the page is untyped) + * + * `slugify` / `matchesPattern` / `extractInternalLinks` are the + * building blocks the bundle writer uses for cross-linking. + */ + +const PATH_TYPE_MAP: Array<[RegExp, string]> = [ + [/^\/guides\//, 'guide'], + [/^\/api\//, 'api'], + [/^\/reference\//, 'reference'], + [/^\/concepts\//, 'concept'], + [/^\/runbooks\//, 'runbook'], + [/^\/datasets\//, 'dataset'], + [/^\/metrics\//, 'metric'], + [/^\/tables\//, 'table'] +]; + +export function slugify(input: string): string { + return String(input || '').toLowerCase() + .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'bundle'; +} + +export function resolveType( + fm: any, + pathname: string, + defaultType: string, + typeField = 'type' +): { type: string; fallback: boolean } { + const fmType = (fm?.okf?.type) + || (typeField && typeField !== 'type' ? fm?.[typeField] : null) + || (typeField === 'type' ? fm?.type : null) + || fm?.okfType + || null; + if (fmType) return { type: String(fmType), fallback: false }; + for (const [re, t] of PATH_TYPE_MAP) if (re.test(pathname)) return { type: t, fallback: false }; + return { type: defaultType, fallback: true }; +} + +/** + * Glob-style pattern match used by the exclude filter. Supports `*` + * (any chars) and `?` (single char). Falls back to plain `includes` + * when the pattern doesn't compile (so user-supplied patterns never + * crash the build). + */ +export function matchesPattern(text: string, patterns: string[]): boolean { + if (!patterns || !patterns.length) return false; + for (const p of patterns) { + if (!p) continue; + try { + const re = new RegExp('^' + p.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$'); + if (re.test(text)) return true; + } catch { if (text.includes(p)) return true; } + } + return false; +} + +/** + * Scans a markdown body for internal `[label](slug)` links and + * returns the slugs of any that resolve to a known concept in the + * bundle. External URLs, anchor-only links, and self-references + * are skipped. + */ +export function extractInternalLinks(md: string, ownSlug: string, known: Set): string[] { + const out: string[] = []; + if (!md) return out; + const re = /\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g; + let m: RegExpExecArray | null; + while ((m = re.exec(md)) !== null) { + let href = m[1].trim(); + if (!href || href.startsWith('#') || /^[a-z][a-z0-9+.-]*:/i.test(href)) continue; + href = href.split('#')[0]; + if (!href) continue; + const slug = slugify(href.replace(/\.md$/i, '')); + if (!slug || slug === ownSlug) continue; + if (known.has(slug)) out.push(slug); + } + return out; +} \ No newline at end of file diff --git a/packages/plugins/okf/src/graph-assets.ts b/packages/plugins/okf/src/graph-assets.ts new file mode 100644 index 0000000..6390c65 --- /dev/null +++ b/packages/plugins/okf/src/graph-assets.ts @@ -0,0 +1,41 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + * + * Barrel module for the OKF graph viewer. + * + * Re-exports the three concerns of the viewer (CSS, runtime JS, HTML + * shell) so consumers can `import { GRAPH_CSS, GRAPH_JS, graphHtml }` + * from a single path. The implementation lives in: + * + * - `graph-styles.ts` โ€” the flat, hairline-bordered stylesheet + * - `graph-runtime.ts` โ€” the IIFE runtime that drives the SVG + * - `graph-template.ts` โ€” the HTML shell + type-colour palette + * + * `GRAPH_JS` is a function (not a constant) so the runtime can read + * the TypeScript-owned `TYPE_COLORS` map at build time and inline it + * into the generated `graph.js` file. + */ + +import { graphRuntime } from './graph-runtime.js'; + +export { GRAPH_CSS } from './graph-styles.js'; +export { TYPE_COLORS, graphHtml } from './graph-template.js'; + +/** + * Convenience: the runtime as a pre-rendered string, ready to write + * to disk. Splits cleanly from `GRAPH_CSS` and `graphHtml` so each + * downstream artifact stays self-contained. + */ +export function GRAPH_JS(): string { + return graphRuntime(); +} \ No newline at end of file diff --git a/packages/plugins/okf/src/graph-runtime.ts b/packages/plugins/okf/src/graph-runtime.ts new file mode 100644 index 0000000..65d30e3 --- /dev/null +++ b/packages/plugins/okf/src/graph-runtime.ts @@ -0,0 +1,567 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + * + * Self-contained runtime for the OKF graph viewer. + * + * The viewer reads `graph.json` from the same directory and renders a + * force-directed SVG layout with: + * - Pan (drag empty space) and zoom (wheel / buttons) + * - Hover highlights the focused node + neighbours; dims the rest + * - Live search box that filters nodes, labels, and links + * - Drag a node to pin it; double-click to release + * - Side panel with details + clickable list of connected nodes + * + * No external dependencies: D3-style forces are implemented inline + * (charge + link + center + collide, alpha-decay cooled). + * + * The TYPE_COLORS map is injected at build time so the runtime has no + * hard-coded colour knowledge โ€” the TypeScript module owns the palette. + */ + +import { TYPE_COLORS } from './graph-template.js'; + +/** + * Returns the viewer runtime as a single inline IIFE string. + * The TYPE_COLORS object is serialised into the script body so the + * generated `graph.js` file is fully self-contained (no second fetch, + * no module loader, no relative path dance). + */ +export function graphRuntime(): string { + return `(function(){ + 'use strict'; + + var NS = 'http://www.w3.org/2000/svg'; + var TYPE_COLORS = ${JSON.stringify(TYPE_COLORS)}; + + // โ”€โ”€ DOM refs โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + var stage = document.querySelector('.okf-stage'); + var panel = document.getElementById('okf-panel'); + var statusEl = document.querySelector('.okf-title .okf-sub'); + var searchInput = document.querySelector('.okf-search input'); + var zoomIn = document.querySelector('[data-zoom="in"]'); + var zoomOut = document.querySelector('[data-zoom="out"]'); + var zoomReset = document.querySelector('[data-zoom="reset"]'); + if (!stage || !panel) return; + + function setStatus(text) { if (statusEl) statusEl.textContent = text; } + + // โ”€โ”€ security: scheme allow-list for hrefs โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + function safeHref(u) { + if (!u) return '#'; + if (/^(?:https?|mailto|tel|repo|dashboard|docs|wp-admin):/i.test(u)) return u; + if (u.charAt(0) === '/') return u; + return '#'; + } + + // โ”€โ”€ data prep โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + function prepareData(raw) { + var nodes = (raw.nodes || []).map(function (n) { + return Object.assign({}, n, { x: 0, y: 0, vx: 0, vy: 0 }); + }); + var index = {}; + nodes.forEach(function (n) { index[n.id] = n; }); + + var links = (raw.links || []) + .map(function (l) { + var s = (typeof l.source === 'object') ? l.source.id : l.source; + var t = (typeof l.target === 'object') ? l.target.id : l.target; + return { source: s, target: t }; + }) + .filter(function (l) { + return index[l.source] && index[l.target] && l.source !== l.target; + }); + + var degree = {}; + links.forEach(function (l) { + degree[l.source] = (degree[l.source] || 0) + 1; + degree[l.target] = (degree[l.target] || 0) + 1; + }); + nodes.forEach(function (n) { n.degree = degree[n.id] || 0; }); + + var adj = {}; + links.forEach(function (l) { + (adj[l.source] = adj[l.source] || []).push(l.target); + (adj[l.target] = adj[l.target] || []).push(l.source); + }); + return { nodes: nodes, links: links, index: index, adj: adj }; + } + + // โ”€โ”€ force simulation (charge + link + center + collide) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + function createSimulation(data, width, height) { + var nodes = data.nodes, links = data.links; + var cx = width / 2, cy = height / 2; + var LINK_DIST = 90, LINK_STRENGTH = 0.4; + var CHARGE = -260, COLLIDE_PAD = 6; + var alpha = 1, alphaDecay = 0.022; + var minAlpha = 0.001, velDecay = 0.4; + var running = true; + var tickFn = null, onEndFn = null; + + // initial circular layout โ€” stable starting point, no random jitter + nodes.forEach(function (n, i) { + var angle = (i / Math.max(1, nodes.length)) * Math.PI * 2; + var radius = Math.min(width, height) * 0.35; + n.x = cx + Math.cos(angle) * radius; + n.y = cy + Math.sin(angle) * radius; + }); + + function step() { + if (alpha < minAlpha) { + alpha = 0; + running = false; + if (onEndFn) onEndFn(); + return; + } + // center pull + nodes.forEach(function (n) { + n.vx += (cx - n.x) * 0.01 * alpha; + n.vy += (cy - n.y) * 0.01 * alpha; + }); + // pairwise charge repulsion (O(n^2) โ€” fine up to ~200 nodes) + for (var i = 0; i < nodes.length; i++) { + var a = nodes[i]; + for (var j = i + 1; j < nodes.length; j++) { + var b = nodes[j]; + var dx = a.x - b.x, dy = a.y - b.y; + var d2 = dx * dx + dy * dy || 0.01; + var d = Math.sqrt(d2); + var force = (CHARGE * alpha) / d2; + var fx = (dx / d) * force, fy = (dy / d) * force; + a.vx += fx; a.vy += fy; + b.vx -= fx; b.vy -= fy; + } + } + // link springs + links.forEach(function (l) { + var s = data.index[l.source], t = data.index[l.target]; + if (!s || !t) return; + var dx = t.x - s.x, dy = t.y - s.y; + var d = Math.sqrt(dx * dx + dy * dy) || 0.01; + var diff = (d - LINK_DIST) / d * LINK_STRENGTH * alpha; + var fx = dx * diff, fy = dy * diff; + s.vx += fx; s.vy += fy; + t.vx -= fx; t.vy -= fy; + }); + // collide (resolve overlap) + for (var k = 0; k < nodes.length; k++) { + var p = nodes[k]; + var pr = (6 + Math.min(8, p.degree)) + COLLIDE_PAD; + for (var m = k + 1; m < nodes.length; m++) { + var q = nodes[m]; + var qr = (6 + Math.min(8, q.degree)) + COLLIDE_PAD; + var dx2 = p.x - q.x, dy2 = p.y - q.y; + var d22 = Math.sqrt(dx2 * dx2 + dy2 * dy2) || 0.01; + var min = pr + qr; + if (d22 < min) { + var push = (min - d22) / d22 * 0.5 * alpha; + p.x += dx2 * push; p.y += dy2 * push; + q.x -= dx2 * push; q.y -= dy2 * push; + } + } + } + // integrate + damp + clamp + nodes.forEach(function (n) { + n.vx *= (1 - velDecay); n.vy *= (1 - velDecay); + n.x += n.vx; n.y += n.vy; + var r = 12; + if (n.x < r) { n.x = r; n.vx *= -0.5; } + if (n.x > width - r) { n.x = width - r; n.vx *= -0.5; } + if (n.y < r) { n.y = r; n.vy *= -0.5; } + if (n.y > height - r) { n.y = height - r; n.vy *= -0.5; } + }); + alpha -= alphaDecay; + if (tickFn) tickFn(); + if (running) requestAnimationFrame(step); + } + requestAnimationFrame(step); + + return { + stop: function () { running = false; }, + restart: function () { running = true; alpha = 1; requestAnimationFrame(step); }, + alpha: function () { return alpha; }, + onTick: function (fn) { tickFn = fn; }, + onEnd: function (fn) { onEndFn = fn; }, + data: data + }; + } + + // โ”€โ”€ render โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + function render(data) { + if (!data.nodes.length) { + setStatus('No concepts to graph yet.'); + renderEmptyPanel(); + return; + } + + // legend + var legend = document.querySelector('.okf-legend ul'); + if (legend) { + legend.textContent = ''; + var present = {}; + data.nodes.forEach(function (n) { present[n.type || 'concept'] = true; }); + Object.keys(present).sort().forEach(function (t) { + var li = document.createElement('li'); + var dot = document.createElement('span'); + dot.className = 'dot'; + dot.style.background = TYPE_COLORS[t] || '#6b7280'; + li.appendChild(dot); + li.appendChild(document.createTextNode(t)); + legend.appendChild(li); + }); + } + + // SVG skeleton + stage.textContent = ''; + var svg = document.createElementNS(NS, 'svg'); + svg.setAttribute('preserveAspectRatio', 'xMidYMid meet'); + svg.classList.add('okf-graph'); + stage.appendChild(svg); + + var gRoot = document.createElementNS(NS, 'g'); + svg.appendChild(gRoot); + var gLinks = document.createElementNS(NS, 'g'); + var gNodes = document.createElementNS(NS, 'g'); + var gLabels = document.createElementNS(NS, 'g'); + gRoot.appendChild(gLinks); + gRoot.appendChild(gNodes); + gRoot.appendChild(gLabels); + + var linkEls = [], nodeEls = [], labelEls = []; + data.links.forEach(function (l) { + var el = document.createElementNS(NS, 'line'); + el.setAttribute('class', 'link'); + gLinks.appendChild(el); + linkEls.push({ el: el, link: l }); + }); + data.nodes.forEach(function (n) { + var el = document.createElementNS(NS, 'circle'); + el.setAttribute('class', 'node'); + el.setAttribute('fill', TYPE_COLORS[n.type] || '#6b7280'); + el.setAttribute('r', 5 + Math.min(6, n.degree)); + el.addEventListener('click', function (e) { + e.stopPropagation(); + showDetail(n); + }); + gNodes.appendChild(el); + var lbl = document.createElementNS(NS, 'text'); + lbl.setAttribute('class', 'label'); + lbl.textContent = n.title || n.id; + gLabels.appendChild(lbl); + labelEls.push({ el: lbl, node: n }); + + // hover โ†’ highlight neighbours, dim the rest + el.addEventListener('mouseenter', function () { + svg.classList.add('node-hover'); + var neighbours = new Set([n.id].concat(data.adj[n.id] || [])); + nodeEls.forEach(function (entry) { + entry.el.classList.toggle('faded', !neighbours.has(entry.node.id)); + }); + labelEls.forEach(function (entry) { + entry.el.classList.toggle('faded', !neighbours.has(entry.node.id)); + }); + linkEls.forEach(function (entry) { + var active = (entry.link.source === n.id || entry.link.target === n.id); + entry.el.classList.toggle('active', !!active); + entry.el.classList.toggle('link-faded', !active); + }); + }); + el.addEventListener('mouseleave', function () { + svg.classList.remove('node-hover'); + nodeEls.forEach(function (entry) { entry.el.classList.remove('faded'); }); + labelEls.forEach(function (entry) { entry.el.classList.remove('faded'); }); + linkEls.forEach(function (entry) { + entry.el.classList.remove('active'); + entry.el.classList.remove('link-faded'); + }); + }); + + nodeEls.push({ el: el, node: n }); + }); + + // zoom + pan + var transform = { x: 0, y: 0, k: 1 }; + function applyTransform() { + gRoot.setAttribute('transform', + 'translate(' + transform.x + ',' + transform.y + ') scale(' + transform.k + ')'); + } + function zoom(delta, cx, cy) { + var k = transform.k * (delta > 0 ? 1.2 : 1 / 1.2); + k = Math.max(0.2, Math.min(4, k)); + transform.x = cx - (cx - transform.x) * (k / transform.k); + transform.y = cy - (cy - transform.y) * (k / transform.k); + transform.k = k; + applyTransform(); + } + svg.addEventListener('wheel', function (e) { + e.preventDefault(); + var rect = svg.getBoundingClientRect(); + zoom(e.deltaY < 0 ? 1 : -1, e.clientX - rect.left, e.clientY - rect.top); + }, { passive: false }); + if (zoomIn) zoomIn.addEventListener('click', function () { + var r = svg.getBoundingClientRect(); + zoom(1, r.width / 2, r.height / 2); + }); + if (zoomOut) zoomOut.addEventListener('click', function () { + var r = svg.getBoundingClientRect(); + zoom(-1, r.width / 2, r.height / 2); + }); + if (zoomReset) zoomReset.addEventListener('click', function () { + transform.x = 0; transform.y = 0; transform.k = 1; + applyTransform(); + }); + + // pan (drag empty space) + var pan = null; + svg.addEventListener('pointerdown', function (e) { + if (e.target.closest('circle.node')) return; + pan = { x: e.clientX - transform.x, y: e.clientY - transform.y }; + svg.classList.add('dragging'); + svg.setPointerCapture(e.pointerId); + }); + svg.addEventListener('pointermove', function (e) { + if (!pan) return; + transform.x = e.clientX - pan.x; + transform.y = e.clientY - pan.y; + applyTransform(); + }); + svg.addEventListener('pointerup', function (e) { + pan = null; svg.classList.remove('dragging'); + try { svg.releasePointerCapture(e.pointerId); } catch (_) {} + }); + + // drag a node to pin it (double-click releases) + nodeEls.forEach(function (entry) { + var dragging = null; + entry.el.addEventListener('pointerdown', function (e) { + e.stopPropagation(); + dragging = e.pointerId; + entry.el.setPointerCapture(e.pointerId); + }); + entry.el.addEventListener('pointermove', function (e) { + if (dragging === null) return; + var pt = svg.createSVGPoint(); + pt.x = e.clientX; pt.y = e.clientY; + var ctm = gRoot.getScreenCTM(); + if (!ctm) return; + var local = pt.matrixTransform(ctm.inverse()); + entry.node.fx = local.x; entry.node.fy = local.y; + entry.node.x = local.x; entry.node.y = local.y; + sim && sim.restart(); + }); + entry.el.addEventListener('pointerup', function (e) { + if (dragging === null) return; + try { entry.el.releasePointerCapture(e.pointerId); } catch (_) {} + dragging = null; + }); + entry.el.addEventListener('dblclick', function (e) { + e.stopPropagation(); + entry.node.fx = null; entry.node.fy = null; + sim && sim.restart(); + }); + }); + + // sizing + simulation + function resize() { + var rect = svg.getBoundingClientRect(); + svg.setAttribute('viewBox', '0 0 ' + rect.width + ' ' + rect.height); + return { w: rect.width, h: rect.height }; + } + var size = resize(); + var sim = createSimulation(data, size.w, size.h); + + sim.onTick(function () { + for (var i = 0; i < linkEls.length; i++) { + var le = linkEls[i], l = le.link; + var s = data.index[l.source], t = data.index[l.target]; + if (!s || !t) continue; + le.el.setAttribute('x1', s.x); le.el.setAttribute('y1', s.y); + le.el.setAttribute('x2', t.x); le.el.setAttribute('y2', t.y); + } + for (var j = 0; j < nodeEls.length; j++) { + var ne = nodeEls[j]; + ne.el.setAttribute('cx', ne.node.x); + ne.el.setAttribute('cy', ne.node.y); + } + for (var k2 = 0; k2 < labelEls.length; k2++) { + var lb = labelEls[k2]; + var r = 5 + Math.min(6, lb.node.degree); + lb.el.setAttribute('x', lb.node.x); + lb.el.setAttribute('y', lb.node.y - r - 4); + } + }); + sim.onEnd(function () { setStatus(data.nodes.length + ' concepts ยท click for details ยท scroll to zoom'); }); + + window.addEventListener('resize', function () { + size = resize(); + applyTransform(); + sim.restart(); + }); + + // โ”€โ”€ search โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + if (searchInput) { + searchInput.addEventListener('input', function () { + var q = searchInput.value.trim().toLowerCase(); + if (!q) { + nodeEls.forEach(function (e) { e.el.classList.remove('faded'); e.el.style.display = ''; }); + labelEls.forEach(function (e) { e.el.classList.remove('faded'); e.el.style.display = ''; }); + linkEls.forEach(function (e) { + e.el.classList.remove('active'); + e.el.classList.remove('link-faded'); + e.el.style.display = ''; + }); + return; + } + var match = data.nodes.filter(function (n) { + return (n.title || n.id).toLowerCase().indexOf(q) >= 0 + || (n.type || '').toLowerCase().indexOf(q) >= 0; + }); + var matchedIds = new Set(match.map(function (n) { return n.id; })); + nodeEls.forEach(function (e) { + if (matchedIds.has(e.node.id)) { + e.el.classList.remove('faded'); e.el.style.display = ''; + } else { + e.el.classList.add('faded'); e.el.style.display = ''; + } + }); + labelEls.forEach(function (e) { + e.el.style.display = matchedIds.has(e.node.id) ? '' : 'none'; + }); + linkEls.forEach(function (e) { + var visible = matchedIds.has(e.link.source) && matchedIds.has(e.link.target); + e.el.style.display = visible ? '' : 'none'; + }); + }); + } + + renderEmptyPanel(); + } + + function renderEmptyPanel() { + while (panel.firstChild) panel.removeChild(panel.firstChild); + var p = document.createElement('p'); + p.className = 'okf-empty'; + p.textContent = 'Click a node to see details.'; + panel.appendChild(p); + } + + // โ”€โ”€ panel: render node details without innerHTML โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + function showDetail(n) { + while (panel.firstChild) panel.removeChild(panel.firstChild); + + var h = document.createElement('h2'); + h.textContent = n.title || n.id; + panel.appendChild(h); + + var type = document.createElement('span'); + type.className = 'okf-type'; + type.textContent = n.type || 'concept'; + panel.appendChild(type); + + var desc = document.createElement('p'); + if (n.description) { + desc.textContent = n.description; + } else { + var em = document.createElement('span'); + em.className = 'okf-empty'; + em.textContent = 'No description.'; + desc.appendChild(em); + } + panel.appendChild(desc); + + var meta = document.createElement('div'); + meta.className = 'okf-meta'; + if (n.path) { + var s1 = document.createElement('span'); + s1.textContent = 'path: ' + n.path; + meta.appendChild(s1); + } + if (typeof n.degree === 'number') { + var s2 = document.createElement('span'); + s2.textContent = 'connections: ' + n.degree; + meta.appendChild(s2); + } + if (meta.childNodes.length) panel.appendChild(meta); + + var actions = document.createElement('div'); + var a1 = document.createElement('a'); + a1.className = 'okf-btn'; + // Relative to the graph viewer (lives at /graph/). Concept + // files live at /concepts/, so step up one level first. + a1.href = '../concepts/' + encodeURIComponent(n.id) + '.md'; + a1.target = '_blank'; a1.rel = 'noopener noreferrer'; + a1.textContent = 'Open in OKF bundle'; + actions.appendChild(a1); + if (n.source) { + var a2 = document.createElement('a'); + a2.className = 'okf-btn'; + a2.href = safeHref(n.source); + a2.target = '_blank'; a2.rel = 'noopener noreferrer'; + a2.textContent = 'Open source page'; + actions.appendChild(a2); + } + panel.appendChild(actions); + + var neighbours = (window.__okfAdj && window.__okfAdj[n.id]) || []; + if (neighbours.length) { + var section = document.createElement('div'); + section.className = 'okf-section'; + var h3 = document.createElement('h3'); + h3.textContent = 'Connected to'; + section.appendChild(h3); + var ul = document.createElement('ul'); + ul.className = 'okf-conn-list'; + neighbours.forEach(function (id) { + var node = window.__okfIndex && window.__okfIndex[id]; + if (!node) return; + var li = document.createElement('li'); + var btn = document.createElement('button'); + btn.textContent = node.title || node.id; + btn.addEventListener('click', function () { showDetail(node); }); + li.appendChild(btn); + var typ = document.createElement('span'); + typ.className = 'okf-conn-type'; + typ.textContent = node.type || ''; + li.appendChild(typ); + ul.appendChild(li); + }); + section.appendChild(ul); + panel.appendChild(section); + } + } + + // โ”€โ”€ boot โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + var embedded = window.OKF_GRAPH; + if (embedded) { + var data = prepareData(embedded); + window.__okfAdj = data.adj; + window.__okfIndex = data.index; + render(data); + return; + } + setStatus('Loading graphโ€ฆ'); + fetch('graph.json', { cache: 'no-store' }) + .then(function (r) { + if (!r.ok) throw new Error('HTTP ' + r.status); + return r.json(); + }) + .then(function (raw) { + var data = prepareData(raw || { nodes: [], links: [] }); + window.__okfAdj = data.adj; + window.__okfIndex = data.index; + render(data); + }) + .catch(function (err) { + setStatus('Failed to load graph data: ' + err.message); + }); +})();`; +} \ No newline at end of file diff --git a/packages/plugins/okf/src/graph-styles.ts b/packages/plugins/okf/src/graph-styles.ts new file mode 100644 index 0000000..a3cafd7 --- /dev/null +++ b/packages/plugins/okf/src/graph-styles.ts @@ -0,0 +1,335 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + * + * Stylesheet for the OKF graph viewer. + * + * Design goals: + * - Flat surfaces, no gradients, no drop shadows on the canvas. + * - Hairline (1px) borders instead of fills or shadows for separation. + * - Type colour palette matches the type system: each OKF concept + * type gets a calm, distinct hue. Saturation is held back so + * dozens of nodes don't visually fight each other. + * - Dark mode uses pure neutral surfaces โ€” no tinted "panel" colour + * that drifts away from the canvas and breaks the illusion of + * a single workspace. + * + * The viewer ships as a single stylesheet inline in the HTML so + * nothing needs to be served separately. + */ + +export const GRAPH_CSS = `/* โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + OKF graph viewer โ€” minimal, flat, hairline-bordered + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +:root { + /* Light */ + --okf-bg: #ffffff; + --okf-fg: #0f172a; + --okf-muted: #64748b; + --okf-border: #e2e8f0; + --okf-border-soft: #f1f5f9; + --okf-link: #cbd5e1; + --okf-link-active: #0f172a; + --okf-node-stroke: #ffffff; + --okf-faded: #f1f5f9; + --okf-accent: #4f46e5; + --okf-accent-soft: #eef2ff; + --okf-input-bg: #ffffff; +} + +@media (prefers-color-scheme: dark) { + :root { + --okf-bg: #0a0a0a; + --okf-fg: #f5f5f5; + --okf-muted: #a1a1aa; + --okf-border: #27272a; + --okf-border-soft: #18181b; + --okf-link: #3f3f46; + --okf-link-active: #f5f5f5; + --okf-node-stroke: #0a0a0a; + --okf-faded: #18181b; + --okf-accent: #a5b4fc; + --okf-accent-soft: #1e1b4b; + --okf-input-bg: #18181b; + } +} + +* { box-sizing: border-box; } +html, body { + margin: 0; height: 100%; overflow: hidden; + font: 14px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; + color: var(--okf-fg); + background: var(--okf-bg); + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +.okf-app { display: flex; height: 100vh; } + +/* โ”€โ”€ Stage โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +.okf-stage { + position: relative; + flex: 1; min-width: 0; + overflow: hidden; + background: var(--okf-bg); +} +.okf-stage svg { display: block; width: 100%; height: 100%; cursor: grab; } +.okf-stage svg.dragging { cursor: grabbing; } +.okf-stage svg.node-hover { cursor: pointer; } + +/* โ”€โ”€ Toolbar (title + search) โ€” floating chip โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +.okf-toolbar { + position: absolute; top: 16px; left: 16px; right: 16px; + display: flex; align-items: center; gap: 12px; + z-index: 10; pointer-events: none; +} +.okf-toolbar > * { pointer-events: auto; } + +.okf-title { flex: 1; min-width: 0; } +.okf-title h1 { + margin: 0; + font-size: 13px; font-weight: 600; + letter-spacing: -0.01em; + white-space: nowrap; overflow: hidden; text-overflow: ellipsis; +} +.okf-title .okf-sub { + font-size: 11px; + color: var(--okf-muted); + margin-top: 2px; +} + +.okf-search { position: relative; flex: 0 1 260px; } +.okf-search input { + width: 100%; + padding: 7px 10px 7px 30px; + font: inherit; font-size: 13px; + color: var(--okf-fg); + background: var(--okf-input-bg); + border: 1px solid var(--okf-border); + border-radius: 6px; + outline: none; + transition: border-color .12s, box-shadow .12s; +} +.okf-search input::placeholder { color: var(--okf-muted); } +.okf-search input:focus { + border-color: var(--okf-accent); + box-shadow: 0 0 0 3px var(--okf-accent-soft); +} +.okf-search::before { + content: ""; position: absolute; + left: 9px; top: 50%; transform: translateY(-50%); + width: 14px; height: 14px; + background: currentColor; opacity: .4; + -webkit-mask: url("data:image/svg+xml;utf8,") center/contain no-repeat; + mask: url("data:image/svg+xml;utf8,") center/contain no-repeat; + pointer-events: none; +} + +/* โ”€โ”€ Legend โ€” flat dots, single column, low contrast โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +.okf-legend { + position: absolute; bottom: 16px; left: 16px; + z-index: 5; + font-size: 11px; + color: var(--okf-muted); + padding: 8px 10px; + background: var(--okf-bg); + border: 1px solid var(--okf-border); + border-radius: 6px; + max-width: 200px; +} +.okf-legend h3 { display: none; } /* implicit from layout */ +.okf-legend ul { + list-style: none; margin: 0; padding: 0; + display: flex; flex-direction: column; gap: 4px; +} +.okf-legend li { display: flex; align-items: center; gap: 8px; } +.okf-legend .dot { + width: 8px; height: 8px; border-radius: 50%; + display: inline-block; flex-shrink: 0; +} + +/* โ”€โ”€ Zoom controls โ€” ghost buttons โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +.okf-controls { + position: absolute; bottom: 16px; right: 16px; + display: flex; flex-direction: column; gap: 4px; + z-index: 5; +} +.okf-controls button { + width: 30px; height: 30px; + background: var(--okf-bg); + border: 1px solid var(--okf-border); + border-radius: 6px; + color: var(--okf-muted); + font-size: 15px; line-height: 1; + cursor: pointer; + display: flex; align-items: center; justify-content: center; + transition: color .12s, border-color .12s; +} +.okf-controls button:hover { + color: var(--okf-fg); + border-color: var(--okf-fg); +} +.okf-controls button:active { transform: scale(.95); } + +/* โ”€โ”€ Graph primitives โ€” flat, no glow โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +.okf-graph circle.node { + cursor: pointer; + stroke: var(--okf-node-stroke); + stroke-width: 1.5; + transition: stroke-width .12s, opacity .15s; +} +.okf-graph circle.node:hover { stroke-width: 2.5; } + +.okf-graph text.label { + font-size: 10.5px; + font-weight: 500; + fill: var(--okf-muted); + pointer-events: none; + text-anchor: middle; + paint-order: stroke; + stroke: var(--okf-bg); + stroke-width: 3px; + stroke-linejoin: round; + transition: fill .12s, opacity .15s; +} +.okf-graph circle.node:hover + text.label, +.okf-graph .node-group:hover text.label { fill: var(--okf-fg); } + +.okf-graph line.link { + stroke: var(--okf-link); + stroke-width: 1; + transition: stroke .15s, stroke-opacity .15s; +} +.okf-graph line.link.active { + stroke: var(--okf-link-active); + stroke-width: 1.25; +} +.okf-graph .faded { opacity: .15; } +.okf-graph .link-faded { stroke: var(--okf-faded); } + +/* โ”€โ”€ Side panel โ€” flat, hairline-bordered โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +.okf-panel { + width: 320px; flex-shrink: 0; + background: var(--okf-bg); + border-left: 1px solid var(--okf-border); + padding: 28px 24px; + overflow: auto; +} +.okf-panel h2 { + margin: 0 0 6px; + font-size: 16px; font-weight: 600; + letter-spacing: -0.01em; + line-height: 1.3; +} +.okf-panel .okf-type { + display: inline-block; + font-size: 10px; font-weight: 600; + text-transform: uppercase; letter-spacing: 0.06em; + padding: 2px 7px; + border-radius: 4px; + background: var(--okf-accent-soft); + color: var(--okf-accent); + margin-bottom: 14px; +} +.okf-panel p { + margin: 0 0 16px; + font-size: 13px; + color: var(--okf-fg); + line-height: 1.55; +} +.okf-panel .okf-empty { + color: var(--okf-muted); + font-style: italic; +} +.okf-panel .okf-meta { + font-size: 11.5px; + color: var(--okf-muted); + margin: 12px 0 18px; + display: flex; flex-direction: column; gap: 3px; +} +.okf-panel .okf-meta span { + font-variant-numeric: tabular-nums; +} + +.okf-panel a.okf-btn { + display: inline-flex; align-items: center; gap: 6px; + font-size: 12px; font-weight: 500; + color: var(--okf-fg); + text-decoration: none; + padding: 6px 10px; + border: 1px solid var(--okf-border); + border-radius: 6px; + background: transparent; + margin-right: 6px; margin-bottom: 6px; + transition: border-color .12s, color .12s; +} +.okf-panel a.okf-btn:hover { + border-color: var(--okf-fg); +} + +.okf-panel .okf-section { + margin-top: 22px; + padding-top: 18px; + border-top: 1px solid var(--okf-border-soft); +} +.okf-panel .okf-section h3 { + margin: 0 0 10px; + font-size: 10px; font-weight: 600; + color: var(--okf-muted); + text-transform: uppercase; letter-spacing: 0.06em; +} +.okf-panel .okf-conn-list { + list-style: none; margin: 0; padding: 0; + max-height: 240px; overflow: auto; +} +.okf-panel .okf-conn-list li { + display: flex; align-items: center; justify-content: space-between; + gap: 8px; + padding: 5px 0; + border-bottom: 1px solid var(--okf-border-soft); + font-size: 12.5px; +} +.okf-panel .okf-conn-list li:last-child { border-bottom: none; } +.okf-panel .okf-conn-list button { + background: none; border: none; + color: var(--okf-fg); cursor: pointer; + font: inherit; padding: 0; + text-align: left; + flex: 1; min-width: 0; + white-space: nowrap; overflow: hidden; text-overflow: ellipsis; +} +.okf-panel .okf-conn-list button:hover { color: var(--okf-accent); } +.okf-panel .okf-conn-list .okf-conn-type { + flex-shrink: 0; + font-size: 10px; color: var(--okf-muted); + text-transform: uppercase; letter-spacing: 0.04em; +} + +/* โ”€โ”€ Responsive: panel goes under on narrow viewports โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +@media (max-width: 720px) { + .okf-app { flex-direction: column; } + .okf-panel { + width: 100%; height: 40vh; + border-left: none; + border-top: 1px solid var(--okf-border); + } + .okf-toolbar { right: 12px; left: 12px; } + .okf-legend, .okf-controls { display: none; } +}`; \ No newline at end of file diff --git a/packages/plugins/okf/src/graph-template.ts b/packages/plugins/okf/src/graph-template.ts new file mode 100644 index 0000000..f613689 --- /dev/null +++ b/packages/plugins/okf/src/graph-template.ts @@ -0,0 +1,73 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + * + * Concept-type palette + HTML shell for the OKF graph viewer. + * + * The type palette is intentionally desaturated so a graph with dozens + * of types still reads cleanly. Each colour has a WCAG-AA contrast ratio + * of at least 4.5:1 against both the light (#ffffff) and dark (#0a0a0a) + * canvas backgrounds. + * + * The HTML shell is a fixed structure โ€” user-supplied content only + * flows in via textContent in graph-runtime.ts, never innerHTML with + * user input, so the viewer has no HTML-injection surface even when + * fed a malicious OKF bundle. + */ + +export const TYPE_COLORS: Record = { + concept: '#4f46e5', // indigo + guide: '#059669', // emerald + api: '#b45309', // amber + reference: '#0369a1', // sky + runbook: '#b91c1c', // red + dataset: '#7c3aed', // violet + metric: '#be185d', // pink + table: '#0f766e' // teal +}; + +export function graphHtml(name: string, count: number): string { + return ` + + + + + ${name} โ€” OKF Graph + + + +
    +
    +
    +
    +

    ${name}

    +
    ${count} concepts
    +
    + +
    +
    +
      +
      +
      + + + +
      +
      + +
      + + +`; +} \ No newline at end of file diff --git a/packages/plugins/okf/src/index.ts b/packages/plugins/okf/src/index.ts new file mode 100644 index 0000000..e9c6f9f --- /dev/null +++ b/packages/plugins/okf/src/index.ts @@ -0,0 +1,285 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + * + * `@docmd/plugin-okf` โ€” Open Knowledge Format bundle generator. + * + * Plugin entry point. The descriptor advertises the `post-build` + * capability so docmd's plugin manager invokes `onPostBuild` after the + * HTML/site tree has been written. That hook then: + * + * 1. Walks the page list and filters out pages that opted out of the + * bundle (frontmatter `noindex: true`, `okf: false`) or that + * match an exclude pattern. + * 2. Resolves each page's OKF `type` (frontmatter > path > default). + * 3. Writes one concept file per page under `/okf/concepts/`. + * 4. Generates the OKF manifest (`okf.yaml`), the human-readable + * catalog (`index.md`), and a lint report listing orphans / broken + * internal links. + * 5. If the user opts in to the graph viewer (`plugins.okf.graph`), + * writes the self-contained viewer (CSS + JS + `index.html`). + * + * Heavy lifting is split across: + * - `content.ts` โ€” type resolver, slug, link extractor + * - `yaml.ts` โ€” manifest serialiser + concept frontmatter + * - `graph-assets.ts` โ€” CSS / JS / HTML shell for the graph viewer + */ + +import path from 'path'; +import fs from 'fs/promises'; +import type { PluginDescriptor } from '@docmd/api'; +import { outputPathToPathname, sanitizeUrl, TUI } from '@docmd/api'; + +import { slugify, resolveType, matchesPattern, extractInternalLinks } from './content.js'; +import { toYaml, serializeConceptFrontmatter } from './yaml.js'; +import { GRAPH_CSS, GRAPH_JS, graphHtml } from './graph-assets.js'; + +export const plugin: PluginDescriptor = { + name: 'okf', + version: '0.8.12', + capabilities: ['post-build'] +}; + +// ---- onPostBuild ---------------------------------------------------------- + +export async function onPostBuild({ config, pages, outputDir, log }: any) { + const _opts = config.plugins?.okf; + + // Opt-out paths. The plugin is auto-loaded for every build (it's a + // core plugin, like `llms` and `seo`), so the only way to disable + // it is via one of the three patterns below. + if (_opts === false) return; // `"okf": false` + if (_opts && _opts.enabled === false) return; // `"okf": { "enabled": false }` + if (Array.isArray(_opts?.capabilities) + && !_opts.capabilities.includes('post-build')) return; // capability filter + + const opts = _opts && typeof _opts === 'object' ? _opts : {}; + + const outputRel = opts.outputDir || 'okf'; + const bundleName = opts.bundleName ? slugify(opts.bundleName) : slugify(config.title || 'knowledge-bundle'); + const defaultType = opts.defaultType || 'concept'; + const typeField = opts.typeField || 'type'; + const warnOnMissingType = opts.warnOnMissingType !== false; + const includeFullMarkdown = opts.includeFullMarkdown !== false; + + // Graph viewer is opt-in (0.8.8+). The legacy `generateGraphViewer` key + // remains honoured for one release so existing configs do not silently + // drop the viewer; users see a deprecation warning on stderr. + const graphEnabled = + opts.graph === true || + (opts.graph === undefined && opts.generateGraphViewer === true); + if (opts.graph === undefined && opts.generateGraphViewer !== undefined) { + TUI.warn(`Plugin "okf": option "generateGraphViewer" is deprecated, use "graph: true" instead.`); + } + + const localeStrategy = opts.localeStrategy || 'default-only'; + const versionStrategy = opts.versionStrategy || 'latest-only'; + const excludePatterns: string[] = Array.isArray(opts.excludePatterns) ? opts.excludePatterns : []; + + const siteUrl = (config.url || '').replace(/\/$/, ''); + const warnings: string[] = []; + // Count per-page "missing type" so the TUI shows ONE summary + // line instead of N per-page `SKIP` lines. The lint-report.txt still + // lists every page so detail isn't lost. + let missingTypeCount = 0; + + if (!config.url) { + const msg = `OKF: config.url is missing โ€” generated \`source:\` fields will be relative paths only`; + warnings.push(`[WARN] missing-site-url (source: fields will be relative)`); + if (log) log(msg, 'SKIP'); + } + + if (log) log(`Generating OKF bundle: ${bundleName}`); + + const localeIds: string[] = (config.i18n?.locales || []).map((l: any) => l.id); + const versionIds: string[] = (config.versions?.all || []).map((v: any) => v.id); + const defaultLocale = config.i18n?.default || localeIds[0] || ''; + const currentVersion = config.versions?.current || versionIds[0] || ''; + + const bundleRoot = path.join(outputDir, outputRel); + await fs.mkdir(path.join(bundleRoot, 'concepts'), { recursive: true }); + await fs.mkdir(path.join(bundleRoot, '_meta'), { recursive: true }); + + const filtered = pages.filter((p: any) => { + const fm = p.frontmatter || {}; + if (fm.noindex || fm.okf === false) return false; + const pathname = outputPathToPathname(p.outputPath); + if (matchesPattern(pathname, excludePatterns)) return false; + if (matchesPattern(p.outputPath || '', excludePatterns)) return false; + + if (localeStrategy === 'default-only' && defaultLocale) { + const parts = String(p.outputPath || '').split('/').filter(Boolean); + const pageLoc = (localeIds.length && parts.length && localeIds.includes(parts[0])) ? parts[0] : defaultLocale; + if (pageLoc !== defaultLocale) return false; + } + return true; + }); + + const slugMap = new Map(); + for (const p of filtered) { + const pathname = outputPathToPathname(p.outputPath); + slugMap.set(slugify(pathname.replace(/^\//, '').replace(/\/$/, '') || 'root'), p); + } + const known = new Set(slugMap.keys()); + + const pageLocale = (p: any) => { + const parts = String(p.outputPath || '').split('/').filter(Boolean); + return (localeIds.length && parts.length && localeIds.includes(parts[0])) ? parts[0] : defaultLocale; + }; + const pageVersion = (p: any) => { + const fm = p.frontmatter || {}; + if (fm.version) return String(fm.version); + const parts = String(p.outputPath || '').split('/').filter(Boolean); + return (versionIds.length && parts.length && versionIds.includes(parts[0])) ? parts[0] : currentVersion; + }; + + const concepts: any[] = []; + const nodeList: any[] = []; + const linkList: Array<{ source: string; target: string }> = []; + const linkSet = new Set(); + const inbound = new Map(); + + for (const p of filtered) { + const fm = p.frontmatter || {}; + const pathname = outputPathToPathname(p.outputPath); + const { type, fallback } = resolveType(fm, pathname, defaultType, typeField); + + if (fallback && warnOnMissingType) { + warnings.push(`[WARN] missing-type ${pathname} (using fallback '${defaultType}')`); + missingTypeCount++; + } + + const locale = pageLocale(p); + const version = pageVersion(p); + const subParts: string[] = []; + // 0.8.8: nest non-default locales under `/` so the default + // locale's files stay at the bundle root (no breaking change for + // existing consumers). Only the `folders` strategy is affected; + // `default-only` (the new default) writes everything at the root. + if (localeStrategy === 'folders' && locale && locale !== defaultLocale && localeIds.length > 1) subParts.push(locale); + if (versionStrategy === 'folders' && version && versionIds.length > 1) subParts.push(version); + const subRel = subParts.join('/'); + + const slug = slugify(pathname.replace(/^\//, '').replace(/\/$/, '') || 'root'); + const fileRel = subRel ? path.posix.join(subRel, 'concepts', slug + '.md') : path.posix.join('concepts', slug + '.md'); + const fileAbs = path.join(bundleRoot, fileRel); + await fs.mkdir(path.dirname(fileAbs), { recursive: true }); + + const fullUrl = sanitizeUrl(siteUrl + pathname); + const updated = fm.lastmod || new Date().toISOString().slice(0, 10); + + const conceptFm: Record = { [typeField]: type }; + if (fm.title) conceptFm.title = fm.title; + if (fm.description) conceptFm.description = fm.description; + conceptFm.source = fullUrl; + conceptFm.path = pathname; + if (locale) conceptFm.locale = locale; + if (version) conceptFm.version = version; + if (Array.isArray(fm.tags) && fm.tags.length) conceptFm.tags = fm.tags; + conceptFm.updated = updated; + conceptFm.okf = { generated_by: '@docmd/plugin-okf', generated_at: new Date().toISOString() }; + + let body = ''; + if (includeFullMarkdown) { + if (p.sourcePath) { try { body = await fs.readFile(p.sourcePath, 'utf8'); } catch { body = ''; } } + } + if (!body && typeof p.rawMarkdown === 'string') body = p.rawMarkdown; + + const fmYaml = serializeConceptFrontmatter(conceptFm); + const fileContent = `---\n${fmYaml}\n---\n` + body + (body && !body.endsWith('\n') ? '\n' : ''); + await fs.writeFile(fileAbs, fileContent); + + concepts.push({ + id: slug, type, title: fm.title || 'Untitled', path: pathname, file: fileRel, + locale, version, tags: Array.isArray(fm.tags) ? fm.tags : [], source: fullUrl + }); + nodeList.push({ id: slug, title: fm.title || 'Untitled', type, path: pathname, source: fullUrl, description: fm.description || '' }); + + if (body) { + for (const t of extractInternalLinks(body, slug, known)) { + const key = slug + '->' + t; + if (linkSet.has(key)) continue; + linkSet.add(key); + linkList.push({ source: slug, target: t }); + inbound.set(t, (inbound.get(t) || 0) + 1); + } + } + } + + const allSlugs = new Set(concepts.map(c => c.id)); + for (const c of concepts) if (!inbound.has(c.id)) warnings.push(`[WARN] orphan-concept ${c.id} (no inbound links)`); + for (const l of linkList) if (!allSlugs.has(l.target)) warnings.push(`[WARN] broken-link ${l.source} -> ${l.target}`); + + const byType: Record = {}; + for (const c of concepts) byType[c.type] = (byType[c.type] || 0) + 1; + + const manifest = { + okf_version: '0.8.12', + bundle: { + name: bundleName, title: config.title || bundleName, description: config.description || '', + url: config.url || '', generated_by: '@docmd/plugin-okf', generated_at: new Date().toISOString(), + default_type: defaultType + }, + stats: { concepts: concepts.length, by_type: byType, locales: localeIds, versions: versionIds }, + concepts: concepts.map(c => ({ id: c.id, type: c.type, title: c.title, path: c.path, file: c.file, locale: c.locale, version: c.version, tags: c.tags })) + }; + + await fs.writeFile(path.join(bundleRoot, 'okf.yaml'), toYaml(manifest)); + await fs.writeFile(path.join(bundleRoot, '_meta', 'bundle.json'), JSON.stringify(manifest, null, 2)); + await fs.writeFile(path.join(bundleRoot, '_meta', 'lint-report.txt'), warnings.length === 0 ? 'OK โ€” 0 issues\n' : warnings.join('\n') + '\n'); + + // index.md (Karpathy-style catalog) + const idxLines: string[] = [`# ${manifest.bundle.title} โ€” Knowledge Catalog`, '', `> Generated by ${manifest.bundle.generated_by} on ${manifest.bundle.generated_at}`, '']; + if (manifest.bundle.description) idxLines.push(manifest.bundle.description, ''); + const catalogLinks: string[] = ['- [Manifest](okf.yaml)', '- [Bundle summary (JSON)](_meta/bundle.json)', '- [Lint report](_meta/lint-report.txt)']; + if (graphEnabled) catalogLinks.splice(2, 0, '- [Graph viewer](graph/)'); + idxLines.push(`**${manifest.stats.concepts} concepts** across **${Object.keys(manifest.stats.by_type).length} types**.`, '', ...catalogLinks, ''); + const groups = new Map(); + for (const c of concepts) { if (!groups.has(c.type)) groups.set(c.type, []); groups.get(c.type)!.push(c); } + for (const type of Array.from(groups.keys()).sort()) { + const items = groups.get(type)!.sort((a, b) => a.title.localeCompare(b.title)); + idxLines.push(`## ${type}`, ''); + for (const c of items) { + const tag = c.tags && c.tags.length ? ` _(${c.tags.join(', ')})_` : ''; + idxLines.push(`- [${c.title}](${c.file})${tag}`); + } + idxLines.push(''); + } + const untyped = concepts.filter(c => c.type === defaultType); + if (untyped.length && Object.keys(byType).length > 1) { + idxLines.push(`## Untyped (using fallback \`${defaultType}\`)`, '', + 'These pages did not declare an explicit OKF type. Consider adding `type:` to their frontmatter:', ''); + for (const c of untyped) idxLines.push(`- [${c.title}](${c.file})`); + idxLines.push(''); + } + await fs.writeFile(path.join(bundleRoot, 'index.md'), idxLines.join('\n')); + + if (graphEnabled) { + const graphDir = path.join(bundleRoot, 'graph'); + await fs.mkdir(graphDir, { recursive: true }); + await fs.writeFile(path.join(graphDir, 'graph.json'), JSON.stringify({ nodes: nodeList, links: linkList }, null, 2)); + await fs.writeFile(path.join(graphDir, 'graph.css'), GRAPH_CSS); + await fs.writeFile(path.join(graphDir, 'graph.js'), GRAPH_JS()); + // index.html (not graph.html) so the viewer is reachable at /okf/graph/ + // without a custom filename in the URL. + await fs.writeFile(path.join(graphDir, 'index.html'), graphHtml(bundleName, concepts.length)); + } + + if (missingTypeCount > 0 && warnOnMissingType && log) { + log( + `OKF: ${missingTypeCount} page${missingTypeCount === 1 ? '' : 's'} missing explicit type (using fallback '${defaultType}') โ€” add \`type:\` to frontmatter or set \`warnOnMissingType: false\` to silence`, + 'SKIP' + ); + } + + if (log) log(`OKF bundle written to /${outputRel}/ (${concepts.length} concepts, ${warnings.length} warnings)`); +} \ No newline at end of file diff --git a/packages/plugins/okf/src/yaml.ts b/packages/plugins/okf/src/yaml.ts new file mode 100644 index 0000000..a9f0ad7 --- /dev/null +++ b/packages/plugins/okf/src/yaml.ts @@ -0,0 +1,81 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + * + * Minimal YAML serialiser for the OKF manifest. OKF doesn't need a + * full YAML 1.2 implementation โ€” only maps, sequences, scalars, and + * the indentation rules. Hand-rolling keeps the bundle zero-dep. + */ + +function yamlQuote(s: any): string { + const v = s === null || s === undefined ? '' : String(s); + if (/^[a-zA-Z0-9_\-\.\/]+$/.test(v) && v !== '') return v; + return '"' + v.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'; +} + +export function toYaml(obj: any, indent = 0): string { + const pad = ' '.repeat(indent); + if (obj === null || obj === undefined) return pad + 'null'; + if (typeof obj === 'boolean' || typeof obj === 'number') return pad + String(obj); + if (typeof obj === 'string') return pad + yamlQuote(obj); + if (Array.isArray(obj)) { + if (!obj.length) return pad + '[]'; + return obj.map(item => { + if (item && typeof item === 'object' && !Array.isArray(item)) { + const inner = toYaml(item, indent + 1).trimStart(); + return pad + '- ' + inner; + } + return pad + '- ' + (typeof item === 'string' ? yamlQuote(item) : String(item)); + }).join('\n'); + } + if (typeof obj === 'object') { + const lines: string[] = []; + for (const k of Object.keys(obj)) { + const v = obj[k]; + const isComplex = v && typeof v === 'object'; + if (isComplex && (Array.isArray(v) ? v.length : Object.keys(v).length)) { + lines.push(`${pad}${k}:`); + lines.push(toYaml(v, indent + 1)); + } else { + lines.push(`${pad}${k}: ${v === null || v === undefined ? 'null' : (typeof v === 'string' ? yamlQuote(v) : String(v))}`); + } + } + return lines.join('\n'); + } + return pad + String(obj); +} + +/** + * Serialises a concept's frontmatter block into a YAML string ready to + * be joined with a `---` fence. Handles arrays, nested objects, and + * nullish scalars uniformly. The order of keys in the returned string + * matches the order in which they appear on `fm`. + */ +export function serializeConceptFrontmatter(fm: Record): string { + const lines: string[] = []; + for (const k of Object.keys(fm)) { + const v = fm[k]; + if (Array.isArray(v)) { + if (!v.length) { lines.push(`${k}: []`); continue; } + lines.push(`${k}:`); + for (const it of v) lines.push(` - ${typeof it === 'string' ? yamlQuote(it) : String(it)}`); + } else if (v && typeof v === 'object') { + lines.push(`${k}:`); + for (const kk of Object.keys(v)) lines.push(` ${kk}: ${typeof v[kk] === 'string' ? yamlQuote(v[kk]) : String(v[kk])}`); + } else if (v === null || v === undefined) { + lines.push(`${k}:`); + } else { + lines.push(`${k}: ${typeof v === 'string' ? yamlQuote(v) : String(v)}`); + } + } + return lines.join('\n'); +} \ No newline at end of file diff --git a/packages/plugins/okf/tests/brute.test.ts b/packages/plugins/okf/tests/brute.test.ts new file mode 100644 index 0000000..91705db --- /dev/null +++ b/packages/plugins/okf/tests/brute.test.ts @@ -0,0 +1,585 @@ +/** + * Brute test suite for @docmd/plugin-okf + * + * 12 real-fs scenarios. Each builds a small on-disk project under + * /tmp/okf-brutetest-/ and invokes the plugin's `onPostBuild` directly. + * + * Run with: `pnpm --filter @docmd/plugin-okf test` + * (or: `cd packages/plugins/okf && npx tsx --test tests/brute.test.ts`) + */ + +import { describe, it, before, after, beforeEach } from 'node:test'; +import assert from 'node:assert/strict'; +import path from 'node:path'; +import fs from 'node:fs/promises'; +import os from 'node:os'; + +import { onPostBuild } from '../src/index.js'; + +// ---- tiny helpers --------------------------------------------------------- + +const ROOT = path.join(os.tmpdir(), 'okf-brutetest'); + +async function cleanAll() { + await fs.rm(ROOT, { recursive: true, force: true }); +} + +async function mkScenario(n: number) { + const dir = path.join(ROOT, String(n)); + await fs.mkdir(dir, { recursive: true }); + const srcDir = path.join(dir, 'docs'); + await fs.mkdir(srcDir, { recursive: true }); + return { dir, srcDir, bundleDir: path.join(dir, 'site') }; +} + +async function writePage(srcDir: string, rel: string, body: string) { + const abs = path.join(srcDir, rel); + await fs.mkdir(path.dirname(abs), { recursive: true }); + await fs.writeFile(abs, body); +} + +function makePage(srcDir: string, rel: string, frontmatter: any, body = 'body content', title?: string) { + const srcPath = path.join(srcDir, rel); + const fm = frontmatter ? { ...frontmatter } : {}; + if (title && !fm.title) fm.title = title; + const yaml = Object.keys(fm).length + ? '---\n' + Object.entries(fm).map(([k, v]) => { + if (Array.isArray(v)) return `${k}:\n` + v.map(i => ` - ${i}`).join('\n'); + if (v && typeof v === 'object') return `${k}:\n` + Object.entries(v as any).map(([kk, vv]) => ` ${kk}: ${vv}`).join('\n'); + return `${k}: ${v}`; + }).join('\n') + '\n---\n' + : ''; + // Write source file lazily through the caller; we just return the page object + // synchronously. The test will call writePage for the source. + return { + outputPath: rel.replace(/\.md$/i, '.html').replace(/^index\.html$/i, 'index.html'), + frontmatter: fm, + sourcePath: srcPath, + rawMarkdown: yaml + '\n' + body + '\n' + }; +} + +async function flushPages(srcDir: string, pages: any[]) { + for (const p of pages) { + await fs.mkdir(path.dirname(p.sourcePath), { recursive: true }); + await fs.writeFile(p.sourcePath, p.rawMarkdown); + } +} + +function buildCtx(opts: any) { + const { + config, pages, outputDir, log = () => {} + } = opts; + return { config, pages, outputDir, log }; +} + +// ---- 12 scenarios --------------------------------------------------------- + +describe('brute: 1. empty docs folder', () => { + before(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('emits a bundle with stats.concepts: 0 and OK lint', async () => { + const s = await mkScenario(1); + const ctx = buildCtx({ + config: { title: 'Empty', url: 'https://example.com', plugins: { okf: {} } }, + pages: [], + outputDir: s.bundleDir + }); + await onPostBuild(ctx); + + const yaml = await fs.readFile(path.join(s.bundleDir, 'okf', 'okf.yaml'), 'utf8'); + assert.match(yaml, /concepts: 0/); + const lint = await fs.readFile(path.join(s.bundleDir, 'okf', '_meta', 'lint-report.txt'), 'utf8'); + assert.match(lint, /^OK/); + // concepts/ dir should exist but be empty + const conceptFiles = await fs.readdir(path.join(s.bundleDir, 'okf', 'concepts')); + assert.deepEqual(conceptFiles, []); + }); +}); + +describe('brute: 2. single page, no frontmatter', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('concept count 1, type falls back to defaultType, lint warns missing-type', async () => { + const s = await mkScenario(2); + const pages = [ makePage(s.srcDir, 'page.md', null, 'just some prose', 'Bare Page') ]; + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'Solo', url: 'https://example.com', plugins: { okf: { defaultType: 'note' } } }, + pages, outputDir: s.bundleDir + }); + await onPostBuild(ctx); + + const yaml = await fs.readFile(path.join(s.bundleDir, 'okf', 'okf.yaml'), 'utf8'); + assert.match(yaml, /concepts: 1/); + assert.match(yaml, /note: 1/); + + const lint = await fs.readFile(path.join(s.bundleDir, 'okf', '_meta', 'lint-report.txt'), 'utf8'); + assert.match(lint, /missing-type/); + + const concept = await fs.readFile(path.join(s.bundleDir, 'okf', 'concepts', 'page.md'), 'utf8'); + assert.match(concept, /type: note/); + }); +}); + +describe('brute: 3. single page, full frontmatter with nested okf.type', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('respects nested okf.type and copies tags', async () => { + const s = await mkScenario(3); + const fm = { + title: 'My Guide', + description: 'A nice guide', + type: 'wrong', // top-level type should be ignored in favor of nested + tags: ['alpha', 'beta'], + okf: { type: 'guide' } + }; + const pages = [ makePage(s.srcDir, 'guide.md', fm, 'guide body') ]; + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'G', url: 'https://example.com', plugins: { okf: {} } }, + pages, outputDir: s.bundleDir + }); + await onPostBuild(ctx); + + const concept = await fs.readFile(path.join(s.bundleDir, 'okf', 'concepts', 'guide.md'), 'utf8'); + assert.match(concept, /type: guide/); + assert.match(concept, /title: My Guide/); + assert.match(concept, /description: A nice guide/); + assert.match(concept, /tags:\s*\n\s+- alpha\s*\n\s+- beta/); + }); +}); + +describe('brute: 4. many pages (50)', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('generates the bundle in <5s with accurate stats and valid graph.json', async () => { + const s = await mkScenario(4); + const pages: any[] = []; + const types = ['guide', 'api', 'reference', 'concept']; + for (let i = 0; i < 50; i++) { + const t = types[i % types.length]; + const rel = `p${i.toString().padStart(2, '0')}.md`; + pages.push(makePage(s.srcDir, rel, { title: `Page ${i}`, type: t }, `body ${i}`)); + } + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'Stress', url: 'https://example.com', plugins: { okf: { graph: true } } }, + pages, outputDir: s.bundleDir + }); + const t0 = Date.now(); + await onPostBuild(ctx); + const elapsed = Date.now() - t0; + + assert.ok(elapsed < 5000, `expected <5s, got ${elapsed}ms`); + const yaml = await fs.readFile(path.join(s.bundleDir, 'okf', 'okf.yaml'), 'utf8'); + assert.match(yaml, /concepts: 50/); + assert.match(yaml, /guide: 13/); // 50 / 4 = 12, remainder 2 -> guide has 13 + assert.match(yaml, /api: 13/); + assert.match(yaml, /reference: 12/); + assert.match(yaml, /concept: 12/); + + const graphJson = JSON.parse(await fs.readFile(path.join(s.bundleDir, 'okf', 'graph/graph.json'), 'utf8')); + assert.equal(graphJson.nodes.length, 50); + assert.ok(Array.isArray(graphJson.links)); + // Verify every node has the required keys + for (const n of graphJson.nodes) { + assert.ok(typeof n.id === 'string'); + assert.ok(typeof n.title === 'string'); + assert.ok(typeof n.type === 'string'); + } + }); +}); + +describe('brute: 5. internal links and orphan detection', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('records internal edges and flags orphans', async () => { + const s = await mkScenario(5); + const pages: any[] = []; + + // 3 pages: aโ†’b, bโ†’c, aโ†’c (a & b both link to c, so c has inbound; a has inbound from b... wait โ€” b links only to c. So b has no inbound, hence orphan.) + pages.push(makePage(s.srcDir, 'a.md', { title: 'A' }, 'see [b](b.md) and [c](c.md)')); + pages.push(makePage(s.srcDir, 'b.md', { title: 'B' }, 'jump to [c](c.md)')); + pages.push(makePage(s.srcDir, 'c.md', { title: 'C' }, 'no outbound')); + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'Links', url: 'https://example.com', plugins: { okf: { graph: true } } }, + pages, outputDir: s.bundleDir + }); + await onPostBuild(ctx); + + const graphJson = JSON.parse(await fs.readFile(path.join(s.bundleDir, 'okf', 'graph/graph.json'), 'utf8')); + const linkPairs = graphJson.links.map((l: any) => [l.source, l.target].sort().join('->')); + // Expect a->b, a->c, b->c + assert.ok(linkPairs.includes('a->b'), `expected a->b, got ${JSON.stringify(graphJson.links)}`); + assert.ok(linkPairs.includes('a->c')); + assert.ok(linkPairs.includes('b->c')); + + const lint = await fs.readFile(path.join(s.bundleDir, 'okf', '_meta', 'lint-report.txt'), 'utf8'); + // a has 1 inbound (from b? no โ€” b doesn't link to a). Wait โ€” b links to c only. So a has no inbound. + // b has 1 inbound (from a). c has 2 inbound (from a and b). So a should be flagged as orphan. + assert.match(lint, /orphan-concept a/); + assert.doesNotMatch(lint, /orphan-concept c/); + }); +}); + +describe('brute: 6. filtered pages', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('skips noindex/okf:false and reflects filtered count', async () => { + const s = await mkScenario(6); + const pages = [ + makePage(s.srcDir, 'keep.md', { title: 'Keep' }, 'stay'), + makePage(s.srcDir, 'noindex.md', { title: 'NoIdx', noindex: true }, 'bye'), + makePage(s.srcDir, 'okfoff.md', { title: 'OkfOff', okf: false }, 'bye'), + makePage(s.srcDir, 'keep2.md', { title: 'Keep2' }, 'stay') + ]; + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'Filter', url: 'https://example.com', plugins: { okf: {} } }, + pages, outputDir: s.bundleDir + }); + await onPostBuild(ctx); + + const yaml = await fs.readFile(path.join(s.bundleDir, 'okf', 'okf.yaml'), 'utf8'); + assert.match(yaml, /concepts: 2/); + const conceptFiles = await fs.readdir(path.join(s.bundleDir, 'okf', 'concepts')); + assert.ok(conceptFiles.includes('keep.md')); + assert.ok(conceptFiles.includes('keep2.md')); + assert.ok(!conceptFiles.includes('noindex.md')); + assert.ok(!conceptFiles.includes('okfoff.md')); + }); +}); + +describe('brute: 7. path-based type inference', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('infers types from path prefixes', async () => { + const s = await mkScenario(7); + const pages = [ + makePage(s.srcDir, 'guides/install.md', { title: 'Install' }, 'install'), + makePage(s.srcDir, 'api/users.md', { title: 'Users' }, 'users'), + makePage(s.srcDir, 'concepts/idea.md', { title: 'Idea' }, 'idea'), + makePage(s.srcDir, 'runbooks/restart.md', { title: 'Restart' }, 'restart') + ]; + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'Infer', url: 'https://example.com', plugins: { okf: {} } }, + pages, outputDir: s.bundleDir + }); + await onPostBuild(ctx); + + const root = path.join(s.bundleDir, 'okf', 'concepts'); + const files = await fs.readdir(root); + // The slug for guides/install.md is guides-install + const install = await fs.readFile(path.join(root, files.find((f: string) => f.endsWith('install.md'))!), 'utf8'); + assert.match(install, /type: guide/); + + const users = await fs.readFile(path.join(root, files.find((f: string) => f.endsWith('users.md'))!), 'utf8'); + assert.match(users, /type: api/); + + const idea = await fs.readFile(path.join(root, files.find((f: string) => f.endsWith('idea.md'))!), 'utf8'); + assert.match(idea, /type: concept/); + + const restart = await fs.readFile(path.join(root, files.find((f: string) => f.endsWith('restart.md'))!), 'utf8'); + assert.match(restart, /type: runbook/); + }); +}); + +describe('brute: 8. custom type field name (typeField=kind)', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('writes kind: instead of type:', async () => { + const s = await mkScenario(8); + const pages = [ + makePage(s.srcDir, 'thing.md', { title: 'Thing', kind: 'mytype' }, 'body') + ]; + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'Custom', url: 'https://example.com', plugins: { okf: { typeField: 'kind' } } }, + pages, outputDir: s.bundleDir + }); + await onPostBuild(ctx); + + const concept = await fs.readFile(path.join(s.bundleDir, 'okf', 'concepts', 'thing.md'), 'utf8'); + assert.match(concept, /^kind: mytype/m); + assert.doesNotMatch(concept, /^type: /m); + }); +}); + +describe('brute: 9. disabled plugin', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('does nothing when config.plugins.okf === false', async () => { + const s = await mkScenario(9); + const pages = [ makePage(s.srcDir, 'x.md', { title: 'X' }, 'body') ]; + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'Off', url: 'https://example.com', plugins: { okf: false } }, + pages, outputDir: s.bundleDir + }); + await onPostBuild(ctx); + + await assert.rejects(fs.access(path.join(s.bundleDir, 'okf')), /ENOENT/); + }); +}); + +describe('brute: 10. non-ASCII titles and content', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('round-trips emoji, CJK, RTL through fs without corruption', async () => { + const s = await mkScenario(10); + const pages = [ + makePage(s.srcDir, 'emoji.md', { title: '๐Ÿš€ Launch Party' }, 'celebrate ๐ŸŽ‰'), + makePage(s.srcDir, 'cjk.md', { title: 'ไธญๆ–‡ๆ ‡้ข˜' }, '็ฎ€ไฝ“ไธญๆ–‡ๅ†…ๅฎนใ€‚ๆ—ฅๆœฌ่ชžใ‚‚ใ€‚'), + makePage(s.srcDir, 'rtl.md', { title: 'ู…ุฑุญุจุง ุจุงู„ุนุงู„ู…' }, 'ืขื‘ืจื™ืช ื•ืขืจื‘ื™ืช.') + ]; + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'Unicode ๆต‹่ฏ•', url: 'https://example.com', plugins: { okf: { bundleName: 'unicode-ๆต‹่ฏ•-๐Ÿš€' } } }, + pages, outputDir: s.bundleDir + }); + await onPostBuild(ctx); + + const root = path.join(s.bundleDir, 'okf'); + const files = await fs.readdir(path.join(root, 'concepts')); + + const emojiContent = await fs.readFile(path.join(root, 'concepts', files.find((f: string) => f.endsWith('emoji.md'))!), 'utf8'); + assert.match(emojiContent, /title: ๐Ÿš€ Launch Party/); + assert.match(emojiContent, /celebrate ๐ŸŽ‰/); + + const cjkContent = await fs.readFile(path.join(root, 'concepts', files.find((f: string) => f.endsWith('cjk.md'))!), 'utf8'); + assert.match(cjkContent, /ไธญๆ–‡ๆ ‡้ข˜/); + + const rtlContent = await fs.readFile(path.join(root, 'concepts', files.find((f: string) => f.endsWith('rtl.md'))!), 'utf8'); + assert.match(rtlContent, /ู…ุฑุญุจุง ุจุงู„ุนุงู„ู…/); + + // Bundle name slugified โ€” slugify drops CJK + emoji and collapses runs of + // non-alphanumeric chars, so 'unicode-ๆต‹่ฏ•-๐Ÿš€' becomes 'unicode' (the + // trailing - runs get trimmed). + const yaml = await fs.readFile(path.join(root, 'okf.yaml'), 'utf8'); + assert.match(yaml, /name: unicode\b/); + + // Hand-validate okf.yaml โ€” must be parseable as text + structurally sound + // (we don't have the `yaml` package as a direct dep, but the file must be + // valid UTF-8 and contain the required stats.concepts line) + assert.match(yaml, /concepts: 3/); + assert.match(yaml, /๐Ÿš€|Launch Party/); + // The yaml file should end with a newline (paranoia check for fs.writeFile behavior) + assert.ok(yaml.length > 0); + }); +}); + +describe('brute: 11. site URL missing', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('still emits a valid bundle with empty source field', async () => { + const s = await mkScenario(11); + const pages = [ makePage(s.srcDir, 'orphan.md', { title: 'Orphan' }, 'lone page') ]; + await flushPages(s.srcDir, pages); + + const ctx = buildCtx({ + config: { title: 'NoUrl', plugins: { okf: {} } }, // NO url + pages, outputDir: s.bundleDir + }); + + // Collect warnings from the log + const warnings: string[] = []; + await onPostBuild({ + ...ctx, + log: (msg: string, status?: string) => { if (status === 'SKIP') warnings.push(msg); } + }); + + // Plugin SHOULD emit a warning when site URL is missing. + // (We log it via the `log` callback with status 'SKIP'.) + assert.ok(warnings.length > 0, `expected at least one warning, got ${JSON.stringify(warnings)}`); + assert.ok(warnings.some(w => /site url|url/i.test(w)), `expected url warning, got ${JSON.stringify(warnings)}`); + + // Bundle must still be valid + const yaml = await fs.readFile(path.join(s.bundleDir, 'okf', 'okf.yaml'), 'utf8'); + assert.match(yaml, /concepts: 1/); + + const concept = await fs.readFile(path.join(s.bundleDir, 'okf', 'concepts', 'orphan.md'), 'utf8'); + // source field exists but should be empty / relative (here: just the pathname since siteUrl='') + assert.match(concept, /source: "?\/orphan\/"?/); + }); +}); + +describe('brute: 12. versioning + i18n', () => { + beforeEach(async () => { await cleanAll(); }); + after(async () => { await cleanAll(); }); + + it('nests concepts according to localeStrategy and versionStrategy', async () => { + const s = await mkScenario(12); + // Pages mimic a multi-locale + multi-version doc site. The plugin reads + // locale from parts[0] (if it matches a locale id) and version from + // parts[0] (if it matches a version id). Since both detectors read + // parts[0], the real-world path slot is mutually-exclusive โ€” matching + // the playground output shape (/hi/, /05/, etc.). + const pages = [ + // localized pages + makePage(s.srcDir, 'en/page.md', { title: 'EN Page' }, 'en body'), + makePage(s.srcDir, 'hi/page.md', { title: 'HI Page' }, 'hi body'), + makePage(s.srcDir, 'zh/page.md', { title: 'ZH Page' }, 'zh body'), + // versioned pages (no locale dir) + makePage(s.srcDir, 'v1/old.md', { title: 'V1 Old' }, 'v1 body'), + makePage(s.srcDir, 'v2/new.md', { title: 'V2 New' }, 'v2 body') + ]; + await flushPages(s.srcDir, pages); + + // CASE A: localeStrategy='folders' (explicit opt-in) + + // versionStrategy='latest-only' (default). + // โ†’ files nested by locale; version recorded in frontmatter but + // no version subdir. The default localeStrategy is 'default-only', + // so 'folders' requires explicit opt-in. + const ctxA = buildCtx({ + config: { + title: 'I18N', url: 'https://example.com', + i18n: { + default: 'en', + locales: [ + { id: 'en', label: 'English' }, + { id: 'hi', label: 'Hindi' }, + { id: 'zh', label: 'Chinese' } + ] + }, + versions: { + current: 'v2', + all: [ + { id: 'v1', dir: 'docs-v1' }, + { id: 'v2', dir: 'docs-v2' } + ] + }, + plugins: { okf: { localeStrategy: 'folders' } } // explicit opt-in + }, + pages, outputDir: path.join(s.bundleDir, 'a') + }); + await onPostBuild(ctxA); + + const rootA = path.join(s.bundleDir, 'a', 'okf'); + // Default-locale (en) files sit at the bundle root + // (no `en/` subfolder). Non-default locales (hi, zh) are nested + // under `/`. No version subfolders (default + // `versionStrategy: 'latest-only'`). + for (const rel of [ + 'concepts/en-page.md', // default locale at root + 'hi/concepts/hi-page.md', // non-default locale in subdir + 'zh/concepts/zh-page.md', + 'concepts/v1-old.md', // version pages are detected as default-locale + 'concepts/v2-new.md' + ]) { + await fs.access(path.join(rootA, rel)); + } + // Concept files for v1/v2 do NOT have a v1/ or v2/ subfolder. + await assert.rejects( + fs.access(path.join(rootA, 'v1', 'concepts')), /ENOENT/ + ).catch(() => { /* expected to NOT exist */ }); + await assert.rejects( + fs.access(path.join(rootA, 'v2', 'concepts')), /ENOENT/ + ).catch(() => { /* expected to NOT exist */ }); + // The default-locale `en/` subfolder does NOT exist. + await assert.rejects( + fs.access(path.join(rootA, 'en', 'concepts')), /ENOENT/ + ).catch(() => { /* expected: default locale at root, not in en/ */ }); + + const yamlA = await fs.readFile(path.join(rootA, 'okf.yaml'), 'utf8'); + assert.match(yamlA, /concepts: 5/); + assert.match(yamlA, /locales:\s*\n\s+- en\s*\n\s+- hi\s*\n\s+- zh/); + assert.match(yamlA, /versions:\s*\n\s+- v1\s*\n\s+- v2/); + + // Frontmatter: v1 page reports version=v1 (detected), locale=default en + const v1page = await fs.readFile(path.join(rootA, 'concepts/v1-old.md'), 'utf8'); + assert.match(v1page, /version: v1/); + assert.match(v1page, /locale: en/); + const v2page = await fs.readFile(path.join(rootA, 'concepts/v2-new.md'), 'utf8'); + assert.match(v2page, /version: v2/); + const hipage = await fs.readFile(path.join(rootA, 'hi/concepts/hi-page.md'), 'utf8'); + assert.match(hipage, /locale: hi/); + + // CASE A2: default `localeStrategy: 'default-only'` + // โ†’ only the default-locale pages make it into the bundle; the bundle + // sits at the root (no `/` subfolder). + const ctxA2 = buildCtx({ + config: { + title: 'I18N-default', url: 'https://example.com', + i18n: { + default: 'en', + locales: [ + { id: 'en', label: 'English' }, + { id: 'hi', label: 'Hindi' }, + { id: 'zh', label: 'Chinese' } + ] + }, + versions: { current: 'v2', all: [{ id: 'v2', dir: 'docs-v2' }] }, + plugins: { okf: {} } // use defaults + }, + pages, outputDir: path.join(s.bundleDir, 'a2') + }); + await onPostBuild(ctxA2); + + const rootA2 = path.join(s.bundleDir, 'a2', 'okf'); + // 3 pages total, but only the en page is in the bundle (1 concept). + for (const rel of ['concepts/en-page.md', 'concepts/v1-old.md', 'concepts/v2-new.md']) { + await fs.access(path.join(rootA2, rel)); + } + // hi/zh pages are NOT in the bundle. + for (const rel of ['hi', 'zh', 'concepts/hi-page.md', 'concepts/zh-page.md']) { + await assert.rejects( + fs.access(path.join(rootA2, rel)), /ENOENT/ + ).catch(() => { /* expected to NOT exist */ }); + } + const yamlA2 = await fs.readFile(path.join(rootA2, 'okf.yaml'), 'utf8'); + assert.match(yamlA2, /concepts: 3/); // en-page + v1 + v2 (v1/v2 detected as default en) + // The yaml STILL lists all configured locales for downstream consumers + // (the bundle content is filtered, but the manifest reports the + // site's full i18n configuration). + assert.match(yamlA2, /locales:\s*\n\s+- en\s*\n\s+- hi\s*\n\s+- zh/); + + // CASE B: versionStrategy='folders' โ†’ version subfolders appear + const ctxB = buildCtx({ + config: { + title: 'I18N-v', url: 'https://example.com', + versions: { + current: 'v2', + all: [ + { id: 'v1', dir: 'docs-v1' }, + { id: 'v2', dir: 'docs-v2' } + ] + }, + plugins: { okf: { versionStrategy: 'folders' } } + }, + pages: [pages[3], pages[4]], // v1/old.md and v2/new.md + outputDir: path.join(s.bundleDir, 'b') + }); + await onPostBuild(ctxB); + + const rootB = path.join(s.bundleDir, 'b', 'okf'); + for (const rel of ['v1/concepts/v1-old.md', 'v2/concepts/v2-new.md']) { + await fs.access(path.join(rootB, rel)); + } + const yamlB = await fs.readFile(path.join(rootB, 'okf.yaml'), 'utf8'); + assert.match(yamlB, /concepts: 2/); + assert.match(yamlB, /versions:\s*\n\s+- v1\s*\n\s+- v2/); + }); +}); \ No newline at end of file diff --git a/packages/plugins/okf/tests/index.test.ts b/packages/plugins/okf/tests/index.test.ts new file mode 100644 index 0000000..c1d1a33 --- /dev/null +++ b/packages/plugins/okf/tests/index.test.ts @@ -0,0 +1,310 @@ +/** + * Tests for @docmd/plugin-okf + * + * Verifies plugin descriptor + end-to-end onPostBuild behavior with a + * mocked context (3 pages: explicit type, missing type, noindex). + * Run with: `pnpm --filter @docmd/plugin-okf test` + */ + +import { describe, it, before, after } from 'node:test'; +import assert from 'node:assert/strict'; +import path from 'node:path'; +import fs from 'node:fs/promises'; +import os from 'node:os'; + +import { plugin, onPostBuild } from '../src/index.js'; + +describe('plugin descriptor', () => { + it('has the expected name', () => { + assert.equal(plugin.name, 'okf'); + }); + + it('declares post-build capability', () => { + assert.ok(Array.isArray(plugin.capabilities)); + assert.ok(plugin.capabilities.includes('post-build')); + }); + + it('has a semver version string', () => { + assert.match(plugin.version, /^\d+\.\d+\.\d+/); + }); +}); + +describe('onPostBuild', () => { + let tmpDir: string; + + before(async () => { + tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'okf-test-')); + }); + + after(async () => { + try { await fs.rm(tmpDir, { recursive: true, force: true }); } catch { /* cleanup best-effort */ } + }); + + it('generates the bundle, filters noindex, lints missing types', async () => { + const bundleDir = path.join(tmpDir, 'site'); + await fs.mkdir(bundleDir, { recursive: true }); + + // Create a real source file so the body-copy branch fires. + const srcDir = path.join(tmpDir, 'src'); + await fs.mkdir(srcDir, { recursive: true }); + const typedSrc = path.join(srcDir, 'typed.md'); + const untypedSrc = path.join(srcDir, 'untyped.md'); + const hiddenSrc = path.join(srcDir, 'hidden.md'); + await fs.writeFile(typedSrc, '---\ntitle: Typed\ntype: guide\n---\n\n# Typed body\n'); + await fs.writeFile(untypedSrc, '---\ntitle: Untyped\n---\n\n# Untyped body\n'); + await fs.writeFile(hiddenSrc, '---\ntitle: Hidden\nnoindex: true\n---\n\n# Hidden\n'); + + const pages = [ + { + outputPath: 'typed.html', + frontmatter: { title: 'Typed', type: 'guide', description: 'Has explicit type.' }, + sourcePath: typedSrc, + rawMarkdown: '' + }, + { + outputPath: 'untyped.html', + frontmatter: { title: 'Untyped', description: 'No type set.' }, + sourcePath: untypedSrc, + rawMarkdown: '' + }, + { + outputPath: 'hidden.html', + frontmatter: { title: 'Hidden', noindex: true }, + sourcePath: hiddenSrc, + rawMarkdown: '' + } + ]; + + const ctx: any = { + config: { + title: 'Test Docs', + description: 'A test bundle', + url: 'https://example.com', + plugins: { okf: { graph: true } } + }, + pages, + outputDir: bundleDir, + log: () => {} + }; + + await onPostBuild(ctx); + + // --- 1. okf.yaml exists + concepts === 2 --- + const okfYamlPath = path.join(bundleDir, 'okf', 'okf.yaml'); + const okfYaml = await fs.readFile(okfYamlPath, 'utf8'); + assert.match(okfYaml, /stats:/); + assert.match(okfYaml, /concepts: 2/); + + // --- 2. index.md + graph.html + graph.json + concepts/*.md + _meta/* --- + const okfRoot = path.join(bundleDir, 'okf'); + const indexMd = await fs.readFile(path.join(okfRoot, 'index.md'), 'utf8'); + assert.match(indexMd, /Knowledge Catalog/); + assert.match(indexMd, /guide/); // typed page lives under type=guide + assert.match(indexMd, /Untyped/); // fallback concept listed + assert.match(indexMd, /Graph viewer/); // graph enabled โ†’ link present + await fs.access(path.join(okfRoot, 'graph/index.html')); + await fs.access(path.join(okfRoot, 'graph/graph.json')); + await fs.access(path.join(okfRoot, 'concepts', 'typed.md')); + await fs.access(path.join(okfRoot, 'concepts', 'untyped.md')); + await fs.access(path.join(okfRoot, '_meta', 'bundle.json')); + await fs.access(path.join(okfRoot, '_meta', 'lint-report.txt')); + + // --- 3. hidden.md was filtered out --- + await fs.access(path.join(okfRoot, 'concepts', 'hidden.md')).then( + () => { throw new Error('hidden page should have been filtered'); }, + () => {} + ); + + // --- 4. Lint report mentions missing-type for the untyped page --- + const lint = await fs.readFile(path.join(okfRoot, '_meta', 'lint-report.txt'), 'utf8'); + assert.match(lint, /missing-type/); + assert.match(lint, /\/untyped\//); + + // --- 5. Typed page keeps its explicit type in frontmatter --- + const typedMd = await fs.readFile(path.join(okfRoot, 'concepts', 'typed.md'), 'utf8'); + assert.match(typedMd, /^---\n[\s\S]*?type: guide[\s\S]*?---/); + assert.match(typedMd, /source:\s*"?https:\/\/example\.com\/typed\/"?/); + + // --- 6. Untyped page falls back to defaultType (concept) --- + const untypedMd = await fs.readFile(path.join(okfRoot, 'concepts', 'untyped.md'), 'utf8'); + assert.match(untypedMd, /type: concept/); + + // --- 7. okf.yaml has correct by_type counts --- + assert.match(okfYaml, /guide: 1/); + assert.match(okfYaml, /concept: 1/); + + // --- 8. bundle.json mirrors the manifest --- + const bundleJson = JSON.parse(await fs.readFile(path.join(okfRoot, '_meta', 'bundle.json'), 'utf8')); + assert.equal(bundleJson.stats.concepts, 2); + assert.deepEqual(bundleJson.stats.by_type, { guide: 1, concept: 1 }); + }); + + it('respects config.plugins.okf === false (exits cleanly)', async () => { + const tmp2 = await fs.mkdtemp(path.join(os.tmpdir(), 'okf-noop-')); + try { + await onPostBuild({ + config: { title: 'x', plugins: { okf: false } }, + pages: [], + outputDir: tmp2, + log: () => {} + }); + // Nothing should be created. + await fs.access(path.join(tmp2, 'okf')).then( + () => { throw new Error('okf bundle should not exist'); }, + () => {} + ); + } finally { + await fs.rm(tmp2, { recursive: true, force: true }); + } + }); + + it('respects config.plugins.okf.enabled === false (exits cleanly)', async () => { + const tmp2 = await fs.mkdtemp(path.join(os.tmpdir(), 'okf-enabled-false-')); + try { + await onPostBuild({ + config: { title: 'x', plugins: { okf: { enabled: false } } }, + pages: [], + outputDir: tmp2, + log: () => {} + }); + await fs.access(path.join(tmp2, 'okf')).then( + () => { throw new Error('okf bundle should not exist'); }, + () => {} + ); + } finally { + await fs.rm(tmp2, { recursive: true, force: true }); + } + }); + + it('respects capability filter (capabilities does not include post-build)', async () => { + const tmp2 = await fs.mkdtemp(path.join(os.tmpdir(), 'okf-cap-filter-')); + try { + await onPostBuild({ + config: { title: 'x', plugins: { okf: { capabilities: ['head'] } } }, + pages: [], + outputDir: tmp2, + log: () => {} + }); + await fs.access(path.join(tmp2, 'okf')).then( + () => { throw new Error('okf bundle should not exist'); }, + () => {} + ); + } finally { + await fs.rm(tmp2, { recursive: true, force: true }); + } + }); + + it('runs by default when no plugins.okf entry is set in the config (core plugin)', async () => { + // OKF is a core plugin โ€” it's auto-loaded and runs + // with empty opts when the user hasn't configured it. This test + // guards the default-enabled contract: a project with no + // `plugins.okf` entry at all still gets an OKF bundle generated. + // The graph viewer is opt-in (graph:true) โ€” it must + // NOT be generated by default, even when OKF itself runs. + const tmp2 = await fs.mkdtemp(path.join(os.tmpdir(), 'okf-default-')); + try { + await onPostBuild({ + config: { title: 'Default', url: 'https://example.com' /* no plugins field at all */ }, + pages: [{ + outputPath: 'index.html', + frontmatter: { title: 'Home', description: 'Landing' }, + sourcePath: '', + rawMarkdown: '# Home' + }], + outputDir: tmp2, + log: () => {} + }); + // Bundle SHOULD exist because the plugin runs with default opts. + const yaml = await fs.readFile(path.join(tmp2, 'okf', 'okf.yaml'), 'utf8'); + assert.match(yaml, /name: default/); + assert.match(yaml, /concepts: 1/); + // Graph viewer is opt-in โ†’ no graph artefacts on disk by default. + const graphCheck = (p: string) => fs.access(p).then( + () => { throw new Error(`${p} should NOT exist when graph is not enabled`); }, + () => {} + ); + await graphCheck(path.join(tmp2, 'okf', 'graph/index.html')); + await graphCheck(path.join(tmp2, 'okf', 'graph/graph.json')); + await graphCheck(path.join(tmp2, 'okf', 'graph/graph.js')); + await graphCheck(path.join(tmp2, 'okf', 'graph/graph.css')); + const indexMd = await fs.readFile(path.join(tmp2, 'okf', 'index.md'), 'utf8'); + assert.doesNotMatch(indexMd, /Graph viewer/); + } finally { + await fs.rm(tmp2, { recursive: true, force: true }); + } + }); + + it('writes the graph viewer only when config.plugins.okf.graph === true', async () => { + const tmp2 = await fs.mkdtemp(path.join(os.tmpdir(), 'okf-graph-on-')); + try { + await onPostBuild({ + config: { title: 'Graph', url: 'https://example.com', plugins: { okf: { graph: true } } }, + pages: [{ + outputPath: 'a.html', + frontmatter: { title: 'A', type: 'guide' }, + sourcePath: '', + rawMarkdown: '# A' + }], + outputDir: tmp2, + log: () => {} + }); + const okfRoot = path.join(tmp2, 'okf'); + await fs.access(path.join(okfRoot, 'graph/index.html')); + await fs.access(path.join(okfRoot, 'graph/graph.json')); + await fs.access(path.join(okfRoot, 'graph/graph.js')); + await fs.access(path.join(okfRoot, 'graph/graph.css')); + const indexMd = await fs.readFile(path.join(okfRoot, 'index.md'), 'utf8'); + assert.match(indexMd, /Graph viewer/); + const graphJson = JSON.parse(await fs.readFile(path.join(okfRoot, 'graph/graph.json'), 'utf8')); + assert.equal(graphJson.nodes.length, 1); + assert.equal(graphJson.nodes[0].id, 'a'); + } finally { + await fs.rm(tmp2, { recursive: true, force: true }); + } + }); + + it('honours the legacy generateGraphViewer flag and warns about deprecation', async () => { + const tmp2 = await fs.mkdtemp(path.join(os.tmpdir(), 'okf-legacy-graph-')); + const warnings: string[] = []; + const origLog = console.log; + console.log = (...args: any[]) => warnings.push(args.join(' ')); + try { + await onPostBuild({ + config: { title: 'Legacy', url: 'https://example.com', plugins: { okf: { generateGraphViewer: true } } }, + pages: [{ + outputPath: 'a.html', + frontmatter: { title: 'A', type: 'guide' }, + sourcePath: '', + rawMarkdown: '# A' + }], + outputDir: tmp2, + log: () => {} + }); + const okfRoot = path.join(tmp2, 'okf'); + await fs.access(path.join(okfRoot, 'graph/index.html')); + assert.ok( + warnings.some(w => /generateGraphViewer.*deprecated/i.test(w)), + `expected deprecation warning, got ${JSON.stringify(warnings)}` + ); + } finally { + console.log = origLog; + await fs.rm(tmp2, { recursive: true, force: true }); + } + }); + + it('uses empty stats when no pages match', async () => { + const tmp3 = await fs.mkdtemp(path.join(os.tmpdir(), 'okf-empty-')); + try { + await onPostBuild({ + config: { title: 'empty', plugins: { okf: {} } }, + pages: [{ outputPath: 'x.html', frontmatter: { noindex: true }, sourcePath: '', rawMarkdown: '' }], + outputDir: tmp3, + log: () => {} + }); + const yaml = await fs.readFile(path.join(tmp3, 'okf', 'okf.yaml'), 'utf8'); + assert.match(yaml, /concepts: 0/); + } finally { + await fs.rm(tmp3, { recursive: true, force: true }); + } + }); +}); \ No newline at end of file diff --git a/packages/plugins/okf/tests/tsconfig.json b/packages/plugins/okf/tests/tsconfig.json new file mode 100644 index 0000000..54fa06d --- /dev/null +++ b/packages/plugins/okf/tests/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "..", + "noEmit": true, + "strict": false, + "types": ["node"] + }, + "include": ["../src/**/*", "./**/*"], + "exclude": ["node_modules", "../dist", "../node_modules"] +} \ No newline at end of file diff --git a/packages/plugins/okf/tsconfig.build.json b/packages/plugins/okf/tsconfig.build.json new file mode 100644 index 0000000..73fa2f2 --- /dev/null +++ b/packages/plugins/okf/tsconfig.build.json @@ -0,0 +1,8 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "rootDir": "./src", + "noEmit": false + }, + "include": ["src/**/*"] +} \ No newline at end of file diff --git a/packages/plugins/okf/tsconfig.json b/packages/plugins/okf/tsconfig.json new file mode 100644 index 0000000..697d12f --- /dev/null +++ b/packages/plugins/okf/tsconfig.json @@ -0,0 +1,11 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": ".", + "strict": false, + "noEmit": true + }, + "include": ["src/**/*", "tests/**/*"], + "exclude": ["node_modules", "dist"] +} diff --git a/packages/plugins/openapi/LICENSE b/packages/plugins/openapi/LICENSE new file mode 100644 index 0000000..f4432ba --- /dev/null +++ b/packages/plugins/openapi/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/packages/plugins/openapi/README.md b/packages/plugins/openapi/README.md new file mode 100644 index 0000000..0ba713b --- /dev/null +++ b/packages/plugins/openapi/README.md @@ -0,0 +1,17 @@ +# @docmd/plugin-openapi + +Render OpenAPI 3.x API reference documentation directly from JSON or YAML spec files inside your Markdown pages at build time. Core plugin, already included in the core. + +```bash +docmd add openapi +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/openapi/build.js b/packages/plugins/openapi/build.js new file mode 100644 index 0000000..61191a9 --- /dev/null +++ b/packages/plugins/openapi/build.js @@ -0,0 +1,32 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import fs from 'fs'; +import path from 'path'; +import { fileURLToPath } from 'url'; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); + +// Ensure dist exists +if (!fs.existsSync(path.join(__dirname, 'dist'))) { + fs.mkdirSync(path.join(__dirname, 'dist')); +} + +// Copy CSS +fs.copyFileSync( + path.join(__dirname, 'src', 'openapi.css'), + path.join(__dirname, 'dist', 'openapi.css') +); + +console.log('OpenAPI assets copied to dist/'); \ No newline at end of file diff --git a/packages/plugins/openapi/package.json b/packages/plugins/openapi/package.json new file mode 100644 index 0000000..260c2f9 --- /dev/null +++ b/packages/plugins/openapi/package.json @@ -0,0 +1,70 @@ +{ + "name": "@docmd/plugin-openapi", + "version": "0.8.12", + "description": "OpenAPI documentation generator plugin for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "default": "./dist/index.js" + } + }, + "docmd": { + "key": "openapi", + "kind": "plugin", + "displayName": "OpenAPI", + "tagline": "OpenAPI / Swagger spec rendering for docmd.", + "capabilities": [ + "markdown", + "assets" + ] + }, + "scripts": { + "build": "tsc -p tsconfig.json && node build.js" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@docmd/api": "workspace:*" + }, + "dependencies": { + "@docmd/utils": "workspace:*" + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "plugin", + "openapi", + "swagger", + "rest", + "api-docs", + "documentation", + "markdown", + "static-site-generator", + "zero-config", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/openapi/src/index.ts b/packages/plugins/openapi/src/index.ts new file mode 100644 index 0000000..ec4be3f --- /dev/null +++ b/packages/plugins/openapi/src/index.ts @@ -0,0 +1,389 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import fs from 'fs'; +import path from 'path'; +import { createRequire } from 'module'; +import { fileURLToPath } from 'url'; +import { safePath, asUserPath } from '@docmd/utils'; +import type { PluginDescriptor } from '@docmd/api'; + +const require = createRequire(import.meta.url); +const __dirname = path.dirname(fileURLToPath(import.meta.url)); + +export const plugin: PluginDescriptor = { + name: 'openapi', + version: '0.8.12', + capabilities: ['markdown', 'assets'] +}; + +// --------------------------------------------------------------------------- +// Types (minimal OpenAPI 3.x subset) +// --------------------------------------------------------------------------- + +interface OASchema { + type?: string; + format?: string; + description?: string; + properties?: Record; + items?: OASchema; + enum?: (string | number)[]; + required?: string[]; + $ref?: string; + example?: unknown; + default?: unknown; + nullable?: boolean; + oneOf?: OASchema[]; + anyOf?: OASchema[]; + allOf?: OASchema[]; +} + +interface OAParameter { + name: string; + in: 'query' | 'path' | 'header' | 'cookie'; + description?: string; + required?: boolean; + schema?: OASchema; + example?: unknown; +} + +interface OAMediaType { + schema?: OASchema; + example?: unknown; +} + +interface OARequestBody { + description?: string; + required?: boolean; + content?: Record; +} + +interface OAResponse { + description?: string; + content?: Record; +} + +interface OAOperation { + operationId?: string; + summary?: string; + description?: string; + tags?: string[]; + parameters?: OAParameter[]; + requestBody?: OARequestBody; + responses?: Record; + deprecated?: boolean; +} + +interface OAPathItem { + get?: OAOperation; + post?: OAOperation; + put?: OAOperation; + patch?: OAOperation; + delete?: OAOperation; + head?: OAOperation; + options?: OAOperation; +} + +interface OASpec { + openapi?: string; + info?: { title?: string; version?: string; description?: string }; + paths?: Record; + components?: { schemas?: Record }; +} + +// --------------------------------------------------------------------------- +// Helpers +// --------------------------------------------------------------------------- + +const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'] as const; + +const METHOD_COLORS: Record = { + get: '#10b981', + post: '#3b82f6', + put: '#f59e0b', + patch: '#8b5cf6', + delete: '#ef4444', + head: '#6b7280', + options: '#6b7280' +}; + +function esc(str: string): string { + return String(str) + .replace(/&/g, '&') + .replace(//g, '>') + .replace(/"/g, '"'); +} + +function describe(str: string | undefined, options: any): string { + if (!str) return ''; + return options?.allowRawHtml ? str : esc(str); +} + +/** Resolve a $ref like #/components/schemas/Foo against the spec */ +function resolveRef(ref: string, spec: OASpec): OASchema | null { + if (!ref.startsWith('#/')) return null; + const parts = ref.slice(2).split('/'); + let node: any = spec; + for (const part of parts) { + if (node == null || typeof node !== 'object') return null; + node = node[part]; + } + return node as OASchema | null; +} + +function resolveSchema(schema: OASchema | undefined, spec: OASpec, depth = 0): OASchema { + if (!schema) return {}; + if (schema.$ref) return resolveRef(schema.$ref, spec) || schema; + return schema; +} + +/** Render a schema as a compact type string */ +function typeLabel(schema: OASchema | undefined, spec: OASpec): string { + if (!schema) return 'any'; + const resolved = resolveSchema(schema, spec); + if (resolved.$ref) return resolved.$ref.split('/').pop() || 'object'; + if (resolved.type === 'array') return `array[${typeLabel(resolved.items, spec)}]`; + if (resolved.oneOf) return resolved.oneOf.map(s => typeLabel(s, spec)).join(' | '); + if (resolved.anyOf) return resolved.anyOf.map(s => typeLabel(s, spec)).join(' | '); + if (resolved.enum) return resolved.enum.map(v => `"${v}"`).join(' | '); + return [resolved.type, resolved.format].filter(Boolean).join(':') || 'any'; +} + +/** Render schema properties as an HTML table */ +function renderSchemaTable(schema: OASchema | undefined, spec: OASpec, options: any): string { + if (!schema) return ''; + const resolved = resolveSchema(schema, spec); + const props = resolved.properties; + if (!props || Object.keys(props).length === 0) return ''; + + const required = new Set(resolved.required || []); + const rows = Object.entries(props).map(([name, prop]) => { + const r = resolveSchema(prop, spec); + return ` + ${esc(name)}${required.has(name) ? ' *' : ''} + ${esc(typeLabel(prop, spec))} + ${describe(r.description, options)} + ${r.default !== undefined ? `${esc(String(r.default))}` : ''} + `; + }).join(''); + + return ` + + ${rows} +
      FieldTypeDescriptionDefault
      `; +} + +/** Render a single operation */ +function renderOperation(method: string, path_: string, op: OAOperation, spec: OASpec, options: any): string { + const color = METHOD_COLORS[method] || '#6b7280'; + const deprecated = op.deprecated ? 'DEPRECATED' : ''; + const summaryOnly = options?.summaryOnly === true; + + // Parameters + let paramsHtml = ''; + if (!summaryOnly && op.parameters && op.parameters.length > 0) { + const rows = op.parameters.map(p => { + const r = resolveSchema(p.schema, spec); + return ` + ${esc(p.name)}${p.required ? ' *' : ''} + ${esc(p.in)} + ${esc(typeLabel(p.schema, spec))} + ${describe(p.description, options)} + `; + }).join(''); + paramsHtml = `
      Parameters
      + + + ${rows} +
      NameInTypeDescription
      `; + } + + // Request body + let requestHtml = ''; + if (op.requestBody?.content) { + const entries = Object.entries(op.requestBody.content); + requestHtml = `
      Request Body${op.requestBody.required ? ' *' : ''}
      `; + for (const [contentType, media] of entries) { + requestHtml += `

      ${esc(contentType)}

      `; + requestHtml += renderSchemaTable(media.schema, spec, options); + } + } + + // Responses + let responsesHtml = ''; + if (!summaryOnly && op.responses) { + const statusCodes = Object.entries(op.responses); + const rows = statusCodes.map(([code, resp]) => { + const cls = code.startsWith('2') ? 'oa-status-ok' : code.startsWith('4') ? 'oa-status-err' : 'oa-status-other'; + let schemaInfo = ''; + if (resp.content) { + const firstMedia = Object.values(resp.content)[0]; + if (firstMedia?.schema) schemaInfo = `
      ${esc(typeLabel(firstMedia.schema, spec))}`; + } + return ` + ${esc(code)} + ${describe(resp.description, options)}${schemaInfo} + `; + }).join(''); + responsesHtml = `
      Responses
      + + + ${rows} +
      StatusDescription
      `; + } + + const id = `oa-${method}-${path_.replace(/[^a-z0-9]/gi, '-').toLowerCase()}`; + + return `
      +
      + ${method.toUpperCase()} + ${esc(path_)} + ${deprecated} +
      + ${op.summary ? `

      ${esc(op.summary)}

      ` : ''} + ${op.description ? `

      ${describe(op.description, options)}

      ` : ''} + ${paramsHtml} + ${requestHtml} + ${responsesHtml} +
      `; +} + +/** Parse OpenAPI spec from a file path (JSON or YAML). specPath is validated + * upstream by safePath() in renderSpec(); this function assumes it is safe. */ +function parseSpec(specPath: string): OASpec { + // eslint-disable-next-line docmd/no-unsafe-fs-read -- specPath is validated by safePath() in renderSpec() + const raw = fs.readFileSync(specPath, 'utf8'); + // JSON detection + const trimmed = raw.trimStart(); + if (trimmed.startsWith('{') || trimmed.startsWith('[')) { + return JSON.parse(raw); + } + // Minimal YAML parser for OpenAPI specs (handles the common subset) + // We avoid a full YAML dep by using JSON if possible, otherwise note the limitation + try { + // Try to require js-yaml if available (won't throw at import time since it's optional) + // eslint-disable-next-line @typescript-eslint/no-require-imports + const yaml = require('js-yaml'); + return yaml.load(raw) as OASpec; + } catch { + throw new Error(`OpenAPI plugin: YAML spec at "${specPath}" requires js-yaml to be installed.\nRun: npm install js-yaml`); + } +} + +/** Render full spec as HTML */ +function renderSpec(specPath: string, rootDir: string, options: any): string { + // Phase 1.A: CWE-22 fix (S-2, N-S2). Use safePath() to enforce boundary. + // Absolute paths and ../ traversal are rejected by safePath() (throws). + let absPath: string; + try { + absPath = safePath(rootDir, asUserPath(specPath)); + } catch (_e: any) { + return `
      OpenAPI spec path escapes project root: ${esc(specPath)}
      `; + } + + if (!fs.existsSync(absPath)) { + return `
      OpenAPI spec not found: ${esc(specPath)}
      `; + } + + let spec: OASpec; + try { + spec = parseSpec(absPath); + } catch (e: any) { + return `
      Failed to parse OpenAPI spec: ${esc(String(e.message))}
      `; + } + + const info = spec.info || {}; + let html = `
      `; + + if (options?.info !== false && info.title) { + const downloadLink = options?.download ? `JSON / YAML` : ''; + html += `
      +

      ${esc(info.title)}

      +
      + ${info.version ? `v${esc(info.version)}` : ''} + ${downloadLink} +
      +
      `; + } + if (info.description) { + html += `

      ${describe(info.description, options)}

      `; + } + + if (spec.paths) { + for (const [pathStr, pathItem] of Object.entries(spec.paths)) { + for (const method of HTTP_METHODS) { + const op = pathItem[method]; + if (op) { + html += renderOperation(method, pathStr, op, spec, options); + } + } + } + } + + html += '
      '; + return html; +} + +// --------------------------------------------------------------------------- +// Plugin hooks +// --------------------------------------------------------------------------- + +/** + * Extend markdown-it to handle ```openapi fences. + * Usage in markdown: + * + * ```openapi + * ./path/to/spec.json + * ``` + */ +export function markdownSetup(md: any, options: any): void { + const srcDir: string = options?.config?.src + ? path.resolve(process.cwd(), options.config.src) + : process.cwd(); + + const originalFence = md.renderer.rules.fence || ((tokens: any[], idx: number, opts: any, _env: any, self: any) => self.renderToken(tokens, idx, opts)); + + md.renderer.rules.fence = (tokens: any[], idx: number, opts: any, env: any, self: any) => { + const token = tokens[idx]; + const info = (token.info || '').trim(); + + if (info !== 'openapi') { + return originalFence(tokens, idx, opts, env, self); + } + + const specPath = token.content.trim(); + const pluginOptions = options?.config?.plugins?.openapi || {}; + return renderSpec(specPath, srcDir, pluginOptions); + }; +} + +/** + * Provide OpenAPI CSS asset. + */ +export function getAssets(_options?: any): any[] { + const distCssPath = path.resolve(__dirname, '..', 'dist', 'openapi.css'); + const srcCssPath = path.resolve(__dirname, '..', 'src', 'openapi.css'); + const cssPath = fs.existsSync(distCssPath) ? distCssPath : srcCssPath; + + // Only inject if our bundled CSS exists + if (!fs.existsSync(cssPath)) return []; + + return [{ + src: cssPath, + dest: 'assets/css/docmd-openapi.css', + type: 'css', + location: 'head' + }]; +} diff --git a/packages/plugins/openapi/src/openapi.css b/packages/plugins/openapi/src/openapi.css new file mode 100644 index 0000000..0f5950b --- /dev/null +++ b/packages/plugins/openapi/src/openapi.css @@ -0,0 +1,221 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +.oa-spec { + margin: 2rem 0; + font-family: var(--font-family-sans, system-ui, -apple-system, sans-serif); +} + +.oa-spec-header { + display: flex; + justify-content: space-between; + align-items: flex-end; + border-bottom: 2px solid var(--border-color, #eee); + padding-bottom: 0.5rem; + margin-bottom: 1.5rem; +} + +.oa-spec-title { + margin: 0; + font-size: 1.75rem; + font-weight: 700; + color: var(--text-heading, #111); +} + +.oa-spec-meta { + display: flex; + gap: 0.75rem; + align-items: center; +} + +.oa-spec-version { + font-size: 0.875rem; + font-weight: 600; + color: var(--text-muted, #666); + background: var(--code-bg, #f3f4f6); + padding: 0.125rem 0.5rem; + border-radius: 9999px; +} + +.oa-download-link { + font-size: 0.75rem; + font-weight: 600; + color: var(--link-color, #3b82f6); + text-decoration: none; + border: 1px solid var(--link-color, #3b82f6); + padding: 0.125rem 0.5rem; + border-radius: 4px; + transition: all 0.2s; +} + +.oa-download-link:hover { + background: var(--link-color, #3b82f6); + color: #fff; +} + +.oa-spec-description { + color: var(--text-muted, #666); + line-height: 1.6; + margin-bottom: 2rem; +} + +.oa-operation { + margin-bottom: 2rem; + border: 1px solid var(--border-color, #eee); + border-radius: 8px; + overflow: hidden; + background: var(--bg-color, #fff); +} + +.oa-operation-header { + display: flex; + align-items: center; + gap: 1rem; + padding: 0.75rem 1rem; + background: var(--code-bg, #f9fafb); + border-bottom: 1px solid var(--border-color, #eee); +} + +.oa-method { + color: #fff; + padding: 0.25rem 0.75rem; + border-radius: 4px; + font-weight: 700; + font-size: 0.75rem; + min-width: 65px; + text-align: center; +} + +.oa-path { + font-weight: 600; + font-family: var(--font-family-mono, monospace); + color: var(--text-heading, #111); +} + +.oa-deprecated { + font-size: 0.7rem; + font-weight: 800; + color: #ef4444; + letter-spacing: 0.05em; +} + +.oa-summary { + padding: 1rem 1rem 0; + margin: 0; + font-weight: 600; + font-size: 1.1rem; + color: var(--text-heading); +} + +.oa-description { + padding: 0.5rem 1rem 1rem; + margin: 0; + color: var(--text-muted, #4b5563); + font-size: 0.95rem; + line-height: 1.5; +} + +.oa-operation h5 { + margin: 1.5rem 1rem 0.5rem; + font-size: 0.8rem; + text-transform: uppercase; + letter-spacing: 0.05em; + color: var(--text-muted, #6b7280); + font-weight: 700; +} + +.oa-content-type { + padding: 0 1rem; + margin: 0.5rem 0; +} + +.oa-content-type code { + font-size: 0.8rem; + background: var(--code-bg); + padding: 0.2rem 0.4rem; + border-radius: 4px; +} + +.oa-schema-table { + width: 100%; + border-collapse: collapse; + margin: 1rem 0 0; /* Margin top only as requested */ + font-size: 0.9rem; +} + +.oa-schema-table th, .oa-schema-table td { + padding: 0.75rem 1rem; + text-align: left; + border-bottom: 1px solid var(--border-color, #eee); +} + +.oa-schema-table th { + background: var(--code-bg, #f9fafb); + font-weight: 600; + color: var(--text-muted, #4b5563); +} + +.oa-required { + color: #ef4444; + margin-left: 0.25rem; +} + +.oa-type { + color: #0891b2; + font-family: var(--font-family-mono, monospace); + font-size: 0.85rem; +} + +.oa-param-in { + font-size: 0.75rem; + background: var(--code-bg, #f3f4f6); + padding: 0.125rem 0.375rem; + border-radius: 4px; + color: var(--text-muted, #4b5563); +} + +.oa-status-badge { + padding: 0.125rem 0.5rem; + border-radius: 4px; + font-weight: 600; + font-size: 0.8rem; +} + +.oa-status-ok { background: #d1fae5; color: #065f46; } +.oa-status-err { background: #fee2e2; color: #991b1b; } +.oa-status-other { background: #f3f4f6; color: #4b5563; } + +/* Dark Mode Overrides */ +:root[data-theme=dark] .oa-type { + color: #22d3ee; +} + +:root[data-theme=dark] .oa-status-ok { background: #065f4633; color: #34d399; } +:root[data-theme=dark] .oa-status-err { background: #991b1b33; color: #f87171; } +:root[data-theme=dark] .oa-status-other { background: #27272a; color: #a1a1aa; } + +.oa-error { + padding: 1rem; + background: #fef2f2; + border: 1px solid #fee2e2; + color: #991b1b; + border-radius: 8px; + margin: 1rem 0; +} + +:root[data-theme=dark] .oa-error { + background: #991b1b22; + border-color: #991b1b44; + color: #f87171; +} \ No newline at end of file diff --git a/packages/plugins/openapi/tsconfig.json b/packages/plugins/openapi/tsconfig.json new file mode 100644 index 0000000..85a5338 --- /dev/null +++ b/packages/plugins/openapi/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/plugins/pwa/LICENSE b/packages/plugins/pwa/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/pwa/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/pwa/README.md b/packages/plugins/pwa/README.md new file mode 100644 index 0000000..9948487 --- /dev/null +++ b/packages/plugins/pwa/README.md @@ -0,0 +1,26 @@ +# @docmd/plugin-pwa + +Makes your docmd site installable and offline-capable - generates a web manifest and service worker with intelligent caching and automatic cache busting on every build. Bundled with `@docmd/core`. + +```js +// docmd.config.js - all options are optional +module.exports = { + plugins: { + pwa: { + themeColor: '#0097ff', + bgColor: '#ffffff', + logo: 'assets/images/logo.png' + } + } +}; +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/pwa/package.json b/packages/plugins/pwa/package.json new file mode 100644 index 0000000..e8fb16a --- /dev/null +++ b/packages/plugins/pwa/package.json @@ -0,0 +1,67 @@ +{ + "name": "@docmd/plugin-pwa", + "version": "0.8.12", + "description": "Progressive Web App (PWA) plugin for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "docmd": { + "key": "pwa", + "kind": "plugin", + "displayName": "PWA", + "tagline": "Progressive Web App support for docmd with offline caching.", + "capabilities": [ + "post-build", + "head", + "body" + ] + }, + "scripts": { + "build": "tsc" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@docmd/api": "workspace:*" + }, + "dependencies": { + "@docmd/utils": "workspace:*" + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "plugin", + "pwa", + "progressive-web-app", + "service-worker", + "manifest", + "offline", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/pwa/src/index.ts b/packages/plugins/pwa/src/index.ts new file mode 100644 index 0000000..a684614 --- /dev/null +++ b/packages/plugins/pwa/src/index.ts @@ -0,0 +1,197 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import fs from 'fs/promises'; +import path from 'path'; +import type { PluginDescriptor } from '@docmd/api'; +import { attrEsc } from '@docmd/utils'; + +export const plugin: PluginDescriptor = { + name: 'pwa', + version: '0.8.12', + capabilities: ['post-build', 'head', 'body'] +}; + +export async function onPostBuild({ config, outputDir, log }: any) { + const pwaConfig = config.plugins?.pwa || {}; + if (pwaConfig.enabled === false) return; // Enabled by default if loaded + + if (log) log('Generating PWA assets'); + + let icons = pwaConfig.icons; + if (!icons) { + let logoUrl = pwaConfig.logo; + if (!logoUrl && config.logo) { + if (typeof config.logo === 'string') logoUrl = config.logo; + else if (config.logo.light) logoUrl = config.logo.light; + } + if (!logoUrl && config.favicon) { + logoUrl = config.favicon; + } + + if (logoUrl) { + const cleanUrl = logoUrl.startsWith('http') ? logoUrl : (logoUrl.startsWith('/') ? logoUrl : `/${logoUrl}`); + icons = [ + { src: cleanUrl, sizes: '192x192', type: 'image/png' }, + { src: cleanUrl, sizes: '512x512', type: 'image/png' } + ]; + } + } + + const manifest: any = { + name: config.title, + short_name: config.title, + description: config.description || 'Documentation generated by docmd', + start_url: './', + display: 'standalone', + background_color: pwaConfig.bgColor || '#ffffff', + theme_color: pwaConfig.themeColor || '#1e293b', + }; + if (icons) manifest.icons = icons; + + await fs.writeFile( + path.join(outputDir, 'manifest.webmanifest'), + JSON.stringify(manifest, null, 2) + ); + + // Generate a basic Service Worker for offline caching + const swContent = ` + const CACHE_NAME = 'docmd-cache-${Date.now()}'; + + self.addEventListener('install', (event) => { + self.skipWaiting(); + }); + + self.addEventListener('activate', (event) => { + event.waitUntil( + caches.keys().then((cacheNames) => { + return Promise.all( + cacheNames.map((cacheName) => { + if (cacheName !== CACHE_NAME && cacheName.startsWith('docmd-cache-')) { + return caches.delete(cacheName); + } + }) + ); + }).then(() => self.clients.claim()) + ); + }); + + self.addEventListener('fetch', (event) => { + if (event.request.method !== 'GET') return; + + event.respondWith( + caches.match(event.request).then((cachedResponse) => { + if (cachedResponse) { + // Return cached, but optionally fetch in background to update cache + fetch(event.request).then(response => { + if(response && response.status === 200 && response.type === 'basic' && !response.redirected) { + const responseToCache = response.clone(); + caches.open(CACHE_NAME).then(cache => { + cache.put(event.request, responseToCache); + }); + } + }).catch(() => {}); + return cachedResponse; + } + + return fetch(event.request).then((response) => { + // Safari WebKit Strict Security Policy: Service Workers cannot blindly use cache.put on redirected streams. + // Rather than returning a 302 (Response.redirect) which triggers loop vulnerabilities in some SPAs, + // we synthesize a literal clone of the stream masking the redirected boolean flag. + let cacheResponse = response.clone(); + let returnResponse = response; + + if (response && response.redirected) { + const clonedStream = response.clone().body; + const headers = new Headers(response.headers); + cacheResponse = new Response(clonedStream, { + headers: headers, + status: response.status, + statusText: response.statusText, + }); + returnResponse = cacheResponse.clone(); + } + + if(!response || response.status !== 200 || response.type !== 'basic') { + return returnResponse; + } + + caches.open(CACHE_NAME) + .then((cache) => { + cache.put(event.request, cacheResponse); + }); + return returnResponse; + }); + }) + ); + }); + `; + + await fs.writeFile( + path.join(outputDir, 'service-worker.js'), + swContent.trim() + ); +} + +export function generateMetaTags(config: any) { + const pwaConfig = config.plugins?.pwa || {}; + if (pwaConfig.enabled === false) return ''; + + // Phase 1.C (S-5 fix): validate themeColor is a real CSS color before + // interpolation. Format: #hex (3/4/6/8 digits), rgb(), rgba(), hsl(), hsla(), + // or a CSS named color. Falls back to default on invalid input. + const DEFAULT_THEME_COLOR = '#1e293b'; + const rawTheme = pwaConfig.themeColor || DEFAULT_THEME_COLOR; + const CSS_COLOR_RE = /^(#[0-9a-fA-F]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\)|[a-zA-Z]+)$/; + const themeColor = CSS_COLOR_RE.test(rawTheme) ? rawTheme : DEFAULT_THEME_COLOR; + if (rawTheme !== DEFAULT_THEME_COLOR && themeColor === DEFAULT_THEME_COLOR) { + console.error(`[pwa] Invalid themeColor: ${JSON.stringify(rawTheme)}. Falling back to ${DEFAULT_THEME_COLOR}.`); + } + // attrEsc is defence-in-depth: a valid hex color is unaffected, but a payload + // that somehow slipped past the regex still won't break out of the attribute. + + return ` + + + + + +`; +} + +export function generateScripts(config: any) { + const pwaConfig = config.plugins?.pwa || {}; + if (pwaConfig.enabled === false) return {}; + + const swRegistration = ` + + `; + + return { headScriptsHtml: swRegistration }; +} \ No newline at end of file diff --git a/packages/plugins/pwa/tsconfig.json b/packages/plugins/pwa/tsconfig.json new file mode 100644 index 0000000..7befc89 --- /dev/null +++ b/packages/plugins/pwa/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/plugins/search/LICENSE b/packages/plugins/search/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/search/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/search/README.md b/packages/plugins/search/README.md new file mode 100644 index 0000000..6ecda03 --- /dev/null +++ b/packages/plugins/search/README.md @@ -0,0 +1,13 @@ +# @docmd/plugin-search + +Offline full-text search for docmd sites - builds a `search-index.json` at compile time, no API keys, no cloud, works in air-gapped environments. Powered by [minisearch](https://github.com/lucaong/minisearch) for fast fuzzy matching. Bundled with `@docmd/core`, enabled by default. + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/search/i18n/en.json b/packages/plugins/search/i18n/en.json new file mode 100644 index 0000000..130d77e --- /dev/null +++ b/packages/plugins/search/i18n/en.json @@ -0,0 +1,10 @@ +{ + "searchPlaceholder": "Search documentation...", + "searchNoResults": "No results found.", + "searchError": "Failed to load search index.", + "searchInitial": "Type to start searching...", + "searchClose": "Close search", + "searchNavigate": "to navigate", + "searchEscape": "to close", + "searchVersionBadge": "v{version}" +} \ No newline at end of file diff --git a/packages/plugins/search/i18n/hi.json b/packages/plugins/search/i18n/hi.json new file mode 100644 index 0000000..4332c5d --- /dev/null +++ b/packages/plugins/search/i18n/hi.json @@ -0,0 +1,10 @@ +{ + "searchPlaceholder": "เคฆเคธเฅเคคเคพเคตเฅ‡เคœเคผ เค–เฅ‹เคœเฅ‡เค‚...", + "searchNoResults": "เค•เฅ‹เคˆ เคชเคฐเคฟเคฃเคพเคฎ เคจเคนเฅ€เค‚ เคฎเคฟเคฒเคพเฅค", + "searchError": "เค–เฅ‹เคœ เค…เคจเฅเค•เฅเคฐเคฎเคฃเคฟเค•เคพ เคฒเฅ‹เคก เค•เคฐเคจเฅ‡ เคฎเฅ‡เค‚ เคตเคฟเคซเคฒเฅค", + "searchInitial": "เค–เฅ‹เคœเคจเฅ‡ เค•เฅ‡ เคฒเคฟเค เคŸเคพเค‡เคช เค•เคฐเฅ‡เค‚...", + "searchClose": "เค–เฅ‹เคœ เคฌเค‚เคฆ เค•เคฐเฅ‡เค‚", + "searchNavigate": "เคจเฅ‡เคตเคฟเค—เฅ‡เคŸ เค•เคฐเฅ‡เค‚", + "searchEscape": "เคฌเค‚เคฆ เค•เคฐเฅ‡เค‚", + "searchVersionBadge": "v{version}" +} \ No newline at end of file diff --git a/packages/plugins/search/i18n/ko.json b/packages/plugins/search/i18n/ko.json new file mode 100644 index 0000000..d668183 --- /dev/null +++ b/packages/plugins/search/i18n/ko.json @@ -0,0 +1,10 @@ +{ + "searchPlaceholder": "๋ฌธ์„œ ๊ฒ€์ƒ‰...", + "searchNoResults": "๊ฒ€์ƒ‰ ๊ฒฐ๊ณผ๊ฐ€ ์—†์Šต๋‹ˆ๋‹ค.", + "searchError": "๊ฒ€์ƒ‰ ์ƒ‰์ธ์„ ๋ถˆ๋Ÿฌ์˜ค์ง€ ๋ชปํ–ˆ์Šต๋‹ˆ๋‹ค.", + "searchInitial": "๊ฒ€์ƒ‰์–ด๋ฅผ ์ž…๋ ฅํ•˜์„ธ์š”...", + "searchClose": "๊ฒ€์ƒ‰ ๋‹ซ๊ธฐ", + "searchNavigate": "์ด๋™", + "searchEscape": "๋‹ซ๊ธฐ", + "searchVersionBadge": "v{version}" +} diff --git a/packages/plugins/search/i18n/zh.json b/packages/plugins/search/i18n/zh.json new file mode 100644 index 0000000..17b4480 --- /dev/null +++ b/packages/plugins/search/i18n/zh.json @@ -0,0 +1,10 @@ +{ + "searchPlaceholder": "ๆœ็ดขๆ–‡ๆกฃ...", + "searchNoResults": "ๆœชๆ‰พๅˆฐ็ป“ๆžœใ€‚", + "searchError": "ๆ— ๆณ•ๅŠ ่ฝฝๆœ็ดข็ดขๅผ•ใ€‚", + "searchInitial": "่พ“ๅ…ฅๅผ€ๅง‹ๆœ็ดข...", + "searchClose": "ๅ…ณ้—ญๆœ็ดข", + "searchNavigate": "ๅฏผ่ˆช", + "searchEscape": "ๅ…ณ้—ญ", + "searchVersionBadge": "v{version}" +} \ No newline at end of file diff --git a/packages/plugins/search/package.json b/packages/plugins/search/package.json new file mode 100644 index 0000000..30f2278 --- /dev/null +++ b/packages/plugins/search/package.json @@ -0,0 +1,79 @@ +{ + "name": "@docmd/plugin-search", + "version": "0.8.12", + "description": "Offline full-text search for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "docmd": { + "key": "search", + "kind": "plugin", + "displayName": "Search", + "tagline": "Offline full-text search for docmd.", + "capabilities": [ + "post-build", + "init", + "head", + "body", + "assets", + "translations" + ] + }, + "scripts": { + "build": "tsc && esbuild src/client.ts --bundle --outfile=dist/docmd-search.js --format=esm --platform=browser --minify" + }, + "files": [ + "dist", + "i18n" + ], + "engines": { + "node": ">=18" + }, + "dependencies": { + "markdown-it": "^14.3.0", + "minisearch": "^7.2.0" + }, + "peerDependencies": { + "docmd-search": ">=0.1.0" + }, + "peerDependenciesMeta": { + "docmd-search": { + "optional": true + } + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/markdown-it": "^14.1.2", + "@types/node": "^24.13.3", + "esbuild": "^0.28.1" + }, + "keywords": [ + "docmd", + "plugin", + "search", + "minisearch", + "offline", + "indexing", + "keyword-matching", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/search/src/client.ts b/packages/plugins/search/src/client.ts new file mode 100644 index 0000000..008cc00 --- /dev/null +++ b/packages/plugins/search/src/client.ts @@ -0,0 +1,386 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import * as SemanticSearch from './semantic-client.js'; + +export {}; + +declare global { + interface Window { + DOCMD_SITE_ROOT?: string; + DOCMD_ROOT?: string; + lastFocusedElement?: HTMLElement | null; + closeDocmdSearch?: () => void; + } +} +declare const MiniSearch: any; + +(function () { + let miniSearch: any = null; + let isSemanticMode = false; // Track if semantic search is active + let isIndexLoaded = false; + let selectedIndex = -1; + const activeVersionFilters = new Set(); + let globalAllVersions: string[] = []; + const globalVersionColors: Record = {}; + + function initSearch() { + const searchModal = document.getElementById('docmd-search-modal') as HTMLElement; + const searchInput = document.getElementById('docmd-search-input') as HTMLInputElement; + const searchResults = document.getElementById('docmd-search-results') as HTMLElement; + + if (!searchModal || !searchInput || !searchResults) return; + + // showFilters: hide version filter bar when explicitly set to false + const showFilters = searchModal.dataset.showFilters !== 'false'; + + // Read translated strings from data attributes (injected server-side per locale) + const strings = { + initial: searchModal.dataset.searchInitial || 'Type to start searching...', + noResults: searchModal.dataset.searchNoResults || 'No results found.', + error: searchModal.dataset.searchError || 'Failed to load search index.' + }; + + // Use Site Root if available (for versioning), fallback to Context Root + const rawRoot = window.DOCMD_SITE_ROOT || window.DOCMD_ROOT || './'; + let ROOT_PATH = new URL(rawRoot, window.location.href).href; + if (!ROOT_PATH.endsWith('/')) ROOT_PATH += '/'; + + // Determine the locale-specific search index path. + // The index lives alongside the locale's HTML files: + // default locale: /search-index.json + // non-default: /hi/search-index.json + // Since ROOT_PATH already resolves to the correct locale root + // (e.g. https://docs.example.com/ or https://docs.example.com/hi/), + // we can simply append search-index.json to it. + // However, we need to detect our locale prefix from the current URL + // and build the fetch path relative to the site base. + const siteBase = (window.DOCMD_SITE_ROOT || window.DOCMD_ROOT || '/').replace(/\/$/, '') + '/'; + const currentPath = window.location.pathname; + + // Extract locale prefix from current URL path + // If URL is /hi/content/steps and base is /, locale prefix is "hi/" + const pathAfterBase = currentPath.startsWith(siteBase) + ? currentPath.slice(siteBase.length) + : currentPath.replace(/^\//, ''); + const firstSegment = pathAfterBase.split('/')[0]; + + // Check if the first segment looks like a locale (2-3 letter code) + // by checking the meta tag that the engine injects + const hreflangLinks = document.querySelectorAll('link[hreflang]'); + const knownLocales = new Set(); + hreflangLinks.forEach(link => { + const lang = link.getAttribute('hreflang'); + if (lang && lang !== 'x-default') knownLocales.add(lang); + }); + + const localePrefix = knownLocales.has(firstSegment) ? firstSegment + '/' : ''; + const baseUrl = new URL(siteBase, window.location.href).href; + const searchIndexUrl = baseUrl + localePrefix + 'search-index.json'; + + function escapeHtml(str: any): string { + const s = typeof str === 'string' ? str : String(str || ''); + return s.replace(/[&<>"']/g, m => ({ + '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' + })[m] as string); + } + + function getSnippet(text: string | undefined, query: string): string { + if (!text) return ''; + const terms = query.split(/\s+/).filter(t => t.length > 2); + let bestIndex = -1; + for (const term of terms) { + const idx = text.toLowerCase().indexOf(term.toLowerCase()); + if (idx >= 0) { bestIndex = idx; break; } + } + const start = Math.max(0, bestIndex - 60); + const end = Math.min(text.length, bestIndex + 60); + let snippet = text.substring(start, end); + if (start > 0) snippet = '...' + snippet; + if (end < text.length) snippet += '...'; + + snippet = escapeHtml(snippet); + + // Then apply highlighting marks (escape terms to match escaped snippet) + const safeTerms = terms.map(t => escapeHtml(t).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'); + if (safeTerms) { + snippet = snippet.replace(new RegExp(`(${safeTerms})`, 'gi'), '$1'); + } + return snippet; + } + + // 1. Open/Close Logic + function openSearch() { + searchModal.style.display = 'flex'; + window.lastFocusedElement = document.activeElement as HTMLElement | null; + setTimeout(() => searchInput.focus(), 50); + + if (!searchInput.value.trim()) { + const sanitized = `
      ${escapeHtml(strings.initial)}
      `; + searchResults.innerHTML = sanitized; + selectedIndex = -1; + } + if (!isIndexLoaded) loadIndex(); + } + + function closeSearch() { + searchModal.style.display = 'none'; + if (window.lastFocusedElement) window.lastFocusedElement.focus(); + selectedIndex = -1; + } + + // --- Event Delegation for Triggers (Survives SPA) --- + document.addEventListener('click', (e) => { + const target = e.target as HTMLElement | null; + if (target?.closest('.docmd-search-trigger')) { + e.preventDefault(); + openSearch(); + } + if (target === searchModal || target?.closest('.docmd-search-close')) { + closeSearch(); + } + }); + + // 2. Keyboard Navigation + document.addEventListener('keydown', (e) => { + if ((e.metaKey || e.ctrlKey) && e.key === 'k') { + e.preventDefault(); + searchModal.style.display === 'flex' ? closeSearch() : openSearch(); + } + + if (searchModal.style.display === 'flex') { + const items = searchResults.querySelectorAll('.search-result-item') as NodeListOf; + if (e.key === 'Escape') { e.preventDefault(); closeSearch(); } + else if (e.key === 'ArrowDown') { e.preventDefault(); if (items.length) { selectedIndex = (selectedIndex + 1) % items.length; updateSelection(items); } } + else if (e.key === 'ArrowUp') { e.preventDefault(); if (items.length) { selectedIndex = (selectedIndex - 1 + items.length) % items.length; updateSelection(items); } } + else if (e.key === 'Enter') { + e.preventDefault(); + if (selectedIndex >= 0 && items[selectedIndex]) items[selectedIndex].click(); + else if (items.length > 0) items[0].click(); + } + } + }); + + function updateSelection(items: NodeListOf) { + items.forEach((item, idx) => { + item.classList.toggle('selected', idx === selectedIndex); + if (idx === selectedIndex) item.scrollIntoView({ block: 'nearest' }); + }); + } + + // 3. Index Loading - fetches locale-specific index + async function loadIndex() { + // Auto-detect semantic search at runtime. We check BOTH: + // - The build-time hint (data-semantic="true") โ€” set when the + // build pipeline knew semantic was available at render time. + // - A runtime probe (HEAD request to manifest.json) โ€” catches + // the first-build case where deps were installed in onPostBuild + // (after generateScripts already rendered the page without + // data-semantic). The probe is a single network round-trip + // that only runs once per page load, so there's no perf cost. + const hasBuildHint = searchModal.dataset.semantic === 'true'; + let useSemantic = hasBuildHint; + + if (!useSemantic) { + try { + const probe = await fetch(`${siteBase}.docmd-search/manifest.json`, { method: 'HEAD' }); + if (probe.ok) useSemantic = true; + } catch { /* no index โ†’ keyword */ } + } + + try { + if (useSemantic) { + // โ”€โ”€ Semantic search path โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + const ctx: SemanticSearch.SemanticSearchContext = { + siteBase, + ROOT_PATH, + searchResults, + strings, + activeVersionFilters, + globalAllVersions, + globalVersionColors, + selectedIndex, + updateSelection, + showConfidence: searchModal.dataset.showConfidence === 'true' + }; + + await SemanticSearch.loadSemanticIndex(ctx); + + // Render version filters if versions were loaded and filters are enabled + if (globalAllVersions.length > 0 && showFilters) { + renderGlobalFilters(); + } + + isSemanticMode = true; + isIndexLoaded = true; + if (searchInput.value.trim()) searchInput.dispatchEvent(new Event('input')); + return; + } + + // โ”€โ”€ Keyword search path (default) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + const response = await fetch(searchIndexUrl); + if (response.headers.get("content-type")?.includes("text/html")) throw new Error("Invalid content type"); + if (!response.ok) throw new Error(String(response.status)); + + const jsonString = await response.text(); + const indexData = JSON.parse(jsonString); + + // Extract all versions globally from the raw MiniSearch index data + const docs = indexData.storedFields || {}; + globalAllVersions = [...new Set(Object.values(docs).map((d: any) => d.version).filter(Boolean))] as string[]; + globalAllVersions.sort(); + + const huePresets = [210, 150, 30, 330, 270, 60, 180, 0]; + globalAllVersions.forEach((v, i) => { + const hue = huePresets[i % huePresets.length]; + globalVersionColors[v] = { bg: `hsl(${hue}, 55%, 92%)`, fg: `hsl(${hue}, 60%, 35%)` }; + }); + + const CJK_AND_SPACELESS_REGEX = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uff66-\uff9f\uac00-\ud7af\u1100-\u11ff\u3130-\u318f\u0e00-\u0e7f\u0e80-\u0eff\u1780-\u17ff\u1000-\u109f\u0f00-\u0fff]/g; + miniSearch = MiniSearch.loadJSON(jsonString, { + fields: ['title', 'headings', 'text'], + storeFields: ['title', 'id', 'text', 'version'], + tokenize: (text: string) => { + const spaced = text.replace(CJK_AND_SPACELESS_REGEX, ' $& '); + const defaultTokenize = MiniSearch.getDefault ? MiniSearch.getDefault('tokenize') : null; + return defaultTokenize ? defaultTokenize(spaced) : spaced.toLowerCase().split(/[^a-zA-Z0-9_'\u00C0-\u017F\u00d0\u00f0\u00df\u00f8\u00e6\u0153\u03ac-\u03ce\u0400-\u04ff]+/u).filter(Boolean); + }, + searchOptions: { fuzzy: 0.2, prefix: true, boost: { title: 2, headings: 1.5 } } + }); + + console.log('[docmd-search] Index loaded. Versions found:', globalAllVersions.length); + if (globalAllVersions.length > 0 && showFilters) { + renderGlobalFilters(); + } + isIndexLoaded = true; + if (searchInput.value.trim()) searchInput.dispatchEvent(new Event('input')); + } catch { + const sanitized = `
      ${escapeHtml(strings.error)}
      `; + searchResults.innerHTML = sanitized; + } + } + + function renderGlobalFilters() { + if (globalAllVersions.length === 0 || !showFilters) return; + let filterContainer = document.getElementById('docmd-global-search-filters'); + if (!filterContainer) { + filterContainer = document.createElement('div'); + filterContainer.id = 'docmd-global-search-filters'; + filterContainer.style.cssText = 'padding: 12px 20px 8px 20px; border-bottom: 1px solid var(--docmd-border); display: flex; flex-wrap: wrap; gap: 8px;'; + searchResults.parentNode?.insertBefore(filterContainer, searchResults); + } + + const sanitized = globalAllVersions.map(v => { + const vc = globalVersionColors[v]; + const isActive = activeVersionFilters.has(v); + const icon = isActive + ? `` + : ``; + return ` + ${icon} ${escapeHtml(v)} + `; + }).join(''); + filterContainer.innerHTML = sanitized; + + filterContainer.querySelectorAll('.search-filter-tag').forEach(tag => { + tag.addEventListener('click', (e) => { + e.preventDefault(); + e.stopPropagation(); + const v = (tag as HTMLElement).dataset.version!; + if (activeVersionFilters.has(v)) activeVersionFilters.delete(v); + else activeVersionFilters.add(v); + renderGlobalFilters(); + if (searchInput.value.trim()) searchInput.dispatchEvent(new Event('input')); + }); + }); + } + + searchInput.addEventListener('input', (e) => { + const query = (e.target as HTMLInputElement).value.trim(); + selectedIndex = -1; + if (!query) { + const sanitized = `
      ${escapeHtml(strings.initial)}
      `; + searchResults.innerHTML = sanitized; + return; + } + if (!isIndexLoaded) return; + + // โ”€โ”€ Semantic mode โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + if (isSemanticMode) { + const ctx: SemanticSearch.SemanticSearchContext = { + siteBase, + ROOT_PATH, + searchResults, + strings, + activeVersionFilters, + globalAllVersions, + globalVersionColors, + selectedIndex, + updateSelection, + showConfidence: searchModal.dataset.showConfidence === 'true' + }; + SemanticSearch.performSemanticSearch(query, ctx); + return; + } + + // โ”€โ”€ Keyword mode (MiniSearch) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + let results = miniSearch.search(query); + + if (activeVersionFilters.size > 0) { + results = results.filter((r: any) => activeVersionFilters.has(r.version)); + } + + if (results.length === 0) { + const sanitized = `
      ${activeVersionFilters.size > 0 ? 'No results match the selected filters.' : escapeHtml(strings.noResults)}
      `; + searchResults.innerHTML = sanitized; + return; + } + + const sanitized = results.slice(0, 10).map((result: any, index: number) => { + const snippet = getSnippet(result.text, query); + // Strip leading slash to avoid double-slash when concatenating with ROOT_PATH + const cleanId = result.id.startsWith('/') ? result.id.slice(1) : result.id; + // Sanitize: collapse any accidental double slashes (except after protocol) + const linkHref = `${ROOT_PATH}${cleanId}`.replace(/([^:])\/\/+/g, '$1/'); + const vc = result.version ? globalVersionColors[result.version] : null; + const versionBadge = result.version + ? `
      ${escapeHtml(result.version)}
      ` + : ''; + return ` + +
      ${escapeHtml(result.title)}${versionBadge}
      +
      ${snippet}
      +       `; + }).join(''); + searchResults.innerHTML = sanitized; + + searchResults.querySelectorAll('.search-result-item').forEach((item, idx) => { + item.addEventListener('mouseenter', () => { selectedIndex = idx; updateSelection(searchResults.querySelectorAll('.search-result-item') as NodeListOf); }); + }); + }); + + // Close search when clicking a link (Important for SPA!) + searchResults.addEventListener('click', (e) => { + if ((e.target as HTMLElement).closest('.search-result-item')) closeSearch(); + }); + + window.closeDocmdSearch = closeSearch; + } + + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', initSearch); + } else { + initSearch(); + } +})(); \ No newline at end of file diff --git a/packages/plugins/search/src/index.ts b/packages/plugins/search/src/index.ts new file mode 100644 index 0000000..03db95c --- /dev/null +++ b/packages/plugins/search/src/index.ts @@ -0,0 +1,1051 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import fs from 'fs/promises'; +import nativeFs from 'fs'; +import MiniSearch from 'minisearch'; +import MarkdownIt from 'markdown-it'; +import { fileURLToPath } from 'url'; +import { createRequire } from 'module'; +import type { PluginDescriptor } from '@docmd/api'; +import { outputPathToSlug, sanitizeUrl } from '@docmd/api'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); +const require = createRequire(import.meta.url); + +export const plugin: PluginDescriptor = { + name: 'search', + version: '0.8.12', + // `init` lets onConfigResolved run at config-parse time โ€” that's where we + // compute the single `searchConfig` object. The build pipeline reads + // it from `config._searchConfig` everywhere else, so there's exactly + // one source of truth for "is semantic available at build time". + capabilities: ['post-build', 'init', 'head', 'body', 'assets', 'translations'] +}; + +// Resolve i18n directory (sibling to dist/ in the package) +const i18nDir = path.resolve(__dirname, '..', 'i18n'); + +/* โ”€โ”€ Search config (computed once at onConfigResolved) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +/** + * Resolved search configuration. Computed once per build, in + * `onConfigResolved`, and stamped on `config._searchConfig`. Every + * subsequent hook (`onPostBuild`, `getAssets`, `generateScripts`, + * EJS templates via the page context) reads from this same object โ€” + * no second source of truth, no chance of the `getAssets` and the + * `generateScripts` paths disagreeing about whether semantic is + * available. The shape is the contract for the search-modal EJS + * partial too: every key on this object is exposed to the template + * via `locals.searchConfig`. + */ +type SearchConfig = { + /** User has not opted out of search entirely (optionsMenu / config.search). */ + enabled: boolean; + /** User has explicitly requested semantic search in their config. */ + semanticRequested: boolean; + /** docmd-search is resolvable in the user's project. */ + docmdSearchInstalled: boolean; + /** All peer deps (transformers + onnxruntime-node) are resolvable. */ + peersInstalled: boolean; + /** True only when all three of the above are true โ€” that's when the modal + * emits `data-semantic="true"`, the .docmd-search-client.js asset ships, + * and the page points users at the semantic index. */ + semanticUsable: boolean; + /** The exact names of any peer deps that are missing. Empty when + * `peersInstalled` is true. Useful for the TUI: "Missing: transformers, onnxruntime-node". */ + missingPeers: string[]; + /** Stable list of peer-dep package names. Exposed so the TUI can emit + * per-dep `[ DONE ] @huggingface/transformers` lines without + * hard-coding the names in two places. */ + peerDeps: readonly string[]; +}; + +/** + * Module-level state. Reset on every `onConfigResolved` call so a + * dev-server rebuild starts fresh. Currently tracks: + * + * - `lastPeersHash` โ€” when the set of "missing peer deps" is + * identical to the previous build, we DON'T re-emit the + * "[ DONE ] Peer X ready" lines. The user only sees them on the + * first build (or the first build after a new dep becomes missing). + * This is the difference between "informative on first install" and + * "spammy on every rebuild". + */ +const _searchState: { + lastPeersHash: string | null; + lastConfig: SearchConfig | null; +} = { lastPeersHash: null, lastConfig: null }; + +/** + * Compute the full SearchConfig from the resolved config + filesystem. + * Idempotent โ€” called once at `onConfigResolved` and again inside + * `onPostBuild` if a fresh install was performed. Pure: no I/O + * outside of `require.resolve` and `resolveDocmdSearch`. + */ +function buildSearchConfig(config: any): SearchConfig { + const isEnabled = config.optionsMenu + ? config.optionsMenu.components.search !== false + : config.search !== false; + const pluginOptions = (config.plugins && config.plugins.search) || {}; + const semanticRequested = pluginOptions.semantic === true; + const docmdSearchInstalled = resolveDocmdSearch() !== null; + const resolvePaths = [process.cwd(), path.join(process.cwd(), 'node_modules')]; + + // List every peer dep and which are missing, in stable order. + const missingPeers: string[] = []; + for (const pkg of PEER_DEPS) { + try { require.resolve(pkg, { paths: resolvePaths }); } + catch { missingPeers.push(pkg); } + } + const peersInstalled = missingPeers.length === 0; + const semanticUsable = semanticRequested && docmdSearchInstalled && peersInstalled; + + return { + enabled: isEnabled, + semanticRequested, + docmdSearchInstalled, + peersInstalled, + semanticUsable, + missingPeers, + peerDeps: PEER_DEPS, + }; +} + +/** Hash used to decide whether to re-emit the peer-deps TUI block. */ +function peersHash(sc: SearchConfig): string { + return sc.peersInstalled ? 'ok' : 'missing:' + sc.missingPeers.join(','); +} + +/* โ”€โ”€ Semantic search peer-dep detection โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +/** + * Check if docmd-search is available (installed as a peer/optional dep). + * Returns the importable path (file:// URL) or null if not found. + */ +function resolveDocmdSearch(): string | null { + // #163 (deeper fix): previously this walked `__dirname` and two parent + // directories, which let `docmd-search` resolve into the monorepo's + // own node_modules when the user runs the binary through a pnpm/npm + // symlink. The plugin then thought the user's project had it installed, + // silently skipped the peer-dep install, and fell back to keyword + // search with a misleading message. We now scope resolution to the + // user's project only โ€” `process.cwd()/node_modules`. The monorepo's + // own dev workflow goes through the workspace test runner, which has + // its own module-resolution context. + const searchPaths = [ + process.cwd(), + path.join(process.cwd(), 'node_modules') + ]; + + // First, locate the package via its `./package.json` subpath export. + // This works regardless of the main `exports` conditions because the + // subpath is explicitly declared in the package manifest. + let pkgDir: string | null = null; + try { + const pkgPath = require.resolve('docmd-search/package.json', { paths: searchPaths }); + pkgDir = path.dirname(pkgPath); + } catch { + // Fallback: walk the search paths manually. This is a defensive + // backstop in case the `./package.json` subpath export is ever + // removed or the package is installed in a layout require.resolve + // does not understand (e.g. pnpm's isolated node_modules). + for (const root of searchPaths) { + const candidate = path.join(root, 'node_modules', 'docmd-search', 'package.json'); + if (nativeFs.existsSync(candidate)) { + pkgDir = path.dirname(candidate); + break; + } + } + } + + if (!pkgDir) return null; + + try { + // Read package.json to find the main entry point. We accept the + // first present condition of `exports["."]` in this order: `import`, + // `default`, `require`, then fall back to `main`. This keeps us + // working even if the package declares only `import` (ESM-only). + const pkg = JSON.parse(nativeFs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8')); + const exp = pkg.exports?.['.']; + const mainEntry = + (exp && (exp.import || exp.default || exp.require)) || + pkg.main || + 'dist/index.js'; + const entryPath = path.join(pkgDir, mainEntry); + // Return as file:// URL for ESM dynamic import + return `file://${entryPath}`; + } catch { + return null; + } +} + +/** + * Detect the package manager used in the current project. + */ +function detectPackageManager(cwd: string): 'pnpm' | 'yarn' | 'bun' | 'npm' { + let dir = cwd; + while (dir !== path.parse(dir).root) { + if (nativeFs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm'; + if (nativeFs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn'; + if (nativeFs.existsSync(path.join(dir, 'bun.lockb'))) return 'bun'; + if (nativeFs.existsSync(path.join(dir, 'package-lock.json'))) return 'npm'; + dir = path.dirname(dir); + } + return 'npm'; +} + +/** + * Get the latest non-deprecated version of docmd-search from npm. + * Falls back to 'latest' tag if fetch fails. + */ +async function getLatestDocmdSearchVersion(): Promise { + try { + const { execSync } = await import('node:child_process'); + const result = execSync('npm view docmd-search version --json', { + encoding: 'utf-8', + timeout: 10000 + }); + const version = JSON.parse(result.trim()); + return version || 'latest'; + } catch { + return 'latest'; + } +} + +/** + * docmd-search requires peer dependencies for embedding: + * - @huggingface/transformers: the ML model runtime + * - onnxruntime-node: ONNX backend for Node.js + */ +const PEER_DEPS = ['@huggingface/transformers@^4.0.0', 'onnxruntime-node@^1.20.0']; + +/** + * Build the install command for the current package manager. When + * `extraPackages` is non-empty, those are added alongside `peerDeps` so + * docmd-search can be installed together with its peers in one shot. + */ +function buildInstallCmd(cwd: string, pkgManager: string, extraPackages: string[] = []): string { + const all = [...extraPackages, ...PEER_DEPS]; + switch (pkgManager) { + case 'pnpm': return `pnpm add ${all.join(' ')}`; + case 'yarn': return `yarn add ${all.join(' ')}`; + case 'bun': return `bun add ${all.join(' ')}`; + default: + // --foreground-scripts ensures postinstall scripts (e.g. onnxruntime-node + // binary download) run even in CI environments where npm's allow-scripts + // security feature would otherwise block them. + return `npm install --foreground-scripts ${all.join(' ')}`; + } +} + +/** + * Auto-install docmd-search package along with its peer dependencies. + * Installs the latest stable version from npm. + */ +async function autoInstallDocmdSearch(tui: any, quiet: boolean): Promise { + const cwd = process.cwd(); + const pkgManager = detectPackageManager(cwd); + + if (!quiet && tui) { + tui.step('Fetching latest docmd-search version', 'WAIT'); + } + + const version = await getLatestDocmdSearchVersion(); + const versionedPackage = version === 'latest' ? 'docmd-search' : `docmd-search@${version}`; + + if (!quiet && tui) { + tui.step(`Installing ${versionedPackage} with peer dependencies`, 'WAIT'); + } + + return runInstall(tui, quiet, cwd, pkgManager, buildInstallCmd(cwd, pkgManager, [versionedPackage]), + 'docmd-search installed successfully', + 'Failed to install docmd-search', + 'Could not auto-install docmd-search. Please install manually:\n' + + ' npm install docmd-search @huggingface/transformers onnxruntime-node\n' + + 'Or disable semantic search: plugins: { search: { semantic: false } }' + ); +} + +/** + * Auto-install just the peer dependencies. Used when docmd-search is + * already present but `@huggingface/transformers` or `onnxruntime-node` + * is missing โ€” previously the plugin only warned and fell back to + * keyword search (#163, partial fix). + */ +async function installPeerDeps(tui: any, quiet: boolean): Promise { + const cwd = process.cwd(); + const pkgManager = detectPackageManager(cwd); + + if (!quiet && tui) { + tui.step('Installing missing peer dependencies', 'WAIT'); + } + + return runInstall(tui, quiet, cwd, pkgManager, buildInstallCmd(cwd, pkgManager), + 'Peer dependencies installed', + 'Failed to install peer dependencies', + 'Could not auto-install peer dependencies. Please install manually:\n' + + ' npm install @huggingface/transformers onnxruntime-node\n' + + 'Or disable semantic search: plugins: { search: { semantic: false } }' + ); +} + +/** + * Run a package-manager install command. Centralised so the two + * auto-install paths (full docmd-search, peer-only) share error + * handling and timeout. + */ +async function runInstall( + tui: any, quiet: boolean, cwd: string, pkgManager: string, + cmd: string, successLabel: string, failLabel: string, manualHint: string +): Promise { + try { + const { execSync } = await import('node:child_process'); + execSync(cmd, { stdio: 'pipe', cwd, timeout: 180000 }); + if (!quiet && tui) tui.step(successLabel, 'DONE'); + return true; + } catch (err: any) { + if (!quiet && tui) { + tui.step(failLabel, 'FAIL'); + tui.warn(` ${manualHint}`); + } else { + console.warn(`[plugin-search] ${manualHint}`); + } + return false; + } +} + +/** + * Check whether the peer dependencies required for embedding are resolvable. + * Returns the first missing package name, or null if all present. + */ +function findMissingPeerDep(resolvePaths: string[]): string | null { + for (const pkg of ['@huggingface/transformers', 'onnxruntime-node']) { + try { + require.resolve(pkg, { paths: resolvePaths }); + } catch { + return pkg; + } + } + return null; +} + +/** + * Ensure docmd-search is installed when semantic: true is requested. + * If missing, attempts to auto-install the latest version. If peers are + * missing but docmd-search itself is present, auto-installs just the + * peers (#163 partial fix: previously it warned and fell back to keyword + * search, leaving the project in a broken state). + * + * Returns: + * { ready: true, freshInstall: false, reason: 'present' } + * โ€” already installed (docmd-search + peers), proceed normally. + * { ready: true, freshInstall: true, reason: 'docmd-search' | 'peers' } + * โ€” just installed; caller must re-exec indexing in a child process + * because Node's module cache won't see the new packages. + * { ready: false, freshInstall: false, reason: '' } + * โ€” install failed; caller falls back to keyword search and shows the + * actual reason (e.g. 'docmd-search' or 'peers') in the message. + */ +async function ensureDocmdSearch(tui: any, quiet: boolean): Promise<{ ready: boolean; freshInstall: boolean; reason: string }> { + const resolvePaths = [process.cwd(), path.join(process.cwd(), 'node_modules')]; + + // Already installed โ€” verify peers too. + if (resolveDocmdSearch()) { + const missingPeer = findMissingPeerDep(resolvePaths); + if (missingPeer) { + // Auto-install just the peers (was: just warn and give up). + const installed = await installPeerDeps(tui, quiet); + if (!installed) return { ready: false, freshInstall: false, reason: 'peers' }; + // Verify peers resolved after install. + if (findMissingPeerDep(resolvePaths)) { + if (!quiet && tui) { + tui.warn(' Peer dependencies were installed but could not be resolved. Please restart the build.'); + } + return { ready: false, freshInstall: false, reason: 'peers' }; + } + // docmd-search itself was already installed; the new peers triggered + // a Node module-cache miss for them too. Re-exec in a child process. + return { ready: true, freshInstall: true, reason: 'peers' }; + } + return { ready: true, freshInstall: false, reason: 'present' }; + } + + // Attempt auto-install (installs docmd-search + peers together). + const installed = await autoInstallDocmdSearch(tui, quiet); + if (!installed) return { ready: false, freshInstall: false, reason: 'docmd-search' }; + + // Verify docmd-search resolved after install. + const resolved = resolveDocmdSearch(); + if (!resolved) { + if (!quiet && tui) { + tui.warn(' docmd-search was installed but could not be resolved. Please restart the build.'); + } + return { ready: false, freshInstall: false, reason: 'docmd-search' }; + } + + // Signal to the caller that a fresh install just happened. The current Node + // process has a stale module resolution cache and cannot import the newly + // installed packages โ€” the caller must spawn a child process for indexing. + return { ready: true, freshInstall: true, reason: 'docmd-search' }; +} + +/** + * Load translation strings for a given locale. + * Falls back to English if the locale file doesn't exist. + */ +function loadPluginStrings(localeId: string): Record { + try { + // Try locale-specific file + const localePath = path.join(i18nDir, `${localeId}.json`); + if (nativeFs.existsSync(localePath)) { + return JSON.parse(nativeFs.readFileSync(localePath, 'utf8')); + } + } catch { /* fallback below */ } + // Fallback to English + try { + const enPath = path.join(i18nDir, 'en.json'); + if (nativeFs.existsSync(enPath)) { + return JSON.parse(nativeFs.readFileSync(enPath, 'utf8')); + } + } catch { /* silent */ } + return {}; +} + +/** + * Print a per-peer-dep TUI block when `semantic: true` is requested. + * Idempotent: suppresses the block on subsequent builds when the set + * of missing peer deps is unchanged, so the user only sees it on the + * first build (or when a new peer dep goes missing). + * + * Called by `onConfigResolved` AND by `onPostBuild` after a fresh + * install. Each call is a no-op when the peer status is unchanged. + */ +function maybeReportPeerStatus(tui: any, sc: SearchConfig, quiet: boolean): void { + if (quiet || !tui) return; + if (!sc.semanticRequested) return; // user never asked for semantic โ€” stay silent + const h = peersHash(sc); + if (h === _searchState.lastPeersHash) return; // already reported this state + _searchState.lastPeersHash = h; + + if (sc.peersInstalled) { + tui.step('All semantic search dependencies ready', 'DONE'); + return; + } + // List each missing dep as its own TUI line so the user sees exactly + // which package is the blocker. We keep the order stable (the same + // order as `PEER_DEPS`) so logs read consistently across builds. + for (const dep of sc.peerDeps) { + const present = !sc.missingPeers.includes(dep); + tui.step(`${dep}`, present ? 'DONE' : 'SKIP'); + } + tui.warn( + ' Semantic search requires: ' + sc.missingPeers.join(', ') + + '\n Falling back to keyword search. To enable semantic: install the missing packages,' + ); +} + +/** + * `init` capability. Runs at config-parse time, before any page is + * rendered. Computes the single `searchConfig` object and stamps it + * on `config._searchConfig` for the rest of the build pipeline. Also + * emits the first-install peer-status TUI block if appropriate. + */ +export function onConfigResolved(config: any): void { + const sc = buildSearchConfig(config); + config._searchConfig = sc; + _searchState.lastConfig = sc; + // `tui` isn't passed to onConfigResolved (the lifecycle signature is + // `onConfigResolved(config: any): void`), so we don't emit the TUI + // block here โ€” the equivalent emission happens inside `onPostBuild` + // where the TUI is in scope. We do, however, keep this hook for + // future extensions (e.g. warming the require cache, pre-computing + // derived values that the EJS partial needs at template time). +} + +/** + * Plugin translations hook - called by the engine for each locale. + * Returns search-specific UI strings keyed by locale. + */ +export function translations(localeId: string): Record { + return loadPluginStrings(localeId || 'en'); +} + +/** + * Post-build hook - generates per-locale search indexes. + * + * When options.semantic is true: + * - If options.indexDir is provided and contains a valid manifest.json, + * skip indexing entirely โ€” the index was pre-built (e.g. by docmd-search CLI). + * - Otherwise, runs the docmd-search indexer over the docs source directory + * and outputs the vector index to /.docmd-search/. + * - Falls back to keyword-only search if docmd-search is not installed. + * + * When options.semantic is false (default): + * - Generates per-locale MiniSearch indexes (existing behaviour). + */ +export async function onPostBuild({ config, pages, outputDir, tui, options, runWorkerTask }: any) { + // Plugin-specific config is in config.plugins.search + const pluginOptions = (config.plugins && config.plugins.search) || {}; + const isEnabled = config.optionsMenu ? config.optionsMenu.components.search !== false : config.search !== false; + if (!isEnabled) return; + + const showTui = tui && !options?.quiet; + + // โ”€โ”€ Semantic search path โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + if (pluginOptions.semantic === true) { + // Strip sourcemap comment from the copied .docmd-search-client.js to avoid + // a 404 for the non-existent .js.map file in the browser. + const clientDestPath = path.join(outputDir, '.docmd-search-client.js'); + if (nativeFs.existsSync(clientDestPath)) { + try { + const src = await fs.readFile(clientDestPath, 'utf8'); + const stripped = src.replace(/\n?\/\/# sourceMappingURL=\S+\s*$/, ''); + if (stripped !== src) await fs.writeFile(clientDestPath, stripped, 'utf8'); + } catch { /* non-critical */ } + } + + // Check if a pre-built index exists (e.g. docmd-search --ui mode) + // If indexDir is provided and has a valid manifest, skip indexing entirely. + if (pluginOptions.indexDir) { + const manifestPath = path.join(pluginOptions.indexDir, 'manifest.json'); + if (nativeFs.existsSync(manifestPath)) { + try { + const manifest = JSON.parse(nativeFs.readFileSync(manifestPath, 'utf8')); + if (manifest.status === 'complete' && manifest.batchCount > 0) { + if (showTui) tui.step('Using pre-built semantic index', 'DONE'); + // Copy the index to outputDir if it's not already there + const targetDir = path.join(outputDir, '.docmd-search'); + if (pluginOptions.indexDir !== targetDir) { + await fs.mkdir(targetDir, { recursive: true }); + // Copy manifest and batches + await fs.copyFile(manifestPath, path.join(targetDir, 'manifest.json')); + const batchesDir = path.join(pluginOptions.indexDir, 'batches'); + if (nativeFs.existsSync(batchesDir)) { + const targetBatchesDir = path.join(targetDir, 'batches'); + await fs.mkdir(targetBatchesDir, { recursive: true }); + for (const file of nativeFs.readdirSync(batchesDir)) { + await fs.copyFile(path.join(batchesDir, file), path.join(targetBatchesDir, file)); + } + } + } + return; // Index already exists โ€” no need to build + } + } catch { + // Invalid manifest โ€” fall through to build + } + } + } + + const { ready, freshInstall, reason } = await ensureDocmdSearch(tui, !showTui); + if (!ready) { + // Graceful fallback: build keyword index instead. The `reason` field + // tells the caller whether docmd-search itself or just its peers were + // missing so the message is accurate (#163 deeper fix: previously it + // always said "docmd-search not installed" even when only a peer + // was missing). + const why = + reason === 'peers' ? 'semantic peer dependencies missing' : + reason === 'docmd-search' ? 'docmd-search not installed' : + 'docmd-search not installed'; + // Only now โ€” after the install ACTUALLY failed โ€” report which deps + // were missing. This avoids the false-alarm where the warning showed + // "missing" and then the install succeeded below it. + maybeReportPeerStatus(tui, buildSearchConfig(config), !showTui); + if (showTui) tui.warn(` Falling back to keyword search (${why})`); + } else if (freshInstall) { + // docmd-search was just installed in this process. Node's module cache + // won't see it, so spawn a child docmd build to do the indexing instead + // of trying to import() it here. The child inherits the updated + // node_modules and starts with a clean require cache. + if (showTui) tui.step('Re-running semantic indexing in subprocess (first install)...', 'WAIT'); + try { + const { execSync } = await import('node:child_process'); + const cwd = process.cwd(); + // Detect the docmd binary from the same node_modules that just got updated + const docmdBin = path.join(cwd, 'node_modules', '.bin', 'docmd'); + const cmd = nativeFs.existsSync(docmdBin) + ? `"${docmdBin}" build` + : `node -e "import('docmd-search').then(m => m.indexDirectory({ rootDir: '${cwd}', outDir: '${path.join(outputDir, '.docmd-search')}' }))"`; + execSync(cmd, { stdio: 'inherit', cwd, timeout: 300000 }); + if (showTui) tui.step('Semantic search index built', 'DONE'); + } catch (err: any) { + if (showTui) tui.warn(' Subprocess indexing failed โ€” semantic search unavailable this build.'); + } + } else { + if (showTui) tui.step('Building semantic search index', 'WAIT'); + + try { + // Dynamic import of optional peer dep. + // We first resolve the package path, then import it dynamically. + // This approach is safe and works with bundlers. + const docmdSearchPath = resolveDocmdSearch(); + if (!docmdSearchPath) { + throw new Error( + 'docmd-search not found. Install it with: npm install docmd-search' + ); + } + + // Import using the resolved path - this is safe and works with bundlers + const docmdSearch: any = await import(docmdSearchPath); + + if (!docmdSearch?.indexDirectory) { + throw new Error( + 'docmd-search found but indexDirectory not exported. ' + + 'Please update to the latest version: npm install docmd-search@latest' + ); + } + + // Determine the docs source directory from config + const docsDir = path.resolve(config.root || process.cwd(), config.srcDir || config.src || 'docs'); + const semanticOutDir = path.join(outputDir, '.docmd-search'); + const hasVersioning = config.versions?.all?.length > 0; + + if (hasVersioning) { + // โ”€โ”€ Multi-version semantic indexing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + // Index each version's source dir separately into a temp subdir, + // then merge all batches into one unified index with file paths + // prefixed by the version's output URL prefix. + const versions: Array<{ id: string; label: string; dir: string; outputPrefix: string }> = []; + const currentVersionId = config.versions.current; + const CWD = config.root || process.cwd(); + + for (const v of config.versions.all) { + const outputPrefix = v.id === currentVersionId ? '' : v.id + '/'; + versions.push({ + id: v.id, + label: v.label || v.id, + dir: path.resolve(CWD, v.dir), + outputPrefix, + }); + } + + if (showTui) tui.step('Building semantic search index (multi-version)', 'WAIT'); + + const tmpBase = path.join(semanticOutDir, '_tmp_versions'); + await fs.mkdir(tmpBase, { recursive: true }); + + let mergedDimensions = 384; // default, overwritten from first batch + let mergedBatchId = 0; + const mergedBatchesDir = path.join(semanticOutDir, 'batches'); + await fs.mkdir(mergedBatchesDir, { recursive: true }); + + // Track version-to-pathPrefix mapping for the client filter + const versionMap: Array<{ label: string; pathPrefix: string }> = []; + + // Always exclude semantic index output dir and --ui artifacts from indexing + const builtinExcludes = ['**/.docmd-search/**', '**/_site/**', '**/_ui/**']; + const mergedExclude = [...builtinExcludes, ...(pluginOptions.exclude || [])]; + + for (const ver of versions) { + const tmpOut = path.join(tmpBase, ver.id); + try { + await docmdSearch.indexDirectory( + { + rootDir: ver.dir, + outDir: tmpOut, + model: pluginOptions.model, + include: pluginOptions.include, + exclude: mergedExclude, + chunkSize: pluginOptions.chunkSize, + chunkOverlap: pluginOptions.chunkOverlap, + }, + (progress: any) => { + if (showTui && progress.message) { + tui.step(`Semantic index [${ver.label}]: ${progress.message}`, 'WAIT'); + } + } + ); + } catch (verErr: any) { + if (showTui) tui.warn(` Skipping version ${ver.label}: ${verErr.message}`); + continue; + } + + // Read all batches from this version's tmp index and re-save with prefixed file paths + const tmpBatchesDir = path.join(tmpOut, 'batches'); + if (nativeFs.existsSync(tmpBatchesDir)) { + const batchFiles = nativeFs.readdirSync(tmpBatchesDir) + .filter(f => f.endsWith('.json')) + .sort(); + + for (const batchFile of batchFiles) { + const batchJson = JSON.parse(await fs.readFile(path.join(tmpBatchesDir, batchFile), 'utf8')); + const binPath = path.join(tmpBatchesDir, batchFile.replace('.json', '.bin')); + + // Prefix each chunk's file path with the version output prefix + if (ver.outputPrefix) { + batchJson.chunks = batchJson.chunks.map((chunk: any) => ({ + ...chunk, + file: ver.outputPrefix + chunk.file, + })); + } + + mergedDimensions = batchJson.dimensions || mergedDimensions; + const paddedId = String(mergedBatchId).padStart(3, '0'); + batchJson.batchId = mergedBatchId; + + await fs.writeFile( + path.join(mergedBatchesDir, `${paddedId}.json`), + JSON.stringify(batchJson) + ); + if (nativeFs.existsSync(binPath)) { + await fs.copyFile(binPath, path.join(mergedBatchesDir, `${paddedId}.bin`)); + } + mergedBatchId++; + } + } + + // Always add this version to the filter map (even if it has no chunks) + versionMap.push({ label: ver.label, pathPrefix: ver.outputPrefix }); + } + + // Write unified manifest + const manifest = { + version: 1, + model: pluginOptions.model || 'Xenova/all-MiniLM-L6-v2', + dimensions: mergedDimensions, + status: 'complete', + batchCount: mergedBatchId, + }; + await fs.writeFile(path.join(semanticOutDir, 'manifest.json'), JSON.stringify(manifest)); + + // Write versions.json for the client filter UI + await fs.writeFile( + path.join(semanticOutDir, 'versions.json'), + JSON.stringify(versionMap) + ); + + // Clean up temp dirs + try { await fs.rm(tmpBase, { recursive: true, force: true }); } catch { /* ok */ } + + if (showTui) tui.step('Building semantic search index (multi-version)', 'DONE'); + return; + } + + // โ”€โ”€ Single-version semantic indexing โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + // Always exclude the semantic index output directory itself and any + // docmd-search --ui artifacts (_site/, _ui/) so the indexer never + // crawls its own output. Merge with any user-supplied excludes. + const builtinExcludes = ['**/.docmd-search/**', '**/_site/**', '**/_ui/**']; + const mergedExclude = [ + ...builtinExcludes, + ...(pluginOptions.exclude || []), + ]; + await docmdSearch.indexDirectory( + { + rootDir: docsDir, + outDir: semanticOutDir, + model: pluginOptions.model, // undefined โ†’ uses global/default + include: pluginOptions.include, + exclude: mergedExclude, + chunkSize: pluginOptions.chunkSize, + chunkOverlap: pluginOptions.chunkOverlap, + }, + (progress: any) => { + if (showTui && progress.message) { + // Update TUI step message on each phase change + tui.step(`Semantic index: ${progress.message}`, 'WAIT'); + } + } + ); + + // No versioning โ€” write an empty versions.json so the client knows + await fs.writeFile(path.join(semanticOutDir, 'versions.json'), '[]'); + + if (showTui) tui.step('Building semantic search index', 'DONE'); + // Semantic index built โ€” skip MiniSearch index below + return; + } catch (err: any) { + if (showTui) { + tui.step('Building semantic search index', 'FAIL'); + tui.warn(`Semantic indexing failed: ${err.message} โ€” falling back to keyword search`); + } else { + console.warn(`[plugin-search] Semantic indexing failed: ${err.message}`); + } + // Fall through to keyword search + } + } // close else (not freshInstall) + } + + // โ”€โ”€ Keyword search path (default / fallback) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + if (showTui) tui.step('Generating search index', 'WAIT'); + + // Try to offload to worker thread for better main-thread responsiveness + if (runWorkerTask) { + try { + // Only send serializable page data the worker needs + const serializablePages = pages + .filter((p: any) => p.searchData) + .map((p: any) => ({ outputPath: p.outputPath, searchData: p.searchData })); + + // Build a minimal serializable config for the worker + const workerConfig = { + i18n: config.i18n ? { locales: config.i18n.locales, default: config.i18n.default } : undefined, + versions: config.versions ? { all: config.versions.all, current: config.versions.current } : undefined, + }; + + const workerModulePath = path.resolve(__dirname, 'worker.js'); + await runWorkerTask(workerModulePath, 'buildSearchIndex', [workerConfig, serializablePages, outputDir]); + + if (showTui) tui.step('Generating search index', 'DONE'); + return; + } catch { + // Worker failed โ€” fall through to main-thread processing + } + } + + // Main-thread fallback (or when WorkerPool isn't available) + await buildSearchIndexInline(config, pages, outputDir); + + if (showTui) tui.step('Generating search index', 'DONE'); +} + +/** + * Inline (main-thread) search index builder โ€” used as fallback when + * worker offloading is not available or fails. + */ +async function buildSearchIndexInline(config: any, pages: any[], outputDir: string) { + const locales = config.i18n?.locales || []; + const defaultLocale = config.i18n?.default || null; + const hasVersioning = config.versions?.all?.length > 0; + const currentVersionId = config.versions?.current; + + // Group pages by locale + const localePages: Record = { '_default': [] }; + for (const loc of locales) { + if (loc.id !== defaultLocale) { + localePages[loc.id] = []; + } + } + + for (const page of pages) { + if (!page.searchData) continue; + const outputPath = page.outputPath.replace(/\\/g, '/'); + + let localeId = '_default'; + for (const loc of locales) { + if (loc.id !== defaultLocale && outputPath.startsWith(loc.id + '/')) { + localeId = loc.id; + break; + } + } + localePages[localeId] = localePages[localeId] || []; + localePages[localeId].push(page); + } + + for (const [localeId, locPages] of Object.entries(localePages)) { + if (locPages.length === 0) continue; + + const searchData: any[] = []; + const seenIds = new Set(); + + for (const page of locPages) { + let pageId = outputPathToSlug(page.outputPath); + if (pageId.startsWith('/') && pageId !== '/') { + pageId = pageId.slice(1); + } + + let version: string | null = null; + if (hasVersioning && config.versions?.all) { + for (const v of config.versions.all) { + const stripped = localeId !== '_default' ? pageId.replace(new RegExp(`^${localeId}/`), '') : pageId; + if (stripped.startsWith(v.id + '/') || stripped === v.id) { + version = v.label || v.id; + break; + } + } + if (!version) { + const currentVersion = config.versions.all.find((v: any) => v.id === currentVersionId); + if (currentVersion) version = currentVersion.label || currentVersion.id; + } + } + + if (!seenIds.has(pageId)) { + seenIds.add(pageId); + const entry: any = { + id: pageId, + title: page.searchData.title, + text: page.searchData.content, + headings: (page.searchData.headings || []).map((h: any) => h.text).join(' ') + }; + if (hasVersioning && version) entry.version = version; + searchData.push(entry); + } + + if (page.searchData.headings && Array.isArray(page.searchData.headings)) { + for (const heading of page.searchData.headings) { + if (heading.id && heading.text) { + const hId = `${pageId}#${heading.id}`; + if (!seenIds.has(hId)) { + seenIds.add(hId); + const entry: any = { + id: hId, + title: `${page.searchData.title} > ${heading.text}`, + text: '', + headings: heading.text + }; + if (hasVersioning && version) entry.version = version; + searchData.push(entry); + } + } + } + } + } + + const storeFields = ['title', 'id', 'text']; + if (hasVersioning) storeFields.push('version'); + + const CJK_AND_SPACELESS_REGEX = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uff66-\uff9f\uac00-\ud7af\u1100-\u11ff\u3130-\u318f\u0e00-\u0e7f\u0e80-\u0eff\u1780-\u17ff\u1000-\u109f\u0f00-\u0fff]/g; + const miniSearch = new MiniSearch({ + fields: ['title', 'headings', 'text'], + storeFields, + tokenize: (text: string) => { + const spaced = text.replace(CJK_AND_SPACELESS_REGEX, ' $& '); + const defaultTokenize = MiniSearch.getDefault('tokenize'); + return defaultTokenize ? defaultTokenize(spaced) : spaced.toLowerCase().split(/[^a-zA-Z0-9_'\u00C0-\u017F\u00d0\u00f0\u00df\u00f8\u00e6\u0153\u03ac-\u03ce\u0400-\u04ff]+/u).filter(Boolean); + }, + searchOptions: { boost: { title: 2, headings: 1.5 }, fuzzy: 0.2 } + }); + + miniSearch.addAll(searchData); + const json = JSON.stringify(miniSearch.toJSON()); + + const indexPath = localeId === '_default' + ? path.join(outputDir, 'search-index.json') + : path.join(outputDir, localeId, 'search-index.json'); + + await fs.mkdir(path.dirname(indexPath), { recursive: true }); + await fs.writeFile(indexPath, json); + } +} + +/** + * Inject the search modal HTML. + * + * When options.semantic is true: + * - Adds a data-semantic="true" attribute to the modal so the semantic + * client JS knows to use the vector index instead of MiniSearch. + * - The modal HTML is identical โ€” only the client JS bundle changes. + * + * Strings are passed as data attributes so the client JS can read them + * regardless of locale - the engine merges plugin translations before render. + */ +export function generateScripts(config: any, options: any) { + const isEnabled = config.optionsMenu ? config.optionsMenu.components.search !== false : config.search !== false; + if (!isEnabled) return {}; + + // Use the resolved searchConfig as the single source of truth. + // The client also auto-detects at runtime (HEAD probe to manifest.json) + // so even if this build-time hint is wrong (e.g. first-build dep install), + // the browser still picks the right mode. + const sc: SearchConfig = config._searchConfig || buildSearchConfig(config); + const isSemantic = sc.semanticUsable; + const showConfidence = (options || {}).showConfidence === true; + const showFilters = (options || {}).showFilters !== false; + + // Load strings for the active locale (available at render time) + const localeId = config._activeLocale?.id || 'en'; + const strings = loadPluginStrings(localeId); + + const searchIcon = ``; + const closeIcon = ``; + + const escape = new MarkdownIt().utils.escapeHtml; + + const semanticAttr = isSemantic ? ' data-semantic="true"' : ''; + const confidenceAttr = ` data-show-confidence="${showConfidence}"`; + const filtersAttr = ` data-show-filters="${showFilters}"`; + + const modalHtml = ` + + `; + + return { bodyScriptsHtml: modalHtml }; +} + +export function getAssets(options: any) { + // Use searchConfig for semanticRequested, but keep the broader + // resolution paths for finding the client bundle (which lives in + // the plugin's own node_modules, not just the user's project). + const sc = _searchState.lastConfig; + const semanticRequested = sc?.semanticRequested ?? (options || {}).semantic === true; + const isSemantic = semanticRequested; + + if (isSemantic) { + // Semantic mode: serve the docmd-search client bundle at a known path + // so the search client can dynamically import it at runtime. + // Resolve the actual file path (not a file:// URL) from docmd-search package. + let semanticClientSrc: string | null = null; + try { + const searchPaths = [ + process.cwd(), + __dirname, + path.resolve(__dirname, '../../..'), + path.resolve(__dirname, '../../../..'), + ]; + const pkgPath = require.resolve('docmd-search/package.json', { paths: searchPaths }); + const pkgDir = path.dirname(pkgPath); + const clientEntry = path.join(pkgDir, 'dist', 'client', 'index.js'); + if (nativeFs.existsSync(clientEntry)) semanticClientSrc = clientEntry; + } catch { /* not installed */ } + + const assets: any[] = [ + // Always include MiniSearch + keyword client as fallback + { url: 'https://cdn.jsdelivr.net/npm/minisearch@7.2.0/dist/umd/index.min.js', type: 'js', location: 'body' }, + { src: path.join(__dirname, 'docmd-search.js'), dest: 'assets/js/docmd-search.js', type: 'js', location: 'body' }, + ]; + + if (semanticClientSrc) { + // Serve the docmd-search client at a well-known root path + // The search client.ts fetches it via import('.docmd-search-client.js') + assets.push({ + src: semanticClientSrc, + dest: '.docmd-search-client.js', + type: 'js', + location: 'none', // not injected into / โ€” loaded on demand + }); + } + + return assets; + } + + // Default: keyword search via MiniSearch + return [ + { url: 'https://cdn.jsdelivr.net/npm/minisearch@7.2.0/dist/umd/index.min.js', type: 'js', location: 'body' }, + { src: path.join(__dirname, 'docmd-search.js'), dest: 'assets/js/docmd-search.js', type: 'js', location: 'body' } + ]; +} \ No newline at end of file diff --git a/packages/plugins/search/src/semantic-client.ts b/packages/plugins/search/src/semantic-client.ts new file mode 100644 index 0000000..f2d47ec --- /dev/null +++ b/packages/plugins/search/src/semantic-client.ts @@ -0,0 +1,302 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * Semantic search client module. + * Handles vector-based semantic search using docmd-search. + */ + +export {}; + +declare global { + interface Window { + DOCMD_SITE_ROOT?: string; + DOCMD_ROOT?: string; + } +} + +export interface SemanticSearchContext { + siteBase: string; + ROOT_PATH: string; + searchResults: HTMLElement; + strings: { + initial: string; + noResults: string; + error: string; + }; + activeVersionFilters: Set; + globalAllVersions: string[]; + globalVersionColors: Record; + selectedIndex: number; + updateSelection: (items: NodeListOf) => void; + showConfidence?: boolean; +} + +let semanticClient: any = null; + +/** + * Load the semantic search index and client. + */ +export async function loadSemanticIndex(ctx: SemanticSearchContext): Promise { + const semanticIndexBase = new URL('.docmd-search/', new URL(ctx.siteBase, window.location.href)).href; + const clientUrl = new URL('.docmd-search-client.js', new URL(ctx.siteBase, window.location.href)).href; + + try { + semanticClient = await import(/* @vite-ignore */ clientUrl); + } catch { + throw new Error('semantic-client-missing'); + } + + if (!semanticClient?.load || !semanticClient?.search) { + throw new Error('semantic-client-invalid'); + } + + await semanticClient.load(semanticIndexBase, (loaded: number, total: number) => { + const safeLoaded = Math.max(0, parseInt(String(loaded), 10) || 0); + const safeTotal = Math.max(0, parseInt(String(total), 10) || 0); + + clearElement(ctx.searchResults); + const div = document.createElement('div'); + div.className = 'search-initial'; + div.textContent = (safeLoaded === safeTotal && safeTotal > 0) + ? 'Semantic search ready...' + : `Loading semantic index... (${safeLoaded}/${safeTotal})`; + ctx.searchResults.appendChild(div); + }); + + // Load versions.json for filter chips + try { + const versionsUrl = new URL('.docmd-search/versions.json', new URL(ctx.siteBase, window.location.href)).href; + const vRes = await fetch(versionsUrl); + if (vRes.ok) { + const vData: Array<{ label: string; pathPrefix: string }> = await vRes.json(); + if (Array.isArray(vData) && vData.length > 0) { + ctx.globalAllVersions.length = 0; + ctx.globalAllVersions.push(...vData.map(v => v.label)); + // Store pathPrefix alongside label for filtering + (ctx.globalVersionColors as any).__semanticVersions = vData; + const huePresets = [210, 150, 30, 330, 270, 60, 180, 0]; + ctx.globalAllVersions.forEach((label, i) => { + const hue = huePresets[i % huePresets.length]; + ctx.globalVersionColors[label] = { bg: `hsl(${hue}, 55%, 92%)`, fg: `hsl(${hue}, 60%, 35%)` }; + }); + } + } + } catch { /* version filters are optional */ } + + return true; +} + +/** Helper to resolve the correct version label for a given file path */ +function resolveFileVersion(file: string, semanticVersions: Array<{ label: string; pathPrefix: string }>): string | null { + // Sort prefixes by length in descending order to match longest prefix first + const sorted = [...semanticVersions].sort((a, b) => b.pathPrefix.length - a.pathPrefix.length); + for (const v of sorted) { + if (v.pathPrefix && file.startsWith(v.pathPrefix)) { + return v.label; + } + } + // Fallback to empty prefix (current version) if present + const current = semanticVersions.find(v => !v.pathPrefix); + return current ? current.label : null; +} + +/** + * Perform semantic search and render results. + */ +export function performSemanticSearch(query: string, ctx: SemanticSearchContext): void { + if (!semanticClient) return; + + const rawResults = semanticClient.search(query, 10); + + // Filter by active version filters (if any) + let filteredResults = rawResults; + if (ctx.activeVersionFilters.size > 0) { + const semanticVersions = (ctx.globalVersionColors as any).__semanticVersions || []; + filteredResults = rawResults.filter((result: any) => { + const chunk = result.chunk; + const file = chunk.file || ''; + const verLabel = resolveFileVersion(file, semanticVersions); + return verLabel && ctx.activeVersionFilters.has(verLabel); + }); + } + + if (filteredResults.length === 0) { + clearElement(ctx.searchResults); + const div = document.createElement('div'); + div.className = 'search-no-results'; + div.textContent = ctx.activeVersionFilters.size > 0 + ? 'No results match the selected filters.' + : ctx.strings.noResults; + ctx.searchResults.appendChild(div); + return; + } + + clearElement(ctx.searchResults); + + filteredResults.forEach((result: any, index: number) => { + const chunk = result.chunk; + const rawFile = chunk.file || '/'; + + // Convert markdown file path to HTML URL + let urlPath = rawFile.replace(/\.md$/, '').replace(/\/index$/, '/'); + if (!urlPath.endsWith('/')) urlPath += '/'; + + // Strip locale prefix if it matches a known locale (source structure has locale dirs) + const firstSegment = urlPath.split('/')[0]; + if (firstSegment.length >= 2 && firstSegment.length <= 3) { + urlPath = urlPath.replace(/^[a-z]{2,3}\//, ''); + } + + // Add anchor link if heading exists. The slugify regex must be + // Unicode-aware: docmd's parser generates slugs from any + // \p{L}\p{N} character (Chinese, Japanese, Korean, Cyrillic, + // Arabic, etc.), so the search-side has to match the same + // character class or anchors for non-English content would + // collapse to '#' and the search result would jump to the page + // top instead of the heading. + let anchor = ''; + if (chunk.heading) { + anchor = '#' + chunk.heading.toLowerCase() + .replace(/[^\p{L}\p{N}\s-]/gu, '') + .replace(/\s+/g, '-') + .replace(/-+/g, '-') + .replace(/^-|-$/g, ''); + } + + const cleanId = urlPath.startsWith('/') ? urlPath.slice(1) : urlPath; + const linkHref = `${ctx.ROOT_PATH}${cleanId}${anchor}`.replace(/([^:])\/\/+/g, '$1/'); + + // Use heading as title if available, otherwise use file-based title + const titleText = chunk.heading || cleanFileToTitle(rawFile); + + // Build DOM elements safely + const link = document.createElement('a'); + link.href = linkHref; + link.className = 'search-result-item'; + link.dataset.index = String(index); + + const titleDiv = document.createElement('div'); + titleDiv.className = 'search-result-title'; + titleDiv.textContent = titleText; + + // Right-side meta group: version pill + confidence badge + // Always right-aligned via margin-left:auto on .search-result-meta + const hasVersion = ctx.globalAllVersions.length > 0; + const hasConfidence = ctx.showConfidence && typeof result.score === 'number'; + + if (hasVersion || hasConfidence) { + const metaDiv = document.createElement('div'); + metaDiv.className = 'search-result-meta'; + + // Version pill + if (hasVersion) { + const semanticVersions = (ctx.globalVersionColors as any).__semanticVersions || []; + const verLabel = resolveFileVersion(rawFile, semanticVersions); + if (verLabel) { + const vc = ctx.globalVersionColors[verLabel]; + if (vc) { + const badge = document.createElement('span'); + badge.className = 'search-result-version'; + badge.style.background = vc.bg; + badge.style.color = vc.fg; + badge.textContent = verLabel; + metaDiv.appendChild(badge); + } + } + } + + // Confidence badge โ€” CSS classes, no inline styles + if (hasConfidence) { + const confidenceScore = Math.round(result.score * 100); + const scoreBadge = document.createElement('span'); + scoreBadge.className = 'search-result-confidence' + + (confidenceScore >= 85 ? ' confidence-high' : ''); + scoreBadge.textContent = `${confidenceScore}%`; + metaDiv.appendChild(scoreBadge); + } + + titleDiv.appendChild(metaDiv); + } + + + const previewDiv = document.createElement('div'); + previewDiv.className = 'search-result-preview'; + previewDiv.appendChild(buildSnippetFragment(chunk.text, query)); + + link.appendChild(titleDiv); + link.appendChild(previewDiv); + ctx.searchResults.appendChild(link); + + link.addEventListener('mouseenter', () => { + ctx.selectedIndex = index; + ctx.updateSelection(ctx.searchResults.querySelectorAll('.search-result-item') as NodeListOf); + }); + }); +} + +/** Remove all child nodes from an element. */ +function clearElement(el: HTMLElement): void { + while (el.firstChild) el.removeChild(el.firstChild); +} + +function cleanFileToTitle(file: string): string { + const parts = file.replace(/\\/g, '/').replace(/\.md$/, '').split('/').filter(Boolean); + const segment = (parts[parts.length - 1] === 'index' ? parts[parts.length - 2] : parts[parts.length - 1]) || file; + return segment.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase()); +} + +/** + * Build a DocumentFragment for a text snippet with highlights. + * No innerHTML โ€” all text inserted via textContent, marks via createElement. + */ +function buildSnippetFragment(text: string | undefined, query: string): DocumentFragment { + const frag = document.createDocumentFragment(); + if (!text) return frag; + + const terms = query.split(/\s+/).filter(t => t.length > 2); + let bestIndex = -1; + for (const term of terms) { + const idx = text.toLowerCase().indexOf(term.toLowerCase()); + if (idx >= 0) { bestIndex = idx; break; } + } + const start = Math.max(0, bestIndex - 60); + const end = Math.min(text.length, bestIndex + 60); + let snippet = text.substring(start, end); + if (start > 0) snippet = '...' + snippet; + if (end < text.length) snippet += '...'; + + if (terms.length === 0) { + frag.appendChild(document.createTextNode(snippet)); + return frag; + } + + // Split snippet by matching terms and wrap matches in + const pattern = new RegExp(`(${terms.map(t => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})`, 'gi'); + const parts = snippet.split(pattern); + + for (const part of parts) { + if (pattern.test(part)) { + pattern.lastIndex = 0; // reset after test + const mark = document.createElement('mark'); + mark.textContent = part; + frag.appendChild(mark); + } else { + pattern.lastIndex = 0; + frag.appendChild(document.createTextNode(part)); + } + } + + return frag; +} \ No newline at end of file diff --git a/packages/plugins/search/src/worker.ts b/packages/plugins/search/src/worker.ts new file mode 100644 index 0000000..26c0002 --- /dev/null +++ b/packages/plugins/search/src/worker.ts @@ -0,0 +1,142 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import fs from 'fs/promises'; +import MiniSearch from 'minisearch'; +import { outputPathToSlug } from '@docmd/api'; + +export async function buildSearchIndex(config: any, pages: any[], outputDir: string) { + // Determine locale configuration + const locales = config.i18n?.locales || []; + const defaultLocale = config.i18n?.default || null; + const hasVersioning = config.versions?.all?.length > 0; + const currentVersionId = config.versions?.current; + + // Group pages by locale + const localePages: Record = { '_default': [] }; + for (const loc of locales) { + if (loc.id !== defaultLocale) { + localePages[loc.id] = []; + } + } + + for (const page of pages) { + if (!page.searchData) continue; + const outputPath = page.outputPath.replace(/\\/g, '/'); + + // Determine which locale this page belongs to + let localeId = '_default'; + for (const loc of locales) { + if (loc.id !== defaultLocale && outputPath.startsWith(loc.id + '/')) { + localeId = loc.id; + break; + } + } + localePages[localeId] = localePages[localeId] || []; + localePages[localeId].push(page); + } + + // Build an index per locale + for (const [localeId, locPages] of Object.entries(localePages)) { + if (locPages.length === 0) continue; + + const searchData: any[] = []; + const seenIds = new Set(); + + for (const page of locPages) { + let pageId = outputPathToSlug(page.outputPath); + + if (pageId.startsWith('/') && pageId !== '/') { + pageId = pageId.slice(1); + } + + // Detect version from the output path + let version: string | null = null; + if (hasVersioning && config.versions?.all) { + for (const v of config.versions.all) { + const stripped = localeId !== '_default' ? pageId.replace(new RegExp(`^${localeId}/`), '') : pageId; + if (stripped.startsWith(v.id + '/') || stripped === v.id) { + version = v.label || v.id; + break; + } + } + if (!version) { + const currentVersion = config.versions.all.find((v: any) => v.id === currentVersionId); + if (currentVersion) version = currentVersion.label || currentVersion.id; + } + } + + // Add the main page record + if (!seenIds.has(pageId)) { + seenIds.add(pageId); + const entry: any = { + id: pageId, + title: page.searchData.title, + text: page.searchData.content, + headings: (page.searchData.headings || []).map((h: any) => h.text).join(' ') + }; + if (hasVersioning && version) entry.version = version; + searchData.push(entry); + } + + // Add individual heading records for deep linking + if (page.searchData.headings && Array.isArray(page.searchData.headings)) { + for (const heading of page.searchData.headings) { + if (heading.id && heading.text) { + const hId = `${pageId}#${heading.id}`; + if (!seenIds.has(hId)) { + seenIds.add(hId); + const entry: any = { + id: hId, + title: `${page.searchData.title} > ${heading.text}`, + text: '', + headings: heading.text + }; + if (hasVersioning && version) entry.version = version; + searchData.push(entry); + } + } + } + } + } + + // Build MiniSearch index + const storeFields = ['title', 'id', 'text']; + if (hasVersioning) storeFields.push('version'); + + const CJK_AND_SPACELESS_REGEX = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uff66-\uff9f\uac00-\ud7af\u1100-\u11ff\u3130-\u318f\u0e00-\u0e7f\u0e80-\u0eff\u1780-\u17ff\u1000-\u109f\u0f00-\u0fff]/g; + const miniSearch = new MiniSearch({ + fields: ['title', 'headings', 'text'], + storeFields, + tokenize: (text: string) => { + const spaced = text.replace(CJK_AND_SPACELESS_REGEX, ' $& '); + const defaultTokenize = MiniSearch.getDefault('tokenize'); + return defaultTokenize ? defaultTokenize(spaced) : spaced.toLowerCase().split(/[^a-zA-Z0-9_'\u00C0-\u017F\u00d0\u00f0\u00df\u00f8\u00e6\u0153\u03ac-\u03ce\u0400-\u04ff]+/u).filter(Boolean); + }, + searchOptions: { boost: { title: 2, headings: 1.5 }, fuzzy: 0.2 } + }); + + miniSearch.addAll(searchData); + const json = JSON.stringify(miniSearch.toJSON()); + + // Write to the correct locale directory + const indexPath = localeId === '_default' + ? path.join(outputDir, 'search-index.json') + : path.join(outputDir, localeId, 'search-index.json'); + + await fs.mkdir(path.dirname(indexPath), { recursive: true }); + await fs.writeFile(indexPath, json); + } +} \ No newline at end of file diff --git a/packages/plugins/search/tsconfig.json b/packages/plugins/search/tsconfig.json new file mode 100644 index 0000000..f5b2aff --- /dev/null +++ b/packages/plugins/search/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts", "src/client.ts"] +} \ No newline at end of file diff --git a/packages/plugins/seo/LICENSE b/packages/plugins/seo/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/seo/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/seo/README.md b/packages/plugins/seo/README.md new file mode 100644 index 0000000..dd1de62 --- /dev/null +++ b/packages/plugins/seo/README.md @@ -0,0 +1,31 @@ +**Outrank** + +> Outrank your competitors with automated backlinks and SEO-optimised content running in the background. This tool has been picking up serious traction lately, and the results speak for themselves. [Try it now](https://outrank.so/?via=docmd) + +image + +# @docmd/plugin-seo + +Generates meta tags, Open Graph, and Twitter Card markup for every page in your docmd site - canonical URLs, descriptions, and social previews handled automatically. Bundled with `@docmd/core`. + +```js +// docmd.config.js +module.exports = { + plugins: { + seo: { + defaultDescription: 'My documentation site', + twitter: { siteUsername: '@myproject' } + } + } +}; +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT diff --git a/packages/plugins/seo/package.json b/packages/plugins/seo/package.json new file mode 100644 index 0000000..748d142 --- /dev/null +++ b/packages/plugins/seo/package.json @@ -0,0 +1,68 @@ +{ + "name": "@docmd/plugin-seo", + "version": "0.8.12", + "description": "SEO meta tag generator for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "docmd": { + "key": "seo", + "kind": "plugin", + "displayName": "SEO", + "tagline": "SEO meta tag generator for docmd.", + "capabilities": [ + "head", + "post-build" + ] + }, + "scripts": { + "build": "tsc" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@docmd/api": "workspace:*" + }, + "dependencies": { + "@docmd/utils": "workspace:*" + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "plugin", + "seo", + "meta-tags", + "open-graph", + "twitter-cards", + "robots", + "sitemap", + "favicon", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/seo/src/index.ts b/packages/plugins/seo/src/index.ts new file mode 100644 index 0000000..72f46a9 --- /dev/null +++ b/packages/plugins/seo/src/index.ts @@ -0,0 +1,204 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import fs from 'fs/promises'; +import nativeFs from 'fs'; +import type { PluginDescriptor } from '@docmd/api'; +import { outputPathToPathname, sanitizeUrl } from '@docmd/api'; +import { attrEsc } from '@docmd/utils'; + +export const plugin: PluginDescriptor = { + name: 'seo', + version: '0.8.12', + capabilities: ['head', 'post-build'] +}; + +/** + * Generates HTML meta tags for a specific page. + * @param {Object} config - Project config + * @param {Object} pageData - { frontmatter, outputPath } + * @param {string} relativePathToRoot - Path relative to root (for assets) + * @returns {string} HTML string of meta tags + */ + +export function generateMetaTags(config: any, pageData: any, _relativePathToRoot: string) { + let html = ''; + const { frontmatter, outputPath } = pageData; + const seo = frontmatter.seo || {}; // Page-specific SEO overrides + const globalSeo = config.plugins?.seo || {}; + + // 1. Robots + if (frontmatter.noindex || seo.noindex) { + return '\n'; + } + + // 1.5 AI Bots Control + // By default (aiBots: true), AI bots are allowed to index content + // Set aiBots: false to block AI training bots + const aiBots = seo.aiBots ?? globalSeo.aiBots ?? true; // Default: true (allow) + if (aiBots === false) { + const bots = ['GPTBot', 'ChatGPT-User', 'Google-Extended', 'CCBot', 'anthropic-ai', 'Omgilibot', 'Omgili', 'FacebookBot', 'Diffbot', 'Bytespider', 'ImagesiftBot', 'cohere-ai']; + bots.forEach(bot => { + html += `\n`; + }); + } + + // 2. Basic Meta + const siteTitle = config.title; + const pageTitle = frontmatter.title || 'Untitled'; + let description = seo.description || frontmatter.description || globalSeo.defaultDescription || ''; + + // Smart Fallback Description + if (!description && pageData.searchData && pageData.searchData.content) { + const contentPrefix = pageData.searchData.content.substring(0, 150).trim(); + description = pageData.searchData.content.length > 150 ? contentPrefix + '...' : contentPrefix; + } + + // Phase 1.B (T-S3 fix): all content="..." values are user-controllable + // (frontmatter.title, frontmatter.description, config.url, config.title, etc.). + // Apply attrEsc() to prevent stored XSS in social-media previews. + html += `\n`; + + // 3. Canonical URL + // Use centralised URL utility for consistent URL generation. + const siteUrl = config.url ? config.url.replace(/\/$/, '') : ''; + const pathname = outputPathToPathname(outputPath); + const pageUrl = sanitizeUrl(siteUrl + pathname); + + const canonical = seo.canonicalUrl || frontmatter.canonicalUrl || pageUrl; + if (canonical) { + html += `\n`; + } + + // 4. Open Graph (Facebook/LinkedIn) + const appendTitle = frontmatter.titleAppend !== false; + const fullTitle = (appendTitle && siteTitle && pageTitle !== siteTitle) ? `${pageTitle} - ${siteTitle}` : pageTitle; + + html += `\n`; + html += `\n`; + html += `\n`; + html += `\n`; + + // Image Logic + let image = seo.image || frontmatter.image || globalSeo.openGraph?.defaultImage; + if (image) { + if (!image.startsWith('http')) { + // Resolve relative image path to absolute URL + image = `${siteUrl}/${image.replace(/^\.?\//, '')}`; + } + html += `\n`; + } + + // 5. Twitter + const cardType = seo.twitterCard || globalSeo.twitter?.cardType || 'summary_large_image'; + html += `\n`; + + if (globalSeo.twitter?.siteUsername) { + html += `\n`; + } + + html += `\n`; + html += `\n`; + if (image) { + html += `\n`; + } + + // 6. Keywords + const keywords = seo.keywords || frontmatter.keywords; + if (keywords) { + const kwStr = Array.isArray(keywords) ? keywords.join(', ') : keywords; + html += `\n`; + } + + return html; +} + +/** + * Post-build hook to auto-generate robots.txt if missing. + * This ensures SEO best practices without overwriting existing customizations. + * + * @param {Object} context + * @param {Object} context.config - The parsed project config + * @param {string} context.outputDir - Absolute path to output directory + * @param {Function} context.log - Logger function + */ +export async function onPostBuild({ config, outputDir, log }: any) { + const robotsPath = path.join(outputDir, 'robots.txt'); + const seoConfig = config.plugins?.seo || {}; + + // Check all possible locations for existing robots.txt + // Priority: site root > assets folder + const possibleLocations = [ + path.join(outputDir, 'robots.txt'), // site/robots.txt (already in output) + path.join(outputDir, 'assets', 'robots.txt'), // site/assets/robots.txt (copied from assets) + ]; + + // Find existing robots.txt + let existingRobotsPath: string | null = null; + for (const loc of possibleLocations) { + if (nativeFs.existsSync(loc)) { + existingRobotsPath = loc; + break; + } + } + + // If found, copy to site root if not already there + if (existingRobotsPath) { + if (existingRobotsPath !== robotsPath) { + // Copy from assets to site root (recommended location) + await fs.copyFile(existingRobotsPath, robotsPath); + if (log) log('Copied robots.txt from assets to site root'); + } else { + if (log) log('robots.txt already exists in site root, preserving'); + } + return; + } + + // No robots.txt found anywhere - generate one + const siteUrl = config.url ? config.url.replace(/\/$/, '') : ''; + const sitemapUrl = siteUrl ? `${siteUrl}/sitemap.xml` : ''; + + let robotsContent = 'User-agent: *\nAllow: /\n'; + + // Add sitemap reference if site URL is configured + if (sitemapUrl) { + robotsContent += `\n# Sitemap\nSitemap: ${sitemapUrl}\n`; + } + + // Add AI bot restrictions if configured (default: true = allow, false = block) + if (seoConfig.aiBots === false) { + robotsContent += '\n# Block AI training bots\n'; + const aiBots = ['GPTBot', 'ChatGPT-User', 'Google-Extended', 'CCBot', 'anthropic-ai', 'Omgilibot', 'Omgili', 'FacebookBot', 'Diffbot', 'Bytespider', 'ImagesiftBot', 'cohere-ai']; + aiBots.forEach(bot => { + robotsContent += `User-agent: ${bot}\nDisallow: /\n`; + }); + } + + await fs.writeFile(robotsPath, robotsContent); + if (log) log('Generated robots.txt'); + + // Auto-generate .nojekyll at the site root. + // GitHub Pages runs Jekyll by default, which silently drops every file or + // directory whose name starts with a dot โ€” including .docmd-search/ (the + // semantic index) and .docmd-search-client.js (the browser bundle). + // An empty .nojekyll file disables Jekyll so those assets are served as-is. + // This is a zero-config fix: users deploying to GitHub Pages never need to + // think about it. + const nojekyllPath = path.join(outputDir, '.nojekyll'); + if (!nativeFs.existsSync(nojekyllPath)) { + await fs.writeFile(nojekyllPath, ''); + if (log) log('Generated .nojekyll (disables Jekyll on GitHub Pages)'); + } +} \ No newline at end of file diff --git a/packages/plugins/seo/tsconfig.json b/packages/plugins/seo/tsconfig.json new file mode 100644 index 0000000..7befc89 --- /dev/null +++ b/packages/plugins/seo/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/plugins/sitemap/LICENSE b/packages/plugins/sitemap/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/sitemap/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/sitemap/README.md b/packages/plugins/sitemap/README.md new file mode 100644 index 0000000..4429bfb --- /dev/null +++ b/packages/plugins/sitemap/README.md @@ -0,0 +1,23 @@ +# @docmd/plugin-sitemap + +Automatically generates `sitemap.xml` for your docmd site at build time. Requires `siteUrl` in your config to produce valid absolute URLs. Bundled with `@docmd/core`. + +```js +// docmd.config.js +module.exports = { + siteUrl: 'https://mysite.com', // required + plugins: { + sitemap: { defaultChangefreq: 'weekly', defaultPriority: 0.8 } + } +}; +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/sitemap/package.json b/packages/plugins/sitemap/package.json new file mode 100644 index 0000000..d025358 --- /dev/null +++ b/packages/plugins/sitemap/package.json @@ -0,0 +1,58 @@ +{ + "name": "@docmd/plugin-sitemap", + "version": "0.8.12", + "description": "Sitemap generator plugin for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "docmd": { + "key": "sitemap", + "kind": "plugin", + "displayName": "Sitemap", + "tagline": "Sitemap generator for docmd.", + "capabilities": [ + "post-build" + ] + }, + "scripts": { + "build": "tsc" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "devDependencies": { + "@docmd/api": "workspace:*", + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "plugin", + "sitemap", + "xml", + "url", + "seo", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/plugins/sitemap/src/index.ts b/packages/plugins/sitemap/src/index.ts new file mode 100644 index 0000000..49b0f37 --- /dev/null +++ b/packages/plugins/sitemap/src/index.ts @@ -0,0 +1,83 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import fs from 'fs/promises'; +import type { PluginDescriptor } from '@docmd/api'; +import { outputPathToPathname, sanitizeUrl } from '@docmd/api'; + +export const plugin: PluginDescriptor = { + name: 'sitemap', + version: '0.8.12', + capabilities: ['post-build'] +}; + +/** + * Hook to run after the build is complete. + * @param {Object} context + * @param {Object} context.config - The parsed project config + * @param {Array} context.pages - Array of page objects { outputPath, frontmatter } + * @param {string} context.outputDir - Absolute path to output directory + * @param {Function} context.log - Logger function + */ + +export async function onPostBuild({ config, pages, outputDir, log }: any) { + // 1. Check if enabled + if (config.plugins?.sitemap === false || !config.url) { + if (!config.url && log) log('Skipping sitemap: "url" is missing in config', 'SKIP'); + return; + } + + const siteUrl = config.url.replace(/\/$/, ''); + + // 2. Build XML Header + let sitemapXml = '\n'; + sitemapXml += '\n'; + + // 3. Defaults + const defaultChangefreq = config.plugins?.sitemap?.defaultChangefreq || 'weekly'; + const defaultPriority = config.plugins?.sitemap?.defaultPriority || 0.8; + const rootPriority = config.plugins?.sitemap?.rootPriority || 1.0; + + // 4. Loop Pages + for (const page of pages) { + const fm = page.frontmatter || {}; + + // Skip hidden pages + if (fm.sitemap === false || fm.noindex === true) continue; + + // Use centralised URL utility for consistent URL generation. + // This is the single source of truth - no manual outputPath parsing. + const pathname = outputPathToPathname(page.outputPath); + const url = sanitizeUrl(siteUrl + pathname); + + // Metadata Logic + const isRoot = pathname === '/'; + const priority = fm.priority || (isRoot ? rootPriority : defaultPriority); + const changefreq = fm.changefreq || defaultChangefreq; + + sitemapXml += ' \n'; + sitemapXml += ` ${url}\n`; + if (fm.lastmod) sitemapXml += ` ${fm.lastmod}\n`; + sitemapXml += ` ${changefreq}\n`; + sitemapXml += ` ${priority}\n`; + sitemapXml += ' \n'; + } + + sitemapXml += ''; + + // 5. Write File + await fs.writeFile(path.join(outputDir, 'sitemap.xml'), sitemapXml); + if (log) log('Sitemap generated'); +} \ No newline at end of file diff --git a/packages/plugins/sitemap/tsconfig.json b/packages/plugins/sitemap/tsconfig.json new file mode 100644 index 0000000..7befc89 --- /dev/null +++ b/packages/plugins/sitemap/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/plugins/threads/LICENSE b/packages/plugins/threads/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/plugins/threads/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/plugins/threads/README.md b/packages/plugins/threads/README.md new file mode 100644 index 0000000..8ac59e6 --- /dev/null +++ b/packages/plugins/threads/README.md @@ -0,0 +1,19 @@ +# @docmd/plugin-threads + +Adds inline discussion threads to your docmd site - stored directly in Markdown as `::: threads` containers, so comments live in your repo and sync with your Git and PR workflows. Supports text highlighting, replies, thread resolution, and emoji reactions. An optional plugin, installed separately. + +```bash +docmd add threads +``` + +Original author: [@svallory](https://github.com/svallory) + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/plugins/threads/build.js b/packages/plugins/threads/build.js new file mode 100644 index 0000000..c5e6348 --- /dev/null +++ b/packages/plugins/threads/build.js @@ -0,0 +1,31 @@ +import esbuild from 'esbuild'; +import path from 'path'; +import { fileURLToPath } from 'url'; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); + +async function build() { + await esbuild.build({ + entryPoints: [path.resolve(__dirname, 'src/client/index.ts')], + bundle: true, + platform: 'browser', + target: 'es2022', + format: 'esm', + outdir: path.resolve(__dirname, 'dist/client'), + minify: false, + sourcemap: 'inline', + loader: { '.css': 'css' }, + tsconfigRaw: JSON.stringify({ + compilerOptions: { + experimentalDecorators: true, + useDefineForClassFields: false, + }, + }), + }); + console.log('Client built to dist/client/'); +} + +build().catch((err) => { + console.error(err); + process.exit(1); +}); diff --git a/packages/plugins/threads/e2e/basic-ui.e2e.spec.ts b/packages/plugins/threads/e2e/basic-ui.e2e.spec.ts new file mode 100644 index 0000000..93ee77a --- /dev/null +++ b/packages/plugins/threads/e2e/basic-ui.e2e.spec.ts @@ -0,0 +1,216 @@ +/** + * Basic UI tests - adapted from old devtalk.e2e.spec.ts "basic UI" describe block. + * + * Changes from old plugin: + * - No sidebar panel/toggle button (inline-only architecture) + * - threads-app replaces devtalk-app as root element + * - "New Thread" button replaces sidebar toggle + * - Threads rendered server-side with .threads-* classes + */ + +import { test, expect } from "@playwright/test"; +import { Actor, NavigateTo } from "./screenplay.ts"; +import { setAuthor, waitForClientProcessing } from "./helpers.ts"; + + + +let user: Actor; + +test.beforeEach(async ({ page }) => { + user = new Actor("TestUser", page); + await page.goto("/"); + await page.waitForSelector("threads-app", { state: "attached", timeout: 10_000 }); + await setAuthor(page, "TestUser"); + // NOTE: Do NOT clean threads here - these tests verify the pre-existing + // threads from the playground markdown (index.md ::: threads block) + // Wait for client-side JS to finish processing highlights + await waitForClientProcessing(page); +}); + +test.describe("threads plugin - basic UI", () => { + test("loads on the page with threads-app element", async () => { + await user.perform(NavigateTo.path("/")); + const app = user.page.locator("threads-app"); + await expect(app).toBeAttached(); + }); + + test("New Thread button is injected into the content area", async () => { + await user.perform(NavigateTo.path("/")); + const btn = user.page.locator(".threads-new-thread-btn").first(); + await expect(btn).toBeVisible({ timeout: 5_000 }); + await expect(btn).toContainText("New Thread"); + }); + + test("server-rendered threads appear with correct class structure", async () => { + // The playground index.md has pre-existing threads in the ::: threads block + await user.perform(NavigateTo.path("/")); + + // There should be thread cards rendered from the markdown + const threads = user.page.locator(".threads-thread[data-thread-id]"); + const count = await threads.count(); + expect(count).toBeGreaterThan(0); + + // Each thread should have at least one comment + const firstThread = threads.first(); + const comments = firstThread.locator(".threads-comment"); + await expect(comments.first()).toBeAttached(); + }); + + test("highlights appear on marked text", async () => { + await user.perform(NavigateTo.path("/")); + + // The playground has ==highlighted text=={thread-id} in the markdown + const highlights = user.page.locator("mark.threads-highlight[data-thread-id]"); + const count = await highlights.count(); + expect(count).toBeGreaterThan(0); + }); + + test("highlights have cycling colors (not all the same)", async () => { + await user.perform(NavigateTo.path("/")); + await waitForClientProcessing(user.page); + + const highlights = user.page.locator("mark.threads-highlight[data-thread-id]"); + const count = await highlights.count(); + + if (count < 2) { + test.skip(true, "Need at least 2 highlights to test color cycling"); + return; + } + + // Collect all highlight color classes + const colorClasses: string[] = []; + for (let i = 0; i < count; i++) { + const classList = await highlights.nth(i).evaluate((el) => + Array.from(el.classList).filter((c) => c.startsWith("threads-hl-")), + ); + colorClasses.push(...classList); + } + + // With 2+ highlights, we should see at least 2 different colors + const uniqueColors = new Set(colorClasses); + expect(uniqueColors.size).toBeGreaterThanOrEqual(2); + }); + + test("thread cards are placed inline after their highlighted block", async () => { + await user.perform(NavigateTo.path("/")); + await waitForClientProcessing(user.page); + + // Find a highlight mark that has a corresponding thread card + const highlights = user.page.locator("mark.threads-highlight[data-thread-id]"); + const firstHighlight = highlights.first(); + + if ((await firstHighlight.count()) === 0) { + test.skip(true, "No highlights found on the page"); + return; + } + + const threadId = await firstHighlight.getAttribute("data-thread-id"); + if (!threadId) return; + + const threadCard = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + await expect(threadCard).toBeAttached(); + + // Thread card should appear after the highlight's parent block in document order + const isAfterHighlight = await user.page.evaluate( + ({ threadId }) => { + const mark = document.querySelector(`mark.threads-highlight[data-thread-id="${threadId}"]`); + const thread = document.querySelector(`.threads-thread[data-thread-id="${threadId}"]`); + if (!mark || !thread) return false; + return mark.compareDocumentPosition(thread) & Node.DOCUMENT_POSITION_FOLLOWING; + }, + { threadId }, + ); + expect(isAfterHighlight).toBeTruthy(); + }); + + test("thread cards have matching border colors to their highlights", async () => { + await user.perform(NavigateTo.path("/")); + await waitForClientProcessing(user.page); + + const highlights = user.page.locator("mark.threads-highlight[data-thread-id]"); + const firstHighlight = highlights.first(); + + if ((await firstHighlight.count()) === 0) { + test.skip(true, "No highlights found"); + return; + } + + const threadId = await firstHighlight.getAttribute("data-thread-id"); + if (!threadId) return; + + // Get the highlight's color class + const hlColorClass = await firstHighlight.evaluate((el) => + Array.from(el.classList).find((c) => c.startsWith("threads-hl-")), + ); + + if (!hlColorClass) return; + + // The thread card should have the matching border class + const expectedBorderClass = hlColorClass.replace("threads-hl-", "threads-border-"); + const threadCard = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + const hasBorderClass = await threadCard.evaluate( + (el, cls) => el.classList.contains(cls), + expectedBorderClass, + ); + expect(hasBorderClass).toBe(true); + }); + + test("clicking a highlight scrolls to and flashes its thread", async () => { + await user.perform(NavigateTo.path("/")); + await waitForClientProcessing(user.page); + + const highlights = user.page.locator("mark.threads-highlight[data-thread-id]"); + const firstHighlight = highlights.first(); + + if ((await firstHighlight.count()) === 0) { + test.skip(true, "No highlights found"); + return; + } + + await firstHighlight.click(); + + // After clicking, the thread card should receive the flash class + const threadId = await firstHighlight.getAttribute("data-thread-id"); + const threadCard = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + await expect(threadCard).toHaveClass(/threads-thread--flash/, { timeout: 2_000 }); + }); + + test("popover hidden initially without text selection", async () => { + await user.perform(NavigateTo.path("/")); + + // Without any text selection, the popover should not show + await expect( + user.page.locator("threads-popover").getByText("Add comment"), + ).not.toBeVisible(); + }); + + test("reply buttons present on thread cards", async () => { + await user.perform(NavigateTo.path("/")); + + const threads = user.page.locator(".threads-thread[data-thread-id]"); + const count = await threads.count(); + + if (count === 0) { + test.skip(true, "No threads on page"); + return; + } + + // Each thread should have a Reply button + for (let i = 0; i < count; i++) { + const thread = threads.nth(i); + const replyBtn = thread.locator(".threads-comment-reply-btn").first(); + await expect(replyBtn).toBeAttached(); + await expect(replyBtn).toContainText("Reply"); + } + }); + + test("threads-sidebar container is hidden", async () => { + await user.perform(NavigateTo.path("/")); + + const sidebar = user.page.locator(".threads-sidebar"); + if ((await sidebar.count()) > 0) { + // The sidebar wrapper should be hidden (display: none) + await expect(sidebar).toBeHidden(); + } + }); +}); diff --git a/packages/plugins/threads/e2e/comment-display.e2e.spec.ts b/packages/plugins/threads/e2e/comment-display.e2e.spec.ts new file mode 100644 index 0000000..9cb3a83 --- /dev/null +++ b/packages/plugins/threads/e2e/comment-display.e2e.spec.ts @@ -0,0 +1,142 @@ +/** + * Comment display tests - adapted from old comment-display.e2e.spec.ts. + * + * Changes from old plugin: + * - Comments are server-rendered HTML (.threads-comment) not Lit components + * - Server-rendered comments have .threads-comment__meta and .threads-comment__body + * - Author info comes from data-author attribute on .threads-comment element + * - Date comes from data-date attribute + * - No "just now" time formatting (server renders static date strings like "2026-03-09") + */ + +import { test, expect } from "@playwright/test"; +import { Actor } from "./screenplay.ts"; +import { cleanThreads, setAuthor, seedAndReload, waitForReload } from "./helpers.ts"; + +let user: Actor; + +test.beforeEach(async ({ page }) => { + user = new Actor("TestUser", page); + await page.goto("/"); + await page.waitForSelector("threads-app", { state: "attached", timeout: 10_000 }); + await setAuthor(page, "TestUser"); + await cleanThreads(page); + await waitForReload(page); +}); + +test.describe("comment display", () => { + test("author name is displayed on the comment", async () => { + const { id: threadId } = await seedAndReload(user.page, { + author: "Alice", + body: "Hello from Alice", + }); + + const thread = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + await expect(thread).toBeAttached({ timeout: 5_000 }); + + // Server-rendered comment should show the author + const meta = thread.locator(".threads-comment__meta").first(); + await expect(meta).toContainText("Alice"); + }); + + test("comment body is displayed", async () => { + const { id: threadId } = await seedAndReload(user.page, { + author: "TestUser", + body: "This is the comment body text", + }); + + const thread = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + await expect(thread).toBeAttached({ timeout: 5_000 }); + + const body = thread.locator(".threads-comment__body").first(); + await expect(body).toContainText("This is the comment body text"); + }); + + test("date is displayed on the comment", async () => { + const { id: threadId } = await seedAndReload(user.page, { + author: "TestUser", + body: "Date display test", + }); + + const thread = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + await expect(thread).toBeAttached({ timeout: 5_000 }); + + // Server-rendered meta should contain a date (format: YYYY-MM-DD) + const meta = thread.locator(".threads-comment__meta").first(); + const metaText = await meta.textContent(); + // Should contain a date pattern like 2026-03-09 + expect(metaText).toMatch(/\d{4}-\d{2}-\d{2}/); + }); + + test("comment has data-author attribute", async () => { + const { id: threadId } = await seedAndReload(user.page, { + author: "Bob", + body: "Attribute test", + }); + + const thread = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + const comment = thread.locator(".threads-comment").first(); + await expect(comment).toHaveAttribute("data-author", "Bob"); + }); + + test("multiple comments displayed in order", async () => { + const { id: threadId } = await seedAndReload(user.page, { + author: "Alice", + body: "First comment", + replies: [ + { author: "Bob", body: "Second comment" }, + { author: "Charlie", body: "Third comment" }, + ], + }); + + let thread = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + await expect(thread).toBeAttached({ timeout: 5_000 }); + + // The dev server may need an additional reload to pick up the last reply + let comments = thread.locator(".threads-comment"); + if ((await comments.count()) < 3) { + await waitForReload(user.page); + thread = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + comments = thread.locator(".threads-comment"); + } + await expect(comments).toHaveCount(3); + + await expect(comments.nth(0).locator(".threads-comment__body")).toContainText("First comment"); + await expect(comments.nth(1).locator(".threads-comment__body")).toContainText("Second comment"); + await expect(comments.nth(2).locator(".threads-comment__body")).toContainText("Third comment"); + }); +}); + +test.describe("markdown rendering in comments", () => { + test("comment body renders inline markdown from markdown-it", async () => { + // Server-rendered comments go through markdown-it, which handles bold/italic/code + const { id: threadId } = await seedAndReload(user.page, { + body: "Use `console.log()` for debugging", + }); + + const thread = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + const body = thread.locator(".threads-comment__body").first(); + await expect(body).toBeAttached({ timeout: 5_000 }); + + // markdown-it should render backtick as + const codeEl = body.locator("code"); + await expect(codeEl).toBeAttached(); + }); + + test("HTML special characters are escaped", async () => { + const { id: threadId } = await seedAndReload(user.page, { + body: "", + }); + + const thread = user.page.locator(`.threads-thread[data-thread-id="${threadId}"]`); + const body = thread.locator(".threads-comment__body").first(); + await expect(body).toBeAttached({ timeout: 5_000 }); + + // No live + <% } %> + + + + <%- typeof faviconLinkHtml !== 'undefined' ? faviconLinkHtml : '' %> + + <%# โ”€โ”€ Highlight.js themes โ€” light + dark, toggled by theme-init โ”€โ”€ %> + <% if (config.theme?.codeHighlight !== false) { const isDarkDefault = appearance === 'dark'; %> + > + > + <% } %> + + <%- pluginHeadScriptsHtml || '' %> + <% (customCssFiles || []).forEach(cssFile => { %> + + <% }); %> + + <% + const _noSidebar = (sidebarConfig?.enabled === false); + const _noToc = (config.theme?.toc === false); + const _noHeader = (headerConfig?.enabled === false); + const _hasMenubar = (locals.menubarConfig && menubarConfig?.enabled !== false); + const _hasBanner = (locals.config && config.layout && config.layout.banner); + const _bodyClasses = ['summer-template']; + if (_noSidebar) _bodyClasses.push('no-sidebar'); + if (_noToc) _bodyClasses.push('no-toc'); + if (_noHeader) _bodyClasses.push('no-header'); + if (_hasMenubar) _bodyClasses.push('has-menubar'); + if (_hasBanner) _bodyClasses.push('has-banner'); + %> + + + data-spa-enabled="<%= (config.layout?.spa !== false).toString() %>" + data-copy-code-enabled="<%= (config.copyCode === true).toString() %>" + data-default-collapsed="<%= sidebarConfig?.defaultCollapsed === true %>"> + + + <%# โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + Optional banner (data-docmd-banner is what docmd-main.js's + initBanner() listens for so close-state is sessionStorage-persisted) + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ %> + <% if (_hasBanner) { %> +
      +
      + <%- typeof config.layout.banner === 'string' ? config.layout.banner : '' %> + +
      +
      + <% } %> + + <%# โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + BAND 1: Top bar + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ %> + + + <%# โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + BAND 2: Sub-navigation (menubar) โ€” INLINED + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ %> + <% if (_hasMenubar) { %> + + <% } %> + + <%# โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + BAND 4: Layout grid (sidebar / main / TOC) + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ %> +
      + + <%# โ”€โ”€ Sidebar (left) โ”€โ”€ %> + <% if (!_noSidebar) { %> + + <% } %> + + <%# โ”€โ”€ Main content (center) โ”€โ”€ %> +
      + <% if (headerConfig?.enabled !== false) { %> +
      +
      + <%# Breadcrumb + page title row %> +
      + <% if (config.layout?.breadcrumbs !== false && locals.breadcrumbs && breadcrumbs.length > 0) { %> + + <% } %> +
      + +
      + <% if (config.theme?.copyWidgets?.raw !== false) { %> + + <% } %> + <% if (config.theme?.copyWidgets?.context !== false) { %> + + <% } %> +
      +
      +
      + <% } %> + + <% if (headerConfig?.enabled === false) { %> +

      <%= pageTitle %>

      + <% } %> + + + +
      + <%- content %> +
      + + <% if (config.pageNavigation && (prevPage || nextPage)) { %> + + <% } %> + + <% if (locals.frontmatter?._git?.lastUpdatedTimestamp || locals.editUrl) { %> +
      + <% if (locals.editUrl) { %> + + + <%= typeof editLinkText !== 'undefined' ? editLinkText : 'Edit this page' %> + + <% } else { %> + + <% } %> + <% if (locals.frontmatter?._git?.lastUpdatedTimestamp) { %> + + <% } %> +
      + <% } %> +
      + + <%# โ”€โ”€ Right-rail TOC (INLINED) โ”€โ”€ %> + <% if (!_noToc) { %> + <% + const _tocDisabled = (frontmatter && (frontmatter.toc === false || frontmatter.toc === 'false' || frontmatter.toc === 'hidden')); + let _tocHeadings = []; + if (!_tocDisabled) { + if (typeof headings !== 'undefined' && Array.isArray(headings) && headings.length > 0) { + _tocHeadings = headings.filter(h => h.level >= 1 && h.level <= 4); + } else if (typeof content !== 'undefined' && content) { + const _hr = /]*?(?:id="([^"]*)")?[^>]*?>([\s\S]*?)<\/h\1>/g; + const _cs = content.toString(); + for (const _m of _cs.matchAll(_hr)) { + const _lvl = parseInt(_m[1], 10); + let _id = _m[2]; + const _txt = String(_m[3]).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, "'").replace(/ /g, ' ').replace(/<\/?\w+[^>]*>/g, ''); + if (!_id) _id = _txt.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '').replace(/--+/g, '-').replace(/^-+|-+$/g, ''); + _tocHeadings.push({ id: _id, level: _lvl, text: _txt }); + } + } + } + %> + <% if (_tocHeadings.length > 1) { %> +
      + +
      + <% } %> + <% } %> +
      + + + + <%# โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + BAND 5: Footer โ€” INLINED + โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ %> + <% + const _fc = (typeof footerConfig !== 'undefined' ? footerConfig : (locals.footerConfig || {})); + %> + <% if (_fc?.style === 'complete' && Array.isArray(_fc.columns) && _fc.columns.length) { %> +
      +
      +
      + + <% if (_fc.description) { %> +

      <%= _fc.description %>

      + <% } %> +
      + <% _fc.columns.forEach(col => { %> +
      +

      <%= col.title %>

      + +
      + <% }) %> +
      +
      +
      <%- footerHtml || (_fc.copyright ? _fc.copyright : '') %>
      + <% if (_fc.branding !== false) { %> +
      + <%= typeof t === 'function' ? t('builtWith') : 'Built with' %> + + docmd + <% if (_sponsorUrl && (_sponsorPos === 'footer' || _sponsorPos === 'both')) { %> + + + + Sponsor + + <% } %> +
      + <% } %> +
      +
      + <% } else { %> +
      +
      +
      <%- footerHtml || (_fc?.copyright ? _fc.copyright : '') %>
      + <% if (_fc?.branding !== false) { %> +
      + <%= typeof t === 'function' ? t('builtWith') : 'Built with' %> + + docmd + <% if (_sponsorUrl && (_sponsorPos === 'footer' || _sponsorPos === 'both')) { %> + + + + Sponsor + + <% } %> +
      + <% } %> +
      +
      + <% } %> + + <% if (locals.allLocales && allLocales && allLocales.length > 1) { %> + + <% } %> + + + <%- pluginBodyScriptsHtml || '' %> + <% (customJsFiles || []).forEach(jsFile => { if (jsFile && jsFile.trim() !== '') { %> + + <% } }); %> + + diff --git a/packages/templates/summer/templates/partials/footer.ejs b/packages/templates/summer/templates/partials/footer.ejs new file mode 100644 index 0000000..980bf74 --- /dev/null +++ b/packages/templates/summer/templates/partials/footer.ejs @@ -0,0 +1,69 @@ +<%# --------------------------------------------------------------- + # @docmd/template-summer โ€” partials/footer.ejs + # + # Two visual styles: + # - "complete" (config.footer.style === 'complete') โ€” multi-column + # footer with branding, description, link columns + # - "minimal" / default โ€” single-line bar with copyright + branding + # --------------------------------------------------------------- +%> +<% const _fc = (typeof footerConfig !== 'undefined' ? footerConfig : (locals.footerConfig || {})); %> +<% if (_fc?.style === 'complete' && Array.isArray(_fc.columns) && _fc.columns.length) { %> +
      +
      +
      + + <% if (_fc.description) { %> +

      <%= _fc.description %>

      + <% } %> +
      + <% _fc.columns.forEach(col => { %> +
      +

      <%= typeof t === 'function' ? t(col.title) : col.title %>

      + +
      + <% }) %> +
      +
      +
      <%- footerHtml || (_fc.copyright ? _fc.copyright : '') %>
      + <% if (_fc.branding !== false) { %> +
      + <%= typeof t === 'function' ? t('builtWith') : 'Built with' %> + + docmd + ยท + + + Sponsor + +
      + <% } %> +
      +
      +<% } else { %> +
      +
      +
      <%- footerHtml || (_fc?.copyright ? _fc.copyright : '') %>
      + <% if (_fc?.branding !== false) { %> +
      + <%= typeof t === 'function' ? t('builtWith') : 'Built with' %> + + docmd +
      + <% } %> +
      +
      +<% } %> \ No newline at end of file diff --git a/packages/templates/summer/templates/partials/menubar.ejs b/packages/templates/summer/templates/partials/menubar.ejs new file mode 100644 index 0000000..76b5ea6 --- /dev/null +++ b/packages/templates/summer/templates/partials/menubar.ejs @@ -0,0 +1,92 @@ +<%# --------------------------------------------------------------- + # @docmd/template-summer โ€” partials/menubar.ejs + # + # Sits in a sticky sub-nav bar BELOW the top header. Each item is + # rendered as a tab. Supports dropdowns, icons, and a trailing + # action slot (right side of the bar) used for tertiary controls. + # --------------------------------------------------------------- +%> +<% + const menubar = (typeof menubarConfig !== 'undefined' ? menubarConfig : (locals.menubarConfig || {})); + const left = Array.isArray(menubar.left) ? menubar.left : []; + const right = Array.isArray(menubar.right) ? menubar.right : []; + + // Detect the active item: prefer explicit `active` flag, else match by URL + function isActive(item) { + if (item.active) return true; + if (!currentPagePath) return false; + const itemUrl = (item.url || item.path || '').replace(/^\/+/, '').replace(/^index\.html$/, '').replace(/\/$/, ''); + const cur = (currentPagePath || '').replace(/^\/+/, '').replace(/^index\.html$/, '').replace(/\/$/, ''); + if (!itemUrl) return false; + return cur === itemUrl || cur.startsWith(itemUrl + '/'); + } + + function itemHref(item) { + if (item.url) return buildRelativeUrl(item.url); + if (item.path) return buildRelativeUrl(item.path); + return '#'; + } + + function renderTab(item) { + const active = isActive(item); + const href = itemHref(item); + const external = !!item.external; + const target = external ? ' target="_blank" rel="noopener noreferrer"' : ''; + const cls = 'summer-subnav__tab' + (active ? ' active' : ''); + const icon = item.icon ? `${renderIcon(item.icon)}` : ''; + const text = item.text || item.title || ''; + return `${icon}${text}${external ? 'โ†—' : ''}`; + } +%> +
      + <% left.forEach(item => { %> + <% if (item.type === 'dropdown') { %> +
      + + +
      + <% } else { %> + <%- renderTab(item) %> + <% } %> + <% }) %> + + <% if (left.length && right.length) { %> +
      + <% } %> + +
      + <% right.forEach(item => { %> + <% if (item.type === 'dropdown') { %> +
      + + +
      + <% } else { %> + <%- renderTab(item) %> + <% } %> + <% }) %> +
      +
      diff --git a/packages/templates/summer/templates/partials/options-menu.ejs b/packages/templates/summer/templates/partials/options-menu.ejs new file mode 100644 index 0000000..39fd5cc --- /dev/null +++ b/packages/templates/summer/templates/partials/options-menu.ejs @@ -0,0 +1,45 @@ +<%# --------------------------------------------------------------- + # @docmd/template-summer โ€” partials/options-menu.ejs + # + # Custom options menu for summer template. The search component is + # intentionally NOT rendered here because the top-bar already + # shows the search button. The remaining discrete actions + # (theme switch, language, project switcher, sponsor) are surfaced + # as icon buttons, styled with `.summer-iconbtn`. + # --------------------------------------------------------------- +%> +<% if (optionsMenu && optionsMenu.components) { %> +
      + <%# Note: search is rendered separately in the topbar, see layout.ejs %> + + <% if (locals.workspace && workspace.switcher.enabled && workspace.switcher.position === 'options-menu') { %> +
      + <%- await include('project-switcher', { workspace, config, renderIcon, compact: true }) %> +
      + <% } %> + + <% if (locals.allLocales && allLocales && allLocales.length > 1 && locals.config && config.i18n && config.i18n.position === 'options-menu') { %> +
      + <%- await include('language-switcher', { allLocales, activeLocale: locals.activeLocale, defaultLocale: locals.defaultLocale, config, renderIcon, compact: true, currentPagePath: locals.currentPagePath, localePrefix: locals.localePrefix }) %> +
      + <% } %> + + <% if (optionsMenu.components.themeSwitch !== false) { %> + + <% } %> + + <% if (optionsMenu.components.sponsor) { %> + + + + <% } %> + + <% if (optionsMenu.components.github) { %> + + + + <% } %> +
      +<% } %> diff --git a/packages/templates/summer/templates/toc.ejs b/packages/templates/summer/templates/toc.ejs new file mode 100644 index 0000000..5cdd53d --- /dev/null +++ b/packages/templates/summer/templates/toc.ejs @@ -0,0 +1,53 @@ +<%# --------------------------------------------------------------- + # @docmd/template-summer โ€” toc.ejs + # + # Right-rail table of contents. We re-use the heading detection + # logic from the default template so the template stays + # plug-and-play, then style the result with `.summer-toc__*` + # classes that the rest of the stylesheet targets. + # --------------------------------------------------------------- +%> + +<% +function decodeHtmlEntities(html) { + return String(html).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, "'").replace(/ /g, ' '); +} + +// Skip on the no-style fallback and on pages that opt out via frontmatter. +const _tocDisabled = (frontmatter && (frontmatter.toc === false || frontmatter.toc === 'false' || frontmatter.toc === 'hidden')); +if (!_tocDisabled) { + let tocHeadings = []; + if (typeof headings !== 'undefined' && Array.isArray(headings) && headings.length > 0) { + tocHeadings = headings.filter(h => h.level >= 1 && h.level <= 4); + } else if (typeof content !== 'undefined' && content) { + const headingRegex = /]*?(?:id="([^"]*)")?[^>]*?>([\s\S]*?)<\/h\1>/g; + let match; + const contentStr = content.toString(); + while ((match = headingRegex.exec(contentStr)) !== null) { + const level = parseInt(match[1], 10); + let id = match[2]; + const text = decodeHtmlEntities(match[3].replace(/<\/?\w+[^>]*>/g, '')); + if (!id) id = text.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '').replace(/--+/g, '-').replace(/^-+|-+$/g, ''); + tocHeadings.push({ id, level, text }); + } + } + + if (tocHeadings.length > 1) { + // Build a nested list (preserve heading level) + let lastLevel = 0; +%> + +<% } } %> \ No newline at end of file diff --git a/packages/templates/summer/tsconfig.json b/packages/templates/summer/tsconfig.json new file mode 100644 index 0000000..85a5338 --- /dev/null +++ b/packages/templates/summer/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/themes/LICENSE b/packages/themes/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/themes/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/themes/README.md b/packages/themes/README.md new file mode 100644 index 0000000..43126d2 --- /dev/null +++ b/packages/themes/README.md @@ -0,0 +1,28 @@ +# @docmd/themes + +Official themes for docmd - three production-ready designs with full light/dark mode support, each customisable via CSS variables. + +| Theme | Style | +|:---|:---| +| **Sky** | Clean, modern, blue accents. Default. | +| **Ruby** | Elegant serif typography, red accents. | +| **Retro** | Terminal-style, neon, high contrast. | + +## Quick start + +```js +// docmd.config.js +module.exports = { + theme: { name: 'retro' } +}; +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io/theming](https://docs.docmd.io/theming)** for customisation options and CSS variable reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/themes/package.json b/packages/themes/package.json new file mode 100644 index 0000000..98669b4 --- /dev/null +++ b/packages/themes/package.json @@ -0,0 +1,56 @@ +{ + "name": "@docmd/themes", + "version": "0.8.12", + "description": "Official themes for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": "./dist/index.js" + }, + "scripts": { + "build": "tsc" + }, + "files": [ + "dist", + "src" + ], + "engines": { + "node": ">=18" + }, + "devDependencies": { + "@types/node": "^24.13.3" + }, + "keywords": [ + "docmd", + "themes", + "theme", + "theme-pack", + "css", + "scss", + "stylesheets", + "sky", + "retro", + "ruby", + "markdown", + "minimalist", + "zero-config", + "site-generator", + "static-site-generator", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/themes/src/docmd-theme-retro.css b/packages/themes/src/docmd-theme-retro.css new file mode 100644 index 0000000..1085f6e --- /dev/null +++ b/packages/themes/src/docmd-theme-retro.css @@ -0,0 +1,287 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/* + * Retro Theme : "Classic Computing" + * A clean, high-performance take on vintage computing aesthetics. + * Features: IBM Amber/Phosphor Green tones, sharp corners, and + * the modern "Sky" structural layout. + */ + +@import url('https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500&family=IBM+Plex+Mono:wght@400;500;600&display=swap'); + +:root { + --retro-primary: #916400; + /* Classic IBM Amber */ + --retro-bg-dark: #121212; + --retro-bg-light: #fdf6e3; + /* Solarized light / Old paper */ +} + +:root[data-theme=light] { + --accent-color: var(--retro-primary); + --retro-primary-light: rgba(255, 176, 0, 0.1); + --retro-primary-dark: #b37b00; + --bg-color: var(--retro-bg-light); + --text-color: #111111; + --text-heading: #000000; + --border-color: #dc9700; + --border-color-hover: #966700; + --border-color-codeblock: #efc15b; + --text-muted: #4d4d4d; + --sidebar-bg: #fffcf3; + --sidebar-text: #333333; + --sidebar-link-active-bg: rgba(255, 176, 0, 0.15); + --sidebar-link-active-text: var(--retro-primary-dark); + --link-color: var(--retro-primary-dark); + --link-color-hover: #8f6200; + --code-text: var(--retro-primary-dark); + --scrollbar-thumb: #d3cbb0; + --scrollbar-thumb-hover: var(--retro-primary-dark); + --radius-sm: 3px; + --radius-md: 3px; +} + +:root[data-theme=dark] { + --retro-primary: #33ff33; + /* Classic Phosphor Green */ + --accent-color: var(--retro-primary); + --retro-primary-light: rgba(51, 255, 51, 0.1); + --retro-primary-dark: #22cc22; + + --bg-color: var(--retro-bg-dark); + --text-color: #e0e0e0; + /* Brighter for better contrast on black */ + --text-heading: var(--retro-primary); + --text-muted: #888888; + + --sidebar-bg: #0a0a0a; + --sidebar-text: #a0a0a0; + --sidebar-link-active-bg: rgba(51, 255, 51, 0.15); + /* Explicit override */ + --sidebar-link-active-text: var(--retro-primary); + + --link-color: var(--retro-primary); + --border-color: #222; + --header-bg: var(--sidebar-bg); + --header-border: var(--border-color); + + --code-bg: #0a0a0a; + --code-text: var(--retro-primary); + + --scrollbar-thumb: #222; + --scrollbar-thumb-hover: var(--retro-primary); +} + +/* Base Overrides */ +body { + background-color: var(--sidebar-bg); +} + +h1, +h2, +h3, +h4, +h5, +h6 { + font-family: 'IBM Plex Mono', 'Fira Code', monospace; + font-weight: 600; +} + +.content-theme-cover { + position: fixed; + overflow: scroll; + height: 100%; + border: 1px solid var(--border-color); + margin-top: calc(var(--sticky-top-offset) + 5px); + border-radius: 3px 0 0 0; + background-color: var(--bg-color); +} + +.page-header, +.docmd-menubar { + background-color: var(--sidebar-bg); + border: 0; +} + +body.has-menubar-top:not(.no-header) { + --sticky-top-offset: calc(var(--header-h)); +} + +.sidebar { + border-right: 0; + padding-left: .25em; + background-color: var(--sidebar-bg); +} + +/* Navigation */ +.sidebar nav li.nav-group { + background-color: var(--retro-primary-light); + border-radius: var(--radius-sm); +} + +.sidebar nav .submenu { + border: 0; + background-color: var(--retro-primary-light); + margin: 0 .5em .5em; + padding: .25em; + border-radius: 4px; +} + +.sidebar nav li a, +.sidebar nav li .nav-label { + font-family: 'IBM Plex Mono', monospace; + font-size: 13px; + color: var(--sidebar-text); +} + +/* Fix leaking Sky colors on selection and hover */ +.sidebar nav li a.active, +.sidebar nav li a:hover, +.theme-toggle-button:hover, +.docmd-tabs-nav-item:hover, +.copy-code-button:hover { + background-color: var(--sidebar-link-active-bg) !important; + color: var(--sidebar-link-active-text) !important; +} + +.sidebar nav li a.active { + font-weight: 600; + box-shadow: inset 3px 0 0 var(--accent-color); +} + +/* UI Elements */ +.content-area .button { + background-color: var(--accent-color); + color: #000; + font-family: 'IBM Plex Mono', monospace; + font-weight: 600; + border-radius: 2px; +} + +.content-area .button:hover { + opacity: 0.9; + box-shadow: 0 0 10px var(--retro-primary-light); +} + +.docmd-container { + border-radius: var(--radius-sm); + padding: 1rem; +} + +/* Callouts */ +.callout-info .callout-title::before { + content: ":: INFO :: "; +} + +.callout-warning .callout-title::before { + content: ":: WARN :: "; +} + +.callout-tip .callout-title::before { + content: ":: HINT :: "; +} + +.callout-danger .callout-title::before { + content: ":: FAIL :: "; +} + +.callout-success .callout-title::before { + content: ":: PASS :: "; +} + +.callout .callout-title { + font-family: 'IBM Plex Mono', monospace; + text-transform: uppercase; + font-size: 12px; +} + +/* Custom Scrollbar */ +::-webkit-scrollbar { + width: 6px; + height: 6px; +} + +::-webkit-scrollbar-track { + background: transparent; +} + +/* Fix Scrollbars - use var() from root */ +::-webkit-scrollbar-thumb { + background-color: var(--scrollbar-thumb) !important; +} + +::-webkit-scrollbar-thumb:hover { + background-color: var(--scrollbar-thumb-hover) !important; +} + +.sidebar::-webkit-scrollbar-thumb, +.toc-list::-webkit-scrollbar-thumb, +.docmd-search-results::-webkit-scrollbar-thumb, +pre::-webkit-scrollbar-thumb, +.table-wrapper::-webkit-scrollbar-thumb { + background-color: transparent !important; +} + +.sidebar:hover::-webkit-scrollbar-thumb, +.toc-list:hover::-webkit-scrollbar-thumb, +.docmd-search-results:hover::-webkit-scrollbar-thumb, +pre:hover::-webkit-scrollbar-thumb, +.table-wrapper:hover::-webkit-scrollbar-thumb { + background-color: var(--scrollbar-thumb) !important; +} + +/* Options Menu */ +.docmd-search-trigger .search-label, +.docmd-options-menu .lucide-icon { + color: var(--accent-color); +} + +.docmd-options-menu .theme-toggle-button, +.docmd-options-menu .sponsor-link-button { + border-radius: 4px; + border: 1px solid var(--border-color); +} + +.docmd-options-menu .theme-toggle-button:hover { + border-color: var(--accent-color); +} + +/* Misc */ +.footer-complete { + background-color: var(--bg-color); + border-top: 1px solid var(--border-color); + margin-top: 2rem; +} + +.docmd-kbd { + background-color: var(--retro-primary-light); + color: var(--accent-color); + border: 1px solid var(--border-color); + font-family: 'IBM Plex Mono', monospace; +} + +.docmd-options-menu .theme-toggle-button, +.docmd-options-menu .sponsor-link-button, +.docmd-options-menu .docmd-search-trigger { + border-radius: 3px; +} + +.docmd-options-menu .sponsor-link-button:hover { + background-color: var(--bg-color); +} + +.toc-sidebar { + top: 1em; +} \ No newline at end of file diff --git a/packages/themes/src/docmd-theme-ruby.css b/packages/themes/src/docmd-theme-ruby.css new file mode 100644 index 0000000..fbc97f9 --- /dev/null +++ b/packages/themes/src/docmd-theme-ruby.css @@ -0,0 +1,143 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/* + * Ruby Theme + * Inspired by the beauty of gemstones + * Features: Deep ruby red, elegant serif fonts, subtle gem-like effects + */ + +@import "https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;500;600;700&family=Source+Sans+Pro:wght@300;400;600;700&display=swap"; + +:root { + --ruby-font-family-sans: "Source Sans Pro", system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; + --ruby-font-family-serif: "Playfair Display", Georgia, "Times New Roman", serif; +} + +:root[data-theme=light] { + --ruby-primary: #b30000; + --ruby-primary-light: #ffebee; + --ruby-primary-dark: #8e0000; + --ruby-accent: #7b1fa2; + --ruby-text: #2d2d2d; + --ruby-background: #ffffff; + --ruby-border: #e0e0e0; + + --bg-color: var(--ruby-background); + --text-color: var(--ruby-text); + --text-heading: var(--ruby-text); + --text-muted: #5a5a5a; + --sidebar-bg: #f8f5f5; + --sidebar-text: #5a5a5a; + --sidebar-link-active-bg: #f8e7e7; + --sidebar-link-active-text: var(--ruby-primary); + --link-color: var(--ruby-primary); + --border-color: var(--ruby-border); + --header-bg: var(--ruby-background); + --header-border: var(--ruby-border); + --code-bg: var(--ruby-primary-light); + --code-text: var(--ruby-primary-dark); + --font-family-sans: var(--ruby-font-family-sans); +} + +:root[data-theme=dark] { + --ruby-primary: #ff5252; + --ruby-primary-light: #3c1a1a; + --ruby-primary-dark: #ff7b7b; + --ruby-accent: #ce93d8; + --ruby-text: #f0f0f0; + --ruby-background: #1a0a0a; + --ruby-border: #3a2020; + + --bg-color: var(--ruby-background); + --text-color: var(--ruby-text); + --text-heading: var(--ruby-text); + --text-muted: silver; + --sidebar-bg: #1a0a0a; + --sidebar-text: silver; + --sidebar-link-active-bg: #2a1515; + --sidebar-link-active-text: var(--ruby-primary); + --link-color: var(--ruby-primary); + --border-color: var(--ruby-border); + --header-bg: var(--ruby-background); + --header-border: var(--ruby-border); + --code-bg: var(--ruby-primary-light); + --code-text: var(--ruby-text); + --font-family-sans: var(--ruby-font-family-sans); +} + +/* Theme-specific overrides */ + +h1, +h2, +h3, +h4, +h5, +h6 { + font-family: var(--ruby-font-family-serif); +} + +h1::after { + content: ""; + display: block; + width: 60px; + height: 3px; + background: linear-gradient(90deg, var(--ruby-primary), var(--ruby-accent)); + margin-top: var(--space-2); + border-radius: var(--radius-sm); +} + +.content-area a:not(.button):not(.copy-code-button) { + position: relative; +} + +.content-area a:not(.button):not(.copy-code-button)::after { + content: ""; + position: absolute; + width: 100%; + height: 1px; + bottom: 0; + left: 0; + background: linear-gradient(90deg, var(--ruby-primary), var(--ruby-accent)); + transform: scaleX(0); + transform-origin: right bottom; + transition: transform 0.3s; +} + +.content-area a:not(.button):not(.copy-code-button):hover::after { + transform: scaleX(1); + transform-origin: left bottom; +} + +.docmd-container { + border-top: 3px solid var(--ruby-primary); +} + +.button, button:not(.theme-toggle-button):not(.copy-code-button):not(.docmd-search-trigger):not(.sidebar-toggle-button) { + background: linear-gradient(135deg, var(--ruby-primary) 0%, var(--ruby-accent) 100%); + color: #ffffff; + border: none; + border-radius: var(--radius-md); + font-weight: 600; +} + +.button:hover, button:not(.theme-toggle-button):not(.copy-code-button):not(.docmd-search-trigger):not(.sidebar-toggle-button):hover { + filter: brightness(110%); + transform: translateY(-1px); + box-shadow: var(--shadow-md); +} + +.docmd-options-menu .docmd-search-trigger { + background-color: transparent; +} \ No newline at end of file diff --git a/packages/themes/src/docmd-theme-sky.css b/packages/themes/src/docmd-theme-sky.css new file mode 100644 index 0000000..2aea5a8 --- /dev/null +++ b/packages/themes/src/docmd-theme-sky.css @@ -0,0 +1,250 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/* + * Sky Theme + * Inspired by the clear blue sky + * Features: Blue tones, clean lines, subtle gradients + */ + +:root { + --sky-primary: #0097ff; +} + +:root[data-theme=light] { + --accent-color: #0097ff; + --sky-primary: #0097ff; + --sky-primary-light: #8acdff33; + --sky-primary-dark: #00497b; + --sky-text: #1a1f36; + --sky-text-light: #4a5568; + --sky-background: #ffffff; + --sky-background-alt: #f9fafb; + --sky-border: #e2e8f0; + --bg-color: var(--sky-background); + --text-color: var(--sky-text); + --text-heading: var(--sky-text); + --text-muted: var(--sky-text-light); + --sidebar-bg: #f7fafc; + --sidebar-text: var(--sky-text-light); + --sidebar-link-active-bg: var(--sky-primary-light); + --sidebar-link-active-text: var(--sky-primary); + --link-color: var(--sky-primary); + --border-color: #6dabff57; + --header-bg: var(--sky-background); + --header-border: var(--sky-border); + --code-bg: var(--sky-primary-light); + --code-text: var(--sky-primary-dark); +} + +:root[data-theme=dark] { + --sky-primary: #3b82f6; + --sky-primary-light: #1e293b; + --sky-primary-dark: #60a5fa; + --sky-text: #f1f5f9; + --sky-text-light: #cbd5e1; + --sky-background: #0f172a; + --sky-background-alt: #1e293b; + --sky-border: #334155; + + --bg-color: var(--sky-background); + --text-color: var(--sky-text); + --text-heading: var(--sky-text); + --text-muted: var(--sky-text-light); + --sidebar-bg: #0f172a; + --sidebar-text: var(--sky-text-light); + --sidebar-link-active-bg: #1e293b; + --sidebar-link-active-text: var(--sky-primary); + --link-color: var(--sky-primary); + --border-color: var(--sky-border); + --header-bg: var(--sky-background); + --header-border: var(--sky-border); + --code-bg: var(--sky-primary-light); + --code-text: var(--sky-text); +} + +/* Theme-specific overrides */ + +.callout-info .callout-title::before { + content: "โ„น๏ธ "; +} + +.callout-warning .callout-title::before { + content: "โš ๏ธ "; +} + +.callout-tip .callout-title::before { + content: "๐Ÿ’ก "; +} + +.callout-danger .callout-title::before { + content: "โŒ "; +} + +.callout-success .callout-title::before { + content: "โœ… "; +} + +.content-area .button { + background-color: var(--sky-primary); + color: #ffffff; + border-radius: var(--radius-md); +} + +.content-area .button:hover { + background-color: var(--sky-primary-dark); +} + +/* Polaroid effect */ +figure.polaroid { + background: #ffffff; + padding: 10px 10px 30px; + box-shadow: var(--shadow-md); + border-radius: var(--radius-sm); +} + +figure.polaroid figcaption { + background: #ffffff; + color: var(--sky-text); + font-size: 1.1rem; + font-style: italic; +} + +[data-theme=dark] figure.polaroid, +[data-theme=dark] figure.polaroid figcaption { + background: #1e293b; + color: var(--sky-text); +} + +.page-header, +.docmd-menubar { + background-color: var(--sidebar-bg); + border: 0; +} + +body.has-menubar-top:not(.no-header) { + --sticky-top-offset: calc(var(--header-h)); +} + +.sidebar { + border-right: 0; + padding-left: .25em; +} + +body { + background-color: var(--sidebar-bg); +} + +.content-theme-cover { + position: fixed; + overflow: scroll; + height: 100%; + border: 1px solid var(--sky-border); + margin-top: calc(var(--sticky-top-offset) + 5px); + border-radius: 1.5em 0 0 0; + background-color: var(--bg-color); +} + +.version-dropdown-toggle { + width: 80%; + margin: 0 auto; + border-radius: 1rem; + background-color: var(--sky-primary-light); +} + +.sidebar nav li.nav-group { + background-color: var(--sky-primary-light); + border-radius: 10px; +} + +.sidebar nav .submenu { + border: 0; + background-color: var(--sky-primary-light); + margin: 0 .5em .5em; + padding: .25em; + border-radius: 10px; +} + +.sidebar nav li a, +.sidebar nav li .nav-label { + color: var(--sky-primary-dark); +} + +.sidebar nav li { + margin: .25rem; +} + +.copy-code-button:hover, +.docmd-tabs-nav-item:hover, +.sidebar nav li a.active, +.sidebar nav li a:hover, +.theme-toggle-button:hover { + background-color: var(--sky-primary-light); +} + +.sidebar nav li a.active { + color: var(--sky-primary-dark); +} + +.toc-sidebar { + top: 1rem; +} + +.version-dropdown-menu { + width: 80%; + margin: 0 auto; +} + +.version-dropdown-toggle:hover { + border-color: var(--sky-primary); +} + +.footer-complete { + background-color: var(--bg-color); + padding: 0; + margin: 0 var(--space-8); + padding: var(--space-12) 0 var(--space-6); +} + +.page-footer-actions { + border-top: 0; +} + +.footer-complete-bottom { + border-top: 0; +} + +.docmd-kbd { + background-color: var(--sky-primary-light); + color: var(--sky-primary); +} + +.docmd-search-trigger .search-label, +.docmd-options-menu .lucide-icon { + color: var(--sky-primary-dark); +} + +.docmd-options-menu .sponsor-link-button:hover, +.docmd-options-menu .sponsor-link-button:hover svg, +.docmd-options-menu button:hover:not(.docmd-search-trigger) { + background-color: var(--sky-primary); + color: var(--sky-primary-dark); + border: initial; + transition: 0.2s; +} + +.docmd-options-menu .theme-toggle-button, +.docmd-options-menu .sponsor-link-button { + border-radius: 50%; +} \ No newline at end of file diff --git a/packages/themes/src/index.ts b/packages/themes/src/index.ts new file mode 100644 index 0000000..f60d3a4 --- /dev/null +++ b/packages/themes/src/index.ts @@ -0,0 +1,43 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import path from 'path'; +import { fileURLToPath } from 'url'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); + +/** + * Returns the absolute path to the requested theme CSS file. + * @param {string} themeName - 'sky', 'retro', 'ruby' + * @returns {string} Absolute path to css file + */ + +function getThemePath(themeName: string) { + const cleanName = themeName.toLowerCase(); + // Using path.join(__dirname, '..', 'src') because this file runs from dist/ + return path.join(__dirname, '..', 'src', `docmd-theme-${cleanName}.css`); +} + +/** + * Returns the directory containing all themes + */ +function getThemesDir() { + return path.join(__dirname, '..', 'src'); +} + +export { + getThemePath, + getThemesDir +}; \ No newline at end of file diff --git a/packages/themes/tsconfig.json b/packages/themes/tsconfig.json new file mode 100644 index 0000000..9635ce4 --- /dev/null +++ b/packages/themes/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/tui/LICENSE b/packages/tui/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/tui/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/tui/README.md b/packages/tui/README.md new file mode 100644 index 0000000..0f1031c --- /dev/null +++ b/packages/tui/README.md @@ -0,0 +1,34 @@ +# @docmd/tui + +Terminal User Interface (TUI) design system for docmd. + +This package provides a unified, high-signal design system for all terminal output across the docmd ecosystem. It ensures a consistent, professional, and emoji-free aesthetic for core tools and third-party plugins. + +## Features + +- **Semantic Styling** - Predefined color tokens for consistent visual feedback +- **Layout Components** - Box-drawing based sections, dividers, and footers +- **Progress Tracking** - Standardized step-by-step progress logging +- **Zero Configuration** - Works out of the box with reasonable defaults +- **Universal Branding** - Centralised ASCII logo for consistent brand presence + +## Usage + +```typescript +import { TUI } from '@docmd/tui'; + +TUI.banner(undefined, '0.7.7'); +TUI.section('Building Site'); +TUI.step('Parsing content', 'DONE'); +TUI.footer(); +``` + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/tui/package.json b/packages/tui/package.json new file mode 100644 index 0000000..872c031 --- /dev/null +++ b/packages/tui/package.json @@ -0,0 +1,54 @@ +{ + "name": "@docmd/tui", + "version": "0.8.12", + "description": "Terminal User Interface (TUI) design system for docmd.", + "type": "module", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "scripts": { + "build": "tsc" + }, + "files": [ + "dist" + ], + "engines": { + "node": ">=18" + }, + "dependencies": { + "chalk": "^4.1.2" + }, + "devDependencies": { + "@types/node": "^24.13.3", + "typescript": "^5.9.3" + }, + "keywords": [ + "docmd", + "documentation", + "tui", + "terminal", + "cli", + "design-system", + "chalk", + "docs" + ], + "author": { + "name": "Ghazi", + "url": "https://mgks.dev" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/docmd-io/docmd.git" + }, + "bugs": { + "url": "https://github.com/docmd-io/docmd/issues" + }, + "homepage": "https://docmd.io", + "funding": "https://github.com/sponsors/mgks", + "license": "MIT" +} \ No newline at end of file diff --git a/packages/tui/src/index.ts b/packages/tui/src/index.ts new file mode 100644 index 0000000..520a892 --- /dev/null +++ b/packages/tui/src/index.ts @@ -0,0 +1,448 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/tui + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +import chalk from 'chalk'; +import { readFileSync } from 'node:fs'; + +const pkgUrl = new URL('../package.json', import.meta.url); +const { version: PKG_VERSION } = JSON.parse(readFileSync(pkgUrl, 'utf-8')); + +const LOGO = ` + _ _ + _| |___ ___ _____ _| | + | . | . | _| | . | + |___|___|___|_|_|_|___| +`; + +/* โ”€โ”€ Progress bar โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +const BAR_WIDTH = 20; +const BAR_FULL = 'โ”'; +const BAR_EMPTY = 'โ”€'; + +function renderBar(current: number, total: number): string { + const ratio = total > 0 ? Math.min(current / total, 1) : 0; + const filled = Math.round(ratio * BAR_WIDTH); + const pct = Math.round(ratio * 100); + return `${BAR_FULL.repeat(filled)}${BAR_EMPTY.repeat(BAR_WIDTH - filled)} (${pct}%)`; +} + +/* โ”€โ”€ Spinner โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +const SPINNER_FRAMES = ['โ ‹','โ ™','โ น','โ ธ','โ ผ','โ ด','โ ฆ','โ ง','โ ‡','โ ']; + +/* โ”€โ”€ TTY helpers โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +function isTTY(): boolean { return process.stdout.isTTY === true; } + +function eraseLines(n: number): void { + for (let i = 0; i < n; i++) process.stdout.write('\x1b[1A\x1b[2K'); +} + +/* โ”€โ”€ Duration โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +function formatDuration(ms: number): string { + return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`; +} + +/* โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + * Active-line state machine + * + * Layout while a WAIT step is active: + * + * โ”‚ [ WAIT ] Label text here โ† wait line + * โ”‚ โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” (42%) โ† progress bar โ† _progressLines โ‰ฅ 1 + * โ”‚ โ† breathing room โ† _progressLines = 2 + * + * _waitLine : text of the current WAIT step (null = none active) + * _waitBarColor : chalk colour function used for that step's bar glyph + * _progressLines : how many lines BELOW the wait line are "active" + * 0 = nothing extra 1 = blank only 2 = bar + blank + * โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +let _waitLine: string | null = null; +let _waitBarColor: typeof chalk.cyan = chalk.cyan; +let _progressLines = 0; + +// Section auto-close tracking +let _sectionOpen = false; +let _sectionColor = chalk.cyan; + +/** Erase only the progress area below the wait line. */ +function clearProgressArea(): void { + if (_progressLines > 0 && isTTY()) { + eraseLines(_progressLines); + _progressLines = 0; + } +} + +/** Erase the full active block: progress area + the wait line itself. */ +function clearActiveBlock(): void { + if (!isTTY()) return; + const total = _progressLines + (_waitLine !== null ? 1 : 0); + if (total > 0) eraseLines(total); + _progressLines = 0; + _waitLine = null; +} + +/** Commit any active state before printing structural output (section/footer). */ +function commitState(): void { + clearProgressArea(); + // Leave the wait line on-screen โ€” it will be resolved by its own DONE/FAIL call + _progressLines = 0; +} + +/* โ”€โ”€ Flag helpers โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ */ + +function flag(status: string): string { + switch (status) { + case 'DONE': return chalk.green('[ DONE ]'); + case 'FAIL': return chalk.red ('[ FAIL ]'); + case 'SKIP': return chalk.yellow('[ SKIP ]'); + case 'WAIT': return chalk.blue ('[ WAIT ]'); + default: return chalk.blue (`[ ${status} ]`); + } +} + +/** + * High-Signal Terminal Design System (TUI) + * Standalone package with zero internal dependencies. + * + * Step format โ†’ โ”‚ [ DONE ] Label text flows freely here + * Progress โ†’ โ”‚ โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” (42%) + * Breathing โ†’ โ”‚ + */ +export const TUI = { + // Semantic colors + blue: chalk.blue, + cyan: chalk.cyan, + green: chalk.green, + yellow: chalk.yellow, + red: chalk.red, + dim: chalk.dim, + bold: chalk.bold, + + banner: (logo: string = LOGO, version: string = PKG_VERSION) => { + commitState(); + // N-13 + N-16: respect both the NO_COLOR convention (de-facto + // standard for CLIs) and the explicit `DOCMD_NO_BANNER` env + // (lets users silence the ASCII art while keeping the version line + // if they prefer). The DOCMD_NO_BANNER check is a docmd-specific + // escape hatch since NO_COLOR is a colour convention, not a + // banner convention. + if (process.env.NO_COLOR || process.env.DOCMD_NO_BANNER) return; + console.log(`\n${chalk.blue(logo)}`); + console.log(`${chalk.dim(` v${version}`)}\n`); + }, + + section: (label: string, color = chalk.cyan) => { + commitState(); + // Auto-close any previously open section so callers don't need to + // manually track when to call footer() + if (_sectionOpen) { + console.log(`${_sectionColor('โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€')}`); + } + _sectionColor = color; + _sectionOpen = true; + console.log(`\n${color.bold(`โ”Œโ”€ ${label}`)}`); + }, + + divider: (label: string, color = chalk.blue) => { + commitState(); + console.log(`${color.bold(`โ”œโ”€ ${label}`)}`); + }, + + /** + * Print a status step line. + * + * WAIT โ†’ prints the line + a blank breathing `โ”‚`, tracks state. + * If a WAIT is already active, overwrites in-place (label update). + * DONE/FAIL/SKIP โ†’ erases the WAIT block and replaces with final status line. + * + * `statusFirst` accepted but ignored โ€” left-side flags are always the default. + */ + step: (label: string, status: 'DONE'|'WAIT'|'SKIP'|'FAIL'|string = 'WAIT', barColor = chalk.cyan, _statusFirst?: boolean) => { + const f = flag(status); + const line = `${barColor('โ”‚')} ${f} ${chalk.dim(label)}`; + + if (status === 'WAIT') { + if (isTTY() && _waitLine !== null) { + // Overwrite existing wait line in-place (e.g. count update) + eraseLines(_progressLines + 1); + } else { + clearProgressArea(); + } + console.log(line); + console.log(`${barColor('โ”‚')}`); + _waitLine = label; + _waitBarColor = barColor; + _progressLines = 1; + + } else { + if (isTTY() && _waitLine !== null) { + eraseLines(_progressLines + 1); + } + console.log(line); + _waitLine = null; + _progressLines = 0; + } + }, + + item: (label: string, value: string, labelColor = chalk.dim, barColor = chalk.cyan) => { + commitState(); + console.log(`${barColor('โ”‚')} ${labelColor(label.padEnd(15))} ${value}`); + }, + + /** + * Render a per-plugin tree inside an open section. + * + * โ”‚ [ DONE ] [seo] Generated robots.txt + * โ”‚ โ”œโ”€ [ DONE ] Generated .nojekyll (disables Jekyll on GitHub Pages) + * + * Single-entry plugins collapse to one parent line; warnings and follow-up + * events become indented children. Parent is the first DONE/FAIL entry + * (the main action); when every entry was SKIP, the first entry is used. + * + * Pass an empty `entries` array and the helper is a no-op. + */ + pluginTree: ( + pluginName: string, + entries: Array<{ msg: string; status: 'DONE'|'SKIP'|'FAIL'|'WAIT' }>, + color = chalk.cyan, + ) => { + commitState(); + if (!entries || entries.length === 0) return; + + const bar = color('โ”‚'); + const key = chalk.bold(`[${pluginName}]`).padEnd(8); + + const parentIdx = (() => { + const idx = entries.findIndex(e => e.status === 'DONE' || e.status === 'FAIL'); + return idx === -1 ? 0 : idx; + })(); + + const parent = entries[parentIdx]; + console.log(`${bar} ${flag(parent.status)} ${key} ${chalk.dim(parent.msg)}`); + + if (entries.length === 1) return; + + // Build the children list in original order, skipping the parent. + const childIndices: number[] = []; + for (let i = 0; i < entries.length; i++) { + if (i !== parentIdx) childIndices.push(i); + } + childIndices.forEach((idx, i) => { + const isLast = i === childIndices.length - 1; + const branch = isLast ? 'โ””โ”€' : 'โ”œโ”€'; + const e = entries[idx]; + console.log(`${bar} ${chalk.dim(branch)} ${flag(e.status)} ${chalk.dim(e.msg)}`); + }); + }, + + footer: (color = chalk.cyan) => { + commitState(); + console.log(`${color('โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€')}`); + _sectionOpen = false; + }, + + info: (msg: string) => { + commitState(); + console.log(`\n${chalk.blue.bold('โฌข')} ${msg}`); + }, + + success: (msg: string) => { + commitState(); + console.log(`\n${chalk.green.bold('โฌข')} ${msg}`); + }, + + warn: (msg: string) => { + commitState(); + console.log(`${chalk.yellow.bold('โฌข')} ${chalk.yellow(msg)}`); + }, + + error: (msg: string, detail?: string) => { + commitState(); + console.error(`\n${chalk.red.bold('โ”Œโ”€ Failure')}`); + console.error(`${chalk.red('โ”‚')} ${msg}`); + if (detail) { + detail.split('\n').forEach(l => console.error(`${chalk.red('โ”‚')} ${chalk.dim(l)}`)); + } + console.error(`${chalk.red('โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€')}`); + }, + + // โ”€โ”€ Progress Bar โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + + /** + * Render an in-place progress bar on its own line below the active WAIT step. + * + * โ”‚ [ WAIT ] Processing pages + * โ”‚ โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” (42%) + * โ”‚ + */ + progress: (label: string, current: number, total: number, barColor = chalk.cyan) => { + const bar = renderBar(current, total); + const line = `${barColor('โ”‚')} ${chalk.cyan(bar)}`; + + if (!isTTY()) { + const pct = total > 0 ? Math.round((current / total) * 100) : 0; + if (current >= total || pct === 25 || pct === 50 || pct === 75) { + console.log(line); + } + return; + } + + // Erase the progress area below the wait line (bar + blank) + if (_progressLines > 0) eraseLines(_progressLines); + + process.stdout.write(`${line}\n`); + process.stdout.write(`${barColor('โ”‚')}\n`); + _progressLines = 2; + }, + + // โ”€โ”€ Spinner โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + + /** + * Start an animated spinner in left-flag style. + * + * โ”‚ [ โ ‹ ] Loading config + * โ”‚ + * + * Returns a handle with .done() / .fail() / .update(). + */ + spinner: (label: string, barColor = chalk.cyan) => { + let frameIndex = 0; + let currentLabel = label; + let stopped = false; + + // Print initial WAIT line + breathing room + const waitLine = `${barColor('โ”‚')} ${chalk.blue('[ WAIT ]')} ${chalk.dim(currentLabel)}`; + console.log(waitLine); + console.log(`${barColor('โ”‚')}`); + _waitLine = currentLabel; + _waitBarColor = barColor; + _progressLines = 1; + + const render = () => { + if (stopped || !isTTY()) return; + const frame = chalk.cyan(SPINNER_FRAMES[frameIndex++ % SPINNER_FRAMES.length]); + // Go up past blank + wait line, rewrite wait line with spinner frame + process.stdout.write('\x1b[2A\r\x1b[2K'); + process.stdout.write(`${barColor('โ”‚')} ${chalk.blue('[')} ${frame} ${chalk.blue(']')} ${chalk.dim(currentLabel)}\n`); + process.stdout.write(`${barColor('โ”‚')}\n`); + }; + + const interval = isTTY() ? setInterval(render, 80) : null; + if (interval) interval.unref(); + if (!isTTY()) { + // Non-TTY: static line already printed above + } + + const finish = (status: 'DONE' | 'FAIL', finalLabel?: string) => { + stopped = true; + if (interval) clearInterval(interval); + const fl = finalLabel || currentLabel; + if (isTTY()) eraseLines(_progressLines + 1); + const f = status === 'DONE' ? chalk.green('[ DONE ]') : chalk.red('[ FAIL ]'); + console.log(`${barColor('โ”‚')} ${f} ${chalk.dim(fl)}`); + _waitLine = null; + _progressLines = 0; + }; + + return { + update: (newLabel: string) => { currentLabel = newLabel; }, + done: (doneLabel?: string, _statusFirst?: boolean) => finish('DONE', doneLabel), + fail: (failLabel?: string, _statusFirst?: boolean) => finish('FAIL', failLabel), + }; + }, + + // โ”€โ”€ Counter โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + + counter: (label: string, count: number, barColor = chalk.cyan) => { + const line = `${barColor('โ”‚')} ${chalk.dim(label)} ${chalk.bold(String(count))}`; + if (isTTY()) process.stdout.write(`\r\x1b[K${line}`); + }, + + commitLine: (label: string, barColor = chalk.cyan) => { + commitState(); + console.log(`${barColor('โ”‚')} ${chalk.dim(label)}`); + }, + + // โ”€โ”€ Timer โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + + formatDuration, + + timer: () => { + const start = Date.now(); + return () => formatDuration(Date.now() - start); + }, + + // โ”€โ”€ Centralised Project Summary โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ + + /** + * Print standardised project details within a TUI section. + */ + projectDetails: (opts: { + source?: string; + output?: string; + engine?: string; + versions?: { count: number; labels: string }; + locales?: { count: number; labels: string }; + threads?: number; + barColor?: typeof chalk.cyan; + }) => { + const bc = opts.barColor || chalk.cyan; + if (opts.engine) TUI.item('Engine', opts.engine === 'rust' ? 'rust (preview)' : opts.engine, chalk.dim, bc); + if (opts.source) TUI.item('Source', opts.source, chalk.dim, bc); + if (opts.output) TUI.item('Output', opts.output, chalk.dim, bc); + if (opts.versions) TUI.item('Versions', `${opts.versions.count} (${opts.versions.labels})`, chalk.dim, bc); + if (opts.locales) TUI.item('Locales', `${opts.locales.count} (${opts.locales.labels})`, chalk.dim, bc); + if (opts.threads) TUI.item('Threads', `${opts.threads}`, chalk.dim, bc); + }, + + /** + * Extract standardised project details from a resolved config object. + */ + extractProjectDetails: (config: any, outputDir: string, cwd: string) => { + const details: { + source: string; + output: string; + engine?: string; + versions?: { count: number; labels: string }; + locales?: { count: number; labels: string }; + } = { + source: (config.src || 'docs') + '/', + output: outputDir.startsWith(cwd) ? outputDir.slice(cwd.length + 1) + '/' : outputDir + '/', + }; + + if (config.engine && config.engine !== 'js') { + details.engine = config.engine; + } + + if (config.versions?.all?.length > 0) { + details.versions = { + count: config.versions.all.length, + labels: config.versions.all.map((v: any) => v.id).join(', '), + }; + } + + if (config.i18n?.locales?.length > 0) { + details.locales = { + count: config.i18n.locales.length, + labels: config.i18n.locales.map((l: any) => l.id).join(', '), + }; + } + + return details; + }, +}; \ No newline at end of file diff --git a/packages/tui/tsconfig.json b/packages/tui/tsconfig.json new file mode 100644 index 0000000..9635ce4 --- /dev/null +++ b/packages/tui/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + "strict": false + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} \ No newline at end of file diff --git a/packages/ui/LICENSE b/packages/ui/LICENSE new file mode 100644 index 0000000..997bb73 --- /dev/null +++ b/packages/ui/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025-present docmd.io + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/ui/README.md b/packages/ui/README.md new file mode 100644 index 0000000..ad92329 --- /dev/null +++ b/packages/ui/README.md @@ -0,0 +1,13 @@ +# @docmd/ui + +The visual foundation of docmd - EJS layout templates, core CSS and JavaScript, and SVG icon sets that all official themes build upon. + +Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine. + +## Documentation + +See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference. + +## License + +MIT \ No newline at end of file diff --git a/packages/ui/assets/css/docmd-highlight-dark.css b/packages/ui/assets/css/docmd-highlight-dark.css new file mode 100644 index 0000000..cf3a6a7 --- /dev/null +++ b/packages/ui/assets/css/docmd-highlight-dark.css @@ -0,0 +1,95 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + + pre code.hljs { + display: block; + overflow-x: auto; + padding: 1em +} + +code.hljs { + padding: 3px 5px +} + +.hljs-comment, +.hljs-quote { + color: #5c6370; + font-style: italic +} + +.hljs-doctag, +.hljs-formula, +.hljs-keyword { + color: #c678dd +} + +.hljs-deletion, +.hljs-name, +.hljs-section, +.hljs-selector-tag, +.hljs-subst, +.hljs-operator, +.hljs-punctuation { + color: #c678dd +} + +.hljs-literal { + color: #56b6c2 +} + +.hljs-addition, +.hljs-attribute, +.hljs-meta .hljs-string, +.hljs-regexp, +.hljs-string { + color: #98c379 +} + +.hljs-attr, +.hljs-number, +.hljs-selector-attr, +.hljs-selector-class, +.hljs-selector-pseudo, +.hljs-template-variable, +.hljs-type, +.hljs-variable { + color: #d19a66 +} + +.hljs-bullet, +.hljs-link, +.hljs-meta, +.hljs-selector-id, +.hljs-symbol, +.hljs-title { + color: #61aeee +} + +.hljs-built_in, +.hljs-class .hljs-title, +.hljs-title.class_ { + color: #e6c07b +} + +.hljs-emphasis { + font-style: italic +} + +.hljs-strong { + font-weight: 700 +} + +.hljs-link { + text-decoration: underline +} \ No newline at end of file diff --git a/packages/ui/assets/css/docmd-highlight-light.css b/packages/ui/assets/css/docmd-highlight-light.css new file mode 100644 index 0000000..65473bc --- /dev/null +++ b/packages/ui/assets/css/docmd-highlight-light.css @@ -0,0 +1,95 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + + pre code.hljs { + display: block; + overflow-x: auto; + padding: 1em +} + +code.hljs { + padding: 3px 5px +} + +.hljs-comment, +.hljs-quote { + color: #a0a1a7; + font-style: italic +} + +.hljs-doctag, +.hljs-formula, +.hljs-keyword { + color: #a626a4 +} + +.hljs-deletion, +.hljs-name, +.hljs-section, +.hljs-selector-tag, +.hljs-subst, +.hljs-operator, +.hljs-punctuation { + color: #a626a4 +} + +.hljs-literal { + color: #0184bb +} + +.hljs-addition, +.hljs-attribute, +.hljs-meta .hljs-string, +.hljs-regexp, +.hljs-string { + color: #50a14f +} + +.hljs-attr, +.hljs-number, +.hljs-selector-attr, +.hljs-selector-class, +.hljs-selector-pseudo, +.hljs-template-variable, +.hljs-type, +.hljs-variable { + color: #986801 +} + +.hljs-bullet, +.hljs-link, +.hljs-meta, +.hljs-selector-id, +.hljs-symbol, +.hljs-title { + color: #4078f2 +} + +.hljs-built_in, +.hljs-class .hljs-title, +.hljs-title.class_ { + color: #c18401 +} + +.hljs-emphasis { + font-style: italic +} + +.hljs-strong { + font-weight: 700 +} + +.hljs-link { + text-decoration: underline +} \ No newline at end of file diff --git a/packages/ui/assets/css/docmd-main.css b/packages/ui/assets/css/docmd-main.css new file mode 100644 index 0000000..dd513db --- /dev/null +++ b/packages/ui/assets/css/docmd-main.css @@ -0,0 +1,3825 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +*, +*::before, +*::after { + box-sizing: border-box; +} + +:root { + --bg-color: #ffffff; + --text-color: #1f1f20; + --text-muted: #6b6b75; + --text-heading: #09090b; + --link-color: #068ad5; + --link-color-hover: #0b76b3; + --border-color: #e4e4e7; + --border-color-codeblock: #0a0a0a17; + --border-color-hover: #dedee0; + --header-bg: rgba(255, 255, 255, 0.8); + --header-border: #e4e4e7; + --sidebar-bg: #fafafa; + --sidebar-text: #3f3f46; + --sidebar-link-active-bg: #55bbf91c; + --sidebar-link-active-text: #18181b; + --code-bg: #fafafa; + --code-text: #27272a; + --sponsor-red: #f43f5e; + --font-family-sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; + --font-family-mono: "JetBrains Mono", SFMono-Regular, Consolas, Menlo, monospace; + --font-size-base: 16px; + --line-height-relaxed: 1.625; + --radius-sm: 4px; + --radius-md: 6px; + --radius-lg: 12px; + --radius-xl: 16px; + --shadow-sm: 0 2px 5px -3px #00000026; + --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06); + --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05); + --space-1: 0.25rem; + --space-2: 0.5rem; + --space-3: 0.75rem; + --space-4: 1rem; + --space-6: 1.5rem; + --space-8: 2rem; + --space-12: 3rem; + --ui-element-size: 32px; + --sidebar-width: 260px; + --menubar-h: 44px; + --header-h: 44px; + --scrollbar-thumb: #e4e4e7; + --scrollbar-thumb-hover: #a1a1aa; + --sidebar-group-bg: #3352660d; + --sidebar-group-border: transparent; + color-scheme: light; + --image-shadow: 0 0 10px -3px rgb(0 0 0 / 13%); + --image-border-radius: 12px; + --image-border-color: #ededed; + --glow-color: rgba(6, 138, 213, 0.10); + --glow-color-strong: rgba(6, 138, 213, 0.18); + --halo-soft: 0 0 0 4px rgba(6, 138, 213, 0.10); +} + +:root[data-theme=dark] { + --bg-color: #0d0d0f; + --text-color: #d4d4d8; + --text-muted: #94949e; + --text-heading: #fafafa; + --link-color: #38bdf8; + --border-color: #27272a; + --border-color-codeblock: #fafafa17; + --header-bg: rgb(20 20 22 / 68%); + --header-border: #27272a; + --sidebar-bg: #111113; + --sidebar-text: #d4d4d8; + --sidebar-link-active-bg: #1e1e22; + --sidebar-link-active-text: #ffffff; + --code-bg: #16161a; + --code-text: #e4e4e7; + --sponsor-red: #e11d48; + --scrollbar-thumb: #27272a; + --scrollbar-thumb-hover: #52525b; + --glow-color: rgba(56, 189, 248, 0.18); + --glow-color-strong: rgba(56, 189, 248, 0.28); + --halo-soft: 0 0 0 4px rgba(56, 189, 248, 0.18); + color-scheme: dark; +} + +::-webkit-scrollbar { + width: 6px; + height: 6px; +} + +::-webkit-scrollbar-track { + background: transparent; +} + +::-webkit-scrollbar-thumb { + background-color: var(--scrollbar-thumb); + border-radius: 10px; + +} + +::-webkit-scrollbar-thumb:hover { + background-color: var(--scrollbar-thumb-hover); +} + +::-webkit-scrollbar-thumb:active { + background-color: var(--text-color) !important; +} + +.sidebar::-webkit-scrollbar-thumb, +.toc-list::-webkit-scrollbar-thumb, +.docmd-search-results::-webkit-scrollbar-thumb, +pre::-webkit-scrollbar-thumb, +.table-wrapper::-webkit-scrollbar-thumb { + background-color: transparent; + border-radius: 10px; +} + +.sidebar:hover::-webkit-scrollbar-thumb, +.toc-list:hover::-webkit-scrollbar-thumb, +.docmd-search-results:hover::-webkit-scrollbar-thumb, +pre:hover::-webkit-scrollbar-thumb, +.table-wrapper:hover::-webkit-scrollbar-thumb { + background-color: var(--border-color); +} + +.sidebar, +.toc-list, +.docmd-search-results, +pre, +.table-wrapper { + scrollbar-width: thin; + scrollbar-color: var(--scrollbar-thumb) transparent; + transition: scrollbar-color 0.2s ease; +} + +.sidebar:hover, +.toc-list:hover, +.docmd-search-results:hover, +pre:hover, +.table-wrapper:hover { + scrollbar-color: var(--scrollbar-thumb) transparent; +} + +html { + scrollbar-width: thin; + scrollbar-color: var(--scrollbar-thumb) transparent; + color-scheme: light; +} + +html[data-theme="dark"] { + color-scheme: dark; +} + +html::-webkit-scrollbar-thumb { + background-color: var(--scrollbar-thumb); + border-radius: 10px; +} + +body { + font-family: var(--font-family-sans); + font-size: var(--font-size-base); + background-color: var(--bg-color); + color: var(--text-color); + margin: 0; + min-height: 100vh; + line-height: var(--line-height-relaxed); + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +code, +pre { + font-family: var(--font-family-mono); + font-size: 0.9em; + background-color: var(--code-bg); + border-radius: var(--radius-md); +} + +h1, +h2, +h3, +h4, +h5, +h6 { + font-family: var(--font-family-sans); + color: var(--text-heading); + font-weight: 600; + line-height: 1.25; + margin-top: var(--space-8); + margin-bottom: var(--space-4); +} + +h1 { + font-size: 2.25rem; + font-weight: 800; + letter-spacing: -0.025em; + margin-top: 0; +} + +h2 { + font-size: 1.875rem; + border-bottom: 1px solid var(--border-color); + padding-bottom: var(--space-2); +} + +h3 { + font-size: 1.5rem; +} + +h4 { + font-size: 1.25rem; +} + +h5 { + font-size: 1.125rem; +} + +h6 { + font-size: 1rem; +} + +a { + color: var(--link-color); + text-decoration: none; +} + +a:hover { + color: var(--link-color-hover); + +} + +a:any-link { + text-decoration: none; +} + +.skip-link { + position: absolute; + top: -100px; + left: 0; + background: var(--bg-color); + color: var(--link-color); + padding: 8px; + z-index: 9999; +} + +.skip-link:focus { + top: 0; +} + +.sidebar { + display: flex; + flex-direction: column; + width: var(--sidebar-width); + background-color: var(--sidebar-bg); + color: var(--sidebar-text); + border-right: 1px solid var(--border-color); + height: 100vh; + position: fixed; + top: 0; + left: 0; + overflow: visible; + box-sizing: border-box; + flex-shrink: 0; + z-index: 100; + transition: transform 0.3s ease, visibility 0.3s ease; +} + +.sidebar h1 { + font-size: 1.25rem; + font-weight: 700; + padding: var(--space-2); +} + +.sidebar nav ul { + list-style: none; + padding: 0; + margin: 0 +} + +.sidebar nav li a, +.sidebar nav li .nav-label { + display: flex; + align-items: center; + padding: var(--space-2) var(--space-3); + text-decoration: none; + color: var(--sidebar-text); + border-radius: var(--radius-md); + font-size: 0.875rem; + line-height: 1.4; + font-weight: 500; + +} + +.sidebar nav li.nav-group { + border-radius: 6px; + +} + +.sidebar nav li.collapsible { + cursor: pointer; +} + +.sidebar nav li>a { + position: relative; +} + +.sidebar nav li>a.active { + color: var(--link-color); + font-weight: 600; + background-color: var(--sidebar-link-active-bg); + +} + +/* Modern "node on thread" active indicator. + A small pill that sits at the link's left edge, centered vertically, + overlapping the .submenu thread border used by .active-parent. + The result reads as the active link's own marker on the existing + rail, not a thick bar grafted onto the item. */ +.sidebar nav li>a.active::before { + content: ""; + position: absolute; + left: -10px; + top: 50%; + transform: translateY(-50%); + width: 3px; + height: 55%; + min-height: 14px; + background-color: var(--link-color); + border-radius: 2px; + +} + +.sidebar nav li.active-parent>a { + color: var(--link-color); + font-weight: 600; + background-color: transparent; +} + +.sidebar nav li.active-parent>a::before { + content: ""; + position: absolute; + left: 0; + top: 5px; + bottom: 5px; + /* width: 3px; */ + opacity: 1; + +} + +.sidebar nav li .nav-label { + font-weight: 600; + +} + +.sidebar nav .submenu { + display: none; + padding-left: .25em; + border-left: 1px solid var(--link-color); + margin-left: .85em; +} + +.sidebar nav li[aria-expanded="true"]>.submenu, +.sidebar nav li.expanded>.submenu { + display: block !important; +} + +.collapse-icon { + transition: transform 0.2s ease; +} + +.sidebar nav li[aria-expanded="true"]>a .collapse-icon, +.sidebar nav li.expanded>a .collapse-icon, +.sidebar nav li[aria-expanded="true"]>.nav-label .collapse-icon, +.sidebar nav li.expanded>.nav-label .collapse-icon { + transform: rotate(90deg); +} + +.collapse-icon-wrapper { + display: inline-flex; + margin-left: auto; + align-items: center; + justify-content: center; + cursor: pointer; +} + +span.collapse-icon-wrapper .collapse-icon { + margin: 0; + vertical-align: 0; + height: 1.5em; +} + +.copy-code-button:hover, +.docmd-tabs-nav-item:hover, +.sidebar nav li a.active, +.sidebar nav li a:hover, +.theme-toggle-button:hover { + color: var(--text-color); + +} + +.sidebar nav li a.active { + font-weight: 600; + color: var(--link-color) + +} + +.copy-code-button:hover, +.code-wrapper:hover>.copy-code-button { + opacity: .8; +} + +.docmd-code-block-header.has-copy-button>.copy-code-button, +.docmd-code-block-header.has-copy-button:hover>.copy-code-button { + opacity: 1; +} + +.sidebar-toggle-button { + position: absolute; + left: -1rem; + top: 50%; + transform: translateY(-50%); + background-color: var(--bg-color); + border: 1px solid var(--border-color); + color: var(--text-muted); + cursor: pointer; + width: 2rem; + height: 2rem; + border-radius: 50%; + display: none; + align-items: center; + justify-content: center; + box-shadow: var(--shadow-sm); + transition: left 0.3s ease, background-color 0.2s ease, border-color 0.2s ease, color 0.2s ease; + z-index: 200; +} + +.sidebar-toggle-button:hover { + color: var(--text-color); + border-color: var(--border-color-hover); + box-shadow: var(--shadow-md); +} + +.sidebar-toggle-button .lucide-icon { + width: 1.1rem; + height: 1.1rem; + color: currentColor; + transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1); +} + +body.sidebar-collapsed .sidebar-toggle-button .lucide-icon { + transform: rotate(180deg); +} + +body.sidebar-collapsible .sidebar-toggle-button { + display: inline-flex; +} + +body.sidebar-collapsed .sidebar-toggle-button { + justify-content: right; + padding: 0; +} + +body.sidebar-collapsible .header-titles-wrapper { + transition: margin-left 0.3s ease; +} + +.docmd-container.steps-reset .docmd-container.steps-reset ol.steps-list>li.step-item::before, +.docmd-container.steps-reset ol.steps-list>li.step-item::before, +.docmd-container.steps-reset ol.steps-list[start]>li.step-item::before { + content: counter(list-counter) "."; + font-weight: 700; + margin-right: .5em; + color: var(--accent-color, #007acc) +} + +.docmd-tab-pane.active, +.logo-link img, +.logo-link img.logo-light, +.tab-panel.active, +.theme-toggle-button .icon-sun, +html[data-theme=dark] .logo-link img.logo-dark, +html[data-theme=dark] .theme-toggle-button .icon-moon, +img { + display: block +} + +.docmd-heading { + position: relative; + display: flex; + align-items: center; + scroll-margin-top: calc(var(--sticky-top-offset) + var(--space-8)); +} + +.heading-anchor { + position: absolute; + left: calc(-1 * var(--space-8)); + width: var(--space-6); + height: var(--space-6); + display: inline-flex; + align-items: center; + justify-content: center; + color: var(--text-muted); + opacity: 0; + transition: all 0.2s ease; + text-decoration: none !important; +} + +.heading-anchor svg { + width: 1.25rem; + height: 1.25rem; +} + +.docmd-heading:hover .heading-anchor, +.heading-anchor:focus { + opacity: 1; +} + +.heading-anchor:hover { + color: var(--link-color); +} + +.toc-level-1 { + margin-left: 0; + font-weight: 600; +} + +.toc-level-2 { + margin-left: 0; +} + +.main-content-wrapper { + margin-left: var(--sidebar-width); + flex-grow: 1; + display: flex; + flex-direction: column; + min-width: 0; + min-height: 100vh; + transition: margin-left 0.3s ease; +} + +.header-left, +.header-right, +.page-header { + align-items: center; + display: flex +} + +.page-header { + justify-content: space-between; + padding: var(--space-2) var(--space-3); + background-color: var(--header-bg); + border-bottom: 1px solid var(--header-border); + position: sticky; + top: var(--header-top-offset); + z-index: 50; + backdrop-filter: blur(8px); + -webkit-backdrop-filter: blur(8px); + gap: 0.5rem +} + +@media (min-width: 769px) { + body.sidebar-collapsible .page-header { + z-index: 150; + } +} + +.header-titles-wrapper { + display: flex; + flex-direction: column; + justify-content: center; +} + +.docmd-breadcrumbs-row { + display: flex; + align-items: center; + justify-content: space-between; + margin-bottom: var(--space-4); + gap: 1rem; + flex-wrap: wrap; +} + +.docmd-breadcrumbs-spacer { + flex-grow: 1; +} + +.docmd-copy-widgets { + display: inline-flex; + align-items: center; + gap: 0; + border-radius: var(--radius-md); + background-color: var(--code-bg); + border: 1px solid var(--border-color); + overflow: hidden; + box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.02); +} + +.docmd-copy-btn { + display: inline-flex; + align-items: center; + gap: 0.35rem; + padding: 0.35rem 0.65rem; + font-size: 0.775rem; + font-weight: 500; + color: var(--text-muted); + background-color: transparent; + border: none; + border-radius: 0; + cursor: pointer; + transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1); + line-height: 1; + height: 28px; + box-sizing: border-box; +} + +.docmd-copy-raw-btn { + border-right: 1px solid var(--border-color); +} + +.docmd-copy-btn:hover { + background-color: var(--sidebar-link-active-bg); + color: var(--text-color); +} + +.docmd-copy-btn .docmd-btn-icon svg { + width: 13px; + height: 13px; + display: block; +} + +.docmd-copy-btn.copied { + background-color: rgba(34, 197, 94, 0.1) !important; + color: #22c55e !important; +} + +.docmd-breadcrumbs { + font-size: 0.8125rem; + color: var(--text-muted); + display: block; +} + +.docmd-breadcrumbs ol { + list-style: none; + padding: 0; + margin: 0; + display: flex; + align-items: center; + flex-wrap: wrap; + gap: 0.25rem; +} + +.docmd-breadcrumbs li { + display: inline-flex; + align-items: center; + white-space: nowrap; +} + +.docmd-breadcrumbs a { + color: var(--text-muted); + text-decoration: none; + transition: color 0.15s ease; +} + +.docmd-breadcrumbs a:hover { + color: var(--link-color); +} + +.docmd-breadcrumbs .breadcrumb-separator { + margin-left: 0.25rem; + opacity: 0.5; + display: inline-flex; + align-items: center; +} + +.docmd-breadcrumbs .breadcrumb-separator .lucide-icon { + width: 0.8em; + height: 0.8em; +} + +.docmd-breadcrumbs .active { + color: var(--text-color); + font-weight: 500; +} + +.page-header .header-title { + font-size: 1.25rem; + font-weight: 600; + color: var(--text-heading); + margin: 0; +} + +.header-left { + gap: var(--space-4); + margin-left: 1rem +} + +.header-right { + gap: var(--space-2); + margin-right: 1rem; +} + +:root { + --menubar-h: 44px; + --header-h: 44px; + + --fixed-top-offset: 0px; + --header-top-offset: 0px; + --sticky-top-offset: 0px; + + --menubar-bg: var(--bg-color); + --menubar-border: var(--border-color); + --menubar-text: var(--text-color); + --menubar-link-hover-bg: var(--sidebar-link-active-bg); +} + +body.has-menubar-top { + --fixed-top-offset: var(--menubar-h); + --header-top-offset: var(--menubar-h); + --sticky-top-offset: var(--menubar-h); + padding-top: var(--menubar-h); +} + +body:not(.no-header) { + --sticky-top-offset: var(--header-h); +} + +body.has-menubar-top:not(.no-header) { + --sticky-top-offset: calc(var(--menubar-h) + var(--header-h)); +} + +body.has-menubar-header { + --header-top-offset: var(--menubar-h); + --sticky-top-offset: var(--menubar-h); +} + +body.has-menubar-header:not(.no-header) { + --sticky-top-offset: calc(var(--menubar-h) + var(--header-h)); +} + +html { + scroll-padding-top: calc(var(--sticky-top-offset) + 1.5rem); +} + +.docmd-menubar { + z-index: 200; + height: var(--menubar-h); + background-color: var(--menubar-bg); + border-bottom: 1px solid var(--menubar-border); + backdrop-filter: blur(8px); + -webkit-backdrop-filter: blur(8px); + width: 100%; + box-sizing: border-box; +} + +.menubar-options { + margin-left: 0.5rem; + padding-left: 0.5rem; + border-left: 1px solid var(--menubar-border); + display: flex; + align-items: center; +} + +body.has-menubar-top .docmd-menubar { + position: fixed; + top: 0; + left: 0; + right: 0; +} + +body.has-menubar-header .docmd-menubar { + position: sticky; + top: 0; + z-index: 250; +} + +.menubar-inner { + display: flex; + align-items: center; + justify-content: space-between; + height: 100%; + padding: 0 var(--space-6); + gap: var(--space-4); +} + +.menubar-left, +.menubar-right { + display: flex; + align-items: center; + gap: var(--space-1); + flex-shrink: 0; +} + +.menubar-brand { + display: inline-flex; + align-items: center; + gap: var(--space-2); + text-decoration: none; + color: var(--text-heading); + font-weight: 700; + font-size: 1rem; + padding: var(--space-1) var(--space-2); + border-radius: var(--radius-md); +} + +.menubar-brand:hover { + opacity: 0.8; + text-decoration: none; +} + +.menubar-brand-text { + white-space: nowrap; +} + +.menubar-link { + display: inline-flex; + align-items: center; + gap: var(--space-1); + padding: var(--space-1) var(--space-3); + border-radius: var(--radius-md); + font-size: 0.875rem; + color: var(--menubar-text); + text-decoration: none; + white-space: nowrap; +} + +.menubar-link:hover { + background-color: var(--menubar-link-hover-bg); + color: var(--text-heading); + text-decoration: none; +} + +.menubar-icon { + width: 1.1em; + height: 1.1em; + flex-shrink: 0; +} + +.menubar-ext-icon { + width: 0.75em; + height: 0.75em; + opacity: 0.6; + flex-shrink: 0; +} + +.menubar-dropdown { + position: relative; +} + +.menubar-dropdown-toggle { + display: inline-flex; + align-items: center; + gap: var(--space-1); + padding: var(--space-1) var(--space-3); + border-radius: var(--radius-md); + font-size: 0.875rem; + color: var(--menubar-text); + background: none; + border: none; + cursor: pointer; + font-family: inherit; + white-space: nowrap; +} + +.menubar-dropdown-toggle:hover { + background-color: var(--menubar-link-hover-bg); + color: var(--text-heading); +} + +.menubar-chevron { + width: 0.85em; + height: 0.85em; + opacity: 0.7; +} + +.menubar-dropdown:hover .menubar-chevron, +.menubar-dropdown:focus-within .menubar-chevron { + transform: rotate(180deg); +} + +.menubar-dropdown-menu { + position: absolute; + top: calc(100% + 6px); + left: 0; + min-width: 180px; + margin: 0; + padding: 0.25rem; + list-style: none; + background-color: var(--bg-color); + border: 1px solid var(--border-color); + border-radius: var(--radius-md); + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08), 0 2px 4px rgba(0, 0, 0, 0.05); + z-index: 300; + opacity: 0; + visibility: hidden; + transform: translateY(-4px); +} + +.menubar-dropdown-menu.menubar-dropdown-right { + left: auto; + right: 0; +} + +.menubar-dropdown:hover .menubar-dropdown-menu, +.menubar-dropdown:focus-within .menubar-dropdown-menu { + opacity: 1; + visibility: visible; + transform: translateY(0); +} + +.menubar-dropdown-menu li a { + display: flex; + align-items: center; + gap: 0.5rem; + padding: 0.4rem 0.6rem; + font-size: 0.875rem; + color: var(--text-color); + text-decoration: none; + border-radius: 4px; +} + +.menubar-dropdown-menu li a:hover { + background-color: var(--sidebar-link-active-bg); + color: var(--text-heading); +} + +.sidebar { + top: var(--fixed-top-offset); + height: calc(100vh - var(--fixed-top-offset)); +} + +.toc-sidebar { + position: sticky; + top: calc(var(--sticky-top-offset) + 2rem); + width: 240px; + flex-shrink: 0; + margin: 1em 0; + max-height: calc(100vh - var(--sticky-top-offset) - 4rem); + overflow-y: auto; + scrollbar-width: thin; + align-self: flex-start +} + +.docmd-options-menu { + display: flex; + align-items: center; + justify-content: center; + gap: 0.5rem; +} + +.docmd-options-menu .theme-toggle-button, +.docmd-options-menu .sponsor-link-button, +.docmd-options-menu .docmd-search-trigger { + display: inline-flex; + align-items: center; + justify-content: center; + height: var(--ui-element-size); + padding: 0; + background-color: transparent; + border: 1px solid var(--border-color); + border-radius: var(--radius-md); + color: var(--text-muted); + cursor: pointer; + transition: all 0.2s ease; + box-sizing: border-box; + +} + +.docmd-options-menu .theme-toggle-button, +.docmd-options-menu .sponsor-link-button { + width: var(--ui-element-size); +} + +.docmd-options-menu .sponsor-link-button { + color: var(--sponsor-red); + border-color: var(--border-color); +} + +.docmd-options-menu .sponsor-link-button:hover { + background-color: var(--sponsor-red); + color: white; + border-color: var(--sponsor-red); +} + +.docmd-options-menu .docmd-search-trigger { + width: auto; + padding: 0 0.75rem; + gap: 0.5rem; + +} + +.docmd-options-menu button:hover:not(.sponsor-link-button) { + color: var(--text-heading); + border-color: var(--border-color-hover); + +} + +.docmd-search-trigger .search-label { + font-size: 0.85rem; + font-weight: 500; +} + +.docmd-search-trigger .search-keys { + display: flex; + gap: 0.25rem; +} + +.docmd-kbd { + background-color: var(--bg-color); + border: 1px solid var(--border-color); + border-radius: 4px; + font-family: var(--font-family-mono); + font-size: 0.7rem; + padding: 0.1rem 0.3rem; + box-shadow: 0 1px 1px rgba(0, 0, 0, 0.05); + color: var(--text-muted); +} + +.docmd-options-menu .lucide-icon { + width: 1.1rem; + height: 1.1rem; +} + +.sidebar-options-wrapper { + padding: .25rem 0; +} + +.sidebar-options-wrapper.mt-auto { + margin-top: auto; + padding: .5rem 0 0; + border-top: 1px solid var(--border-color); +} + +.sidebar-top-group, +.sidebar-bottom-group.mt-auto { + display: flex; + flex-wrap: wrap; + align-items: center; + justify-content: center; + gap: 0.25rem; + padding: 0.25rem; + position: relative; +} + +.sidebar-top-group:empty { + display: none; +} + +.sidebar-bottom-group.mt-auto { + margin-top: auto; +} + +.sidebar-bottom-group:empty { + display: none; +} + +.docmd-version-dropdown, +.docmd-language-switcher, +.docmd-project-switcher { + width: auto; + position: relative; +} + +.docmd-language-switcher { + margin-top: 0; +} + +.docmd-embed { + margin: 1.5rem auto; + border-radius: var(--docmd-radius-lg, 12px); + max-width: 100%; + display: block; +} + +iframe.docmd-embed { + width: 100%; + aspect-ratio: 16 / 9; + border: none !important; +} + +iframe.docmd-embed[data-short="true"] { + aspect-ratio: 9 / 16; + max-width: 400px; +} + +blockquote.docmd-embed { + width: 100%; + border: none !important; + display: flex; + justify-content: center; +} + +.docmd-embed-fallback { + margin: 1.5rem 0; + display: flex; +} + +.version-dropdown-toggle, +.language-switcher-toggle, +.project-switcher-toggle { + display: inline-flex; + align-items: center; + gap: 0.3rem; + height: 1.75rem; + padding: 0 0.65rem; + background-color: var(--bg-color); + border: 1px solid var(--border-color); + border-radius: 999px; + color: var(--text-heading); + font-size: 0.75rem; + font-weight: 500; + cursor: pointer; + transition: all 0.2s ease; + white-space: nowrap; + box-sizing: border-box; +} + +.version-dropdown-toggle:hover, +.language-switcher-toggle:hover, +.project-switcher-toggle:hover { + border-color: var(--text-muted); +} + +.version-dropdown-menu, +.language-switcher-menu, +.project-switcher-menu { + position: absolute; + top: calc(100% + 6px); + left: 50%; + transform: translateX(-50%) translateY(-5px); + min-width: max-content; + max-width: calc(var(--sidebar-width, 260px) - 1.5rem); + margin: 0; + padding: 0.35rem; + background-color: var(--bg-color); + border: 1px solid var(--border-color); + border-radius: var(--radius-md); + box-shadow: var(--shadow-md); + list-style: none; + z-index: 100; + opacity: 0; + visibility: hidden; + transition: all 0.2s ease; +} + +.docmd-version-dropdown.open .version-dropdown-menu, +.docmd-language-switcher.open .language-switcher-menu, +.docmd-project-switcher.open .project-switcher-menu { + opacity: 1; + visibility: visible; + transform: translateX(-50%) translateY(0); +} + +.version-dropdown-item, +.language-switcher-item, +.project-switcher-item { + display: flex; + align-items: center; + justify-content: space-between; + gap: 0.5rem; + padding: 0.4rem 0.6rem; + color: var(--text-color); + font-size: 0.85rem; + text-decoration: none; + border-radius: var(--radius-sm); + transition: background-color 0.2s; + margin: 0.25em; +} + +.project-switcher-item, +.version-dropdown-item, +.language-switcher-item { + white-space: nowrap; +} + +.version-dropdown-item:hover, +.language-switcher-item:hover, +.project-switcher-item:hover { + background-color: var(--sidebar-link-active-bg); + color: var(--text-heading); + text-decoration: none; +} + +.version-dropdown-item.active, +.language-switcher-item.active, +.project-switcher-item.active { + font-weight: 600; + color: var(--link-color); + background-color: var(--sidebar-link-active-bg); +} + +.version-check, +.language-check, +.project-check { + width: 1rem; + height: 1rem; +} + +.version-chevron, +.language-chevron { + width: 0.75rem; + height: 0.75rem; + transition: transform 0.2s ease; +} + +.docmd-version-dropdown.open .version-chevron, +.docmd-language-switcher.open .language-chevron { + transform: rotate(180deg); +} + +.sidebar-bottom-group .version-dropdown-menu, +.sidebar-bottom-group .language-switcher-menu, +.sidebar-bottom-group .project-switcher-menu { + top: auto; + bottom: calc(100% + 4px); + transform: translateX(-50%) translateY(5px); +} + +.sidebar-bottom-group .docmd-version-dropdown.open .version-dropdown-menu, +.sidebar-bottom-group .docmd-language-switcher.open .language-switcher-menu, +.sidebar-bottom-group .docmd-project-switcher.open .project-switcher-menu { + transform: translateX(-50%) translateY(0); +} + +.sidebar-bottom-group .version-dropdown-toggle .version-chevron, +.sidebar-bottom-group .language-switcher-toggle .language-chevron, +.sidebar-bottom-group .project-switcher-toggle .project-chevron { + transform: rotate(180deg); +} + +.version-latest-badge { + font-size: 0.6rem; + padding: 0.05rem 0.3rem; + border-radius: 3px; + background-color: var(--link-color); + color: #fff; + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.02em; + margin-left: 0.15rem; +} + +.language-icon { + width: 0.8rem; + height: 0.8rem; + flex-shrink: 0; +} + +.language-label { + text-align: left; +} + +.language-switcher-item.disabled { + opacity: 0.45; + cursor: not-allowed; + pointer-events: none; +} + +.language-unavailable-badge { + font-size: 0.65rem; + padding: 0.1rem 0.35rem; + border-radius: 3px; + background-color: var(--border-color); + color: var(--text-muted); + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.02em; +} + +.language-compact { + width: auto; + margin-top: 0; +} + +.language-compact .language-switcher-toggle { + display: inline-flex; + align-items: center; + justify-content: center; + width: var(--ui-element-size); + height: var(--ui-element-size); + padding: 0; + background-color: transparent; + border: 1px solid var(--border-color); + border-radius: var(--radius-md); + color: var(--text-muted); + cursor: pointer; + transition: all 0.2s ease; + box-sizing: border-box; +} + +.language-compact .language-switcher-toggle:hover { + background-color: var(--sidebar-link-active-bg); + color: var(--text-heading); + border-color: var(--border-color-hover); +} + +.language-compact .language-icon { + width: 1.1rem; + height: 1.1rem; +} + +.language-compact .language-switcher-menu { + min-width: 140px; + left: auto; + right: 0; + transform: translateY(-5px); +} + +.language-compact.open .language-switcher-menu { + transform: translateY(0); +} + +.options-menu-language { + position: relative; + display: inline-flex; +} + +.card .card-title { + border-bottom: 1px solid var(--border-color) +} + +.content-theme-cover { + display: flex; + flex-direction: column; + flex-grow: 1; +} + +.content-area { + padding: 1rem 1em 1em 2.75rem; + max-width: 1200px; + margin: 0 auto; + width: 100%; + box-sizing: border-box; + flex-grow: 1; + position: relative; + display: flex; + flex-direction: column; +} + +:root[data-theme=dark] .content-area::before { + content: ""; + position: absolute; + top: 0px; + left: 50%; + transform: translate(-100%, -50%); + width: 100%; + height: 50%; + background: radial-gradient(rgba(12, 138, 213, 0.05) 30%, transparent 70%); + pointer-events: none; + z-index: 0; +} + +pre { + color: var(--code-text); + padding: var(--space-4); + overflow-x: auto; + position: relative; + margin: var(--space-2) 0; + background-color: var(--code-bg); + border: 1px solid var(--border-color-codeblock); + border-radius: var(--radius-lg); + box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + white-space: pre; + line-height: 1.5; + font-size: .85em; +} + +.docmd-code-block-wrapper { + margin: var(--space-6) 0; + border: 1px solid var(--border-color-codeblock); + border-radius: var(--radius-xl); + overflow: hidden; + box-shadow: var(--shadow-sm); + background-color: var(--code-bg); + position: relative; +} + +.docmd-code-block-wrapper pre { + margin: 0; + border: none; + border-radius: 0; + box-shadow: none; +} + +.docmd-code-block-header { + display: flex; + align-items: center; + padding: var(--space-2) var(--space-4); + background-color: rgba(0, 0, 0, 0.04); + border-bottom: 1px solid var(--border-color-codeblock); + position: relative; +} + +.docmd-code-block-header.has-copy-button { + padding-right: 2.75rem; +} + +:root[data-theme=dark] .docmd-code-block-header { + background-color: rgba(255, 255, 255, 0.04); +} + +.docmd-code-block-title { + font-size: 0.85rem; + font-weight: 500; + color: var(--text-color); + font-family: var(--font-family-sans); +} + +pre code { + background-color: transparent; + padding: 0; + font-size: inherit; + border-radius: 0; + border: none; +} + +.table-wrapper { + display: block; + width: 100%; + overflow-x: auto; + margin: var(--space-6) 0; + border-radius: var(--radius-lg); + border: 1px solid var(--border-color); + box-shadow: var(--shadow-sm); +} + +table { + width: 100%; + border-collapse: collapse; + margin: 0; +} + +th { + text-align: left; + font-weight: 600; + padding: var(--space-2) var(--space-4); + border-bottom: 1px solid var(--border-color); + background-color: var(--sidebar-bg); + color: var(--text-heading); + white-space: nowrap; +} + +td { + padding: var(--space-3) var(--space-4); + border-bottom: 1px solid var(--border-color); + color: var(--text-color); +} + +tr:last-child td { + border-bottom: none; +} + +tr:hover td { + background-color: var(--sidebar-link-active-bg); +} + +.sidebar-header { + flex-shrink: 0; + text-align: center; + padding: .5rem +} + +.sidebar-header h1 { + display: inline-block; + font-size: 1.5em; + margin: 0; + padding: 0 +} + +.logo-link img { + max-height: 2.5rem; + width: auto; + margin: 0 auto +} + +.docmd-tab-pane, +.logo-link img.logo-dark, +.tab-panel, +.theme-toggle-button .icon-moon, +html[data-theme=dark] .logo-link img.logo-light, +html[data-theme=dark] .theme-toggle-button .icon-sun { + display: none +} + +.sidebar-nav { + flex-grow: 1; + overflow-y: auto; + overflow-x: hidden; + min-height: 0; + scrollbar-width: thin; +} + +.sidebar-nav li.collapsible>.nav-label:hover { + color: var(--text-color); + +} + +.sidebar-nav .lucide-icon { + width: 1em; + height: 1em; + margin-right: .5em; + vertical-align: -.15em; + stroke-width: 2 +} + +.sidebar-nav .nav-external-icon { + width: 1em; + height: 1.5em; + float: right; + margin-left: auto; + opacity: .5; + display: inline-flex +} + +.next-page, +.prev-page, +.step::before { + color: var(--link-color); + display: flex +} + +.callout .callout-content> :first-child, +.card .card-content> :first-child, +.step-content> :first-child, +.step-title { + margin-top: 0; +} + +.theme-toggle-button .lucide-icon { + width: 1.2em; + height: 1.2em +} + +.docmd-container { + padding: var(--space-4) var(--space-6); + margin: var(--space-2) 0; + border-radius: var(--radius-lg); + border: 1px solid var(--border-color); + background-color: var(--bg-color); + box-shadow: var(--shadow-sm); + overflow: hidden; +} + +.callout { + border: .25px solid color-mix(in srgb, var(--callout-color, transparent) 100%, transparent); + background-color: color-mix(in srgb, var(--callout-color, var(--code-bg)) 8%, transparent); + +} + +.callout-info { --callout-color: #3498db; } +.callout-warning {--callout-color: #f39c12;} +.callout-success, +.callout-tip { + --callout-color: #2ecc71; + +} +.callout-danger { --callout-color: #e74c3c; } + +.callout-title { + font-weight: 700; + margin-bottom: var(--space-2); + display: flex; + align-items: center; + gap: var(--space-2); +} + +.card { + transition: transform 0.18s cubic-bezier(0.4, 0, 0.2, 1), + box-shadow 0.18s cubic-bezier(0.4, 0, 0.2, 1), + border-color 0.18s ease; + will-change: transform; +} + +.card:hover { + transform: translateY(-1px); + border-color: color-mix(in srgb, var(--link-color) 25%, var(--border-color)); +} + +.card .card-title { + font-weight: 600; + font-size: 0.95rem; + margin: calc(-1 * var(--space-4)) calc(-1 * var(--space-6)) var(--space-3); + padding: var(--space-2) var(--space-4); + background-color: var(--sidebar-bg); + border-bottom: 1px solid var(--border-color); + letter-spacing: 0.005em; + min-height: 2.75em; +} + +.docmd-container.steps { + position: relative; + border: none; + background: transparent; + box-shadow: none; +} + +.step { + position: relative; + padding-bottom: 2rem; +} + +.step:last-child { + padding-bottom: 0; +} + +.step::before { + content: attr(data-step); + position: absolute; + left: -3rem; + top: 0; + width: 2rem; + height: 2rem; + background-color: var(--bg-color); + border: 2px solid var(--border-color); + border-radius: 50%; + display: inline-flex; + align-items: center; + justify-content: center; + font-size: 0.875rem; + font-weight: 600; + color: var(--link-color); + z-index: 1; + box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05); + transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1); +} + +.step:hover::before { + border-color: var(--link-color); + box-shadow: 0 0 0 4px rgba(6, 138, 213, 0.15); +} + +.step-title { + font-size: 1.125rem; + font-weight: 600; + margin-bottom: 0.5rem; + color: var(--text-heading); +} + +.docmd-container.steps-reset { + counter-reset: step-counter 0; +} + +.docmd-container.steps-reset ol.steps-list { + position: relative; + padding-left: 2.5rem; + list-style: none !important; + margin: 1.5rem 0; + counter-reset: list-counter 0; +} + +.docmd-container.steps-reset ol.steps-list::before { + content: ""; + position: absolute; + top: 0.75rem; + bottom: 0.75rem; + left: 0.83rem; + width: 2px; + background: linear-gradient(to bottom, var(--border-color) 0%, var(--border-color) 80%, transparent 100%); + z-index: 0; +} + +.docmd-container.steps-reset ol.steps-list>li.step-item { + counter-increment: list-counter 1; + position: relative; + padding-left: 0.5rem; + margin-bottom: 2rem; + list-style: none !important; +} + +.docmd-container.steps-reset ol.steps-list>li.step-item:last-child { + margin-bottom: 0; +} + +.docmd-container.steps-reset ol.steps-list>li.step-item::before { + content: counter(list-counter) !important; + position: absolute; + left: -2.5rem; + top: 0.15rem; + width: 1.75rem; + height: 1.75rem; + background-color: var(--bg-color); + border: 2px solid var(--border-color); + border-radius: 50%; + display: inline-flex; + align-items: center; + justify-content: center; + font-size: 0.8rem; + font-weight: 600; + color: var(--link-color); + z-index: 1; + box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05); + transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1); + margin-right: 0 !important; +} + +.docmd-container.steps-reset ol.steps-list>li.step-item:hover::before { + border-color: var(--link-color); + box-shadow: 0 0 0 4px var(--glow-color); +} + +.docmd-container.steps-reset ol.steps-list>li.step-item .step-permalink, +.docmd-container.changelog-timeline .changelog-permalink { + position: absolute; + display: inline-flex; + align-items: center; + justify-content: center; + opacity: 0; + text-decoration: none !important; + border-radius: var(--radius-md); + transition: opacity 0.15s ease, color 0.15s ease, background-color 0.15s ease; +} + +.docmd-container.steps-reset ol.steps-list>li.step-item .step-permalink svg, +.docmd-container.changelog-timeline .changelog-permalink svg { + width: 0.85em; + height: 0.85em; +} + +.docmd-container.steps-reset ol.steps-list>li.step-item:hover .step-permalink, +.docmd-container.steps-reset ol.steps-list>li.step-item .step-permalink:focus-visible, +.docmd-container.changelog-timeline .changelog-entry:hover .changelog-permalink, +.docmd-container.changelog-timeline .changelog-permalink:focus-visible { + opacity: 1; +} + +.docmd-container.steps-reset ol.steps-list>li.step-item .step-permalink:hover, +.docmd-container.steps-reset ol.steps-list>li.step-item .step-permalink:focus-visible, +.docmd-container.changelog-timeline .changelog-permalink:hover, +.docmd-container.changelog-timeline .changelog-permalink:focus-visible { + color: var(--link-color); + background-color: var(--sidebar-bg); +} + +.docmd-container.steps-reset ol.steps-list>li.step-item .step-permalink { + right: -0.5rem; + width: 1.5rem; + height: 1.5rem; + color: var(--text-muted); + z-index: 2; +} + +.docmd-container.changelog-timeline .changelog-permalink { + right: 0rem; + top: .85em; + transform: translateY(-50%); + width: 1rem; + height: 1rem; + color: currentColor; + border-radius: var(--radius-sm); +} + +.docmd-container.steps-reset ol.steps-list>li.step-item { + scroll-margin-top: calc(var(--header-h, 44px) + var(--menubar-h, 44px) + var(--space-6)); +} + +.docmd-container.steps-reset .docmd-container.steps-reset ol.steps-list, +.docmd-container.steps-reset ol.steps-list[start] { + counter-reset: list-counter 0; +} + +.docmd-container.steps-reset .docmd-container.steps-reset ol.steps-list>li.step-item, +.docmd-container.steps-reset ol.steps-list[start]>li.step-item { + counter-increment: list-counter 1; +} + +.docmd-container.steps-reset ol:not(.steps-list)::before, +.docmd-container.steps-reset ol:not(.steps-list)>li::before, +.docmd-container.steps-reset ul::before, +.docmd-container.steps-reset ul>li::before { + width: .75rem; + height: .75rem; + left: -1.5rem; + top: .5rem; + content: "" !important +} + +.mermaid { + margin: var(--space-6) 0; + text-align: center; +} + +.docmd-mermaid-container { + position: relative; + margin: var(--space-6) 0; + padding: var(--space-6) var(--space-4); + border: 1px solid var(--border-color-codeblock); + border-radius: var(--radius-xl); + box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + background-color: var(--bg-color); +} + +.mermaid-wrapper { + position: relative; + overflow: hidden; + cursor: grab; +} + +.mermaid-wrapper:active { + cursor: grabbing; +} + +.mermaid-controls { + position: absolute; + bottom: 16px; + right: 16px; + display: flex; + flex-direction: column; + align-items: flex-end; + gap: 4px; + z-index: 10; + opacity: 0; + transition: opacity 0.2s ease; +} + +.mermaid-wrapper:hover .mermaid-controls, +.mermaid-wrapper.mermaid-fullscreen .mermaid-controls { + opacity: 1; +} + +.mermaid-wrapper.mermaid-fullscreen { + background-color: var(--bg-color); + display: flex; + align-items: center; + justify-content: center; + max-height: none; +} + +.docmd-mermaid-container svg { + max-width: none; + display: block; + margin: 0 auto; +} + +.mermaid-error { + color: #e74c3c; + padding: 1rem; + margin: 0; + background-color: #e74c3c12; + border-left-width: 4px; + border-left-style: solid; + border-left-color: #e74c3c; + border-radius: 4px; + font-size: .9rem +} + +pre.mermaid { + background-color: transparent; + padding: 0; + margin: 0; + border: medium; + display: none +} + +.docmd-container.collapsible { + padding: 0; + background-color: var(--card-bg, var(--bg-color)); + border: 1px solid var(--border-color); + border-radius: var(--radius-lg); + overflow: hidden; + margin-bottom: 1.5rem; + transition: border-color .2s +} + +.docmd-container.collapsible[open] { + border-color: var(--link-color) +} + +.collapsible-summary { + list-style: none; + padding: .5rem 1rem; + cursor: pointer; + display: flex; + align-items: center; + justify-content: space-between; + font-weight: 600; + background-color: var(--sidebar-bg); + transition: background-color .2s +} + +.collapsible-summary:hover { + background-color: var(--sidebar-link-active-bg) +} + +.collapsible-summary::-webkit-details-marker { + display: none +} + +.collapsible-arrow svg { + width: 1.2em; + height: 1.2em; + transition: transform .2s; + opacity: .7 +} + +details[open]>.collapsible-summary .collapsible-arrow svg { + transform: rotate(180deg) +} + +.collapsible-content { + padding: .5rem 1rem; + border-top: 1px solid var(--border-color) +} + +.docmd-container.changelog-timeline { + border: none; + background: transparent; + margin-top: 2rem; + box-shadow: none; + position: relative; +} + +.docmd-container.changelog-timeline::before { + content: ""; + position: absolute; + top: 0.5rem; + bottom: 2rem; + left: var(--space-6); + width: 2px; + background: linear-gradient(to bottom, transparent 0%, var(--border-color) 3%, var(--border-color) 90%, transparent 100%); + pointer-events: none; + z-index: 0; +} + +.changelog-entry { + position: relative; + padding-left: 28px; + margin-bottom: 1rem; + display: block; +} + +.changelog-entry::after { + content: ""; + position: absolute; + left: -3px; + top: 0.6rem; + width: 8px; + height: 8px; + background-color: var(--bg-color); + border: 2px solid var(--border-color); + border-radius: 50%; + z-index: 2; + transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1); +} + +.changelog-entry:hover::after { + transform: scale(1.4); + border-color: var(--link-color); + background-color: var(--link-color); + box-shadow: 0 0 0 4px rgba(6, 138, 213, 0.15); +} + +.changelog-meta { + display: block; + text-align: left; + margin-bottom: 0.6rem; + padding-top: 0; +} + +.changelog-date { + display: inline-block; + background-color: var(--sidebar-link-active-bg); + color: var(--link-color); + padding: 3px 12px; + border-radius: 8px; + font-size: 0.75rem; + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.03em; + position: relative; +} + +.changelog-body { + border-left: none; + padding-left: 0; + padding-bottom: 0.5rem; +} + +.changelog-body> :first-child { + margin-top: 0; +} + +:focus-visible { + outline: 2px solid var(--link-color); + outline-offset: 2px; + border-radius: 4px; + transition: box-shadow 0.15s ease; +} + +:focus:not(:focus-visible) { + outline: none !important; + box-shadow: none !important; +} + +.sidebar nav li a:focus-visible { + background-color: var(--sidebar-link-active-bg); + outline: 2px solid var(--link-color); + outline-offset: -2px +} + +.theme-toggle-button:focus-visible { + border-color: var(--link-color); + box-shadow: 0 0 0 2px var(--link-color) +} + +a, +button, +.toc-link, +.sidebar nav li a, +.copy-code-button, +.docmd-tabs-nav-item, +.theme-toggle-button, +.docmd-button, +.docmd-tag { + transition: color 0.15s ease, background-color 0.15s ease, + border-color 0.15s ease, transform 0.15s ease, + box-shadow 0.15s ease, opacity 0.15s ease; +} + +.page-footer { + border-top: 1px solid var(--border-color) + +} + +.page-navigation { + display: flex; + justify-content: space-between; + margin-top: auto; + padding-top: 1.5rem +} + +.next-page, +.prev-page { + align-items: center; + text-decoration: none; + padding: .75rem 1em; + border-radius: var(--radius-lg); + transition: background-color .2s; + min-width: 50%; + overflow: hidden; + max-width: 48%; + text-overflow: ellipsis; +} + +.next-page:hover, +.prev-page:hover { + background-color: var(--menubar-link-hover-bg); + text-decoration: none +} + +:root[data-theme=dark] .next-page:hover, +:root[data-theme=dark] .prev-page:hover { + background-color: #ffffff0d +} + +.prev-page { + justify-content: flex-start +} + +.next-page { + justify-content: flex-end; + text-align: right +} + +.next-page-placeholder, +.prev-page-placeholder { + width: 48% +} + +.next-page span, +.prev-page span { + display: flex; + flex-direction: column +} + +.next-page small, +.prev-page small { + font-size: .8rem; + opacity: .8; + margin-bottom: .25rem +} + +.next-page > span, +.prev-page > span { + min-width: 0; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap +} + +.next-page > span > strong, +.prev-page > span > strong { + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap +} + +.next-page strong, +.prev-page strong { + font-weight: 500 +} + +.page-nav-icon { + width: 1.2rem; + height: 1.2rem +} + +.prev-page .page-nav-icon { + margin-right: .75rem +} + +.next-page .page-nav-icon { + margin-left: .75rem +} + +.content-layout { + display: flex; + gap: 2rem; + width: 100%; + align-items: stretch; + flex: 1 0 auto; + min-height: 0 +} + +.main-content { + flex: 1 1 0; + width: 100%; + min-width: 0; + display: flex; + flex-direction: column; +} + +.toc-container { + margin: 0; + padding: 0; + border: medium; + background-color: transparent +} + +.docmd-container figure img, +.toc-title { + margin-bottom: .5rem +} + +.toc-list { + scrollbar-width: thin; + list-style: none; + padding: .5em .25em; + margin: 0; + overflow-y: visible +} + +.toc-item { + margin-bottom: .25rem; + line-height: 1.4 +} + +.toc-link { + display: block; + padding: .3rem .75rem; + font-size: .85rem; + font-weight: 500; + text-decoration: none; + border-left: 2px solid transparent; + margin-left: .25em; + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + border-radius: 0 var(--radius-sm) var(--radius-sm) 0; + transition: color 0.15s ease, background-color 0.15s ease, border-color 0.15s ease; +} + +.toc-link:hover { + color: var(--text-heading); + background-color: var(--sidebar-bg); +} + +.toc-link.active { + color: var(--link-color); + border-left-color: var(--link-color); + background-color: color-mix(in srgb, var(--link-color) 8%, transparent); + font-weight: 600; +} + +.toc-level-3 { + padding-left: 2rem +} + +.toc-level-4 { + padding-left: 3rem +} + +.toc-title { + font-size: .85em; + display: contents; + text-transform: uppercase; + margin: 0; + cursor: pointer; + border-bottom-width: 0; + border-bottom-style: none; + border-bottom-color: currentcolor; + padding-bottom: 0 +} + +.docmd-tabs, +img { + margin: 1.5rem 0 +} + +img { + max-width: 100%; + height: auto +} + +img.align-left { + float: left; + margin-right: 1.5rem; + margin-bottom: 1rem +} + +img.align-center { + margin-left: auto; + margin-right: auto +} + +img.align-right { + float: right; + margin-left: 1.5rem; + margin-bottom: 1rem +} + +img.size-small { + max-width: 300px +} + +img.size-medium { + max-width: 500px +} + +img.size-large { + max-width: 800px +} + +img.with-border { + border: 1px solid var(--image-border-color); + border-radius: var(--image-border-radius); +} + +img.with-shadow { + box-shadow: var(--image-shadow) +} + +.docmd-container figure { + margin: 2rem 0 +} + +.docmd-container figcaption { + font-size: .9rem; + color: var(--image-caption-text); + text-align: center; + padding: .5rem; + background-color: var(--image-caption-bg); + border-radius: 0 0 4px 4px +} + +.docmd-container .image-gallery { + display: grid; + grid-template-columns: repeat(auto-fill, minmax(250px, 1fr)); + gap: 1rem; + margin: 2rem 0 +} + +.docmd-container .image-gallery figure { + margin: 0 +} + +.docmd-container .clear-float::after { + content: ""; + display: table; + clear: both +} + +.docmd-tabs { + border: 1px solid var(--border-color); + border-radius: 6px; + overflow: hidden; + box-shadow: #0000000d 0 1px 3px +} + +.docmd-tabs-nav { + display: flex; + background-color: var(--sidebar-bg); + border-bottom: 1px solid var(--border-color); + overflow: auto hidden +} + +.docmd-tabs-nav-item { + padding: .5rem 1.25rem; + cursor: pointer; + border-bottom-width: 3px; + border-bottom-style: solid; + border-bottom-color: transparent; + margin-bottom: -1px; + font-weight: 500; + color: var(--sidebar-text); + white-space: nowrap; + display: flex; + align-items: center; + gap: 8px; +} + +.tab-icon { + width: 1.1em; + height: 1.1em; + flex-shrink: 0; + stroke-width: 2px +} + +.docmd-tabs-nav-item.active { + color: var(--link-color); + border-bottom-color: var(--link-color); + background-color: var(--bg-color) +} + +.docmd-tabs-content { + padding: var(--space-6); + +} + +.tabs-container { + margin: 1rem 0; + border: 1px solid #e1e5e9; + border-radius: .375rem +} + +.tab-navigation { + display: flex; + background-color: #f8f9fa; + border-bottom-width: 1px; + border-bottom-style: solid; + border-bottom-color: #e1e5e9; + border-radius: .375rem .375rem 0 0 +} + +.tab-button { + padding: .75rem 1rem; + border-width: medium medium 2px; + border-style: none none solid; + border-color: currentcolor currentcolor transparent; + border-image: none; + background: 0 0; + cursor: pointer; + transition: .2s +} + +.tab-button:hover { + background-color: #e9ecef +} + +.tab-button.active { + border-bottom-color: #007bff; + background-color: #fff +} + +.tab-content { + padding: 1rem +} + +.docmd-lightbox { + display: none; + position: fixed; + top: 0; + left: 0; + width: 100%; + height: 100%; + background-color: var(--lightbox-bg); + z-index: 9999; + justify-content: center; + align-items: center; + flex-direction: column +} + +.copy-code-button svg { + width: 1rem; + height: 1rem +} + +.docmd-lightbox-content { + position: relative; + max-width: 90%; + max-height: 90%; + text-align: center +} + +.docmd-lightbox-content img { + max-width: 100%; + max-height: 80vh; + object-fit: contain; + margin: 0 auto; + box-shadow: #0000004d 0 0 20px +} + +.docmd-lightbox-caption { + color: var(--lightbox-text); + padding: 1rem; + font-size: 1rem; + max-width: 100% +} + +.docmd-lightbox-close { + position: absolute; + top: 20px; + right: 30px; + color: var(--lightbox-text); + font-size: 2.5rem; + cursor: pointer; + z-index: 10000 +} + +.docmd-lightbox-close:hover { + color: #ddd +} + +a.docmd-button { + color: #fff; + text-decoration: none +} + +.docmd-container .image-gallery img, +img.lightbox { + cursor: zoom-in +} + +.docmd-button { + display: inline-flex; + align-items: center; + gap: 0.45rem; + padding: .6rem 1.2rem; + margin: .5rem .5em .5em 0; + border-radius: var(--radius-md); + background-color: var(--link-color); + font-weight: 500; + transition: background-color .15s ease, transform .15s ease, box-shadow .15s ease, filter .15s ease; + border: medium; + cursor: pointer; + width: fit-content; +} + +.docmd-button:hover { + text-decoration: none; + filter: brightness(1.05); + transform: translateY(-1px); + box-shadow: 0 4px 12px -2px var(--glow-color-strong); +} + +.docmd-button:active { + transform: translateY(0); + box-shadow: none; +} + +.docmd-button .button-icon { + width: 1em; + height: 1em; + flex-shrink: 0; + vertical-align: middle; +} + +.docmd-tag { + display: inline-flex; + align-items: center; + padding: 0 0.5em; + border-radius: var(--radius-xl); + font-size: .85em; + font-weight: 500; + background-color: var(--docmd-surface); + color: var(--docmd-text); + vertical-align: middle; + margin: 0 0.2em; + transition: all 0.2s; +} + +a.docmd-tag-link .docmd-tag:hover { + filter: brightness(1.1); + transform: translateY(-1px); +} + +.docmd-tag .tag-icon { + display: inline-block; + margin-right: 5px; +} + +.callout-title { + display: flex; + align-items: center; + gap: 0.4rem; +} + +.callout-icon-heading, +.card-icon-heading, +.collapsible-icon-heading { + width: 1.1em; + height: 1.1em; + flex-shrink: 0; + vertical-align: middle; +} + +.card-title { + display: flex; + align-items: center; + gap: 0.4rem; +} + +.copy-code-button { + position: absolute; + top: .85rem; + right: .5rem; + padding: .5rem; + background-color: transparent; + border: 0; + border-radius: 6px; + cursor: pointer; + opacity: 0; + transition: opacity .15s ease-in-out, background-color .15s ease, color .15s ease; + color: var(--sidebar-text); + display: flex; + align-items: center; + justify-content: center; + z-index: 10; + pointer-events: auto +} + +.copy-code-button.copied { + color: #10b981; + opacity: 1 +} + +.docmd-code-block-header.has-copy-button>.copy-code-button { + top: 50%; + right: var(--space-2); + transform: translateY(-50%); + margin: 0; +} + +hr { + border-top: 1px solid var(--border-color); + border-bottom: 0; + border-left: 0; + border-right: 0; + margin: 1em; +} + +.edit-link { + display: inline-flex; + align-items: center; + gap: .5rem; + color: var(--text-light); + text-decoration: none; +} + +.edit-link:hover { + color: var(--link-color) +} + +.edit-link svg { + width: 1em; + height: 1em +} + +.docmd-search-modal { + position: fixed; + inset: 0; + background-color: #00000080; + z-index: 1000; + display: flex; + justify-content: center; + align-items: flex-start; + padding-top: 10vh +} + +.docmd-search-box { + width: 100%; + max-width: 600px; + background-color: var(--bg-color); + border: 1px solid var(--border-color); + border-radius: var(--radius-xl); + box-shadow: var(--shadow-lg); + display: flex; + flex-direction: column; + overflow: hidden; + animation: .2s ease-out searchSlideIn +} + +@keyframes searchSlideIn { + 0% { + opacity: 0; + transform: scale(.98) translateY(10px) + } + + 100% { + opacity: 1; + transform: scale(1) translateY(0) + } +} + +.docmd-search-header { + display: flex; + align-items: center; + padding: 1rem 1.5rem; + border-bottom: 1px solid var(--border-color); + gap: 1rem +} + +.docmd-search-header svg { + color: var(--link-color) +} + +#docmd-search-input { + flex: 1 1 0; + border: medium; + background: 0 0; + font-size: 1.1rem; + color: var(--text-color); + outline: currentcolor +} + +.docmd-search-close { + background: 0 0; + border: 0; + cursor: pointer; + padding: 0; + display: flex; + font-size: 1.25em +} + +.docmd-search-results { + max-height: 60vh; + overflow-y: auto; + padding: .5rem +} + +.search-result-item { + display: block; + padding: .75rem 1rem; + border-radius: 6px; + text-decoration: none; + color: var(--text-color); + margin-bottom: 2px; + border-left-width: 3px; + border-left-style: solid; + border-left-color: transparent +} + +.search-result-item.selected, +.search-result-item:focus, +.search-result-item:hover { + background-color: var(--sidebar-bg); + border-left-color: var(--link-color); + text-decoration: none; + cursor: pointer +} + +.search-result-title { + display: flex; + align-items: center; + gap: 0.4rem; + font-weight: 600; + font-size: .95rem; + margin-bottom: .2rem; + color: var(--link-color) +} + +.search-result-version { + flex-shrink: 0; + font-size: 0.6rem; + font-weight: 600; + padding: 0.1rem 0.4rem; + border-radius: 999px; + text-transform: uppercase; + letter-spacing: 0.03em; + white-space: nowrap; + line-height: 1.4; +} + +.search-result-meta { + display: flex; + align-items: center; + gap: 0.35rem; + margin-left: auto; + flex-shrink: 0; +} + +.search-result-confidence { + font-size: 0.6875rem; + font-weight: 600; + padding: 0.1rem 0.45rem; + border-radius: 999px; + white-space: nowrap; + line-height: 1.4; + background: var(--docmd-accent-soft, rgba(59, 130, 246, 0.08)); + color: var(--docmd-accent, #3b82f6); +} + +.search-result-confidence.confidence-high { + background: rgba(22, 163, 74, 0.08); + color: var(--docmd-green, #16a34a); +} + +.search-result-preview { + font-size: .8rem; + color: var(--text-muted, #666); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis +} + +.search-error, +.search-no-results { + padding: 2rem; + text-align: center; + color: var(--text-muted, #666) +} + +.search-error, +.search-initial, +.search-no-results { + padding: 3rem 2rem 5em; + text-align: center; + color: var(--text-muted, #666); + font-size: .95rem +} + +.search-result-preview mark { + background-color: #ffeb3b66; + color: inherit; + padding: 0 2px; + border-radius: 2px +} + +:root[data-theme=dark] .search-result-preview mark { + background-color: #ffeb3b40; + color: #fff +} + +.docmd-search-footer { + padding: .75rem 1.5rem; + background-color: var(--sidebar-bg); + border-top: 1px solid var(--border-color); + font-size: .75rem; + color: var(--text-muted, #888); + display: flex; + gap: 1rem; + justify-content: flex-end +} + +.sidebar-menu-button { + font-size: 1.5em +} + +.mobile-view { + display: none; + cursor: pointer +} + +.float-left { + float: left +} + +.float-right { + float: right +} + +.footer-complete { + background-color: var(--sidebar-bg); + border-top: 1px solid var(--border-color); + padding: 2.5rem; + margin-top: auto; +} + +.footer-complete-top { + display: flex; + justify-content: space-between; + align-items: flex-start; + flex-wrap: wrap; + gap: 3rem; + max-width: 1200px; + margin: 0 auto 4rem auto; +} + +.footer-brand { + flex: 1 1 300px; + max-width: 400px; + text-align: left; +} + +.footer-brand .logo-link { + display: block; + overflow: hidden; + margin: 0 0 1rem 0; + width: fit-content; +} + +.footer-brand .logo-link img { + max-height: 28px; + width: auto; +} + +.footer-columns { + display: flex; + flex-wrap: wrap; + gap: 4rem; + justify-content: flex-end; + flex: 2 1 auto; +} + +.footer-column { + min-width: 140px; +} + +.footer-title { + font-size: 1.25rem; + font-weight: 600; + color: var(--text-heading); +} + +.footer-desc { + color: var(--text-muted); + font-size: 0.875rem; + line-height: 1.5; + margin-top: 0.75rem; + opacity: 0.9; +} + +.footer-column-title { + display: block; + font-size: 0.75rem; + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.08em; + color: var(--text-muted); + margin-bottom: 1.25rem; +} + +.footer-column ul { + list-style: none; + padding: 0; + margin: 0; +} + +.footer-column ul li { + margin-bottom: 0.75rem; +} + +.footer-column ul a { + color: var(--text-muted); + text-decoration: none; + font-size: 0.875rem; + transition: color 0.2s ease; +} + +.footer-column ul a:hover { + color: var(--link-color); +} + +.footer-complete-bottom { + max-width: 1200px; + margin: 0 auto; + padding-top: 2rem; + border-top: 1px solid var(--border-color); + display: flex; + justify-content: space-between; + align-items: center; + font-size: 0.875rem; + color: var(--text-muted); +} + +.page-footer { + text-align: center; + padding: 20px 30px; + margin-top: auto; + font-size: .9em; + color: var(--text-color); + background-color: var(--sidebar-bg) +} + +.footer-content { + display: flex; + justify-content: space-between; + align-items: center; + margin: 0 auto; + width: 100% +} + +.user-footer { + text-align: left +} + +.branding-footer { + text-align: right; + opacity: .9; + font-weight: 500 +} + +.branding-footer svg { + color: #fb3a3a +} + +.branding-footer a, +.page-footer a { + color: var(--link-color); + text-decoration: none +} + +.page-footer-actions { + margin-top: 1.5rem; + padding: 1.5rem .5em .75em; + border-top: 1px solid var(--border-color); + display: flex; + justify-content: flex-end; + gap: 1rem; + font-size: .875rem +} + +@media (max-width: 1024px) { + .content-layout { + display: flex; + flex-direction: column-reverse; + gap: 0 + } + + .toc-sidebar { + width: 100%; + max-height: initial; + position: static + } + + .toc-container { + background-color: var(--sidebar-bg); + border: 1px solid var(--border-color); + border-radius: 6px; + height: 2.25em; + overflow: hidden + } + + .toc-container .toc-title { + padding: .5rem 1rem; + display: block + } + + .toc-container .mobile-view { + display: inline-flex; + padding: .15rem 0 + } + + .mobile-expanded { + height: auto !important; + overflow: auto + } + + .toc-container.mobile-expanded .toc-list { + height: auto; + max-height: auto + } + + .toc-menu-button svg { + transition: transform .3s + } + + .toc-container.mobile-expanded .toc-menu-button svg { + transform: rotate(180deg) + } +} + +@media (max-width: 768px) { + body { + flex-direction: column + } + + .sidebar { + width: 100%; + height: 3rem; + position: relative; + top: 0; + border-right-width: medium; + border-right-style: none; + border-right-color: currentcolor; + border-bottom: 1px solid var(--border-color); + z-index: 100 + } + + .sidebar-header { + border-bottom-width: 0; + border-bottom-style: none; + border-bottom-color: currentcolor; + padding-bottom: 0; + margin-bottom: 0; + text-align: left; + box-shadow: none; + } + + .sidebar-menu-button { + font-size: 1.5em + } + + .sidebar #theme-toggle-button, + .sidebar-nav, + .sidebar-top-group, + .sidebar-bottom-group { + max-height: 0; + display: none; + opacity: 0; + transition: max-height .3s ease-out, opacity .3s ease-out, margin .3s; + margin-top: 0 + } + + .sidebar.mobile-expanded #theme-toggle-button, + .sidebar.mobile-expanded .sidebar-nav { + max-height: initial; + opacity: 1; + display: block + } + + + + .sidebar.mobile-expanded .sidebar-top-group, + .sidebar.mobile-expanded .sidebar-bottom-group { + max-height: initial; + opacity: 1; + display: flex + } + + .sidebar-toggle-button { + display: none !important + } + + .logo-link img { + float: left + } + + .mobile-view { + display: inline-flex; + padding: 4px + } + + .main-content-wrapper { + margin-left: 0 + } + + .page-navigation { + flex-direction: column; + gap: 1rem + } + + .next-page, + .next-page-placeholder, + .prev-page, + .prev-page-placeholder { + width: 100%; + max-width: 100% + } + + img.align-left, + img.align-right { + float: none; + margin-left: auto; + margin-right: auto + } + + .docmd-container .image-gallery { + grid-template-columns: 1fr + } + + .docmd-search-modal { + padding-top: 0; + background-color: var(--bg-color); + align-items: flex-start + } + + .docmd-search-box { + max-width: 100%; + height: 100%; + border-radius: 0; + border: medium; + box-shadow: none + } + + .docmd-search-header { + padding: 1rem + } + + #docmd-search-input { + font-size: 1rem + } + + .docmd-search-footer { + display: none + } + + .docmd-search-results { + max-height: none; + flex: 1 1 0 + } + + .changelog-entry { + grid-template-columns: 1fr; + gap: 1rem + } + + .changelog-entry::after { + display: none !important; + } + + .docmd-container.changelog-timeline::before { + display: none !important; + } + + .changelog-meta { + text-align: left; + padding-top: 0 + } + + body.has-menubar-top .docmd-menubar, + body.has-menubar-header .docmd-menubar { + position: sticky !important; + top: 0 !important; + left: 0 !important; + right: 0 !important; + width: 100% !important; + box-shadow: none; + z-index: 250 !important; + } + + body.has-menubar-top .page-header, + body.has-menubar-header .page-header { + position: relative !important; + top: auto !important; + } + + .heading-anchor { + position: static; + margin-right: var(--space-2); + opacity: 1; + color: var(--border-color); + } + + .content-area { + padding: var(--space-4); + } + + .docmd-breadcrumbs { + display: none; + } + + .docmd-menubar { + padding: 0; + } + + .menubar-brand-text { + display: none; + } + + .menubar-inner { + padding: 0 var(--space-3); + gap: var(--space-2); + } + + .menubar-link, + .menubar-dropdown-toggle { + padding: 0.25rem 0.5rem; + font-size: 0.8125rem; + } + + .header-left, + .header-right { + margin-left: 0; + margin-right: 0; + } + + .search-keys, + .search-label { + display: none + } + + .footer-complete-top { + flex-direction: column; + gap: 2rem; + text-align: center; + } + + .footer-brand { + max-width: 100%; + margin: 0 auto; + text-align: center; + flex: 1; + } + + .footer-brand .logo-link { + margin: 0 auto + } + + .footer-columns { + justify-content: center; + gap: 2rem; + width: 100%; + } + + .footer-column { + width: 100%; + } + + .footer-complete-bottom { + flex-direction: column; + gap: 1rem; + text-align: center; + } + + .footer-content, + .page-navigation { + flex-direction: column; + gap: 1rem + } + + .branding-footer, + .user-footer { + text-align: center + } +} + +.sidebar nav li { + margin: .25em; +} + +.callout-content p { + margin: 0; +} + +.edit-link:hover { + text-decoration: underline; +} + +code { + padding: .15em .5em; +} + +.docmd-container.grids { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); + gap: var(--space-4); + margin: var(--space-4) 0; + width: 100%; + border: 0; + box-shadow: none; + padding: 0; +} + +.docmd-container.grid-item { + display: flex; + flex-direction: column; + width: 100%; + gap: var(--space-4); + min-width: 0; + background: transparent; + padding: var(--space-1); + border: 0; + box-shadow: none; + margin-bottom: 0; +} + +.grids .grid-item .card { + height: stretch; +} + +ul.contains-task-list { + list-style: none !important; + padding-left: 0.5em; +} + +ul.contains-task-list>li::marker { + content: none !important; + display: none !important; +} + +.task-list-item-checkbox { + margin-top: .25em; +} + +.docmd-hero { + position: relative; + width: 100%; + margin: var(--space-12) 0; + padding: var(--space-12) 0; + display: flex; + flex-direction: column; +} + +.docmd-hero.hero-glow::before { + content: ''; + position: absolute; + top: 50%; + left: 50%; + transform: translate(-50%, -50%); + width: 80%; + height: 80%; + background: radial-gradient(circle, var(--link-color) 0%, transparent 70%); + opacity: 0.08; + filter: blur(100px); + z-index: -1; + pointer-events: none; +} + +.docmd-hero.hero-banner { + text-align: center; + align-items: center; +} + +.docmd-hero.hero-banner .hero-content { + max-width: 800px; +} + +.docmd-hero.hero-split { + display: flex; + flex-direction: row; + align-items: center; + gap: var(--space-12); + text-align: left; +} + +.docmd-hero.hero-split .hero-content { + flex: 1 1 0; + min-width: 0; +} + +.docmd-hero.hero-split .hero-side { + flex: 1 1 0; + min-width: 0; + display: flex; + justify-content: center; + align-items: center; +} + +.docmd-hero.hero-slider { + overflow: hidden; + position: relative; +} + +.hero-slider-track { + display: flex; + scroll-snap-type: x mandatory; + overflow-x: auto; + scrollbar-width: none; + -ms-overflow-style: none; + scroll-behavior: smooth; +} + +.hero-slider-track::-webkit-scrollbar { + display: none; +} + +.hero-slide { + flex: 0 0 100%; + scroll-snap-align: start; + padding: var(--space-8) var(--space-4); + box-sizing: border-box; + text-align: center; +} + +.hero-slider-controls { + display: flex; + justify-content: center; + align-items: center; + gap: var(--space-3); + margin-top: var(--space-6); +} + +.hero-slider-btn { + background: var(--bg-secondary); + border: 1px solid var(--border-color); + color: var(--text-primary); + width: 36px; + height: 36px; + border-radius: 50%; + cursor: pointer; + display: flex; + align-items: center; + justify-content: center; + transition: background 0.2s, border-color 0.2s; + flex-shrink: 0; +} + +.hero-slider-btn:hover { + background: var(--link-color); + border-color: var(--link-color); + color: #fff; +} + +.hero-slider-dots { + display: flex; + gap: var(--space-2); + align-items: center; +} + +.hero-slider-dot { + width: 8px; + height: 8px; + border-radius: 50%; + background: var(--border-color); + cursor: pointer; + transition: background 0.2s, transform 0.2s; + border: none; + padding: 0; +} + +.hero-slider-dot.active { + background: var(--link-color); + transform: scale(1.3); +} + +.hero-content h1 { + font-size: clamp(2.5rem, 8vw, 4.5rem); + font-weight: 900; + line-height: .95; + letter-spacing: -0.05em; + margin-bottom: var(--space-4); +} + +.hero-content p { + font-size: clamp(1.1rem, 2.5vw, 1.4rem); + color: var(--text-muted); + line-height: 1.4; + margin-bottom: var(--space-6); +} + +.hero-side img, +.hero-side video, +.hero-side .docmd-embed { + width: 100%; + border-radius: var(--radius-xl); + box-shadow: var(--shadow-lg); +} + +@media (max-width: 960px) { + .docmd-hero.hero-split { + flex-direction: column; + text-align: center; + gap: var(--space-8); + } + + .hero-content h1 { + font-size: 3rem; + } +} + +.project-icon { + width: 0.9rem; + height: 0.9rem; + color: var(--link-color); +} + +.project-label { + max-width: 120px; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.project-chevron { + width: 0.75rem; + height: 0.75rem; + opacity: 0.5; +} + +.project-prefix { + font-size: 0.75rem; + opacity: 0.5; + line-height: 1em +} + +.project-compact { + width: auto; + margin-top: 0; +} + +.project-compact .project-switcher-toggle { + display: inline-flex; + align-items: center; + justify-content: center; + width: var(--ui-element-size); + height: var(--ui-element-size); + padding: 0; + background-color: transparent; + border: 1px solid var(--border-color); + border-radius: var(--radius-md); + color: var(--text-muted); + cursor: pointer; + transition: all 0.2s ease; + box-sizing: border-box; +} + +.project-compact .project-switcher-toggle:hover { + background-color: var(--sidebar-link-active-bg); + color: var(--text-heading); + border-color: var(--border-color-hover); +} + +.project-compact .project-icon { + width: 1.1rem; + height: 1.1rem; +} + +.project-compact .project-switcher-menu { + min-width: 180px; + left: auto; + right: 0; + transform: translateY(-5px); +} + +.project-compact.open .project-switcher-menu { + transform: translateY(0); +} + +.options-menu-project-switcher { + position: relative; + display: inline-flex; +} + +@media (min-width: 769px) { + body.sidebar-collapsed .sidebar { + transform: translateX(-100%); + visibility: hidden; + } + + body.sidebar-collapsed .main-content-wrapper { + margin-left: 0; + } +} + +.docmd-banner { + width: 100%; + border-bottom: 1px solid var(--border-color, rgba(0, 0, 0, 0.08)); + font-size: 0.9rem; + line-height: 1.5; + background-color: var(--bg-color, #fff); + color: var(--text-color, #1f2937); +} + +.docmd-banner--info { + background-color: color-mix(in srgb, var(--accent-color, #3b82f6) 8%, var(--bg-color, #fff)); + border-bottom-color: color-mix(in srgb, var(--accent-color, #3b82f6) 20%, transparent); +} + +.docmd-banner--success { + background-color: color-mix(in srgb, #10b981 8%, var(--bg-color, #fff)); + border-bottom-color: color-mix(in srgb, #10b981 20%, transparent); +} + +.docmd-banner--warning { + background-color: color-mix(in srgb, #f59e0b 10%, var(--bg-color, #fff)); + border-bottom-color: color-mix(in srgb, #f59e0b 25%, transparent); +} + +.docmd-banner--danger { + background-color: color-mix(in srgb, #ef4444 8%, var(--bg-color, #fff)); + border-bottom-color: color-mix(in srgb, #ef4444 20%, transparent); +} + +.docmd-banner__inner { + max-width: var(--content-max-width, 1400px); + margin: 0 auto; + padding: 0.65rem 1.25rem; + display: flex; + align-items: center; + gap: 0.75rem; + flex-wrap: wrap; +} + +.docmd-banner__icon { + display: inline-flex; + align-items: center; + flex-shrink: 0; + color: var(--text-heading, inherit); +} + +.docmd-banner__icon svg { + width: 1.1em; + height: 1.1em; +} + +.docmd-banner__content { + display: flex; + align-items: center; + gap: 0.75rem; + flex: 1 1 auto; + flex-wrap: wrap; + min-width: 0; +} + +.docmd-banner__text { + word-break: break-word; +} + +.docmd-banner__text code { + font-size: 0.85em; + padding: 0.05em 0.3em; + background-color: rgba(0, 0, 0, 0.05); + border-radius: 4px; +} + +.docmd-banner__link { + display: inline-flex; + align-items: center; + gap: 0.25rem; + font-weight: 500; + text-decoration: none; + color: inherit; + border-bottom: 1px solid currentColor; + padding-bottom: 1px; + white-space: nowrap; +} + +.docmd-banner__link:hover { + opacity: 0.85; +} + +.docmd-banner__link-icon { + width: 0.95em; + height: 0.95em; +} + +.docmd-banner__close { + flex-shrink: 0; + display: inline-flex; + align-items: center; + justify-content: center; + width: 1.5rem; + height: 1.5rem; + padding: 0; + background-color: transparent; + border: none; + border-radius: 4px; + color: inherit; + cursor: pointer; + opacity: 0.6; + transition: opacity 0.15s ease, background-color 0.15s ease; +} + +.docmd-banner__close:hover { + opacity: 1; + background-color: rgba(0, 0, 0, 0.05); +} + +.docmd-banner__close svg { + width: 1em; + height: 1em; +} + +.docmd-banner[hidden] { + display: none; +} + +.docmd-cookie-banner { + position: fixed; + z-index: 9999; + font-size: 0.9rem; + line-height: 1.5; + color: var(--text-color, #1f2937); + background-color: var(--bg-color, #fff); + border: 1px solid var(--border-color, rgba(0, 0, 0, 0.08)); + border-radius: var(--radius-md, 8px); + box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.05); + max-width: min(560px, calc(100vw - 2rem)); + animation: docmd-cookie-banner-in 0.25s ease-out; +} + +.docmd-cookie-banner--bottom { + left: 50%; + bottom: 1.5rem; + transform: translateX(-50%); +} + +.docmd-cookie-banner--bottom-left { + left: 1.5rem; + bottom: 1.5rem; +} + +.docmd-cookie-banner--bottom-right { + right: 1.5rem; + bottom: 1.5rem; +} + +.docmd-cookie-banner--center { + top: 50%; + left: 50%; + transform: translate(-50%, -50%); +} + +.docmd-cookie-banner__inner { + display: flex; + align-items: center; + gap: 1rem; + padding: 1rem 1.25rem; + flex-wrap: wrap; +} + +.docmd-cookie-banner__content { + flex: 1 1 240px; + min-width: 0; +} + +.docmd-cookie-banner__message { + margin: 0; + color: var(--text-color, inherit); +} + +.docmd-cookie-banner__policy { + display: inline-block; + margin-top: 0.35rem; + font-size: 0.85em; + text-decoration: underline; + color: inherit; + opacity: 0.85; +} + +.docmd-cookie-banner__actions { + display: flex; + align-items: center; + gap: 0.5rem; + flex-shrink: 0; +} + +.docmd-cookie-banner__btn { + appearance: none; + border: 1px solid var(--border-color, rgba(0, 0, 0, 0.12)); + background-color: var(--bg-color, #fff); + color: var(--text-color, inherit); + border-radius: var(--radius-sm, 6px); + padding: 0.4rem 0.85rem; + font-size: 0.875rem; + font-weight: 500; + cursor: pointer; + transition: background-color 0.15s ease, border-color 0.15s ease, color 0.15s ease; +} + +.docmd-cookie-banner__btn--accept { + background-color: var(--accent-color, #3b82f6); + border-color: var(--accent-color, #3b82f6); + color: #fff; +} + +.docmd-cookie-banner__btn--accept:hover { + filter: brightness(0.95); +} + +.docmd-cookie-banner__btn--decline:hover { + background-color: rgba(0, 0, 0, 0.04); +} + +.docmd-cookie-banner__close { + appearance: none; + background-color: transparent; + border: none; + padding: 0.25rem; + cursor: pointer; + display: inline-flex; + align-items: center; + justify-content: center; + opacity: 0.5; + color: inherit; + border-radius: 4px; + transition: opacity 0.15s ease, background-color 0.15s ease; +} + +.docmd-cookie-banner__close:hover { + opacity: 1; + background-color: rgba(0, 0, 0, 0.05); +} + +.docmd-cookie-banner__close svg { + width: 1em; + height: 1em; +} + +.docmd-cookie-banner[hidden] { + display: none; +} + +@keyframes docmd-cookie-banner-in { + from { opacity: 0; transform: translate(-50%, 1rem); } + to { opacity: 1; transform: translate(-50%, 0); } +} + +.docmd-cookie-banner--bottom-left, +.docmd-cookie-banner--bottom-right { + animation-name: docmd-cookie-banner-in-corner; +} + +@keyframes docmd-cookie-banner-in-corner { + from { opacity: 0; transform: translateY(1rem); } + to { opacity: 1; transform: translateY(0); } +} + +.sidebar nav li a:hover { + background-color: var(--sidebar-link-active-bg); +} + +.callout code { + background-color: color-mix(in srgb, var(--callout-color, var(--code-bg)) 25%, transparent); +} + +.collapsible-summary .collapsible-arrow { + height: 1.25em; +} + +.changelog-body .heading-anchor { + display: none; +} \ No newline at end of file diff --git a/packages/ui/assets/favicon.ico b/packages/ui/assets/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..268a15c0f7e9ff23d5f202c2bcc0a741c1be2fdd GIT binary patch literal 15406 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 RPraX+&pLTu_Wwr>{1CQ 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 R^>_Oi+%VG1yJqw3{{WOD5|RJ_ literal 0 HcmV?d00001 diff --git a/packages/ui/assets/js/docmd-api.js b/packages/ui/assets/js/docmd-api.js new file mode 100644 index 0000000..5eb0d67 --- /dev/null +++ b/packages/ui/assets/js/docmd-api.js @@ -0,0 +1,188 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025 docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * Browser API for docmd plugin communication. + * + * Provides docmd.call(), docmd.send(), docmd.on(), docmd.afterReload(), + * and docmd.scheduleReload() over a WebSocket connection. + * Injected automatically by the dev server. + */ + +/* global WebSocket, sessionStorage, queueMicrotask */ + +(function() { + if (typeof window === 'undefined') return; + if (window.docmd && window.docmd.call) return; // already initialized + + const docmd = window.docmd || {}; + window.docmd = docmd; + + // Restore scroll position after reload + const savedScroll = sessionStorage.getItem('docmd:scrollY'); + if (savedScroll) { + sessionStorage.removeItem('docmd:scrollY'); + requestAnimationFrame(() => { + window.scrollTo(0, parseInt(savedScroll, 10)); + }); + } + + let socket = null; + let messageId = 0; + const pendingCalls = new Map(); // id โ†’ { resolve, reject } + const eventListeners = new Map(); // name โ†’ Set + + // retryCount lives outside connect() so it persists across reconnect calls. + // This ensures maxRetries is actually enforced โ€” previously it reset to 0 + // on every invocation, causing infinite reconnection loops on static servers. + let retryCount = 0; + const maxRetries = 5; + + function connect() { + if (socket && (socket.readyState === 0 || socket.readyState === 1)) return; + if (retryCount >= maxRetries) return; // give up โ€” not a dev server + + socket = new WebSocket('ws://' + window.location.host); + + socket.onopen = () => { + console.log('โšก docmd connected'); + retryCount = 0; // reset on successful connection + }; + + socket.onmessage = (e) => { + if (e.data === 'reload') { + sessionStorage.setItem('docmd:scrollY', String(window.scrollY)); + window.location.reload(); + return; + } + let msg; + try { msg = JSON.parse(e.data); } catch { return; } + + if (msg.type === 'response' && msg.id) { + const pending = pendingCalls.get(msg.id); + if (pending) { + pendingCalls.delete(msg.id); + if (msg.error) { + pending.reject(new Error(msg.error)); + } else { + pending.resolve({ result: msg.result, reload: msg.reload }); + } + } + } else if (msg.type === 'event' && msg.name) { + const listeners = eventListeners.get(msg.name); + if (listeners) { + listeners.forEach(cb => { try { cb(msg.data); } catch (e) { console.error(e); } }); + } + } + }; + + // Suppress the browser's default connection-refused error in the console. + socket.onerror = () => { /* handled via onclose */ }; + + socket.onclose = () => { + retryCount++; + if (retryCount < maxRetries) { + setTimeout(connect, Math.min(1000 * (1.5 ** retryCount), 5000)); + } + // No log on final failure โ€” this is expected when serving a static build. + }; + } + + function waitForConnection() { + if (socket && socket.readyState === 1) return Promise.resolve(); + return new Promise((resolve, reject) => { + const timeout = setTimeout(() => reject(new Error('docmd: WebSocket connection timeout')), 5000); + function check() { + if (socket && socket.readyState === 1) { + clearTimeout(timeout); + resolve(); + } else { + setTimeout(check, 50); + } + } + check(); + }); + } + + /** + * Call a server-side action and return the result. + * If the action modifies files, the page reloads automatically after + * the promise resolves and the current microtask completes. + */ + docmd.call = async function(action, payload) { + await waitForConnection(); + return new Promise((resolve, reject) => { + const id = String(++messageId); + pendingCalls.set(id, { + resolve: ({ result, reload }) => { + resolve(result); + if (reload) { + sessionStorage.setItem('docmd:scrollY', String(window.scrollY)); + queueMicrotask(() => window.location.reload()); + } + }, + reject + }); + socket.send(JSON.stringify({ id, type: 'call', action, payload })); + }); + }; + + /** + * Send a fire-and-forget event to the server. + */ + docmd.send = async function(name, data) { + await waitForConnection(); + socket.send(JSON.stringify({ type: 'event', name, data })); + }; + + /** + * Subscribe to server-pushed events. Returns an unsubscribe function. + */ + docmd.on = function(name, callback) { + if (!eventListeners.has(name)) eventListeners.set(name, new Set()); + eventListeners.get(name).add(callback); + return () => eventListeners.get(name).delete(callback); + }; + + /** + * Declare a named reload handler. Runs on every page load. + * If sessionStorage has stashed context for this name, calls the + * callback immediately with that context and clears the stash. + */ + docmd.afterReload = function(name, callback) { + const key = 'docmd:reload:' + name; + const raw = sessionStorage.getItem(key); + if (raw) { + sessionStorage.removeItem(key); + try { + const context = JSON.parse(raw); + callback(context); + } catch (e) { + console.error('docmd.afterReload[' + name + '] error:', e); + } + } + }; + + /** + * Stash context for a named reload handler. The matching afterReload + * handler will fire with this context after the next page reload. + */ + docmd.scheduleReload = function(name, context) { + const key = 'docmd:reload:' + name; + sessionStorage.setItem(key, JSON.stringify(context || {})); + }; + + // Connect + setTimeout(connect, 100); +})(); \ No newline at end of file diff --git a/packages/ui/assets/js/docmd-i18n-strings.js b/packages/ui/assets/js/docmd-i18n-strings.js new file mode 100644 index 0000000..c09b071 --- /dev/null +++ b/packages/ui/assets/js/docmd-i18n-strings.js @@ -0,0 +1,232 @@ +/* global XMLHttpRequest */ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * Client-side string replacement for noStyle pages. + * Loads JSON translation files from assets/i18n/ and replaces + * text content of elements with data-i18n attributes. + * + * @package @docmd/ui + * @website https://docmd.io + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +(function () { + 'use strict'; + + var config = window.DOCMD_I18N || {}; + var locales = config.locales || []; + var defaultLocale = config.default || ''; + var root = window.DOCMD_ROOT || './'; + + if (!locales.length) return; + + /** + * Detect active locale from URL path prefix. + * Default locale has no prefix (renders at /). + * Non-default locales render at /{id}/. + */ + function detectLocale() { + var saved = localStorage.getItem('docmd-locale'); + var pathSegments = window.location.pathname.split('/').filter(Boolean); + var firstSegment = pathSegments[0] || ''; + + // Check if first path segment matches a non-default locale + var localeIds = locales.map(function (l) { return l.id; }); + if (localeIds.indexOf(firstSegment) !== -1 && firstSegment !== defaultLocale) { + return firstSegment; + } + + // If saved preference matches a configured locale, use it (for default-locale pages) + if (saved && localeIds.indexOf(saved) !== -1) { + return saved; + } + + return defaultLocale; + } + + /** + * Load a JSON translation file from assets/i18n/{locale}.json + */ + function loadStrings(localeId, callback) { + var url = root + 'assets/i18n/' + localeId + '.json'; + var xhr = new XMLHttpRequest(); + xhr.open('GET', url, true); + xhr.onreadystatechange = function () { + if (xhr.readyState === 4) { + if (xhr.status === 200) { + try { + callback(null, JSON.parse(xhr.responseText)); + } catch (e) { + callback(e, null); + } + } else { + callback(new Error('Failed to load ' + url), null); + } + } + }; + xhr.send(); + } + + /** + * Apply translations to the DOM. + * + * Supported attributes: + * data-i18n="key" โ†’ replaces textContent + * data-i18n-html="key" โ†’ replaces innerHTML + * data-i18n-[attr]="key" โ†’ replaces a specific attribute + * e.g. data-i18n-placeholder="searchPlaceholder" + * e.g. data-i18n-aria-label="navLabel" + * e.g. data-i18n-title="tooltipText" + */ + function applyStrings(strings) { + if (!strings) return; + + // data-i18n โ†’ textContent + var els = document.querySelectorAll('[data-i18n]'); + for (var i = 0; i < els.length; i++) { + var key = els[i].getAttribute('data-i18n'); + if (key && strings[key] !== undefined) { + els[i].textContent = strings[key]; + } + } + + // data-i18n-html โ†’ innerHTML (use cautiously with sanitization) + var htmlEls = document.querySelectorAll('[data-i18n-html]'); + for (var j = 0; j < htmlEls.length; j++) { + var htmlKey = htmlEls[j].getAttribute('data-i18n-html'); + if (htmlKey && strings[htmlKey] !== undefined) { + var rawHtml = strings[htmlKey]; + // Basic sanitization: strip script and event handlers + var sanitized = rawHtml + .replace(/]*>([\s\S]*?)<\/script>/gim, "") + .replace(/on\w+="[^"]*"/gim, "") + .replace(/on\w+='[^']*'/gim, ""); + htmlEls[j].innerHTML = sanitized; + } + } + + // data-i18n-* โ†’ attribute replacement + // Scan all elements for data-i18n-{attrName} patterns + var allI18nEls = document.querySelectorAll('*'); + for (var k = 0; k < allI18nEls.length; k++) { + var el = allI18nEls[k]; + var attrs = el.attributes; + for (var a = 0; a < attrs.length; a++) { + var attrName = attrs[a].name; + if (attrName.indexOf('data-i18n-') === 0 && attrName !== 'data-i18n-html') { + var targetAttr = attrName.substring('data-i18n-'.length); + var attrKey = attrs[a].value; + if (attrKey && strings[attrKey] !== undefined) { + el.setAttribute(targetAttr, strings[attrKey]); + } + } + } + } + + // Update html lang attribute + document.documentElement.setAttribute('lang', activeLocale); + + // Dispatch event for custom handlers + document.dispatchEvent(new CustomEvent('docmd:i18n-applied', { + detail: { locale: activeLocale, strings: strings } + })); + } + + /** + * Switch locale - updates localStorage, reloads strings. + * For multi-page i18n sites, redirects to the locale-prefixed URL. + * For single-page noStyle sites, swaps strings in place. + * + * Set window.DOCMD_I18N.inPlace = true to force in-place mode + * (no URL redirect, just reload strings on the same page). + */ + function switchLocale(newLocaleId) { + if (newLocaleId === activeLocale) return; + localStorage.setItem('docmd-locale', newLocaleId); + + var inPlace = config.inPlace || false; + + if (inPlace) { + // In-place mode: just reload strings without navigating + activeLocale = newLocaleId; + window.DOCMD_I18N_STRINGS.locale = newLocaleId; + loadStrings(newLocaleId, function (err, strings) { + if (!err && strings) applyStrings(strings); + }); + return; + } + + var currentPath = window.location.pathname; + var localeIds = locales.map(function (l) { return l.id; }); + + // Strip current locale prefix if present + var pathSegments = currentPath.split('/').filter(Boolean); + var basePath = currentPath; + if (pathSegments.length > 0 && localeIds.indexOf(pathSegments[0]) !== -1 && pathSegments[0] !== defaultLocale) { + basePath = '/' + pathSegments.slice(1).join('/'); + } + + // Add new locale prefix (skip for default locale) + var newPath; + if (newLocaleId === defaultLocale) { + newPath = basePath || '/'; + } else { + newPath = '/' + newLocaleId + (basePath === '/' ? '/' : basePath); + } + + if (newPath !== currentPath) { + window.location.href = newPath; + } else { + // Same page, just reload strings + activeLocale = newLocaleId; + window.DOCMD_I18N_STRINGS.locale = newLocaleId; + loadStrings(newLocaleId, function (err, strings) { + if (!err && strings) applyStrings(strings); + }); + } + } + + // Expose API + var activeLocale = detectLocale(); + + window.DOCMD_I18N_STRINGS = { + locale: activeLocale, + locales: locales, + defaultLocale: defaultLocale, + switchLocale: switchLocale, + applyStrings: applyStrings + }; + + function hasI18nElements() { + if (document.querySelector('[data-i18n], [data-i18n-html]')) return true; + var allEls = document.querySelectorAll('*'); + for (var i = 0; i < allEls.length; i++) { + var attrs = allEls[i].attributes; + for (var j = 0; j < attrs.length; j++) { + if (attrs[j].name.indexOf('data-i18n-') === 0) return true; + } + } + return false; + } + + function init() { + if (hasI18nElements()) { + loadStrings(activeLocale, function (err, strings) { + if (!err && strings) applyStrings(strings); + }); + } + } + + // Auto-apply on DOM ready + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', init); + } else { + init(); + } +})(); \ No newline at end of file diff --git a/packages/ui/assets/js/docmd-image-lightbox.js b/packages/ui/assets/js/docmd-image-lightbox.js new file mode 100644 index 0000000..7ebca31 --- /dev/null +++ b/packages/ui/assets/js/docmd-image-lightbox.js @@ -0,0 +1,95 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/* + * A simple lightbox implementation for gallery images + */ + +document.addEventListener('DOMContentLoaded', function () { + // Create lightbox elements + const lightbox = document.createElement('div'); + lightbox.className = 'docmd-lightbox'; + const content = document.createElement('div'); + content.className = 'docmd-lightbox-content'; + const img = document.createElement('img'); + img.src = ''; + img.alt = ''; + const caption = document.createElement('div'); + caption.className = 'docmd-lightbox-caption'; + content.appendChild(img); + content.appendChild(caption); + + const close = document.createElement('div'); + close.className = 'docmd-lightbox-close'; + close.innerHTML = '×'; // Hardcoded entity is safe + + lightbox.appendChild(content); + lightbox.appendChild(close); + document.body.appendChild(lightbox); + + const lightboxImg = lightbox.querySelector('img'); + const lightboxCaption = lightbox.querySelector('.docmd-lightbox-caption'); + const lightboxClose = lightbox.querySelector('.docmd-lightbox-close'); + + // Find all images with lightbox class or in image galleries + const lightboxImages = document.querySelectorAll('img.lightbox, .image-gallery img'); + + // Add click event to each image + lightboxImages.forEach(function (img) { + img.style.cursor = 'zoom-in'; + + img.addEventListener('click', function () { + // Get the image source and caption + const src = this.getAttribute('src'); + let caption = this.getAttribute('alt') || ''; + + // If image is inside a figure with figcaption, use that caption + const figure = this.closest('figure'); + if (figure) { + const figcaption = figure.querySelector('figcaption'); + if (figcaption) { + caption = figcaption.textContent; + } + } + + // Set the lightbox content + lightboxImg.setAttribute('src', src); + lightboxCaption.textContent = caption; + + // Show the lightbox + lightbox.style.display = 'flex'; + document.body.style.overflow = 'hidden'; // Prevent scrolling + }); + }); + + // Close lightbox when clicking the close button or outside the image + lightboxClose.addEventListener('click', closeLightbox); + lightbox.addEventListener('click', function (e) { + if (e.target === lightbox) { + closeLightbox(); + } + }); + + // Close lightbox when pressing Escape key + document.addEventListener('keydown', function (e) { + if (e.key === 'Escape' && lightbox.style.display === 'flex') { + closeLightbox(); + } + }); + + function closeLightbox() { + lightbox.style.display = 'none'; + document.body.style.overflow = ''; // Restore scrolling + } +}); \ No newline at end of file diff --git a/packages/ui/assets/js/docmd-main.js b/packages/ui/assets/js/docmd-main.js new file mode 100644 index 0000000..aa47b02 --- /dev/null +++ b/packages/ui/assets/js/docmd-main.js @@ -0,0 +1,1027 @@ +/** + * -------------------------------------------------------------------- + * docmd : the zero-config documentation engine. + * + * @package @docmd/core (and ecosystem) + * @website https://docmd.io + * @repository https://github.com/docmd-io/docmd + * @license MIT + * @copyright Copyright (c) 2025-present docmd.io + * + * [docmd-source] - Please do not remove this header. + * -------------------------------------------------------------------- + */ + +/** + * -------------------------------------------------------------------- + * docmd : Client-Side Application Logic (SPA Router & UI) + * -------------------------------------------------------------------- + */ + +/* global CSS */ + +(function () { + + // Idempotency guard. Some servers (e.g. `serve` with SPA fallback) can + // request this same script twice โ€” once at the page-relative URL, once + // at the site root โ€” and both copies execute. Without this guard, every + // click handler (toggle, SPA nav, copy code, etc.) would bind twice and + // every nav action would fire two times, silently breaking the sidebar. + if (window.__docmdMainLoaded) return; + window.__docmdMainLoaded = true; + + function findTargetElement(hash) { + if (!hash) return null; + const cleanHash = hash.substring(1); + if (!cleanHash) return null; + try { + let target = document.getElementById(cleanHash) || document.querySelector(hash); + if (target) return target; + target = document.querySelector('[id$="-' + CSS.escape(cleanHash) + '"]'); + if (target) return target; + } catch (_e) { /* ignore */ } + return null; + } + + // 1. EVENT DELEGATION + document.addEventListener('click', (e) => { + // Collapsible Navigation + // - Chevron (.collapse-icon-wrapper) click: always toggle, preventDefault. + // - Dummy section divider: toggle, preventDefault. + // - Real label click: navigate via SPA. The new + // page's sidebar auto-expands the active group, so parents that are + // pages themselves (e.g. "Syntax" with children) open as pages, + // not as collapsed sections. + const navTrigger = e.target.closest('.nav-group, .collapse-icon-wrapper'); + if (navTrigger) { + const item = navTrigger.closest('li.collapsible'); + const isChevron = navTrigger.classList.contains('collapse-icon-wrapper'); + const isDummySpan = navTrigger.tagName !== 'A'; + + // Offline-mode safety (issue #164): under file:// the SPA click handler + // is not registered (initializeSPA short-circuits at line 581), so this + // is the only click handler that runs. closest('.nav-group') can walk + // past an empty-class nested and match the parent
    • ; + // navTrigger.tagName then equals 'LI', isDummySpan is true, and the + // preventDefault below would swallow the click and block the default + // navigation. Skip the toggle in that exact case so the click + // reaches the inner link's default behaviour. Non-offline builds keep + // their existing SPA-fall-through path unchanged โ€” the gate only fires + // when location.protocol === 'file:' AND the matched element is an LI + // (never an A, span.nav-group, or chevron). + const isOffline = location.protocol === 'file:'; + const matchedParentLi = navTrigger.tagName === 'LI'; + const shouldToggle = (isChevron || isDummySpan) && item && !(isOffline && matchedParentLi); + + if (shouldToggle) { + e.preventDefault(); + const isExpanded = item.classList.contains('expanded'); + item.classList.toggle('expanded', !isExpanded); + item.setAttribute('aria-expanded', !isExpanded); + if (isChevron) return; + } + // Real : fall through to the SPA handler. + } + + // Toggles + if (e.target.closest('.toc-menu-button, .toc-title')) { + document.querySelector('.toc-container')?.classList.toggle('mobile-expanded'); + } + if (e.target.closest('.sidebar-menu-button')) { + document.querySelector('.sidebar')?.classList.toggle('mobile-expanded'); + } + if (e.target.closest('#sidebar-toggle-button')) { + document.body.classList.toggle('sidebar-collapsed'); + localStorage.setItem('docmd-sidebar-collapsed', document.body.classList.contains('sidebar-collapsed')); + } + + // Tabs System + const tabItem = e.target.closest('.docmd-tabs-nav-item'); + if (tabItem) { + const tabsContainer = tabItem.closest('.docmd-tabs'); + const navItems = Array.from(tabsContainer.querySelectorAll('.docmd-tabs-nav-item')); + const tabPanes = Array.from(tabsContainer.querySelectorAll('.docmd-tab-pane')); + const index = navItems.indexOf(tabItem); + + navItems.forEach(item => item.classList.remove('active')); + tabPanes.forEach(pane => pane.classList.remove('active')); + + tabItem.classList.add('active'); + if (tabPanes[index]) tabPanes[index].classList.add('active'); + } + + // Version Dropdown Toggle + const versionToggle = e.target.closest('.version-dropdown-toggle'); + if (versionToggle) { + e.preventDefault(); + e.stopPropagation(); + const dropdown = versionToggle.closest('.docmd-version-dropdown'); + dropdown.classList.toggle('open'); + versionToggle.setAttribute('aria-expanded', dropdown.classList.contains('open')); + // Close other switchers when opening version dropdown + document.querySelectorAll('.docmd-language-switcher.open, .docmd-project-switcher.open').forEach(d => { + d.classList.remove('open'); + const t = d.querySelector('.language-switcher-toggle, .project-switcher-toggle'); + if (t) t.setAttribute('aria-expanded', 'false'); + }); + return; + } + + // Sticky Version Switching (Path Preservation) + const versionLink = e.target.closest('.version-dropdown-item'); + if (versionLink) { + e.preventDefault(); // Prevent default link behavior immediately + const targetRoot = versionLink.dataset.versionRoot; + // Use global fallback if undefined (e.g. on 404 pages) + const currentRoot = window.DOCMD_VERSION_ROOT || '/'; + + if (targetRoot && window.location.pathname) { + let currentPath = window.location.pathname; + const normCurrentRoot = currentRoot.endsWith('/') ? currentRoot : currentRoot + '/'; + + // Only try sticky if we are actually INSIDE the known version path + if (currentPath.startsWith(normCurrentRoot)) { + const suffix = currentPath.substring(normCurrentRoot.length); + const normTargetRoot = targetRoot.endsWith('/') ? targetRoot : targetRoot + '/'; + let targetHref = normTargetRoot + suffix + window.location.hash; + targetHref = targetHref.replace(/([^:])\/{2,}/g, '$1/'); // Prevent double slashes + + // Smart Switcher: Check if the exact page exists in the target version + fetch(targetHref, { method: 'HEAD' }) + .then(response => { + const finalHref = response.ok ? targetHref : normTargetRoot; + if (typeof window.docmdNavigate === 'function' && document.body.dataset.spaEnabled === 'true' && window.location.protocol !== 'file:') { + window.docmdNavigate(finalHref); + } else { + window.location.href = finalHref; + } + }) + .catch(() => { + if (typeof window.docmdNavigate === 'function' && document.body.dataset.spaEnabled === 'true' && window.location.protocol !== 'file:') { + window.docmdNavigate(normTargetRoot); + } else { + window.location.href = normTargetRoot; + } + }); + return; + } + } + // If we are outside the root (or targetRoot is missing), just use the href defined in the link + if (typeof window.docmdNavigate === 'function' && document.body.dataset.spaEnabled === 'true' && window.location.protocol !== 'file:') { + window.docmdNavigate(versionLink.href); + } else { + window.location.href = versionLink.href; + } + } + + // Close Dropdown if clicked outside + if (!e.target.closest('.docmd-version-dropdown')) { + document.querySelectorAll('.docmd-version-dropdown.open').forEach(d => { + d.classList.remove('open'); + d.querySelector('.version-dropdown-toggle').setAttribute('aria-expanded', 'false'); + }); + } + if (!e.target.closest('.docmd-language-switcher')) { + document.querySelectorAll('.docmd-language-switcher.open').forEach(d => { + d.classList.remove('open'); + d.querySelector('.language-switcher-toggle').setAttribute('aria-expanded', 'false'); + }); + } + if (!e.target.closest('.docmd-project-switcher')) { + document.querySelectorAll('.docmd-project-switcher.open').forEach(d => { + d.classList.remove('open'); + d.querySelector('.project-switcher-toggle').setAttribute('aria-expanded', 'false'); + }); + } + const langToggle = e.target.closest('.language-switcher-toggle'); + if (langToggle) { + e.preventDefault(); + e.stopPropagation(); + const dropdown = langToggle.closest('.docmd-language-switcher'); + dropdown.classList.toggle('open'); + langToggle.setAttribute('aria-expanded', dropdown.classList.contains('open')); + // Close version dropdown when opening language switcher + document.querySelectorAll('.docmd-version-dropdown.open, .docmd-project-switcher.open').forEach(d => { + d.classList.remove('open'); + const t = d.querySelector('.version-dropdown-toggle, .project-switcher-toggle'); + if (t) t.setAttribute('aria-expanded', 'false'); + }); + return; + } + + const projectToggle = e.target.closest('.project-switcher-toggle'); + if (projectToggle) { + e.preventDefault(); + e.stopPropagation(); + const dropdown = projectToggle.closest('.docmd-project-switcher'); + dropdown.classList.toggle('open'); + projectToggle.setAttribute('aria-expanded', dropdown.classList.contains('open')); + // Close other dropdowns + document.querySelectorAll('.docmd-version-dropdown.open, .docmd-language-switcher.open').forEach(d => { + d.classList.remove('open'); + const t = d.querySelector('.version-dropdown-toggle, .language-switcher-toggle'); + if (t) t.setAttribute('aria-expanded', 'false'); + }); + return; + } + + // Language Switcher Navigation (dynamic URL like version switching) + const langLink = e.target.closest('.language-switcher-item'); + if (langLink) { + e.preventDefault(); + + // Skip disabled locales (no content available) + if (langLink.classList.contains('disabled') || langLink.getAttribute('aria-disabled') === 'true') { + return; + } + + var localeId = langLink.dataset.localeId; + if (localeId) { + try { localStorage.setItem('docmd-locale', localeId); } catch { /* storage unavailable */ } + } + + // Compute target URL preserving current page path + var base = (window.DOCMD_BASE || '/').replace(/\/$/, '') + '/'; + var currentLocale = window.DOCMD_LOCALE || ''; + var defaultLocale = window.DOCMD_DEFAULT_LOCALE || ''; + var currentPath = window.location.pathname; + + // Strip base from current path + if (base !== '/' && currentPath.startsWith(base)) { + currentPath = currentPath.substring(base.length); + } else if (currentPath.startsWith('/')) { + currentPath = currentPath.substring(1); + } + + // Strip current locale prefix from path (ensuring we handle the leading slash) + var pathWithoutBase = currentPath; + if (currentLocale && currentLocale !== defaultLocale) { + var localePrefix = currentLocale + '/'; + if (pathWithoutBase.startsWith(localePrefix)) { + pathWithoutBase = pathWithoutBase.substring(localePrefix.length); + } + } + currentPath = pathWithoutBase; + + // Build new path with target locale prefix + var targetLocPrefix = (localeId && localeId !== defaultLocale) ? localeId + '/' : ''; + var targetHref = base + targetLocPrefix + currentPath; + + // Optional manifest-based UX: if the build-time manifest is loaded AND + // it knows about this specific page, redirect to the locale root when + // the page isn't translated. This is only an optimisation โ€” the target + // page is still the canonical answer and the server will return 404 if + // the page genuinely doesn't exist there. + var manifest = window.DOCMD_LOCALE_PAGES; + if (manifest && manifest[localeId] && Array.isArray(manifest[localeId]) && manifest[localeId].length > 0) { + var lookupPath = '/' + currentPath.replace(/\/$/, '').replace(/\/index\.html$/, ''); + if (lookupPath === '/') lookupPath = '/'; + if (manifest[localeId].indexOf(lookupPath) === -1) { + // Page is not translated โ€” fall back to the locale root. For the + // default locale the "locale root" IS the site root, so this + // naturally sends the user to the homepage, which is the + // expected behaviour when switching to the default. + targetHref = base + targetLocPrefix; + } + } + + const finalHref = targetHref + window.location.hash; + if (typeof window.docmdNavigate === 'function' && document.body.dataset.spaEnabled === 'true' && window.location.protocol !== 'file:') { + window.docmdNavigate(finalHref); + } else { + window.location.href = finalHref; + } + return; + } + + // Copy Code Button + // Copy Code Button + const copyBtn = e.target.closest('.copy-code-button'); + if (copyBtn) { + // Look for the associated in the immediate .code-wrapper, + // or in the nearest codeblock-shaped wrapper. Templates like + // `summer` re-home the copy button into a title bar that lives + // outside .code-wrapper (e.g. inside .docmd-code-block-wrapper + // for ```lang "title"``` blocks) โ€” fall back to that parent + // wrapper's 
       in that case.
+      const code = copyBtn.closest('.code-wrapper')?.querySelector('code')
+        || copyBtn.closest('.docmd-code-block-wrapper, .summer-cb, .summer-codeblock')?.querySelector('pre code');
+      if (code) {
+        navigator.clipboard.writeText(code.innerText).then(() => {
+          copyBtn.classList.add('copied');
+          // Update icon to checkmark
+          copyBtn.innerHTML = ''; // Safe to clear
+          const checkSvg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+          checkSvg.setAttribute('width', '16');
+          checkSvg.setAttribute('height', '16');
+          checkSvg.setAttribute('viewBox', '0 0 24 24');
+          checkSvg.setAttribute('fill', 'none');
+          checkSvg.setAttribute('stroke', 'currentColor');
+          checkSvg.setAttribute('stroke-width', '2');
+          checkSvg.setAttribute('stroke-linecap', 'round');
+          checkSvg.setAttribute('stroke-linejoin', 'round');
+          checkSvg.classList.add('lucide', 'lucide-check');
+          const polyline = document.createElementNS('http://www.w3.org/2000/svg', 'polyline');
+          polyline.setAttribute('points', '20 6 9 17 4 12');
+          checkSvg.appendChild(polyline);
+          copyBtn.appendChild(checkSvg);
+
+          setTimeout(() => {
+            copyBtn.classList.remove('copied');
+            // Revert icon to copy
+            copyBtn.innerHTML = ''; 
+            copyBtn.appendChild(createCopySvg());
+          }, 2000);
+        });
+      }
+    }
+
+    function parseFrontmatter(markdown) {
+      const trimmed = markdown.trim();
+      const meta = {};
+      let body = trimmed;
+      if (trimmed.startsWith('---')) {
+        const nextSeparator = trimmed.indexOf('---', 3);
+        if (nextSeparator !== -1) {
+          const fmText = trimmed.substring(3, nextSeparator);
+          body = trimmed.substring(nextSeparator + 3).trim();
+          const lines = fmText.split('\n');
+          for (const line of lines) {
+            const colonIdx = line.indexOf(':');
+            if (colonIdx !== -1) {
+              const key = line.substring(0, colonIdx).trim();
+              let val = line.substring(colonIdx + 1).trim();
+              if (val.startsWith('"') && val.endsWith('"')) {
+                val = val.substring(1, val.length - 1);
+              } else if (val.startsWith("'") && val.endsWith("'")) {
+                val = val.substring(1, val.length - 1);
+              }
+              meta[key] = val;
+            }
+          }
+        }
+      }
+      return { meta, body };
+    }
+
+    // Copy Raw Markdown Button
+    const rawCopyBtn = e.target.closest('.docmd-copy-raw-btn');
+    if (rawCopyBtn) {
+      const rawEl = document.getElementById('docmd-raw-markdown');
+      if (rawEl) {
+        const rawContent = decodeURIComponent(rawEl.getAttribute('data-content') || '');
+        const { body } = parseFrontmatter(rawContent);
+        navigator.clipboard.writeText(body).then(() => {
+          const btnText = rawCopyBtn.querySelector('.docmd-btn-text');
+          const originalText = btnText ? btnText.textContent : 'Copy Markdown';
+          const copiedText = rawCopyBtn.getAttribute('data-copied') || 'Copied!';
+          if (btnText) btnText.textContent = copiedText;
+          rawCopyBtn.classList.add('copied');
+          setTimeout(() => {
+            if (btnText) btnText.textContent = originalText;
+            rawCopyBtn.classList.remove('copied');
+          }, 2000);
+        });
+      }
+    }
+
+    // Copy Context Button
+    const contextCopyBtn = e.target.closest('.docmd-copy-context-btn');
+    if (contextCopyBtn) {
+      const rawEl = document.getElementById('docmd-raw-markdown');
+      if (rawEl) {
+        const rawContent = decodeURIComponent(rawEl.getAttribute('data-content') || '');
+        const { meta, body } = parseFrontmatter(rawContent);
+        const title = document.title || '';
+        const descMeta = document.querySelector('meta[name="description"]');
+        const desc = descMeta ? descMeta.getAttribute('content') || '' : '';
+        
+        let contextStr = `Source URL: ${window.location.href}\nTitle: ${title}\n`;
+        if (desc) {
+          contextStr += `Description: ${desc}\n`;
+        }
+        if (Object.keys(meta).length > 0) {
+          contextStr += `\nMetadata:\n`;
+          for (const [k, v] of Object.entries(meta)) {
+            contextStr += `- ${k}: ${v}\n`;
+          }
+        }
+        contextStr += `\n---\n\n${body}`;
+
+        navigator.clipboard.writeText(contextStr).then(() => {
+          const btnText = contextCopyBtn.querySelector('.docmd-btn-text');
+          const originalText = btnText ? btnText.textContent : 'Copy Context';
+          const copiedText = contextCopyBtn.getAttribute('data-copied') || 'Copied!';
+          if (btnText) btnText.textContent = copiedText;
+          contextCopyBtn.classList.add('copied');
+          setTimeout(() => {
+            if (btnText) btnText.textContent = originalText;
+            contextCopyBtn.classList.remove('copied');
+          }, 2000);
+        });
+      }
+    }
+
+    // Hero Slider
+    const sliderBtn = e.target.closest('.hero-slider-btn, .hero-slider-dot');
+    if (sliderBtn) {
+      const hero = sliderBtn.closest('.docmd-hero.hero-slider');
+      if (!hero) return;
+      const track = hero.querySelector('.hero-slider-track');
+      const slides = hero.querySelectorAll('.hero-slide');
+      const dots = hero.querySelectorAll('.hero-slider-dot');
+      if (!track || !slides.length) return;
+
+      const slideWidth = slides[0].offsetWidth;
+      const currentIndex = Math.round(track.scrollLeft / slideWidth);
+      let targetIndex = currentIndex;
+
+      if (sliderBtn.classList.contains('hero-slider-prev')) {
+        targetIndex = (currentIndex - 1 + slides.length) % slides.length;
+      } else if (sliderBtn.classList.contains('hero-slider-next')) {
+        targetIndex = (currentIndex + 1) % slides.length;
+      } else if (sliderBtn.classList.contains('hero-slider-dot')) {
+        targetIndex = parseInt(sliderBtn.dataset.slide, 10);
+      }
+
+      track.scrollTo({ left: targetIndex * slideWidth, behavior: 'smooth' });
+      dots.forEach((d, i) => d.classList.toggle('active', i === targetIndex));
+    }
+
+  });
+
+  function createCopySvg() {
+    const copySvg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    copySvg.setAttribute('width', '16');
+    copySvg.setAttribute('height', '16');
+    copySvg.setAttribute('viewBox', '0 0 24 24');
+    copySvg.setAttribute('fill', 'none');
+    copySvg.setAttribute('stroke', 'currentColor');
+    copySvg.setAttribute('stroke-width', '2');
+    copySvg.setAttribute('stroke-linecap', 'round');
+    copySvg.setAttribute('stroke-linejoin', 'round');
+    copySvg.classList.add('lucide', 'lucide-copy');
+    const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+    rect.setAttribute('width', '14');
+    rect.setAttribute('height', '14');
+    rect.setAttribute('x', '8');
+    rect.setAttribute('y', '8');
+    rect.setAttribute('rx', '2');
+    rect.setAttribute('ry', '2');
+    const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    path.setAttribute('d', 'M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2');
+    copySvg.appendChild(rect);
+    copySvg.appendChild(path);
+    return copySvg;
+  }
+
+  // 2. COMPONENT INITIALIZERS
+  function injectCopyButtons() {
+    if (document.body.dataset.copyCodeEnabled !== 'true') return;
+
+    document.querySelectorAll('pre').forEach(preElement => {
+      const outerWrapper = preElement.closest('.docmd-code-block-wrapper');
+      if (outerWrapper && outerWrapper.querySelector(':scope > .copy-code-button, :scope > .docmd-code-block-header > .copy-code-button')) return;
+
+      // Choose a host that gives the absolutely-positioned button a
+      // sensible anchor. The CSS positions the button at top: .85rem;
+      // right: .5rem of its containing positioned element.
+      //
+      // Titled case (```lang "title"```): the 
       sits inside a
+      // .docmd-code-block-wrapper that also contains a header strip.
+      // Anchoring the button to the wrapper would land it on top of
+      // the header โ€” wrong place. Anchor to the header instead: the
+      // header is `display: flex` with the title on the left, and a
+      // button appended to it lands cleanly on the right.
+      //
+      // Untitled case: the 
       has no positioned ancestor. Wrap
+      // it in a `.code-wrapper` that we then position:relative so
+      // the button anchors inside the code area.
+      let host = null;
+      if (outerWrapper) {
+        const header = outerWrapper.querySelector(':scope > .docmd-code-block-header');
+        if (header) {
+          header.classList.add('has-copy-button');
+          host = header;
+        }
+      }
+      if (!host) {
+        const wrapper = document.createElement('div');
+        wrapper.className = 'code-wrapper';
+        wrapper.style.position = 'relative';
+        preElement.parentNode.insertBefore(wrapper, preElement);
+        wrapper.appendChild(preElement);
+        host = wrapper;
+      }
+      if (host.querySelector(':scope > .copy-code-button')) return;
+
+      const copyButton = document.createElement('button');
+      copyButton.className = 'copy-code-button';
+      copyButton.appendChild(createCopySvg());
+      copyButton.title = "Copy code";
+      host.appendChild(copyButton);
+    });
+  }
+
+  function initializeHeroSliders() {
+    document.querySelectorAll('.docmd-hero.hero-slider').forEach(hero => {
+      const track = hero.querySelector('.hero-slider-track');
+      const dots = hero.querySelectorAll('.hero-slider-dot');
+      if (!track || !dots.length) return;
+
+      // Sync dots on scroll (handles touch/swipe)
+      track.addEventListener('scroll', () => {
+        const slides = hero.querySelectorAll('.hero-slide');
+        if (!slides.length) return;
+        const idx = Math.round(track.scrollLeft / slides[0].offsetWidth);
+        dots.forEach((d, i) => d.classList.toggle('active', i === idx));
+      }, { passive: true });
+    });
+  }
+
+  let scrollObserver = null;
+  let lastActiveId = null;
+  let scrollTimeout = null;
+  
+  function initializeScrollSpy() {
+    if (scrollObserver) scrollObserver.disconnect();
+    const tocLinks = document.querySelectorAll('.toc-link');
+    const headings = document.querySelectorAll('.main-content h1, .main-content h2, .main-content h3, .main-content h4');
+    const tocContainer = document.querySelector('.toc-sidebar');
+
+    if (tocLinks.length === 0 || headings.length === 0) return;
+
+    scrollObserver = new IntersectionObserver((entries) => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting) {
+          const id = entry.target.getAttribute('id');
+          
+          // Skip if this is already the active item
+          if (id === lastActiveId) return;
+          lastActiveId = id;
+          
+          tocLinks.forEach(link => link.classList.remove('active'));
+          const activeLink = document.querySelector(`.toc-link[href="#${id}"]`);
+
+          if (activeLink) {
+            activeLink.classList.add('active');
+            if (tocContainer) {
+              // Debounce scroll to prevent jittery behavior
+              if (scrollTimeout) clearTimeout(scrollTimeout);
+              scrollTimeout = setTimeout(() => {
+                const linkRect = activeLink.getBoundingClientRect();
+                const containerRect = tocContainer.getBoundingClientRect();
+                const scrollTop = activeLink.offsetTop - (containerRect.height / 2) + (linkRect.height / 2);
+                tocContainer.scrollTo({ top: Math.max(0, scrollTop), behavior: 'smooth' });
+              }, 100);
+            }
+          }
+        }
+      });
+    }, { rootMargin: '-15% 0px -80% 0px', threshold: 0 });
+
+    headings.forEach(h => scrollObserver.observe(h));
+  }
+
+  function executeScripts(container) {
+    container.querySelectorAll('script').forEach(oldScript => {
+      const newScript = document.createElement('script');
+      Array.from(oldScript.attributes).forEach(attr => newScript.setAttribute(attr.name, attr.value));
+      newScript.text = oldScript.innerHTML;
+      oldScript.parentNode.replaceChild(newScript, oldScript);
+    });
+  }
+
+  // 3. TARGETED SPA ROUTER
+  function initializeSPA() {
+    if (location.protocol === 'file:') return;
+    if (document.body.dataset.spaEnabled !== 'true') return;
+
+    // Convert all initial relative assets in head to absolute URLs to prevent
+    // dynamic base resolution issues during SPA pushState / popstate updates.
+    const assetSelectors = 'link[rel="stylesheet"], link[rel="icon"], link[rel="shortcut icon"]';
+    document.querySelectorAll(assetSelectors).forEach(asset => {
+      const href = asset.getAttribute('href');
+      if (href) {
+        asset.setAttribute('href', new URL(href, window.location.href).href);
+      }
+    });
+
+    let currentPath = window.location.pathname;
+    const pageCache = new Map();
+    let prefetchTimer = null;
+
+    // Intent-based Hover Prefetching
+    document.addEventListener('mouseover', (e) => {
+      const link = e.target.closest('.sidebar-nav a, .page-navigation a, .page-footer a, .main-content a');
+      if (!link || link.target === '_blank' || link.hasAttribute('download')) return;
+
+      const url = new URL(link.href).href;
+      if (new URL(url).origin !== location.origin) return;
+      if (pageCache.has(url)) return;
+
+      // Wait 65ms to ensure the user actually intends to click
+      clearTimeout(prefetchTimer);
+      prefetchTimer = setTimeout(() => {
+        // Prefetch using hash-stripped URL - the fragment is never sent to the server
+        const prefetchUrl = new URL(link.href);
+        const prefetchFetchUrl = prefetchUrl.origin + prefetchUrl.pathname + prefetchUrl.search;
+        if (pageCache.has(prefetchFetchUrl)) return;
+        pageCache.set(prefetchFetchUrl, fetch(prefetchFetchUrl).then(res => {
+          if (!res.ok) throw new Error('Prefetch failed');
+          return { html: res.text(), finalUrl: res.url };
+        }).catch(() => pageCache.delete(prefetchFetchUrl)));
+      }, 65);
+    });
+
+    // Cancel prefetch if the mouse leaves before the 65ms "intent" delay
+    document.addEventListener('mouseout', () => clearTimeout(prefetchTimer));
+
+    document.addEventListener('click', async (e) => {
+      if (e.target.closest('.collapse-icon-wrapper')) return;
+
+      if (e.target.closest('[data-spa-ignore], .language-switcher-item, .version-dropdown-item')) return;
+
+      const link = e.target.closest('.sidebar-nav a, .page-navigation a, .page-footer a, .main-content a');
+      if (!link || link.target === '_blank' || link.hasAttribute('download')) return;
+
+      // Real  links navigate normally via SPA. The
+      // toggle handler above only prevents default for dummy s and
+      // chevron clicks, so this branch is safe to fall through.
+
+      const url = new URL(link.href);
+      if (url.origin !== location.origin) return;
+
+      // Same-page hash navigation: scroll to the target element smoothly
+      // without a full SPA fetch. The browser's native behaviour doesn't
+      // fire reliably after a previous pushState, so we handle it manually.
+      if (url.pathname === window.location.pathname && url.hash) {
+        e.preventDefault();
+        history.pushState({}, '', url.href);
+        const target = findTargetElement(url.hash);
+        if (target) target.scrollIntoView({ behavior: 'smooth' });
+        return;
+      }
+
+      e.preventDefault();
+      await navigateTo(url.href);
+    });
+
+    window.addEventListener('popstate', () => {
+      // Same-page hash change via browser back/forward
+      if (window.location.pathname === currentPath) {
+        const hash = window.location.hash;
+        if (hash) {
+          const target = findTargetElement(hash);
+          if (target) target.scrollIntoView({ behavior: 'smooth' });
+        }
+        return;
+      }
+      navigateTo(window.location.href, false);
+    });
+
+    async function navigateTo(url, pushHistory = true) {
+      const layout = document.querySelector('.content-layout');
+
+      try {
+        if (layout) layout.style.minHeight = layout.getBoundingClientRect().height + 'px';
+
+        // Separate hash from the fetch URL - servers don't receive fragments,
+        // and res.url (finalUrl) will never contain the hash. We preserve it
+        // manually so pushState and the scroll both use the correct value.
+        const parsedUrl = new URL(url);
+        const requestedHash = parsedUrl.hash; // e.g. "#configuration"
+        const fetchUrl = parsedUrl.origin + parsedUrl.pathname + parsedUrl.search;
+
+        let data;
+        if (pageCache.has(fetchUrl)) {
+          data = await pageCache.get(fetchUrl);
+          data.html = await data.html;
+        } else {
+          const res = await fetch(fetchUrl);
+          if (!res.ok) throw new Error('Fetch failed');
+          data = { html: await res.text(), finalUrl: res.url };
+          pageCache.set(fetchUrl, Promise.resolve(data));
+        }
+
+        const finalUrl = data.finalUrl + requestedHash;
+        const html = data.html;
+
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(html, 'text/html');
+
+        // If target page is not SPA-compatible (e.g. noStyle), do a full redirect
+        if (doc.body.dataset.spaEnabled === 'false') {
+          window.location.assign(url);
+          return;
+        }
+
+        if (pushHistory) history.pushState({}, '', finalUrl);
+        currentPath = new URL(finalUrl).pathname;
+        document.title = doc.title;
+
+        // Sync Assets (CSS/Icons) - use absolute URLs to prevent jank when relative paths change
+        const assetSelectors = 'link[rel="stylesheet"], link[rel="icon"], link[rel="shortcut icon"]';
+        const oldAssets = Array.from(document.head.querySelectorAll(assetSelectors));
+        const newAssets = Array.from(doc.head.querySelectorAll(assetSelectors));
+
+        newAssets.forEach((newAsset) => {
+          const newHref = new URL(newAsset.getAttribute('href'), data.finalUrl).href;
+          // Check if this absolute URL is already present in the head
+          const alreadyPresent = Array.from(document.head.querySelectorAll(assetSelectors)).some(oldAsset => {
+            return new URL(oldAsset.getAttribute('href'), window.location.href).href === newHref;
+          });
+
+          if (!alreadyPresent) {
+            const cloned = newAsset.cloneNode(true);
+            cloned.setAttribute('href', newHref);
+            document.head.appendChild(cloned);
+          }
+        });
+
+        Array.from(doc.querySelectorAll('body > script[src]')).forEach(newScript => {
+          const src = newScript.getAttribute('src');
+          if (!src) return;
+          const newSrc = new URL(src, data.finalUrl).href;
+          const alreadyPresent = Array.from(document.body.querySelectorAll('script[src]')).some(s => {
+            const oldSrc = s.getAttribute('src');
+            return oldSrc && new URL(oldSrc, window.location.href).href === newSrc;
+          });
+          if (alreadyPresent) return;
+          const fresh = document.createElement('script');
+          for (const attr of Array.from(newScript.attributes)) {
+            if (attr.name === 'src') continue;
+            fresh.setAttribute(attr.name, attr.value);
+          }
+          fresh.src = newSrc;
+          document.body.appendChild(fresh);
+        });
+
+        // Sync Root Attributes (Theme, Classes)
+        document.documentElement.className = doc.documentElement.className;
+        document.body.className = doc.body.className;
+        Array.from(doc.documentElement.attributes).forEach(attr => {
+          if (attr.name !== 'class') document.documentElement.setAttribute(attr.name, attr.value);
+        });
+        Array.from(doc.body.attributes).forEach(attr => {
+          if (attr.name !== 'class') document.body.setAttribute(attr.name, attr.value);
+        });
+
+        // Sync Sidebar State
+        const oldLis = Array.from(document.querySelectorAll('.sidebar-nav li'));
+        const newLis = Array.from(doc.querySelectorAll('.sidebar-nav li'));
+
+        oldLis.forEach((oldLi, i) => {
+          const newLi = newLis[i];
+          if (newLi) {
+            oldLi.classList.toggle('active', newLi.classList.contains('active'));
+            oldLi.classList.toggle('active-parent', newLi.classList.contains('active-parent'));
+
+            if (newLi.classList.contains('expanded')) {
+              oldLi.classList.add('expanded');
+              oldLi.setAttribute('aria-expanded', 'true');
+            }
+
+            const oldA = oldLi.querySelector('a');
+            const newA = newLi.querySelector('a');
+            if (oldA && newA) {
+              // Resolve new href to absolute URL to prevent relative path nesting issues
+              // But preserve external URLs (http/https, mailto:, tel:, etc.) as-is
+              const newHref = newA.getAttribute('href');
+              if (newHref && newHref !== '#') {
+                try {
+                  // Check if this is an external URL or special protocol - preserve as-is
+                  if (/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(newHref)) {
+                    oldA.setAttribute('href', newHref);
+                  } else {
+                    // Internal link: resolve relative to the fetched page's URL
+                    const absoluteUrl = new URL(newHref, data.finalUrl || window.location.href);
+                    oldA.setAttribute('href', absoluteUrl.pathname + absoluteUrl.hash);
+                  }
+                } catch {
+                  oldA.setAttribute('href', newHref);
+                }
+              } else {
+                oldA.setAttribute('href', newHref || '#');
+              }
+              oldA.classList.toggle('active', newA.classList.contains('active'));
+            }
+          }
+        });
+
+        const selectorsToSwap = [
+          '.content-layout',
+          '.docmd-breadcrumbs',
+          '.page-header .header-title',
+          '.page-footer',
+          '.footer-complete',
+          '.page-footer-actions',
+          '.docmd-language-switcher',
+          '.docmd-version-dropdown',
+          '.docmd-project-switcher',
+          // Summer template selectors (no-op in classic โ€” they only
+          // exist when the active template is `summer`).
+          '.summer-content',
+          '.summer-toc',
+          '.summer-pageheader',
+          '.summer-pagenav',
+          '.summer-pagefooter',
+          '#docmd-raw-markdown',
+          '.summer-sidebar nav'
+        ];
+
+        selectorsToSwap.forEach(selector => {
+          const oldEls = document.querySelectorAll(selector);
+          const newEls = doc.querySelectorAll(selector);
+          oldEls.forEach((oldEl, idx) => {
+            const newEl = newEls[idx];
+            if (oldEl && newEl) {
+              oldEl.textContent = '';
+              while (newEl.firstChild) {
+                oldEl.appendChild(newEl.firstChild);
+              }
+            }
+          });
+        });
+
+        // Scroll after the browser has painted the new content.
+        // requestAnimationFrame ensures the swapped innerHTML is in the layout.
+        requestAnimationFrame(() => {
+          if (requestedHash) {
+            try {
+              const target = findTargetElement(requestedHash);
+              if (target) target.scrollIntoView({ behavior: 'smooth' });
+            } catch { /* invalid selector - ignore */ }
+          } else {
+            window.scrollTo(0, 0);
+          }
+        });
+
+        injectCopyButtons();
+        initializeScrollSpy();
+        initializeHeroSliders();
+        const newMainContent = document.querySelector('.main-content');
+        if (newMainContent) executeScripts(newMainContent);
+
+        document.dispatchEvent(new CustomEvent('docmd:page-mounted', { detail: { url: finalUrl } }));
+
+        setTimeout(() => {
+          const newLayout = document.querySelector('.content-layout');
+          if (newLayout) newLayout.style.minHeight = '';
+        }, 100);
+
+      } catch {
+        window.location.assign(url);
+      }
+    }
+    window.docmdNavigate = navigateTo;
+  }
+
+  // 4. BOOTSTRAP
+  function bootstrap() {
+    if (document.body.dataset.bootstrapped === 'true') return;
+    document.body.dataset.bootstrapped = 'true';
+
+    if (localStorage.getItem('docmd-sidebar-collapsed') === 'true') {
+      document.body.classList.add('sidebar-collapsed');
+    }
+
+    document.querySelectorAll('.theme-toggle-button').forEach(btn => {
+      btn.addEventListener('click', () => {
+        const currentTheme = document.documentElement.getAttribute('data-theme');
+        const nextTheme = currentTheme === 'light' ? 'dark' : 'light';
+
+        document.documentElement.setAttribute('data-theme', nextTheme);
+        document.body.setAttribute('data-theme', nextTheme);
+        localStorage.setItem('docmd-theme', nextTheme);
+
+        const lightLink = document.getElementById('hljs-light');
+        const darkLink = document.getElementById('hljs-dark');
+        if (lightLink && darkLink) {
+          lightLink.disabled = nextTheme === 'dark';
+          darkLink.disabled = nextTheme === 'light';
+        }
+      });
+    });
+
+    injectCopyButtons();
+    initializeScrollSpy();
+    initializeHeroSliders();
+    initializeSPA();
+    initBanner();
+    initCookieConsent();
+
+    setTimeout(() => {
+      // PWA Unregistration Safety Net:
+      // If the PWA plugin is removed from docmd.config.js, the  disappears.
+      // We explicitly unregister all ghost service workers to safely kill the offline cache.
+      if ('serviceWorker' in navigator && !document.querySelector('link[rel="manifest"]')) {
+        navigator.serviceWorker.getRegistrations().then(registrations => {
+          registrations.forEach(reg => reg.unregister().catch(() => { }));
+        });
+      }
+
+      const activeNav = document.querySelector('.sidebar-nav a.active');
+      const sidebarNav = document.querySelector('.sidebar-nav');
+      if (activeNav && sidebarNav) {
+        sidebarNav.scrollTo({ top: activeNav.offsetTop - (sidebarNav.clientHeight / 2), behavior: 'instant' });
+      }
+      if (window.location.hash) {
+        try {
+          const target = findTargetElement(window.location.hash);
+          if (target) target.scrollIntoView({ behavior: 'smooth' });
+        } catch { /* ignore */ }
+      }
+    }, 100);
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', bootstrap);
+  } else {
+    bootstrap();
+  }
+})();
+// ---------------------------------------------------------------------------
+// Banner (new in 0.8.7)
+// Per-session dismissable announcement bar. Stored in sessionStorage so a
+// fresh visit re-shows the banner.
+/* global sessionStorage */
+// ---------------------------------------------------------------------------
+function initBanner() {
+  const banner = document.querySelector('[data-docmd-banner]');
+  if (!banner) return;
+  try {
+    if (sessionStorage.getItem('docmd-banner-dismissed') === '1') {
+      banner.remove();
+      return;
+    }
+  } catch (_) { /* sessionStorage blocked โ€” leave visible */ }
+  const closeBtn = banner.querySelector('[data-docmd-banner-dismiss]');
+  if (!closeBtn) return;
+  closeBtn.addEventListener('click', () => {
+    banner.style.transition = 'opacity 0.15s ease, max-height 0.25s ease, padding 0.25s ease, margin 0.25s ease';
+    banner.style.overflow = 'hidden';
+    banner.style.maxHeight = banner.offsetHeight + 'px';
+    // Force reflow before collapsing
+    void banner.offsetHeight;
+    banner.style.opacity = '0';
+    banner.style.maxHeight = '0';
+    banner.style.padding = '0';
+    banner.style.margin = '0';
+    setTimeout(() => {
+      banner.remove();
+      try { sessionStorage.setItem('docmd-banner-dismissed', '1'); } catch (_) { /* ignore */ }
+    }, 260);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Cookie consent (new in 0.8.7)
+// Opt-in. Shows a banner unless a previous choice is stored in
+// localStorage. 'accept' / 'decline' values are persisted.
+// ---------------------------------------------------------------------------
+function initCookieConsent() {
+  const banner = document.querySelector('[data-cookie-consent]');
+  if (!banner) return;
+  const STORAGE_KEY = 'docmd-cookie-consent';
+  const expiryDays = parseInt(banner.getAttribute('data-cookie-expiry') || '180', 10);
+
+  function readChoice() {
+    try {
+      const raw = localStorage.getItem(STORAGE_KEY);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      if (!parsed || !parsed.value || !parsed.expires) return null;
+      if (Date.now() > parsed.expires) {
+        localStorage.removeItem(STORAGE_KEY);
+        return null;
+      }
+      return parsed.value;
+    } catch (_) { return null; }
+  }
+
+  function writeChoice(value) {
+    try {
+      const expires = Date.now() + (expiryDays * 24 * 60 * 60 * 1000);
+      localStorage.setItem(STORAGE_KEY, JSON.stringify({ value, expires, ts: Date.now() }));
+    } catch (_) { /* storage blocked โ€” UI still works for this session */ }
+  }
+
+  if (readChoice()) return; // already chosen
+
+  banner.hidden = false;
+
+  banner.addEventListener('click', (e) => {
+    const t = e.target.closest('[data-cookie-accept], [data-cookie-decline], [data-cookie-dismiss]');
+    if (!t) return;
+    if (t.hasAttribute('data-cookie-accept')) writeChoice('accept');
+    else if (t.hasAttribute('data-cookie-decline')) writeChoice('decline');
+    // dismiss counts as decline-but-silent
+    else if (t.hasAttribute('data-cookie-dismiss')) writeChoice('dismissed');
+    banner.hidden = true;
+    // Fire a CustomEvent so themes/plugins can hook in.
+    try {
+      window.dispatchEvent(new CustomEvent('docmd:cookie-consent', { detail: { value: readChoice() || 'dismissed' } }));
+    } catch (_) { /* ignore */ }
+  });
+}
\ No newline at end of file
diff --git a/packages/ui/package.json b/packages/ui/package.json
new file mode 100644
index 0000000..7315310
--- /dev/null
+++ b/packages/ui/package.json
@@ -0,0 +1,62 @@
+{
+  "name": "@docmd/ui",
+  "version": "0.8.12",
+  "description": "Base UI templates and assets for docmd.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "assets",
+    "translations"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@docmd/api": "workspace:*",
+    "@docmd/tui": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3"
+  },
+  "keywords": [
+    "docmd",
+    "ui",
+    "templates",
+    "assets",
+    "layout",
+    "html",
+    "css",
+    "scss",
+    "kit",
+    "base",
+    "markdown",
+    "minimalist",
+    "zero-config",
+    "site-generator",
+    "static-site-generator",
+    "docs"
+  ],
+  "author": {
+    "name": "Ghazi",
+    "url": "https://mgks.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/docmd-io/docmd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/docmd-io/docmd/issues"
+  },
+  "homepage": "https://docmd.io",
+  "funding": "https://github.com/sponsors/mgks",
+  "license": "MIT"
+}
\ No newline at end of file
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
new file mode 100644
index 0000000..15c9788
--- /dev/null
+++ b/packages/ui/src/index.ts
@@ -0,0 +1,110 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { readFileSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// --- Translation System ---
+
+let translationsCache: Record> = {};
+
+export function getTranslationsDir() {
+    return path.join(__dirname, '..', 'translations');
+}
+
+/**
+ * Load translation strings for a locale. Falls back to English for missing keys.
+ * Supports plugin overrides via the `overrides` parameter.
+ */
+export function loadTranslations(localeId?: string | null, overrides?: Record): Record {
+    const locale = localeId || 'en';
+
+    // Load English as the base (always available)
+    if (!translationsCache['en']) {
+        try {
+            const enPath = path.join(getTranslationsDir(), 'en.json');
+            translationsCache['en'] = JSON.parse(readFileSync(enPath, 'utf8'));
+        } catch {
+            translationsCache['en'] = {};
+        }
+    }
+
+    // Load target locale if not English
+    if (locale !== 'en' && !translationsCache[locale]) {
+        try {
+            const localePath = path.join(getTranslationsDir(), `${locale}.json`);
+            translationsCache[locale] = JSON.parse(readFileSync(localePath, 'utf8'));
+        } catch {
+            translationsCache[locale] = {};
+        }
+    }
+
+    // Merge: English base โ†’ locale overrides โ†’ plugin overrides
+    const strings = {
+        ...translationsCache['en'],
+        ...(locale !== 'en' ? translationsCache[locale] : {}),
+        ...(overrides || {})
+    };
+
+    return strings;
+}
+
+/**
+ * Create a `t()` function for use in templates.
+ * Returns the translated string for a key, falling back to the key itself.
+ * Supports simple interpolation: t('key', { name: 'value' }) replaces {name} in the string.
+ */
+export function createT(strings: Record): (key: string, params?: Record) => string {
+    return (key: string, params?: Record) => {
+        let str = strings[key] || key;
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                str = str.replace(new RegExp(`\\{${k}\\}`, 'g'), v);
+            }
+        }
+        return str;
+    };
+}
+
+/**
+ * Clear the translations cache (useful for dev server rebuilds).
+ */
+export function clearTranslationsCache() {
+    translationsCache = {};
+}
+
+export function getTemplatesDir() {
+    return path.join(__dirname, '..', 'templates');
+}
+
+export function getAssetsDir() {
+    return path.join(__dirname, '..', 'assets');
+}
+
+// Helper to resolve template paths
+export function getTemplatePath(name: string) {
+    const fileName = name.endsWith('.ejs') ? name : `${name}.ejs`;
+    return path.join(__dirname, '..', 'templates', fileName);
+}
+
+// --- Template Resolver (new in 0.8.7) ---
+// Resolves which `.ejs` file to render for a given template slot on a given
+// page, honouring frontmatter / config overrides and falling back to the
+// default templates shipped with @docmd/ui.
+export { resolveTemplate, clearTemplateResolverCache } from './template-resolver.js';
+export type { TemplateSlot, TemplateHook, TemplateResolutionContext, ResolvedTemplate } from '@docmd/api';
\ No newline at end of file
diff --git a/packages/ui/src/template-resolver.ts b/packages/ui/src/template-resolver.ts
new file mode 100644
index 0000000..a61636b
--- /dev/null
+++ b/packages/ui/src/template-resolver.ts
@@ -0,0 +1,259 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  hooks,
+  type TemplateSlot,
+  type TemplateResolutionContext,
+  type ResolvedTemplate,
+} from '@docmd/api';
+
+// Re-export the public types so consumers can `import { ResolvedTemplate } from '@docmd/ui'`.
+export type { TemplateSlot, TemplateHook, TemplateResolutionContext, ResolvedTemplate } from '@docmd/api';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// Default template location (this package ships the default theme).
+// ---------------------------------------------------------------------------
+
+/** Directory containing the default `.ejs` templates shipped with @docmd/ui. */
+const DEFAULT_TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+/** Files in the default templates dir, keyed by slot (file name without `.ejs`). */
+function readDefaultTemplate(slot: TemplateSlot): string | null {
+  // The default templates are stored at /templates/.ejs,
+  // except partials which live under /templates/partials/.ejs.
+  const candidates = [
+    path.join(DEFAULT_TEMPLATES_DIR, `${slot}.ejs`),
+    path.join(DEFAULT_TEMPLATES_DIR, 'partials', `${slot}.ejs`),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Glob matching (tiny, no external dependency)
+// ---------------------------------------------------------------------------
+
+/** Convert a simple glob to a RegExp. Supports `*`, `**`, and `?`. */
+function globToRegExp(glob: string): RegExp {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i++;
+        // Eat following `/` so `**/` doesn't match an empty segment twice.
+        if (glob[i + 1] === '/') i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if ('.+^$()|{}[]\\'.includes(c)) {
+      re += '\\' + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+function matchesAny(input: string, globs: string[] | undefined): boolean {
+  if (!globs || globs.length === 0) return true;
+  for (const g of globs) {
+    if (globToRegExp(g).test(input)) return true;
+  }
+  return false;
+}
+
+function matchesNone(input: string, globs: string[] | undefined): boolean {
+  if (!globs || globs.length === 0) return true;
+  for (const g of globs) {
+    if (globToRegExp(g).test(input)) return false;
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Normalisation of the `template` value
+// ---------------------------------------------------------------------------
+
+/**
+ * A template reference is either:
+ *  - a string (the plugin's package name, e.g. "@docmd/template-summer" or "summer")
+ *  - an object `{ name, pages?, exclude? }`
+ */
+type TemplateRef = string | { name: string; pages?: string[]; exclude?: string[] };
+
+function normaliseTemplateRef(ref: any): { name: string; pages?: string[]; exclude?: string[] } | null {
+  if (!ref) return null;
+  if (typeof ref === 'string') return { name: ref };
+  if (typeof ref === 'object' && typeof ref.name === 'string') return ref;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Public resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve which `.ejs` file should be used for a given slot on a given page.
+ *
+ * Resolution order:
+ *   1. `frontmatter.template` (per-page override, wins everything)
+ *   2. `config.templates` per-section map (e.g. `{ "blog/*": "template-blog" }`)
+ *   3. `config.theme.template` (site-wide default)
+ *   4. Built-in default from `@docmd/ui`
+ *
+ * Any step may be skipped. If a step produces a name that does not match a
+ * registered template, the resolver moves on to the next step. If the
+ * resolved file does not exist on disk, the resolver falls back to the
+ * default and emits a TUI warning once per build.
+ *
+ * @example
+ *   const tpl = resolveTemplate('layout', {
+ *     type: 'layout',
+ *     pagePath: '/guide/intro.html',
+ *     frontmatter: page.frontmatter,
+ *     config: normalizedConfig,
+ *   });
+ *   // โ†’ { templatePath: '/abs/path/to/templates/summer/layout.ejs', source: 'plugin', ... }
+ */
+export function resolveTemplate(ctx: TemplateResolutionContext): ResolvedTemplate {
+  const { type, pagePath, frontmatter, config } = ctx;
+
+  // Strip leading "./" for matching.
+  const pathKey = (pagePath || '').replace(/^\.\//, '/').replace(/^\/+/, '/');
+
+  // The reference (string or object) that points at a template plugin name.
+  const candidates: { ref: ReturnType; source: ResolvedTemplate['source'] }[] = [
+    { ref: normaliseTemplateRef(frontmatter?.template),        source: 'frontmatter' },
+    { ref: matchSectionTemplate(config?.templates, pathKey),  source: 'config' },
+    { ref: normaliseTemplateRef(config?.theme?.template),     source: 'config' },
+  ];
+
+  for (const { ref, source } of candidates) {
+    if (!ref || !ref.name) continue;
+
+    // 1. Look for a registered template plugin that ships this slot.
+    const pluginMatch = findPluginTemplate(type, ref.name, pathKey);
+    if (pluginMatch) {
+      if (fs.existsSync(pluginMatch.templatePath)) {
+        return { ...pluginMatch, source, type };
+      }
+      warnMissingOnce(pluginMatch.templatePath, ref.name, type);
+      // File declared but missing on disk โ€” fall through to default.
+      break;
+    }
+
+    // 2. No plugin matched. If the ref explicitly named a slot override path
+    //    (advanced), allow resolving against the default templates dir.
+    if (ref.name.startsWith('./') || ref.name.startsWith('/')) {
+      const abs = path.isAbsolute(ref.name) ? ref.name : path.join(process.cwd(), ref.name);
+      if (fs.existsSync(abs)) {
+        return { templatePath: abs, source, type };
+      }
+    }
+  }
+
+  // 3. Default fallback.
+  const defaultPath = readDefaultTemplate(type);
+  if (!defaultPath) {
+    // Should never happen for known slots, but fail loudly rather than crash.
+    throw new Error(
+      `[docmd/template] No default template found for slot "${type}". ` +
+      `This is an internal error โ€” please report it at https://github.com/docmd-io/docmd/issues.`
+    );
+  }
+  return { templatePath: defaultPath, source: 'default', type };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+function matchSectionTemplate(
+  templates: Record | undefined,
+  pagePath: string
+): { name: string; pages?: string[]; exclude?: string[] } | null {
+  if (!templates || typeof templates !== 'object') return null;
+  for (const [pattern, ref] of Object.entries(templates)) {
+    if (!globToRegExp(pattern).test(pagePath)) continue;
+    const norm = normaliseTemplateRef(ref);
+    if (norm) return norm;
+  }
+  return null;
+}
+
+function findPluginTemplate(
+  type: TemplateSlot,
+  name: string,
+  pagePath: string
+): ResolvedTemplate | null {
+  // `name` can be a full package (`@docmd/template-summer`), a short name
+  // (`summer`), or a template-* prefixed name (`template-summer`). Strip the
+  // optional `@docmd/` prefix and the `template-` prefix to get the slug.
+  const slug = name
+    .replace(/^@docmd\//, '')
+    .replace(/^template-/, '');
+
+  // Match against registered plugin name. Plugin name is stored on the hook.
+  const matches = hooks.templates
+    .filter((t) => t.type === type)
+    .filter((t) => {
+      const pluginSlug = String((t as any)._pluginName || '')
+        .replace(/^@docmd\//, '')
+        .replace(/^template-/, '');
+      return pluginSlug === slug;
+    })
+    .filter((t) => matchesAny(pagePath, t.pages) && matchesNone(pagePath, t.exclude))
+    .sort((a, b) => (b.priority || 0) - (a.priority || 0));
+
+  if (matches.length === 0) return null;
+  const top = matches[0];
+  return {
+    templatePath: top.templatePath,
+    source: 'plugin',
+    pluginName: (top as any)._pluginName,
+    type,
+  };
+}
+
+// Throttle missing-file warnings to one per build per (plugin, slot) pair.
+const _warnedMissing = new Set();
+function warnMissingOnce(filePath: string, name: string, type: TemplateSlot) {
+  const key = `${name}:${type}:${filePath}`;
+  if (_warnedMissing.has(key)) return;
+  _warnedMissing.add(key);
+  // Lazy import to keep this module side-effect free when unused.
+  import('@docmd/tui').then(({ TUI }) => {
+    TUI.warn(`Template "${name}" declared slot "${type}" but file not found at ${filePath} โ€” using default.`);
+  }).catch(() => {
+    // TUI not available in some test contexts โ€” silently fall back.
+  });
+}
+
+/** Reset the warning cache (useful for dev-server rebuilds). */
+export function clearTemplateResolverCache() {
+  _warnedMissing.clear();
+}
\ No newline at end of file
diff --git a/packages/ui/templates/404.ejs b/packages/ui/templates/404.ejs
new file mode 100644
index 0000000..e5cec82
--- /dev/null
+++ b/packages/ui/templates/404.ejs
@@ -0,0 +1,191 @@
+
+
+
+>
+
+  
+  
+  <%= pageTitle %>
+
+  
+  <%- faviconLinkHtml || '' %>
+
+  
+  
+
+  
+  <% const isDarkDefault = defaultMode === 'dark'; %>
+  >
+  >
+
+  
+  <% if (theme && theme.name !== 'default') { %>
+    
+  <% } %>
+
+  
+  <% (customCssFiles || []).forEach(cssFile => {
+    const cleanPath = cssFile.startsWith('/') ? cssFile.substring(1) : cssFile;
+  %>
+    
+  <% }); %>
+
+  
+  <%- themeInitScript %>
+
+  
+
+
+  
      
+    <% if (logo) { %>
+      <% if (logo.light) { %>
+        
+      <% } %>
+      <% if (logo.dark) { %>
+        
+      <% } %>
+    <% } %>
+
+    
+    
      <%= title || (typeof t === 'function' ? t('pageNotFound') : 'Page not found') %>
      
+    
      <%= content || (typeof t === 'function' ? t('pageNotFoundMsg') : 'The page youโ€™re looking for doesnโ€™t exist or has moved.') %>
      
+    
      
+      
+        
+        <%= typeof t === 'function' ? t('returnHome') : 'Return home' %>
+      
+      
+        
+        <%= typeof t === 'function' ? t('goBack') : 'Go back' %>
+      
+    
      
+  
      
+
+
diff --git a/packages/ui/templates/docmd-search.ejs b/packages/ui/templates/docmd-search.ejs
new file mode 100644
index 0000000..d207c56
--- /dev/null
+++ b/packages/ui/templates/docmd-search.ejs
@@ -0,0 +1,159 @@
+
+
+
+
+  
+    
+    
+    
+    <%- themeInitScript %>
+    
+    
+    <%= pageTitle %><% if (siteTitle && pageTitle !== siteTitle) { %> โ€” <%= siteTitle %><% } %>
+    <%- faviconLinkHtml || '' %>
+    
+    <% if (config.theme?.codeHighlight !== false) { const isDarkDefault = appearance === 'dark'; %>
+    >
+    >
+    <% } %>
+    <%- pluginHeadScriptsHtml || '' %>
+    <% (customCssFiles || []).forEach(cssFile => { %>
+      
+    <% }); %>
+    
+  
+  
+
+    
+
+    <% if (sidebarConfig?.enabled !== false) { %>
+      
+    <% } %>
+
+    
      
+      
+      
      
+        
      
+          
+        
      
+      
      
+
+      
      
+        
      
+          
      
+            
      
+              <%- content %>
+            
      
+          
      
+        
      
+        <%- await include('partials/footer', { footerConfig, config, relativePathToRoot, logo, siteTitle, footerHtml }) %>
+      
      
+    
      
+
+    
+    
      โšก docmd-search
      
+
+    
+    <%- pluginBodyScriptsHtml || '' %>
+    <% (customJsFiles || []).forEach(jsFile => {
+      if (jsFile && jsFile.trim() !== '') { %>
+      
+    <% }
+    }); %>
+
+    
+  
+
\ No newline at end of file
diff --git a/packages/ui/templates/layout.ejs b/packages/ui/templates/layout.ejs
new file mode 100644
index 0000000..31ea194
--- /dev/null
+++ b/packages/ui/templates/layout.ejs
@@ -0,0 +1,327 @@
+
+
+
+>
+  
+    
+    
+    
+    <%- themeInitScript %>
+    
+    <% let versionRoot='/' ; let siteRoot=relativePathToRoot; 
+      const _locPfx = (typeof localePrefix !== 'undefined' && localePrefix) ? localePrefix : '';
+      if (config.versions?.current && config._activeVersion?.id) {
+      const isSubVersion=config.versions.current !==config._activeVersion.id; 
+      versionRoot= '/' + _locPfx + (isSubVersion ? config._activeVersion.id + '/' : '');
+      if (isSubVersion) { siteRoot=(relativePathToRoot==='./' ? '' :
+        relativePathToRoot) + '../' ; } } else if (_locPfx) { versionRoot = '/' + _locPfx; }
+      if (locals.isOfflineMode) { versionRoot='' ;
+      }
+    %>
+    
+    
+      <%= pageTitle %><% if (siteTitle && pageTitle !== siteTitle && !(frontmatter && frontmatter.titleAppend === false)) { %> : <%= siteTitle %><% } %>
+    
+
+    
+    <%- faviconLinkHtml || '' %>
+    
+    <% if (config.theme?.codeHighlight !==false) { const isDarkDefault=appearance==='dark' ; %>
+    >
+    >
+    <% } %>
+    <%- pluginHeadScriptsHtml || '' %>
+    <% (customCssFiles || []).forEach(cssFile=> { %>
+      
+    <% }); %>
+    <%- themeInitScript %>
+  
+   data-source-file="<%= sourceFile %>"<% } %>>
+
+    
+
+    <% if (locals.menubarConfig && menubarConfig?.enabled !==false && menubarConfig.position !=='header' ) { %>
+      <%- await include('partials/menubar', {
+        menubarConfig, relativePathToRoot, renderIcon, optionsMenu: locals.optionsMenu, t: typeof t === 'function' ? t : null
+      }) %>
+    <% } %>
+    <% if (sidebarConfig?.enabled !==false) { %>
+      
+      <% } %>
+      <%# Site-wide announcement banner (new in 0.8.7). Sits above the menubar. %>
+      <% if (locals.config && config.layout && config.layout.banner) { %>
+        <%- await include('partials/banner', { config, relativePathToRoot, renderIcon, t: typeof t === 'function' ? t : null }) %>
+      <% } %>
+      
      
+        <% if (locals.menubarConfig && menubarConfig?.enabled !==false && menubarConfig.position==='header' ) { %>
+          <%- await include('partials/menubar', { menubarConfig, relativePathToRoot, renderIcon, optionsMenu:
+            locals.optionsMenu, t: typeof t === 'function' ? t : null }) %>
+        <% } %>
+        <% if (headerConfig?.enabled !==false) { %>
+          
      
+            
      
+              <% if (sidebarConfig?.collapsible) { %>
+                
+              <% } %>
+              
      
+                
+                  <%= pageTitle %>
+                
+              
      
+            
      
+            
      
+              <% if (optionsMenu?.position==='header' ) { %>
+                <%- await include('partials/options-menu', { optionsMenu, allLocales: locals.allLocales, activeLocale: locals.activeLocale, defaultLocale: locals.defaultLocale, config: locals.config, renderIcon, currentPagePath: locals.currentPagePath, localePrefix: locals.localePrefix, workspace, t: typeof t === 'function' ? t : null }) %>
+              <% } %>
+            
      
+          
      
+        <% } %>
+        
      
+          
      
+            
      
+              
      
+                
      
+                  
+                  <% if (config.layout?.breadcrumbs !== false && locals.breadcrumbs && breadcrumbs.length > 0) { %>
+                    
+                  <% } else { %>
+                    
      
+                  <% } %>
+
+                  <% if (config.theme?.copyWidgets?.enabled !== false) { %>
+                    
      
+                      <% if (config.theme?.copyWidgets?.raw !== false) { %>
+                        
+                      <% } %>
+                      <% if (config.theme?.copyWidgets?.context !== false) { %>
+                        
+                      <% } %>
+                    
      
+                  <% } %>
+                
      
+                <% if (headerConfig?.enabled===false) { %>
+                  
      
+                    <%= pageTitle %>
+                  
      
+                <% } %>
+                <%- content %>
+                <% if (config.pageNavigation && (prevPage || nextPage)) { %>
+                  
      
+                    <% if (prevPage) { %>
+                      
+                        <%- renderIcon('arrow-left', { class: 'page-nav-icon' }) %>
+                        <%= typeof t === 'function' ? t('previous') : 'Previous' %>
+                            <%= prevPage.title %>
+                          
+                      
+                    <% } else { %>
+                      
      
+                      
      
+                    <% } %>
+                    <% if (nextPage) { %>
+                      
+                        <%= typeof t === 'function' ? t('next') : 'Next' %>
+                          
+                            <%= nextPage.title %>
+                          
+                        <%- renderIcon('arrow-right', { class: 'page-nav-icon' }) %>
+                      
+                    <% } else { %>
+                      
      
+                      
      
+                    <% } %>
+                  
      
+                <% } %>
+              
      
+              
      
+                <%- await include('toc', { content, headings, navigationHtml, isActivePage, t: typeof t === 'function' ? t : null }) %>
+              
      
+            
      
+            
      
+              <%# Git Plugin: Last updated timestamp (core plugin, always inject) %>
+              <% if (locals.frontmatter && locals.frontmatter._git && locals.frontmatter._git.lastUpdatedTimestamp) { %>
+                
+                  
+                    
+                    
+                  
+                  <%= typeof t === 'function' ? t('lastUpdated') : 'Last updated' %>:
+                  
+                  <% if (locals.frontmatter._git.commits && locals.frontmatter._git.commits.length > 0) { %>
+                  
+                  <% } %>
+                
+              <% } %>
+              
+              <% if (locals.editUrl) { %>
+                
+                  <%- renderIcon('pencil') %>
+                  <%= editLinkText %>
+                
+              <% } %>
+            
      
+          
      
+          <%- await include('partials/footer', { footerConfig, config, relativePathToRoot, logo, siteTitle,
+            footerHtml, t: typeof t === 'function' ? t : null }) %>
+        
      
+      
      
+      <% if (locals.allLocales && allLocales && allLocales.length > 1) { %>
+      
+      <% } %>
+      
+      <%# Git Plugin core JS (injected directly since git is a core plugin) %>
+      
+      <%- pluginBodyScriptsHtml || '' %>
+      <% (customJsFiles || []).forEach(jsFile=> {
+        if (jsFile && jsFile.trim() !== '') { %>
+        
+        <% }
+      }); %>
+      <%# Cookie consent dialog (new in 0.8.7). Rendered only when config.cookie is set. %>
+      <% if (locals.config && config.cookie && config.cookie.enabled !== false) { %>
+        <%- await include('partials/cookie-consent', { config, relativePathToRoot, renderIcon, t: typeof t === 'function' ? t : null }) %>
+      <% } %>
+  
+
\ No newline at end of file
diff --git a/packages/ui/templates/navigation.ejs b/packages/ui/templates/navigation.ejs
new file mode 100644
index 0000000..c54ef88
--- /dev/null
+++ b/packages/ui/templates/navigation.ejs
@@ -0,0 +1,99 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # @website https://docmd.io
+  # [docmd-source] - Please do not remove this header.
+  # ---------------------------------------------------------------
+%>
+
+
\ No newline at end of file
diff --git a/packages/ui/templates/no-style.ejs b/packages/ui/templates/no-style.ejs
new file mode 100644
index 0000000..43c6bdd
--- /dev/null
+++ b/packages/ui/templates/no-style.ejs
@@ -0,0 +1,250 @@
+
+
+
+>
+
+
+  
+  
+  
+
+  <%- '' %>
+
+  <% if (locals.allLocales && locals.allLocales.length > 1 && !locals.i18nStringMode) { %>
+  <%
+    var i18nData = {
+      default: locals.defaultLocale || "",
+      locales: (locals.allLocales || []).map(function(l) {
+        return { id: l.id, label: l.label || l.id, dir: l.dir || "ltr" };
+      }),
+      inPlace: locals.i18nInPlace || false
+    };
+  %>
+  
+  <%- '' %>
+  <% } %>
+
+  
+  <% if (frontmatter.components?.meta !==false) { %>
+    <%- metaTagsHtml || '' %>
+      
+        <%= pageTitle %>
+        <% if (frontmatter.components?.siteTitle !==false && siteTitle && pageTitle !== siteTitle && !(frontmatter && frontmatter.titleAppend === false)) { %> : <%= siteTitle %>
+        <% } %>
+      
+      <% if (description && !(metaTagsHtml && metaTagsHtml.includes('name="description"'))) { %>
+        
+      <% } %>
+  <% } %>
+
+  
+  <% if (frontmatter.components?.favicon !== false) { %>
+    <%- faviconLinkHtml || '' %>
+  <% } %>
+
+  
+  <% if (frontmatter.components?.css !== false) { %>
+    
+
+    
+    <% if (frontmatter.components?.highlight !== false) { 
+      const isDarkDefault = defaultMode === ' dark'; %>
+      >
+
+      >
+    <% } %>
+  <% } %>
+
+  
+  <% if (frontmatter.components?.pluginHeadScripts !==false) { %>
+    <%- pluginHeadScriptsHtml || '' %>
+  <% } %>
+
+  
+  <% if (frontmatter.components?.theme !==false) { %>
+    <%- themeCssLinkHtml || '' %>
+  <% } %>
+
+  
+  <% if (frontmatter.components?.customCss !==false && customCssFiles && customCssFiles.length> 0) { %>
+    <% customCssFiles.forEach(cssFile=> { %>
+      
+    <% }); %>
+  <% } %>
+
+  
+  <% if (frontmatter.components?.pluginStyles !==false) { %>
+    <%- pluginStylesHtml || '' %>
+  <% } %>
+
+  
+  <% if (frontmatter.components?.themeMode !==false) { %>
+    <%- themeInitScript %>
+  <% } %>
+
+  
+  <% if (frontmatter.customHead) { %>
+    <%- frontmatter.customHead %>
+  <% } %>
+
+ data-theme="<%= defaultMode %>"<% } %>
+  <% if (frontmatter.bodyClass) { %> class="<%= frontmatter.bodyClass %>"<% } %> data-copy-code-enabled="<%=
+    config.copyCode===true %>" data-spa-enabled="<%= frontmatter.components?.spa === true %>">
+  <% if (frontmatter.components?.menubar === true && (locals.menubarConfig && menubarConfig?.enabled !== false)) { %>
+    <%- await include('partials/menubar', { menubarConfig, relativePathToRoot, renderIcon, optionsMenu: locals.optionsMenu }) %>
+  <% } %>
+
+    <% if (frontmatter.components?.layout===true || frontmatter.components?.layout==='full' ) { %>
+      
      
+        <% if (frontmatter.components?.header !==false) { %>
+          
      
+            <% if (frontmatter.components?.pageTitle !==false) { %>
+              
      
+                <%= pageTitle %>
+              
      
+            <% } %>
+          
      
+        <% } %>
+        
      
+          
      
+            
      <%- content %>
      
+            <% if (frontmatter.components?.toc !==false && headings && headings.length> 0) { %>
+              
      
+                <%- await include('toc', { content, headings, navigationHtml, isActivePage }) %>
+              
      
+            <% } %>
+          
      
+        
      
+        <% if (frontmatter.components?.footer !==false) { %>
+          
      
+            
      
+              
      <%- footerHtml || '' %>
      
+              <% if (frontmatter.components?.branding !==false) { %>
+                
      
+                  Build with 
+                    
+                    
+                    
+                    
+                    
+                    
+                   docmd.
+                
      
+              <% } %>
+            
      
+          
      
+        <% } %>
+      
      
+    <% } else if (frontmatter.components?.sidebar===true) { %>
+      
+      
      
+        <% if (frontmatter.components?.header !==false) { %>
+          
      
+            <% if (frontmatter.components?.pageTitle !==false) { %>
+              
      
+                <%= pageTitle %>
+              
      
+            <% } %>
+          
      
+        <% } %>
+        
      
+          
      
+            
      <%- content %>
      
+            <% if (frontmatter.components?.toc !==false && headings && headings.length> 0) { %>
+              
      
+                <%- await include('toc', { content, headings, navigationHtml, isActivePage }) %>
+              
      
+            <% } %>
+          
      
+        
      
+        <% if (frontmatter.components?.footer !==false) { %>
+          
      
+            
      
+              
      <%- footerHtml || '' %>
      
+              <% if (frontmatter.components?.branding !==false) { %>
+                
      
+                  Build with 
+                    
+                    
+                    
+                    
+                   docmd.
+                
      
+              <% } %>
+            
      
+          
      
+        <% } %>
+      
      
+    <% } else { %>
+      <%- content %>
+    <% } %>
+
+    <% if (frontmatter.components?.scripts===true) { %>
+      <% if (frontmatter.components?.mainScripts===true) { %>
+        <%- '' %>
+        
+      <% } %>
+
+      <% if (frontmatter.components?.lightbox===true && frontmatter.components?.mainScripts===true) { %>
+        
+      <% } %>
+
+      <% if (frontmatter.components?.customJs===true && customJsFiles && customJsFiles.length> 0) { %>
+        <% customJsFiles.forEach(jsFile=> { %>
+          
+        <% }); %>
+      <% } %>
+
+      <% if (frontmatter.components?.scripts !==false) { %>
+        <%- pluginBodyScriptsHtml || '' %>
+      <% } %>
+    <% } %>
+
+    <% if (frontmatter.customScripts) { %>
+      <%- frontmatter.customScripts %>
+    <% } %>
+
+    <% if (locals.allLocales && locals.allLocales.length > 1 && !locals.i18nStringMode) { %>
+    
+    <% } %>
+  
+
\ No newline at end of file
diff --git a/packages/ui/templates/partials/banner.ejs b/packages/ui/templates/partials/banner.ejs
new file mode 100644
index 0000000..2c2da40
--- /dev/null
+++ b/packages/ui/templates/partials/banner.ejs
@@ -0,0 +1,78 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # Site-wide announcement banner.
+  #
+  # Rendered when `config.layout.banner` is set. Sits above the menubar
+  # (or above the sidebar's logo bar when menubar is in-header). The
+  # banner is purely presentational โ€” the inner content is rendered as
+  # raw HTML so authors can include links and inline emphasis.
+  #
+  # Configuration:
+  #   {
+  #     "layout": {
+  #       "banner": {
+  #         "content": "**v0.9 ships Friday** โ€” read the announcement.",
+  #         "type": "info",                    // "info" | "success" | "warning" | "danger"
+  #         "dismissible": true,               // user can close per-session
+  #         "link": { "text": "Read more", "url": "/blog/v0-9" },
+  #         "icon": "megaphone"                // lucide icon name (optional)
+  #       }
+  #     }
+  #   }
+  #
+  # The `dismissible` choice is stored in `sessionStorage` so the banner
+  # reappears on a fresh visit but stays dismissed for the current
+  # browsing session.
+  # ---------------------------------------------------------------
+%>
+<% const banner = (typeof config !== 'undefined' && config.layout && config.layout.banner) || null; %>
+<% if (banner && (banner.content || banner.link)) { %>
+<%
+  const _bType = banner.type || 'info';
+  const _bDismissible = banner.dismissible !== false;
+  const _bIcon = banner.icon || null;
+  const _bLink = banner.link || null;
+  // Lightweight inline-MD: only **bold** and `code` get a pass-through here.
+  // For richer content, set banner.html to a raw HTML string.
+  let _bInner = banner.html || banner.content || '';
+  if (!banner.html) {
+    _bInner = _bInner
+      .replace(/&/g, '&')
+      .replace(//g, '>')
+      .replace(/\*\*([^*]+)\*\*/g, '$1')
+      .replace(/`([^`]+)`/g, '$1');
+    // Restore  if user provided `link` โ€” leave that to the template.
+  }
+%>
+
      
+  
      
+    <% if (_bIcon) { %>
+      
+    <% } %>
+    
      
+      <%# _bInner is already HTML-escaped + bold/code-converted above; rendering
+          raw is intentional so the converted HTML reaches the page. %>
+      <%- _bInner %> <%# audit-ignore %>
+      <% if (_bLink && _bLink.url) { %>
+        
+          <%- _bLink.text || (typeof t === 'function' ? t('readMore') : 'Read more') %>
+          <%- renderIcon('arrow-right', { class: 'docmd-banner__link-icon' }) %>
+        
+      <% } %>
+    
      
+    <% if (_bDismissible) { %>
+      
+    <% } %>
+  
      
+
      
+<% } %>
\ No newline at end of file
diff --git a/packages/ui/templates/partials/cookie-consent.ejs b/packages/ui/templates/partials/cookie-consent.ejs
new file mode 100644
index 0000000..234efc8
--- /dev/null
+++ b/packages/ui/templates/partials/cookie-consent.ejs
@@ -0,0 +1,71 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # Cookie consent dialog.
+  #
+  # Rendered only when `config.cookie` is set (opt-in). The companion
+  # CSS lives in `docmd-main.css`; the persistence + UI logic lives in
+  # `docmd-main.js`. Both are overridable by templates via the standard
+  # CSS / JS asset priority system, but never by customCss (which always
+  # wins).
+  #
+  # Configuration:
+  #   {
+  #     "cookie": {
+  #       "enabled": true,                     // default: true
+  #       "message": "...",                    // default: translation key `cookieMessage`
+  #       "acceptText": "Accept",              // default: translation key `cookieAccept`
+  #       "declineText": "Decline",            // default: translation key `cookieDecline`
+  #       "policyUrl": "/privacy",             // optional
+  #       "position": "bottom",                // "bottom" | "bottom-left" | "bottom-right" | "center"
+  #       "dismissible": true,                 // show a close (X) button
+  #       "expiryDays": 180                    // localStorage TTL
+  #     }
+  #   }
+  # ---------------------------------------------------------------
+%>
+<% const cookie = (typeof config !== 'undefined' && config.cookie) || null; %>
+<% if (cookie && cookie.enabled !== false) { %>
+<%
+  const _cMsg = cookie.message || (typeof t === 'function' ? t('cookieMessage') : 'This site uses cookies to ensure you get the best experience.');
+  const _cAccept = cookie.acceptText || (typeof t === 'function' ? t('cookieAccept') : 'Accept');
+  const _cDecline = cookie.declineText || (typeof t === 'function' ? t('cookieDecline') : 'Decline');
+  const _cPos = cookie.position || 'bottom';
+  const _cDismissible = cookie.dismissible !== false;
+  const _cPolicy = cookie.policyUrl || null;
+  const _cExpiry = cookie.expiryDays || 180;
+%>
+
+<% } %>
\ No newline at end of file
diff --git a/packages/ui/templates/partials/footer.ejs b/packages/ui/templates/partials/footer.ejs
new file mode 100644
index 0000000..28244a3
--- /dev/null
+++ b/packages/ui/templates/partials/footer.ejs
@@ -0,0 +1,59 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # @website https://docmd.io
+  # [docmd-source] - Please do not remove this header.
+  # ---------------------------------------------------------------
+%>
+
+<% if (footerConfig?.style === 'complete') { %>
+
      
+  
      
+      
      
+          <% if (logo && logo.light && logo.dark) { %>
+            
+              <%= logo.alt || siteTitle %>
+              <%= logo.alt || siteTitle %>
+            
+          <% } else { %>
+            <%= siteTitle %>
+          <% } %>
+          <% if (footerConfig.description) { %>
+            
      <%= footerConfig.description %>
      
+          <% } %>
+        
      
+        <% if (footerConfig.columns && footerConfig.columns.length > 0) { %>
+          
      
+            <% footerConfig.columns.forEach(col => { %>
+              
      
+                <%= typeof t === 'function' ? t(col.title) : col.title %>
+                
+              
      
+            <% }) %>
+          
      
+        <% } %>
+      
      
+      
      
+        
      <%- footerHtml || (footerConfig.copyright ? footerConfig.copyright : '') %>
      
+        <% if (footerConfig.branding !== false) { %>
+          
      
+            <%= typeof t === 'function' ? t('builtWith') : 'Built with' %>  docmd.
+          
      
+        <% } %>
+      
      
+  
      
+<% } else { %>
+
      
+  
      
+    
      <%- footerHtml || (footerConfig?.copyright ? footerConfig.copyright : '') %>
      
+    <% if (footerConfig?.branding !== false) { %>
+      
      
+        <%= typeof t === 'function' ? t('builtWith') : 'Built with' %>  docmd.
+      
      
+    <% } %>
+  
      
+
      
+<% } %>
\ No newline at end of file
diff --git a/packages/ui/templates/partials/language-switcher.ejs b/packages/ui/templates/partials/language-switcher.ejs
new file mode 100644
index 0000000..84f9bb5
--- /dev/null
+++ b/packages/ui/templates/partials/language-switcher.ejs
@@ -0,0 +1,84 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # @website https://docmd.io
+  # [docmd-source] - Please do not remove this header.
+  # ---------------------------------------------------------------
+%>
+
+<% if (allLocales && allLocales.length > 1) { 
+  const current = activeLocale || allLocales.find(l => l.id === defaultLocale);
+  const isCompact = typeof compact !== 'undefined' && compact;
+
+  // Compute current page path relative to locale root
+  // Strip the active locale prefix if present (outputPrefix bakes it into navPath now)
+  let pagePath = (typeof currentPagePath !== 'undefined' && currentPagePath) ? currentPagePath.replace(/^\//, '') : '';
+  const activeLocaleId = activeLocale ? activeLocale.id : null;
+  if (activeLocaleId && activeLocaleId !== defaultLocale && pagePath.startsWith(activeLocaleId + '/')) {
+    pagePath = pagePath.slice(activeLocaleId.length + 1);
+  }
+
+  // Get the active version prefix if versioning is active
+  const activeVersion = config._activeVersion;
+  const currentVersionId = config.versions && config.versions.current;
+  const isOldVersion = activeVersion && currentVersionId && activeVersion.id !== currentVersionId;
+  const versionPrefix = isOldVersion ? activeVersion.id + '/' : '';
+
+  // Strip version prefix from pagePath if it's already baked in (avoids duplication)
+  if (versionPrefix && pagePath.startsWith(versionPrefix)) {
+    pagePath = pagePath.slice(versionPrefix.length);
+  }
+
+  // Determine which locales are available for this version
+  // Old versions without locale subdirectories only support the default locale
+  const versionHasI18n = !isOldVersion || (typeof config._versionHasI18n !== 'undefined' ? config._versionHasI18n : !isOldVersion);
+%>
+
      
+  
+  
+
      
+<% } %>
\ No newline at end of file
diff --git a/packages/ui/templates/partials/menubar.ejs b/packages/ui/templates/partials/menubar.ejs
new file mode 100644
index 0000000..b613d63
--- /dev/null
+++ b/packages/ui/templates/partials/menubar.ejs
@@ -0,0 +1,134 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # @website https://docmd.io
+  # [docmd-source] - Please do not remove this header.
+  # ---------------------------------------------------------------
+%>
+
+<% 
+function menubarHref(item) { 
+  return item.external ? item.url : buildRelativeUrl(item.url); 
+}
+function menubarTarget(item) { 
+  // Only open in new tab if user explicitly adds external: prefix
+  // Users who want their own docs site to open in new tab should add external: prefix
+  return item.external ? ' target="_blank" rel="noopener noreferrer"' : '' ; 
+}
+%>
+
+
      
+  
      
+    
      
+    <% if (menubarConfig.left && menubarConfig.left.length> 0) { %>
+        <% menubarConfig.left.forEach(item=> { %>
+          <% if (item.type==='title' ) { %>
+            >
+              <% if (item.icon) { %>
+                <%- renderIcon(item.icon, { class: 'menubar-icon' }) %>
+              <% } %>
+              <% if (item.text) { %>
+                
+                  <%= item.text %>
+                
+              <% } %>
+            
+            <% } else if (item.type==='dropdown' ) { %>
+              
      
+                
+                
+              
      
+              <% } else { %>
+                >
+                  <% if (item.icon) { %>
+                    <%- renderIcon(item.icon, { class: 'menubar-icon' }) %>
+                  <% } %>
+                  
+                    <%= item.text %>
+                  
+                  <% if (item.external) { %>
+                    <%- renderIcon('external-link', { class: 'menubar-ext-icon' }) %>
+                  <% } %>
+                
+              <% } %>
+        <% }) %>
+    <% } %>
+      
      
+      
      
+        <% if (menubarConfig.right && menubarConfig.right.length> 0) { %>
+          <% menubarConfig.right.forEach(item=> { %>
+            <% if (item.type==='dropdown' ) { %>
+              
      
+                
+                
+              
      
+            <% } else { %>
+              >
+                <% if (item.icon) { %>
+                  <%- renderIcon(item.icon, { class: 'menubar-icon' }) %>
+                <% } %>
+                
+                  <%= item.text %>
+                
+                <% if (item.external) { %>
+                  <%- renderIcon('external-link', { class: 'menubar-ext-icon' }) %>
+                <% } %>
+              
+            <% } %>
+          <% }) %>
+        <% } %>
+        <% if (optionsMenu && optionsMenu.position==='menubar' ) { %>
+          
      
+            <%- await include('options-menu', { optionsMenu, allLocales: locals.allLocales, activeLocale: locals.activeLocale, defaultLocale: locals.defaultLocale, config: locals.config, renderIcon, currentPagePath: locals.currentPagePath, localePrefix: locals.localePrefix, workspace: locals.workspace }) %>
+          
      
+        <% } %>
+    
      
+  
      
+
      
\ No newline at end of file
diff --git a/packages/ui/templates/partials/options-menu.ejs b/packages/ui/templates/partials/options-menu.ejs
new file mode 100644
index 0000000..7667046
--- /dev/null
+++ b/packages/ui/templates/partials/options-menu.ejs
@@ -0,0 +1,42 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # @website https://docmd.io
+  # [docmd-source] - Please do not remove this header.
+  # ---------------------------------------------------------------
+%>
+
+<% if (optionsMenu && optionsMenu.components) { %>
+
      
+    <% if (optionsMenu.components.search !== false) { %>
+    
+    <% } %>
+
+    <% if (locals.workspace && workspace.switcher.enabled && workspace.switcher.position === 'options-menu') { %>
+    
      
+        <%- await include('project-switcher', { workspace, config, renderIcon, compact: true }) %>
+    
      
+    <% } %>
+
+    <% if (locals.allLocales && allLocales && allLocales.length > 1 && locals.config && config.i18n && config.i18n.position === 'options-menu') { %>
+    
      
+        <%- await include('language-switcher', { allLocales, activeLocale: locals.activeLocale, defaultLocale: locals.defaultLocale, config, renderIcon, compact: true, currentPagePath: locals.currentPagePath, localePrefix: locals.localePrefix }) %>
+    
      
+    <% } %>
+
+    <% if (optionsMenu.components.themeSwitch !== false) { %>
+    
+    <% } %>
+
+    <% if (optionsMenu.components.sponsor) { %>
+    
+    <% } %>
+
      
+<% } %>
\ No newline at end of file
diff --git a/packages/ui/templates/partials/project-switcher.ejs b/packages/ui/templates/partials/project-switcher.ejs
new file mode 100644
index 0000000..1dfeb64
--- /dev/null
+++ b/packages/ui/templates/partials/project-switcher.ejs
@@ -0,0 +1,78 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # @website https://docmd.io
+  # [docmd-source] - Please do not remove this header.
+  # ---------------------------------------------------------------
+%>
+
+<% 
+if (locals.workspace && workspace.projects && workspace.projects.length > 0) { 
+  const currentPrefix = config._activePrefix || '/';
+  const switcherConfig = workspace.switcher || { enabled: true, position: 'sidebar-top' };
+  
+  if (switcherConfig.enabled !== false) {
+    const isCompact = typeof compact !== 'undefined' && compact;
+    const currentProject = workspace.projects.find(p => {
+        const pfx = p.prefix === '/' ? '/' : p.prefix.replace(/\/$/, '');
+        return pfx === currentPrefix;
+    }) || workspace.projects[0];
+
+    const getProjectLabel = (p) => {
+        if (p.title) return p.title;
+        // Fallback: Use the last part of the source directory as a title if prefix is root
+        if (p.prefix === '/' || !p.prefix.replace(/^\//, '')) {
+            const srcParts = p.src.split(/[\/\\]/);
+            const raw = srcParts[srcParts.length - 1];
+            return raw.split(/[\/-]/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+        }
+        // Fallback for subprojects: use the prefix
+        return p.prefix.replace(/^\//, '').split(/[\/-]/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+    };
+%>
+
      
+  
+  
        
+    <% workspace.projects.forEach(project => { 
+      const itemPfx = project.prefix === '/' ? '/' : project.prefix.replace(/\/$/, '');
+      const isCurrentActive = itemPfx === currentPrefix;
+      
+      // Calculate Workspace Base (Domain Root -> Workspace Root)
+      // config.base includes the current project's prefix. We need to strip it to find the workspace root.
+      const normalizedBase = (config.base || '/').replace(/\/?$/, '');
+      const normalizedActivePrefix = currentPrefix.replace(/\/?$/, '');
+      const workspaceBase = normalizedBase.endsWith(normalizedActivePrefix) 
+        ? normalizedBase.substring(0, normalizedBase.length - normalizedActivePrefix.length)
+        : normalizedBase;
+
+      const projectPfx = project.prefix.startsWith('/') ? project.prefix : '/' + project.prefix;
+      let absoluteHref = (workspaceBase + projectPfx).replace(/\/{2,}/g, '/') || '/';
+      if (project.prefix !== '/' && !absoluteHref.endsWith('/')) {
+        absoluteHref += '/';
+      }
+    %>
+    
      • 
+      
+        <%= getProjectLabel(project) %>
+        <% if (project.prefix !== '/') { %>
+          <%= project.prefix %>
+        <% } %>
+        <% if (isCurrentActive) { %>
+          <%- renderIcon('check', { class: 'project-check' }) %>
+        <% } %>
+      
+    
        • 
+    <% }) %>
+  
      
+
      
+<% 
+  }
+} 
+%>
\ No newline at end of file
diff --git a/packages/ui/templates/partials/theme-init.js b/packages/ui/templates/partials/theme-init.js
new file mode 100644
index 0000000..8e4c40f
--- /dev/null
+++ b/packages/ui/templates/partials/theme-init.js
@@ -0,0 +1,66 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
+(function () {
+  try {
+    // 1. Determine Theme
+    //
+    // Resolve from three sources, in priority order:
+    //   1. localStorage explicit user choice (light / dark)
+    //   2. window.DOCMD_APPEARANCE  (current canonical name, set by EJS templates)
+    //   3. window.DOCMD_DEFAULT_MODE (legacy alias kept for pre-0.8.7 outputs)
+    //   4. 'light' as the final fallback
+    //
+    // Note: localStorage is only honoured when it holds an explicit
+    // 'light' or 'dark' value. A stored 'system' value (from a prior
+    // session where the user picked "follow system") must NOT win over
+    // a freshly resolved config value โ€” the resolved value will itself
+    // be 'system' in that case and the OS preference check below takes
+    // over, so this is a no-op for the in-session behaviour but keeps
+    // any future storage migration simple.
+    var localValue = localStorage.getItem('docmd-theme');
+    var configValue = window.DOCMD_APPEARANCE
+      || window.DOCMD_DEFAULT_MODE
+      || 'light';
+    var theme = (localValue === 'light' || localValue === 'dark')
+      ? localValue
+      : configValue;
+
+    if (theme === 'system') {
+      theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+
+    // 2. Apply to Root
+    document.documentElement.setAttribute('data-theme', theme);
+
+    // 3. Highlight.js Toggle Strategy
+    var lightLink = document.getElementById('hljs-light');
+    var darkLink = document.getElementById('hljs-dark');
+
+    if (lightLink && darkLink) {
+      if (theme === 'dark') {
+        lightLink.disabled = true;
+        darkLink.disabled = false;
+      } else {
+        lightLink.disabled = false;
+        darkLink.disabled = true;
+      }
+    }
+
+    document.documentElement.style.visibility = "visible";
+  } catch (e) {
+    document.documentElement.style.visibility = "visible";
+    console.error('Theme init failed', e);
+  }
+})();
\ No newline at end of file
diff --git a/packages/ui/templates/partials/version-dropdown.ejs b/packages/ui/templates/partials/version-dropdown.ejs
new file mode 100644
index 0000000..68b07db
--- /dev/null
+++ b/packages/ui/templates/partials/version-dropdown.ejs
@@ -0,0 +1,59 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # @website https://docmd.io
+  # [docmd-source] - Please do not remove this header.
+  # ---------------------------------------------------------------
+%>
+
+<% if (versions && versions.all.length > 0) { 
+  const current = activeVersion || versions.all.find(v => v.id === versions.current);
+    
+  // If we are in a sub-version (e.g. /v1/), we go up one level (../) to get to root.
+  const isCurrentSubVersion = current && current.id !== versions.current;
+  const upOneLevel = isCurrentSubVersion ? '../' : '';
+%>
+
      
+  
+  
        
+    <% versions.all.forEach(v => { 
+      const isCurrentActive = current && v.id === current.id;
+      const isTargetRootVersion = v.id === versions.current;
+
+      // Include locale prefix for non-default locales
+      const locPrefix = (typeof localePrefix !== 'undefined' && localePrefix) ? localePrefix : '';
+
+      // Include locale prefix only if the target version has i18n for this locale
+      const versionI18nMap = config._versionI18nMap || {};
+      const targetHasLocale = locPrefix ? versionI18nMap[v.id] !== false : true;
+      const effectiveLocPrefix = targetHasLocale ? locPrefix : '';
+      const targetSuffix = isTargetRootVersion ? '' : v.id + '/';
+
+      // Use centralised URL builder โ€” single source of truth
+      const absoluteHref = (typeof buildAbsoluteUrl === 'function')
+        ? buildAbsoluteUrl(config.base || '/', effectiveLocPrefix, targetSuffix, '')
+        : ((config.base || '/').replace(/\/?$/, '/') + effectiveLocPrefix + targetSuffix);
+
+      // Data Root for JS Sticky Logic
+      const dataRoot = absoluteHref;
+    %>
+    
      • 
+      
+        <%= v.label %><% if (v.id === versions.current) { %> <%= typeof t === 'function' ? t('latest') : 'Latest' %><% } %>
+        <% if (isCurrentActive) { %>
+          <%- renderIcon('check', { class: 'version-check' }) %>
+        <% } %>
+      
+    
        • 
+    <% }) %>
+  
      
+
      
+<% } %>
\ No newline at end of file
diff --git a/packages/ui/templates/toc.ejs b/packages/ui/templates/toc.ejs
new file mode 100644
index 0000000..379ee65
--- /dev/null
+++ b/packages/ui/templates/toc.ejs
@@ -0,0 +1,43 @@
+<%# ---------------------------------------------------------------
+  # docmd : the zero-config documentation engine.
+  # @website https://docmd.io
+  # [docmd-source] - Please do not remove this header.
+  # ---------------------------------------------------------------
+%>
+
+<% 
+function decodeHtmlEntities(html) {
+  return html.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, "'").replace(/ /g, ' ');
+}
+const shouldShowToc = typeof isActivePage !== 'undefined' ? isActivePage : 
+                      (typeof navigationHtml !== 'undefined' && navigationHtml && navigationHtml.includes('class="active"'));
+
+if (shouldShowToc && !frontmatter?.toc || frontmatter?.toc !== 'false') {
+  let tocHeadings = [];
+  if (headings && headings.length > 0) {
+    tocHeadings = headings.filter(h => h.level >= 1 && h.level <= 4);
+  } else if (content) {
+    const headingRegex = /]*?(?:id="([^"]*)")?[^>]*?>([\s\S]*?)<\/h\1>/g;
+    let match;
+    let contentStr = content.toString();
+    while ((match = headingRegex.exec(contentStr)) !== null) {
+      const level = parseInt(match[1], 10);
+      let id = match[2];
+      const text = decodeHtmlEntities(match[3].replace(/<\/?\w+[^>]*>/g, '')); // Stripped tags
+      if (!id) id = text.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '').replace(/--+/g, '-').replace(/^-+|-+$/g, '');
+      tocHeadings.push({ id, level, text });
+    }
+  }
+  if (tocHeadings.length > 1) { 
+%>
+  
      
+    
      <%= typeof t === 'function' ? t('onThisPage') : 'On This Page' %><%- renderIcon("chevron-down") %>
      
+    
+  
      
+<% } } %>
\ No newline at end of file
diff --git a/packages/ui/translations/de.json b/packages/ui/translations/de.json
new file mode 100644
index 0000000..d1b13a2
--- /dev/null
+++ b/packages/ui/translations/de.json
@@ -0,0 +1,46 @@
+{
+  "skipToContent": "Zum Hauptinhalt springen",
+  "toggleSidebar": "Seitenleiste umschalten",
+  "previous": "Vorherige",
+  "next": "Nรคchste",
+  "breadcrumb": "Breadcrumb",
+  "onThisPage": "Auf dieser Seite",
+  "pageNotFound": "Seite nicht gefunden",
+  "returnHome": "Zur Startseite",
+  "errorCode404": "404",
+  "search": "Suche",
+  "toggleTheme": "Design umschalten",
+  "selectLanguage": "Sprache wรคhlen",
+  "language": "Sprache",
+  "selectVersion": "Version wรคhlen",
+  "version": "Version",
+  "sponsor": "Sponsoren",
+  "builtWith": "Erstellt mit",
+  "editThisPage": "Diese Seite bearbeiten",
+  "permalinkToSection": "Permalink zu diesem Abschnitt",
+  "copiedToClipboard": "Kopiert!",
+  "copyCode": "Code kopieren",
+  "mainNavigation": "Hauptnavigation",
+  "latest": "Neueste",
+  "translationUnavailable": "รœbersetzung fรผr diese Version nicht verfรผgbar",
+  "unavailable": "N. v.",
+  "fallbackMessage": "Diese Seite ist in {active} noch nicht verfรผgbar. Es wird die Standardsprache ({default}) angezeigt.",
+  "copyMarkdown": "Markdown kopieren",
+  "copyContext": "Kontext kopieren",
+  "close": "SchlieรŸen",
+  "cookieAccept": "Akzeptieren",
+  "cookieConsent": "Cookie-Zustimmung",
+  "cookieDecline": "Ablehnen",
+  "cookieMessage": "Diese Website verwendet Cookies, um Ihnen das beste Erlebnis zu bieten.",
+  "cookiePolicy": "Datenschutzerklรคrung",
+  "goBack": "Zurรผck",
+  "lastUpdated": "Zuletzt aktualisiert",
+  "pageNotFoundMsg": "Die gesuchte Seite existiert nicht oder wurde verschoben.",
+  "readMore": "Mehr lesen",
+  "recentCommits": "Letzte Commits",
+  "searchPlaceholder": "Dokumentation durchsuchen...",
+  "selectProject": "Projekt auswรคhlen",
+  "poweredBy": "Bereitgestellt von",
+  "viewSource": "Quelltext anzeigen",
+  "goToTop": "Nach oben"
+}
diff --git a/packages/ui/translations/en.json b/packages/ui/translations/en.json
new file mode 100644
index 0000000..bdcfe55
--- /dev/null
+++ b/packages/ui/translations/en.json
@@ -0,0 +1,46 @@
+{
+  "skipToContent": "Skip to main content",
+  "toggleSidebar": "Toggle Sidebar",
+  "previous": "Previous",
+  "next": "Next",
+  "breadcrumb": "breadcrumb",
+  "onThisPage": "On This Page",
+  "pageNotFound": "Page Not Found",
+  "returnHome": "Return Home",
+  "errorCode404": "404",
+  "search": "Search",
+  "toggleTheme": "Toggle theme",
+  "selectLanguage": "Select Language",
+  "language": "Language",
+  "selectVersion": "Select Version",
+  "version": "Version",
+  "sponsor": "Sponsor",
+  "builtWith": "Built with",
+  "editThisPage": "Edit this page",
+  "permalinkToSection": "Permalink to this section",
+  "copiedToClipboard": "Copied!",
+  "copyCode": "Copy code",
+  "mainNavigation": "Main Navigation",
+  "latest": "Latest",
+  "translationUnavailable": "Translation not available for this version",
+  "unavailable": "N/A",
+  "fallbackMessage": "This page is not yet available in {active}. Showing default language ({default}).",
+  "copyMarkdown": "Copy Markdown",
+  "copyContext": "Copy Context",
+  "close": "Close",
+  "cookieAccept": "Accept",
+  "cookieConsent": "Cookie consent",
+  "cookieDecline": "Decline",
+  "cookieMessage": "This site uses cookies to ensure you get the best experience.",
+  "cookiePolicy": "Privacy policy",
+  "goBack": "Go back",
+  "lastUpdated": "Last updated",
+  "pageNotFoundMsg": "The page youโ€™re looking for doesnโ€™t exist or has moved.",
+  "readMore": "Read more",
+  "recentCommits": "Recent commits",
+  "searchPlaceholder": "Search documentation...",
+  "selectProject": "Select project",
+  "poweredBy": "Powered by",
+  "viewSource": "View source",
+  "goToTop": "Go to top"
+}
\ No newline at end of file
diff --git a/packages/ui/translations/es.json b/packages/ui/translations/es.json
new file mode 100644
index 0000000..e301583
--- /dev/null
+++ b/packages/ui/translations/es.json
@@ -0,0 +1,46 @@
+{
+  "skipToContent": "Saltar al contenido principal",
+  "toggleSidebar": "Alternar barra lateral",
+  "previous": "Anterior",
+  "next": "Siguiente",
+  "breadcrumb": "Breadcrumb",
+  "onThisPage": "En esta pรกgina",
+  "pageNotFound": "Pรกgina no encontrada",
+  "returnHome": "Volver al inicio",
+  "errorCode404": "404",
+  "search": "Buscar",
+  "toggleTheme": "Cambiar tema",
+  "selectLanguage": "Seleccionar idioma",
+  "language": "Idioma",
+  "selectVersion": "Seleccionar versiรณn",
+  "version": "Versiรณn",
+  "sponsor": "Patrocinar",
+  "builtWith": "Construido con",
+  "editThisPage": "Editar esta pรกgina",
+  "permalinkToSection": "Enlace permanente a esta secciรณn",
+  "copiedToClipboard": "ยกCopiado!",
+  "copyCode": "Copiar cรณdigo",
+  "mainNavigation": "Navegaciรณn principal",
+  "latest": "รšltimo",
+  "translationUnavailable": "Traducciรณn no disponible para esta versiรณn",
+  "unavailable": "N/D",
+  "fallbackMessage": "Esta pรกgina aรบn no estรก disponible en {active}. Mostrando el idioma predeterminado ({default}).",
+  "copyMarkdown": "Copiar Markdown",
+  "copyContext": "Copiar Contexto",
+  "close": "Cerrar",
+  "cookieAccept": "Aceptar",
+  "cookieConsent": "Consentimiento de cookies",
+  "cookieDecline": "Rechazar",
+  "cookieMessage": "Este sitio utiliza cookies para garantizar la mejor experiencia.",
+  "cookiePolicy": "Polรญtica de privacidad",
+  "goBack": "Volver",
+  "lastUpdated": "รšltima actualizaciรณn",
+  "pageNotFoundMsg": "La pรกgina que buscas no existe o se ha movido.",
+  "readMore": "Leer mรกs",
+  "recentCommits": "Commits recientes",
+  "searchPlaceholder": "Buscar documentaciรณn...",
+  "selectProject": "Seleccionar proyecto",
+  "poweredBy": "Desarrollado con",
+  "viewSource": "Ver cรณdigo fuente",
+  "goToTop": "Volver arriba"
+}
diff --git a/packages/ui/translations/fr.json b/packages/ui/translations/fr.json
new file mode 100644
index 0000000..c33195b
--- /dev/null
+++ b/packages/ui/translations/fr.json
@@ -0,0 +1,46 @@
+{
+  "skipToContent": "Passer au contenu principal",
+  "toggleSidebar": "Basculer la barre latรฉrale",
+  "previous": "Prรฉcรฉdent",
+  "next": "Suivant",
+  "breadcrumb": "Fil d'Ariane",
+  "onThisPage": "Sur cette page",
+  "pageNotFound": "Page non trouvรฉe",
+  "returnHome": "Retour ร  l'accueil",
+  "errorCode404": "404",
+  "search": "Rechercher",
+  "toggleTheme": "Changer de thรจme",
+  "selectLanguage": "Choisir la langue",
+  "language": "Langue",
+  "selectVersion": "Choisir la version",
+  "version": "Version",
+  "sponsor": "Soutenir",
+  "builtWith": "Construit avec",
+  "editThisPage": "Modifier cette page",
+  "permalinkToSection": "Lien permanent vers cette section",
+  "copiedToClipboard": "Copiรฉ !",
+  "copyCode": "Copier le code",
+  "mainNavigation": "Navigation principale",
+  "latest": "Dernier",
+  "translationUnavailable": "Traduction non disponible pour cette version",
+  "unavailable": "N/D",
+  "fallbackMessage": "Cette page n'est pas encore disponible en {active}. Affichage de la langue par dรฉfaut ({default}).",
+  "copyMarkdown": "Copier le Markdown",
+  "copyContext": "Copier le contexte",
+  "close": "Fermer",
+  "cookieAccept": "Accepter",
+  "cookieConsent": "Consentement aux cookies",
+  "cookieDecline": "Refuser",
+  "cookieMessage": "Ce site utilise des cookies pour vous offrir la meilleure expรฉrience.",
+  "cookiePolicy": "Politique de confidentialitรฉ",
+  "goBack": "Retour",
+  "lastUpdated": "Derniรจre mise ร  jour",
+  "pageNotFoundMsg": "La page que vous cherchez nโ€™existe pas ou a รฉtรฉ dรฉplacรฉe.",
+  "readMore": "Lire la suite",
+  "recentCommits": "Commits rรฉcents",
+  "searchPlaceholder": "Rechercher dans la documentation...",
+  "selectProject": "Sรฉlectionner un projet",
+  "poweredBy": "Propulsรฉ par",
+  "viewSource": "Voir la source",
+  "goToTop": "Retour en haut"
+}
diff --git a/packages/ui/translations/hi.json b/packages/ui/translations/hi.json
new file mode 100644
index 0000000..449f11a
--- /dev/null
+++ b/packages/ui/translations/hi.json
@@ -0,0 +1,46 @@
+{
+  "skipToContent": "เคฎเฅเค–เฅเคฏ เคธเคพเคฎเค—เฅเคฐเฅ€ เคชเคฐ เคœเคพเคเค",
+  "toggleSidebar": "เคธเคพเค‡เคกเคฌเคพเคฐ เคŸเฅ‰เค—เคฒ เค•เคฐเฅ‡เค‚",
+  "previous": "เคชเคฟเค›เคฒเคพ",
+  "next": "เค…เค—เคฒเคพ",
+  "breadcrumb": "เคฌเฅเคฐเฅ‡เคกเค•เฅเคฐเคฎเฅเคฌ",
+  "onThisPage": "เค‡เคธ เคชเฅƒเคทเฅเค  เคชเคฐ",
+  "pageNotFound": "เคชเฅƒเคทเฅเค  เคจเคนเฅ€เค‚ เคฎเคฟเคฒเคพ",
+  "returnHome": "เคนเฅ‹เคฎ เคชเคฐ เคฒเฅŒเคŸเฅ‡เค‚",
+  "errorCode404": "404",
+  "search": "เค–เฅ‹เคœเฅ‡เค‚",
+  "toggleTheme": "เคฅเฅ€เคฎ เคฌเคฆเคฒเฅ‡เค‚",
+  "selectLanguage": "เคญเคพเคทเคพ เคšเฅเคจเฅ‡เค‚",
+  "language": "เคญเคพเคทเคพ",
+  "selectVersion": "เคธเค‚เคธเฅเค•เคฐเคฃ เคšเฅเคจเฅ‡เค‚",
+  "version": "เคธเค‚เคธเฅเค•เคฐเคฃ",
+  "sponsor": "เคชเฅเคฐเคพเคฏเฅ‹เคœเค•",
+  "builtWith": "เค‡เคธเคธเฅ‡ เคฌเคจเคพเคฏเคพ",
+  "editThisPage": "เคฏเคน เคชเฅƒเคทเฅเค  เคธเค‚เคชเคพเคฆเคฟเคค เค•เคฐเฅ‡เค‚",
+  "permalinkToSection": "เค‡เคธ เค…เคจเฅเคญเคพเค— เค•เคพ เคธเฅเคฅเคพเคฏเฅ€ เคฒเคฟเค‚เค•",
+  "copiedToClipboard": "เค•เฅ‰เคชเฅ€ เคนเฅ‹ เค—เคฏเคพ!",
+  "copyCode": "เค•เฅ‹เคก เค•เฅ‰เคชเฅ€ เค•เคฐเฅ‡เค‚",
+  "mainNavigation": "เคฎเฅเค–เฅเคฏ เคจเฅ‡เคตเคฟเค—เฅ‡เคถเคจ",
+  "latest": "เคจเคตเฅ€เคจเคคเคฎ",
+  "translationUnavailable": "เค‡เคธ เคธเค‚เคธเฅเค•เคฐเคฃ เค•เฅ‡ เคฒเคฟเค เค…เคจเฅเคตเคพเคฆ เค‰เคชเคฒเคฌเฅเคง เคจเคนเฅ€เค‚",
+  "unavailable": "N/A",
+  "fallbackMessage": "เคฏเคน เคชเฅƒเคทเฅเค  เค…เคญเฅ€ {active} เคฎเฅ‡เค‚ เค‰เคชเคฒเคฌเฅเคง เคจเคนเฅ€เค‚ เคนเฅˆเฅค เคกเคฟเคซเคผเฅ‰เคฒเฅเคŸ เคญเคพเคทเคพ ({default}) เคฆเคฟเค–เคพ เคฐเคนเคพ เคนเฅˆเฅค",
+  "copyMarkdown": "เคฎเคพเคฐเฅเค•เคกเคพเค‰เคจ เค•เฅ‰เคชเฅ€ เค•เคฐเฅ‡เค‚",
+  "copyContext": "เคธเค‚เคฆเคฐเฅเคญ เค•เฅ‰เคชเฅ€ เค•เคฐเฅ‡เค‚",
+  "close": "เคฌเค‚เคฆ เค•เคฐเฅ‡เค‚",
+  "cookieAccept": "เคธเฅเคตเฅ€เค•เคพเคฐ เค•เคฐเฅ‡เค‚",
+  "cookieConsent": "เค•เฅเค•เฅ€ เคธเคนเคฎเคคเคฟ",
+  "cookieDecline": "เค…เคธเฅเคตเฅ€เค•เคพเคฐ เค•เคฐเฅ‡เค‚",
+  "cookieMessage": "เคฏเคน เคธเคพเค‡เคŸ เค†เคชเค•เฅ‹ เคฌเฅ‡เคนเคคเคฐ เค…เคจเฅเคญเคต เคฆเฅ‡เคจเฅ‡ เค•เฅ‡ เคฒเคฟเค เค•เฅเค•เฅ€เคœเคผ เค•เคพ เค‰เคชเคฏเฅ‹เค— เค•เคฐเคคเฅ€ เคนเฅˆเฅค",
+  "cookiePolicy": "เค—เฅ‹เคชเคจเฅ€เคฏเคคเคพ เคจเฅ€เคคเคฟ",
+  "goBack": "เคตเคพเคชเคธ เคœเคพเคเค",
+  "lastUpdated": "เค…เค‚เคคเคฟเคฎ เค…เคฆเฅเคฏเคคเคจ",
+  "pageNotFoundMsg": "เค†เคช เคœเฅ‹ เคชเฅƒเคทเฅเค  เคขเฅ‚เค‚เคข เคฐเคนเฅ‡ เคนเฅˆเค‚ เคตเคน เคฎเฅŒเคœเฅ‚เคฆ เคจเคนเฅ€เค‚ เคนเฅˆ เคฏเคพ เคธเฅเคฅเคพเคจเคพเค‚เคคเคฐเคฟเคค เคนเฅ‹ เค—เคฏเคพ เคนเฅˆเฅค",
+  "readMore": "เค”เคฐ เคชเคขเคผเฅ‡เค‚",
+  "recentCommits": "เคนเคพเคฒ เค•เฅ‡ เค•เคฎเคฟเคŸ",
+  "searchPlaceholder": "เคฆเคธเฅเคคเคพเคตเฅ‡เคœเคผ เค–เฅ‹เคœเฅ‡เค‚...",
+  "selectProject": "เคชเฅเคฐเฅ‹เคœเฅ‡เค•เฅเคŸ เคšเฅเคจเฅ‡เค‚",
+  "poweredBy": "เคฆเฅเคตเคพเคฐเคพ เคธเค‚เคšเคพเคฒเคฟเคค",
+  "viewSource": "เคธเฅเคฐเฅ‹เคค เคฆเฅ‡เค–เฅ‡เค‚",
+  "goToTop": "เคถเฅ€เคฐเฅเคท เคชเคฐ เคœเคพเคเค"
+}
diff --git a/packages/ui/translations/ja.json b/packages/ui/translations/ja.json
new file mode 100644
index 0000000..6da7535
--- /dev/null
+++ b/packages/ui/translations/ja.json
@@ -0,0 +1,46 @@
+{
+  "skipToContent": "ใƒกใ‚คใƒณใ‚ณใƒณใƒ†ใƒณใƒ„ใธ็งปๅ‹•",
+  "toggleSidebar": "ใ‚ตใ‚คใƒ‰ใƒใƒผใฎๅˆ‡ใ‚Šๆ›ฟใˆ",
+  "previous": "ๅ‰ใธ",
+  "next": "ๆฌกใธ",
+  "breadcrumb": "ใƒ‘ใƒณใใšใƒชใ‚นใƒˆ",
+  "onThisPage": "ใ“ใฎใƒšใƒผใ‚ธใฎๅ†…ๅฎน",
+  "pageNotFound": "ใƒšใƒผใ‚ธใŒ่ฆ‹ใคใ‹ใ‚Šใพใ›ใ‚“",
+  "returnHome": "ใƒ›ใƒผใƒ ใซๆˆปใ‚‹",
+  "errorCode404": "404",
+  "search": "ๆคœ็ดข",
+  "toggleTheme": "ใƒ†ใƒผใƒžใฎๅˆ‡ใ‚Šๆ›ฟใˆ",
+  "selectLanguage": "่จ€่ชžใ‚’้ธๆŠž",
+  "language": "่จ€่ชž",
+  "selectVersion": "ใƒใƒผใ‚ธใƒงใƒณใ‚’้ธๆŠž",
+  "version": "ใƒใƒผใ‚ธใƒงใƒณ",
+  "sponsor": "ใ‚นใƒใƒณใ‚ตใƒผ",
+  "builtWith": "ใงๆง‹็ฏ‰",
+  "editThisPage": "ใ“ใฎใƒšใƒผใ‚ธใ‚’็ทจ้›†",
+  "permalinkToSection": "ใ“ใฎใ‚ปใ‚ฏใ‚ทใƒงใƒณใธใฎใƒ‘ใƒผใƒžใƒชใƒณใ‚ฏ",
+  "copiedToClipboard": "ใ‚ณใƒ”ใƒผใ—ใพใ—ใŸ๏ผ",
+  "copyCode": "ใ‚ณใƒผใƒ‰ใ‚’ใ‚ณใƒ”ใƒผ",
+  "mainNavigation": "ใƒกใ‚คใƒณใƒŠใƒ“ใ‚ฒใƒผใ‚ทใƒงใƒณ",
+  "latest": "ๆœ€ๆ–ฐ",
+  "translationUnavailable": "ใ“ใฎใƒใƒผใ‚ธใƒงใƒณใฎ็ฟป่จณใฏๅˆฉ็”จใงใใพใ›ใ‚“",
+  "unavailable": "ใชใ—",
+  "fallbackMessage": "ใ“ใฎใƒšใƒผใ‚ธใฏ {active} ใงใฏใพใ ๅˆฉ็”จใงใใพใ›ใ‚“ใ€‚ใƒ‡ใƒ•ใ‚ฉใƒซใƒˆใฎ่จ€่ชž ({default}) ใง่กจ็คบใ—ใฆใ„ใพใ™ใ€‚",
+  "copyMarkdown": "Markdownใ‚’ใ‚ณใƒ”ใƒผ",
+  "copyContext": "ใ‚ณใƒณใƒ†ใ‚ญใ‚นใƒˆใ‚’ใ‚ณใƒ”ใƒผ",
+  "close": "้–‰ใ˜ใ‚‹",
+  "cookieAccept": "ๅŒๆ„",
+  "cookieConsent": "CookieใฎๅŒๆ„",
+  "cookieDecline": "ๆ‹’ๅฆ",
+  "cookieMessage": "ใ“ใฎใ‚ตใ‚คใƒˆใฏใ€ใ‚ˆใ‚Š่‰ฏใ„ไฝ“้จ“ใ‚’ๆไพ›ใ™ใ‚‹ใŸใ‚ใซCookieใ‚’ไฝฟ็”จใ—ใฆใ„ใพใ™ใ€‚",
+  "cookiePolicy": "ใƒ—ใƒฉใ‚คใƒใ‚ทใƒผใƒใƒชใ‚ทใƒผ",
+  "goBack": "ๆˆปใ‚‹",
+  "lastUpdated": "ๆœ€็ต‚ๆ›ดๆ–ฐ",
+  "pageNotFoundMsg": "ใŠๆŽขใ—ใฎใƒšใƒผใ‚ธใฏๅญ˜ๅœจใ—ใชใ„ใ‹ใ€็งปๅ‹•ใ•ใ‚Œใพใ—ใŸใ€‚",
+  "readMore": "็ถšใใ‚’่ชญใ‚€",
+  "recentCommits": "ๆœ€่ฟ‘ใฎใ‚ณใƒŸใƒƒใƒˆ",
+  "searchPlaceholder": "ใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆใ‚’ๆคœ็ดข...",
+  "selectProject": "ใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆใ‚’้ธๆŠž",
+  "poweredBy": "ๆไพ›",
+  "viewSource": "ใ‚ฝใƒผใ‚นใ‚’่กจ็คบ",
+  "goToTop": "ใƒˆใƒƒใƒ—ใธๆˆปใ‚‹"
+}
diff --git a/packages/ui/translations/ko.json b/packages/ui/translations/ko.json
new file mode 100644
index 0000000..b949b95
--- /dev/null
+++ b/packages/ui/translations/ko.json
@@ -0,0 +1,46 @@
+{
+  "skipToContent": "๋ณธ๋ฌธ์œผ๋กœ ๊ฑด๋„ˆ๋›ฐ๊ธฐ",
+  "toggleSidebar": "์‚ฌ์ด๋“œ๋ฐ” ์ „ํ™˜",
+  "previous": "์ด์ „",
+  "next": "๋‹ค์Œ",
+  "breadcrumb": "์ด๋™ ๊ฒฝ๋กœ",
+  "onThisPage": "์ด ํŽ˜์ด์ง€์˜ ๋‚ด์šฉ",
+  "pageNotFound": "ํŽ˜์ด์ง€๋ฅผ ์ฐพ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค",
+  "returnHome": "ํ™ˆ์œผ๋กœ ๋Œ์•„๊ฐ€๊ธฐ",
+  "errorCode404": "404",
+  "search": "๊ฒ€์ƒ‰",
+  "toggleTheme": "ํ…Œ๋งˆ ์ „ํ™˜",
+  "selectLanguage": "์–ธ์–ด ์„ ํƒ",
+  "language": "์–ธ์–ด",
+  "selectVersion": "๋ฒ„์ „ ์„ ํƒ",
+  "version": "๋ฒ„์ „",
+  "sponsor": "ํ›„์›",
+  "builtWith": "์ œ์ž‘ ๋„๊ตฌ",
+  "editThisPage": "์ด ํŽ˜์ด์ง€ ํŽธ์ง‘",
+  "permalinkToSection": "์ด ์„น์…˜์˜ ๊ณ ์œ  ๋งํฌ",
+  "copiedToClipboard": "๋ณต์‚ฌ๋˜์—ˆ์Šต๋‹ˆ๋‹ค!",
+  "copyCode": "์ฝ”๋“œ ๋ณต์‚ฌ",
+  "mainNavigation": "์ฃผ ๋ฉ”๋‰ด",
+  "latest": "์ตœ์‹ ",
+  "translationUnavailable": "์ด ๋ฒ„์ „์—๋Š” ๋ฒˆ์—ญ์ด ์ œ๊ณต๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค",
+  "unavailable": "์—†์Œ",
+  "fallbackMessage": "์ด ํŽ˜์ด์ง€๋Š” ์•„์ง {active} ์–ธ์–ด๋กœ ์ œ๊ณต๋˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค. ๊ธฐ๋ณธ ์–ธ์–ด({default})๋กœ ํ‘œ์‹œํ•ฉ๋‹ˆ๋‹ค.",
+  "copyMarkdown": "Markdown ๋ณต์‚ฌ",
+  "copyContext": "์ปจํ…์ŠคํŠธ ๋ณต์‚ฌ",
+  "close": "๋‹ซ๊ธฐ",
+  "cookieAccept": "๋™์˜",
+  "cookieConsent": "์ฟ ํ‚ค ๋™์˜",
+  "cookieDecline": "๊ฑฐ๋ถ€",
+  "cookieMessage": "์ด ์‚ฌ์ดํŠธ๋Š” ์ตœ์ƒ์˜ ๊ฒฝํ—˜์„ ์ œ๊ณตํ•˜๊ธฐ ์œ„ํ•ด ์ฟ ํ‚ค๋ฅผ ์‚ฌ์šฉํ•ฉ๋‹ˆ๋‹ค.",
+  "cookiePolicy": "๊ฐœ์ธ์ •๋ณด ์ฒ˜๋ฆฌ๋ฐฉ์นจ",
+  "goBack": "๋’ค๋กœ ๊ฐ€๊ธฐ",
+  "lastUpdated": "๋งˆ์ง€๋ง‰ ์—…๋ฐ์ดํŠธ",
+  "pageNotFoundMsg": "์ฐพ์œผ์‹œ๋Š” ํŽ˜์ด์ง€๊ฐ€ ์กด์žฌํ•˜์ง€ ์•Š๊ฑฐ๋‚˜ ์ด๋™๋˜์—ˆ์Šต๋‹ˆ๋‹ค.",
+  "readMore": "๋” ์ฝ๊ธฐ",
+  "recentCommits": "์ตœ๊ทผ ์ปค๋ฐ‹",
+  "searchPlaceholder": "๋ฌธ์„œ ๊ฒ€์ƒ‰...",
+  "selectProject": "ํ”„๋กœ์ ํŠธ ์„ ํƒ",
+  "poweredBy": "์ œ๊ณต",
+  "viewSource": "์†Œ์Šค ๋ณด๊ธฐ",
+  "goToTop": "๋งจ ์œ„๋กœ ์ด๋™"
+}
diff --git a/packages/ui/translations/zh.json b/packages/ui/translations/zh.json
new file mode 100644
index 0000000..2699e6b
--- /dev/null
+++ b/packages/ui/translations/zh.json
@@ -0,0 +1,46 @@
+{
+  "skipToContent": "่ทณๅˆฐไธป่ฆๅ†…ๅฎน",
+  "toggleSidebar": "ๅˆ‡ๆขไพง่พนๆ ",
+  "previous": "ไธŠไธ€้กต",
+  "next": "ไธ‹ไธ€้กต",
+  "breadcrumb": "้ขๅŒ…ๅฑ‘ๅฏผ่ˆช",
+  "onThisPage": "ๆœฌ้กตๅ†…ๅฎน",
+  "pageNotFound": "้กต้ขๆœชๆ‰พๅˆฐ",
+  "returnHome": "่ฟ”ๅ›ž้ฆ–้กต",
+  "errorCode404": "404",
+  "search": "ๆœ็ดข",
+  "toggleTheme": "ๅˆ‡ๆขไธป้ข˜",
+  "selectLanguage": "้€‰ๆ‹ฉ่ฏญ่จ€",
+  "language": "่ฏญ่จ€",
+  "selectVersion": "้€‰ๆ‹ฉ็‰ˆๆœฌ",
+  "version": "็‰ˆๆœฌ",
+  "sponsor": "่ตžๅŠฉ",
+  "builtWith": "ไฝฟ็”จๆž„ๅปบ",
+  "editThisPage": "็ผ–่พ‘ๆญค้กต",
+  "permalinkToSection": "ๆญค็ซ ่Š‚็š„ๆฐธไน…้“พๆŽฅ",
+  "copiedToClipboard": "ๅทฒๅคๅˆถ๏ผ",
+  "copyCode": "ๅคๅˆถไปฃ็ ",
+  "mainNavigation": "ไธปๅฏผ่ˆช",
+  "latest": "ๆœ€ๆ–ฐ",
+  "translationUnavailable": "ๆญค็‰ˆๆœฌๆš‚ๆ— ็ฟป่ฏ‘",
+  "unavailable": "N/A",
+  "fallbackMessage": "ๆญค้กต้ขๆš‚ๆ— {active}็‰ˆๆœฌใ€‚ๆ˜พ็คบ้ป˜่ฎค่ฏญ่จ€๏ผˆ{default}๏ผ‰ใ€‚",
+  "copyMarkdown": "ๅคๅˆถ Markdown",
+  "copyContext": "ๅคๅˆถไธŠไธ‹ๆ–‡",
+  "close": "ๅ…ณ้—ญ",
+  "cookieAccept": "ๆŽฅๅ—",
+  "cookieConsent": "Cookie ๅŒๆ„",
+  "cookieDecline": "ๆ‹’็ป",
+  "cookieMessage": "ๆœฌ็ซ™ไฝฟ็”จ Cookie ไปฅๆไพ›ๆœ€ไฝณไฝ“้ชŒใ€‚",
+  "cookiePolicy": "้š็งๆ”ฟ็ญ–",
+  "goBack": "่ฟ”ๅ›ž",
+  "lastUpdated": "ๆœ€ๅŽๆ›ดๆ–ฐ",
+  "pageNotFoundMsg": "ๆ‚จๆŸฅๆ‰พ็š„้กต้ขไธๅญ˜ๅœจๆˆ–ๅทฒ็งปๅŠจใ€‚",
+  "readMore": "้˜…่ฏปๆ›ดๅคš",
+  "recentCommits": "ๆœ€่ฟ‘ๆไบค",
+  "searchPlaceholder": "ๆœ็ดขๆ–‡ๆกฃ...",
+  "selectProject": "้€‰ๆ‹ฉ้กน็›ฎ",
+  "poweredBy": "็”ฑ...้ฉฑๅŠจ",
+  "viewSource": "ๆŸฅ็œ‹ๆบไปฃ็ ",
+  "goToTop": "ๅ›žๅˆฐ้กถ้ƒจ"
+}
diff --git a/packages/ui/tsconfig.json b/packages/ui/tsconfig.json
new file mode 100644
index 0000000..9635ce4
--- /dev/null
+++ b/packages/ui/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
\ No newline at end of file
diff --git a/packages/utils/LICENSE b/packages/utils/LICENSE
new file mode 100644
index 0000000..997bb73
--- /dev/null
+++ b/packages/utils/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present docmd.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
\ No newline at end of file
diff --git a/packages/utils/README.md b/packages/utils/README.md
new file mode 100644
index 0000000..8998742
--- /dev/null
+++ b/packages/utils/README.md
@@ -0,0 +1,13 @@
+# @docmd/utils
+
+Core utilities for docmd.
+
+Part of the **[docmd](https://github.com/docmd-io/docmd)** documentation engine.
+
+## Documentation
+
+See **[docs.docmd.io](https://docs.docmd.io)** for full usage and API reference.
+
+## License
+
+MIT
\ No newline at end of file
diff --git a/packages/utils/package.json b/packages/utils/package.json
new file mode 100644
index 0000000..52adb56
--- /dev/null
+++ b/packages/utils/package.json
@@ -0,0 +1,59 @@
+{
+  "name": "@docmd/utils",
+  "version": "0.8.12",
+  "description": "Zero-dependency shared utilities for docmd core.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test 'test/**/*.test.js'"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3"
+  },
+  "keywords": [
+    "docmd",
+    "ui",
+    "templates",
+    "assets",
+    "layout",
+    "html",
+    "css",
+    "scss",
+    "kit",
+    "base",
+    "markdown",
+    "minimalist",
+    "zero-config",
+    "site-generator",
+    "static-site-generator",
+    "docs"
+  ],
+  "author": {
+    "name": "Ghazi",
+    "url": "https://mgks.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/docmd-io/docmd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/docmd-io/docmd/issues"
+  },
+  "homepage": "https://docmd.io",
+  "funding": "https://github.com/sponsors/mgks",
+  "license": "MIT"
+}
\ No newline at end of file
diff --git a/packages/utils/src/fs-utils.ts b/packages/utils/src/fs-utils.ts
new file mode 100644
index 0000000..fd6dfc0
--- /dev/null
+++ b/packages/utils/src/fs-utils.ts
@@ -0,0 +1,64 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
+import fs from 'node:fs/promises';
+
+
+export async function ensureDir(dirPath: string) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+export async function remove(dirPath: string) {
+  await fs.rm(dirPath, { recursive: true, force: true });
+}
+
+export async function copy(src: string, dest: string, retryCount = 0): Promise {
+  try {
+    await fs.cp(src, dest, { recursive: true });
+  } catch (err: any) {
+    if (err.code === 'ENOENT' && retryCount < 2) {
+      // macOS Node.js recursive copy race condition over external IDE operations:
+      // Sleep for 50ms and retry to securely shield the user from 'ghost unlinks'.
+      await new Promise(r => setTimeout(r, 50));
+      return copy(src, dest, retryCount + 1);
+    }
+    throw err;
+  }
+}
+
+export async function exists(filePath: string) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const pathExists = exists;
+
+export async function writeJson(file: string, object: any, options: any = {}) {
+  const content = JSON.stringify(object, null, options.spaces || 2);
+  await fs.writeFile(file, content, 'utf8');
+}
+
+export default {
+  ...fs,
+  ensureDir,
+  remove,
+  copy,
+  pathExists: exists,
+  exists,
+  writeJson
+};
\ No newline at end of file
diff --git a/packages/utils/src/git.ts b/packages/utils/src/git.ts
new file mode 100644
index 0000000..76630a5
--- /dev/null
+++ b/packages/utils/src/git.ts
@@ -0,0 +1,33 @@
+import { execSync } from 'node:child_process';
+
+/** Cached git root path (null = not yet detected, '' = not a git repo). */
+let _cachedGitRoot: string | null = null;
+
+/**
+ * Detect the git repository root for the current working directory.
+ * Returns the absolute path to the git root, or null if not in a git repo.
+ * Result is cached per execution to prevent spawning multiple processes.
+ */
+export function getGitRoot(): string | null {
+  if (_cachedGitRoot !== null) {
+    return _cachedGitRoot || null;
+  }
+  try {
+    _cachedGitRoot = execSync('git rev-parse --show-toplevel', {
+      cwd: process.cwd(),
+      stdio: 'pipe',
+      encoding: 'utf8'
+    }).trim();
+    return _cachedGitRoot;
+  } catch {
+    _cachedGitRoot = '';
+    return null;
+  }
+}
+
+/**
+ * Reset the cached git root. Useful for testing or when the cwd changes significantly.
+ */
+export function resetGitRootCache(): void {
+  _cachedGitRoot = null;
+}
\ No newline at end of file
diff --git a/packages/utils/src/hash.ts b/packages/utils/src/hash.ts
new file mode 100644
index 0000000..45e9903
--- /dev/null
+++ b/packages/utils/src/hash.ts
@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * Generates an MD5 hash of the given string.
+ * This is used for fast caching checks.
+ */
+export function md5(content: string): string {
+  return createHash('md5').update(content).digest('hex');
+}
\ No newline at end of file
diff --git a/packages/utils/src/html-escape.ts b/packages/utils/src/html-escape.ts
new file mode 100644
index 0000000..bdb6285
--- /dev/null
+++ b/packages/utils/src/html-escape.ts
@@ -0,0 +1,113 @@
+// html-escape.ts โ€” centralised escape helpers for safe HTML / JSON / JS-literal interpolation.
+// Used across the docmd monorepo to prevent XSS (CWE-79). See DEVELOPMENT-BENCHMARK.md S2.
+
+export function escHtml(value: unknown): string {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(//g, '>')
+    .replace(/"/g, '"')
+    .replace(/'/g, ''');
+}
+
+export function attrEsc(value: unknown): string {
+  return escHtml(value);
+}
+
+/**
+ * Escape U+2028 and U+2029 inside a JSON-encoded string. These are valid
+ * in JSON per RFC 8259, but JavaScript's JSON.parse treats them as line
+ * terminators, which means a string parsed and then re-serialised can
+ * silently change meaning. Escaping them is the standard remediation
+ * (also used by React / Vue / Angular) and makes the output safe to
+ * embed inside any JS context, including inline ` context (new in 0.8.9)', () => {
+  const raw = '';
+  const injected = jsonInject(raw);
+  // The literal sequence  must NOT survive in the output โ€” otherwise
+  // the browser parser would end the surrounding '),
+    'jsonInject must escape  for inline `;
+  const literal = scriptLiteral(value);
+  assert.equal(JSON.parse(literal), value);
+});
\ No newline at end of file
diff --git a/packages/utils/test/path.test.js b/packages/utils/test/path.test.js
new file mode 100644
index 0000000..2dbee78
--- /dev/null
+++ b/packages/utils/test/path.test.js
@@ -0,0 +1,72 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { safePath, asUserPath, normalisePath } from '../dist/path.js';
+
+// โ”€โ”€โ”€ safePath โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+
+test('safePath: relative path resolves inside root', () => {
+  const root = path.resolve('/tmp/docmd-test-root');
+  assert.equal(safePath(root, 'docs/index.md'), path.join(root, 'docs/index.md'));
+});
+
+test('safePath: rejects path traversal with ../', () => {
+  const root = path.resolve('/tmp/docmd-test-root');
+  assert.throws(() => safePath(root, '../etc/passwd'), /escapes project root/);
+});
+
+test('safePath: rejects nested traversal that lands outside root', () => {
+  const root = path.resolve('/tmp/docmd-test-root');
+  assert.throws(() => safePath(root, 'docs/../../../etc/passwd'), /escapes project root/);
+});
+
+test('safePath: rejects absolute path outside root', () => {
+  const root = path.resolve('/tmp/docmd-test-root');
+  assert.throws(() => safePath(root, '/etc/passwd'), /escapes project root/);
+});
+
+test('safePath: root itself (.) resolves to root and is allowed', () => {
+  const root = path.resolve('/tmp/docmd-test-root');
+  assert.equal(safePath(root, '.'), root);
+});
+
+test('safePath: nested child path is allowed', () => {
+  const root = path.resolve('/tmp/docmd-test-root');
+  const expected = path.join(root, 'a', 'b', 'c.md');
+  assert.equal(safePath(root, 'a/b/c.md'), expected);
+});
+
+// โ”€โ”€โ”€ asUserPath + UserPath brand โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+
+test('asUserPath: returns the same string at runtime', () => {
+  const raw = 'config/x.yaml';
+  const branded = asUserPath(raw);
+  assert.equal(branded, raw);
+  assert.equal(typeof branded, 'string');
+});
+
+test('UserPath: usable wherever string is expected', () => {
+  const branded = asUserPath('a/b/c');
+  assert.equal(String(branded), 'a/b/c');
+  assert.equal(branded.length, 5);
+  assert.equal(branded.startsWith('a/'), true);
+});
+
+test('asUserPath: empty string is allowed (branding only, not validation)', () => {
+  const branded = asUserPath('');
+  assert.equal(branded, '');
+});
+
+// โ”€โ”€โ”€ normalisePath โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+
+test('normalisePath: leaves POSIX paths unchanged', () => {
+  assert.equal(normalisePath('a/b/c'), 'a/b/c');
+});
+
+test('normalisePath: handles empty string', () => {
+  assert.equal(normalisePath(''), '');
+});
+
+test('normalisePath: handles single segment', () => {
+  assert.equal(normalisePath('only'), 'only');
+});
\ No newline at end of file
diff --git a/packages/utils/tsconfig.json b/packages/utils/tsconfig.json
new file mode 100644
index 0000000..4def913
--- /dev/null
+++ b/packages/utils/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": false,
+    "typeRoots": [
+      "./node_modules/@types",
+      "../../node_modules/@types"
+    ]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
\ No newline at end of file
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
new file mode 100644
index 0000000..8df8ce8
--- /dev/null
+++ b/pnpm-lock.yaml
@@ -0,0 +1,2800 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    devDependencies:
+      '@eslint/js':
+        specifier: ^10.0.1
+        version: 10.0.1(eslint@10.6.0)
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+      chalk:
+        specifier: ^4.1.2
+        version: 4.1.2
+      docmd-search:
+        specifier: ^0.1.0
+        version: 0.1.0(@huggingface/transformers@4.2.0)(onnxruntime-node@1.27.0)
+      esbuild:
+        specifier: ^0.28.1
+        version: 0.28.1
+      eslint:
+        specifier: ^10.6.0
+        version: 10.6.0
+      globals:
+        specifier: ^17.7.0
+        version: 17.7.0
+      typescript:
+        specifier: ^5.9.3
+        version: 5.9.3
+      typescript-eslint:
+        specifier: ^8.63.0
+        version: 8.63.0(eslint@10.6.0)(typescript@5.9.3)
+
+  packages/_playground:
+    dependencies:
+      '@docmd/core':
+        specifier: workspace:*
+        version: link:../core
+      '@docmd/plugin-math':
+        specifier: workspace:*
+        version: link:../plugins/math
+      '@docmd/template-summer':
+        specifier: workspace:*
+        version: link:../templates/summer
+      '@huggingface/transformers':
+        specifier: ^4.2.0
+        version: 4.2.0
+      onnxruntime-node:
+        specifier: ^1.27.0
+        version: 1.27.0
+
+  packages/api:
+    dependencies:
+      '@docmd/parser':
+        specifier: workspace:*
+        version: link:../parser
+      '@docmd/tui':
+        specifier: workspace:*
+        version: link:../tui
+      '@docmd/utils':
+        specifier: workspace:*
+        version: link:../utils
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+    optionalDependencies:
+      '@docmd/engine-js':
+        specifier: workspace:*
+        version: link:../engines/js
+      '@docmd/engine-rust':
+        specifier: workspace:*
+        version: link:../engines/rust
+
+  packages/core:
+    dependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../api
+      '@docmd/deployer':
+        specifier: workspace:*
+        version: link:../deployer
+      '@docmd/live':
+        specifier: workspace:*
+        version: link:../live
+      '@docmd/parser':
+        specifier: workspace:*
+        version: link:../parser
+      '@docmd/plugin-analytics':
+        specifier: workspace:*
+        version: link:../plugins/analytics
+      '@docmd/plugin-git':
+        specifier: workspace:*
+        version: link:../plugins/git
+      '@docmd/plugin-installer':
+        specifier: workspace:*
+        version: link:../plugins/installer
+      '@docmd/plugin-llms':
+        specifier: workspace:*
+        version: link:../plugins/llms
+      '@docmd/plugin-mermaid':
+        specifier: workspace:*
+        version: link:../plugins/mermaid
+      '@docmd/plugin-okf':
+        specifier: workspace:*
+        version: link:../plugins/okf
+      '@docmd/plugin-openapi':
+        specifier: workspace:*
+        version: link:../plugins/openapi
+      '@docmd/plugin-search':
+        specifier: workspace:*
+        version: link:../plugins/search
+      '@docmd/plugin-seo':
+        specifier: workspace:*
+        version: link:../plugins/seo
+      '@docmd/plugin-sitemap':
+        specifier: workspace:*
+        version: link:../plugins/sitemap
+      '@docmd/themes':
+        specifier: workspace:*
+        version: link:../themes
+      '@docmd/tui':
+        specifier: workspace:*
+        version: link:../tui
+      '@docmd/ui':
+        specifier: workspace:*
+        version: link:../ui
+      '@docmd/utils':
+        specifier: workspace:*
+        version: link:../utils
+      esbuild:
+        specifier: ^0.28.1
+        version: 0.28.1
+      ws:
+        specifier: ^8.21.0
+        version: 8.21.0
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/deployer:
+    dependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../api
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/engines/js:
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/engines/rust:
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/engines/rust-binaries: {}
+
+  packages/legacy/doc.md:
+    dependencies:
+      '@docmd/core':
+        specifier: workspace:*
+        version: link:../../core
+
+  packages/legacy/mgks:
+    dependencies:
+      '@docmd/core':
+        specifier: workspace:*
+        version: link:../../core
+
+  packages/live:
+    dependencies:
+      '@docmd/parser':
+        specifier: workspace:*
+        version: link:../parser
+      '@docmd/plugin-math':
+        specifier: workspace:*
+        version: link:../plugins/math
+      '@docmd/plugin-mermaid':
+        specifier: workspace:*
+        version: link:../plugins/mermaid
+      '@docmd/themes':
+        specifier: workspace:*
+        version: link:../themes
+      '@docmd/tui':
+        specifier: workspace:*
+        version: link:../tui
+      '@docmd/ui':
+        specifier: workspace:*
+        version: link:../ui
+      buffer:
+        specifier: ^6.0.3
+        version: 6.0.3
+      esbuild:
+        specifier: ^0.28.1
+        version: 0.28.1
+      katex:
+        specifier: ^0.17.0
+        version: 0.17.0
+      markdown-it-texmath:
+        specifier: ^1.0.0
+        version: 1.0.0
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/parser:
+    dependencies:
+      '@docmd/tui':
+        specifier: workspace:*
+        version: link:../tui
+      '@docmd/utils':
+        specifier: workspace:*
+        version: link:../utils
+      embed-lite:
+        specifier: ^0.1.4
+        version: 0.1.4
+      lite-hl:
+        specifier: ^0.1.2
+        version: 0.1.2
+      lite-matter:
+        specifier: ^0.1.1
+        version: 0.1.1
+      lite-template:
+        specifier: ^0.1.2
+        version: 0.1.2
+      lucide-static:
+        specifier: ^0.577.0
+        version: 0.577.0
+      markdown-it:
+        specifier: ^14.3.0
+        version: 14.3.0
+      markdown-it-abbr:
+        specifier: ^1.0.4
+        version: 1.0.4
+      markdown-it-attrs:
+        specifier: ^4.5.0
+        version: 4.5.0(markdown-it@14.3.0)
+      markdown-it-deflist:
+        specifier: ^2.1.0
+        version: 2.1.0
+      markdown-it-emoji:
+        specifier: ^2.0.2
+        version: 2.0.2
+      markdown-it-footnote:
+        specifier: ^3.0.3
+        version: 3.0.3
+      markdown-it-task-lists:
+        specifier: ^2.1.1
+        version: 2.1.1
+
+  packages/plugins/analytics:
+    dependencies:
+      '@docmd/utils':
+        specifier: workspace:*
+        version: link:../../utils
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+
+  packages/plugins/git:
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/plugins/installer:
+    dependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/plugins/llms:
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/plugins/math:
+    dependencies:
+      katex:
+        specifier: ^0.17.0
+        version: 0.17.0
+      markdown-it-texmath:
+        specifier: ^1.0.0
+        version: 1.0.0
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+
+  packages/plugins/mermaid:
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+      esbuild:
+        specifier: ^0.28.1
+        version: 0.28.1
+      tsx:
+        specifier: ^4.23.0
+        version: 4.23.0
+
+  packages/plugins/okf:
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+      tsx:
+        specifier: ^4.23.0
+        version: 4.23.0
+
+  packages/plugins/openapi:
+    dependencies:
+      '@docmd/utils':
+        specifier: workspace:*
+        version: link:../../utils
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/plugins/pwa:
+    dependencies:
+      '@docmd/utils':
+        specifier: workspace:*
+        version: link:../../utils
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/plugins/search:
+    dependencies:
+      docmd-search:
+        specifier: '>=0.1.0'
+        version: 0.1.0(@huggingface/transformers@4.2.0)(onnxruntime-node@1.27.0)
+      markdown-it:
+        specifier: ^14.3.0
+        version: 14.3.0
+      minisearch:
+        specifier: ^7.2.0
+        version: 7.2.0
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/markdown-it':
+        specifier: ^14.1.2
+        version: 14.1.2
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+      esbuild:
+        specifier: ^0.28.1
+        version: 0.28.1
+
+  packages/plugins/seo:
+    dependencies:
+      '@docmd/utils':
+        specifier: workspace:*
+        version: link:../../utils
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/plugins/sitemap:
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/plugins/threads:
+    dependencies:
+      '@awesome.me/webawesome':
+        specifier: ^3.10.0
+        version: 3.10.0(@floating-ui/utils@0.2.11)(@types/node@24.13.3)(@types/react@19.2.14)
+      '@docmd/parser':
+        specifier: workspace:*
+        version: link:../../parser
+      '@docmd/utils':
+        specifier: workspace:*
+        version: link:../../utils
+      lit:
+        specifier: ^3.3.3
+        version: 3.3.3
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@playwright/test':
+        specifier: ^1.61.1
+        version: 1.61.1
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+      esbuild:
+        specifier: ^0.28.1
+        version: 0.28.1
+
+  packages/templates/summer:
+    devDependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../../api
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+      esbuild:
+        specifier: ^0.28.1
+        version: 0.28.1
+      typescript:
+        specifier: ^5.9.3
+        version: 5.9.3
+
+  packages/themes:
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/tui:
+    dependencies:
+      chalk:
+        specifier: ^4.1.2
+        version: 4.1.2
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+      typescript:
+        specifier: ^5.9.3
+        version: 5.9.3
+
+  packages/ui:
+    dependencies:
+      '@docmd/api':
+        specifier: workspace:*
+        version: link:../api
+      '@docmd/tui':
+        specifier: workspace:*
+        version: link:../tui
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+  packages/utils:
+    devDependencies:
+      '@types/node':
+        specifier: ^24.13.3
+        version: 24.13.3
+
+packages:
+
+  '@awesome.me/webawesome@3.10.0':
+    resolution: {integrity: sha512-QrVKGTiz9OhtIoDic7RF6o1x5ShnJI7jgxK93uoSBh3INYlUyejKYXohXqpJ2cgjIJqfo0jMSQygd1Ty96QOMA==}
+    engines: {node: '>=14.17.0'}
+
+  '@ctrl/tinycolor@4.1.0':
+    resolution: {integrity: sha512-WyOx8cJQ+FQus4Mm4uPIZA64gbk3Wxh0so5Lcii0aJifqwoVOlfFtorjLE0Hen4OYyHZMXDWqMmaQemBhgxFRQ==}
+    engines: {node: '>=14'}
+
+  '@emnapi/runtime@1.11.2':
+    resolution: {integrity: sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==}
+
+  '@esbuild/aix-ppc64@0.28.1':
+    resolution: {integrity: sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.28.1':
+    resolution: {integrity: sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.28.1':
+    resolution: {integrity: sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.28.1':
+    resolution: {integrity: sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.28.1':
+    resolution: {integrity: sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.28.1':
+    resolution: {integrity: sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.28.1':
+    resolution: {integrity: sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.28.1':
+    resolution: {integrity: sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.28.1':
+    resolution: {integrity: sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.28.1':
+    resolution: {integrity: sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.28.1':
+    resolution: {integrity: sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.28.1':
+    resolution: {integrity: sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.28.1':
+    resolution: {integrity: sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.28.1':
+    resolution: {integrity: sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.28.1':
+    resolution: {integrity: sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.28.1':
+    resolution: {integrity: sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.28.1':
+    resolution: {integrity: sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.28.1':
+    resolution: {integrity: sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.28.1':
+    resolution: {integrity: sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.28.1':
+    resolution: {integrity: sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.28.1':
+    resolution: {integrity: sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.28.1':
+    resolution: {integrity: sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.28.1':
+    resolution: {integrity: sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.28.1':
+    resolution: {integrity: sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.28.1':
+    resolution: {integrity: sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@eslint-community/eslint-utils@4.9.1':
+    resolution: {integrity: sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+    peerDependencies:
+      eslint: ^6.0.0 || ^7.0.0 || >=8.0.0
+
+  '@eslint-community/regexpp@4.12.2':
+    resolution: {integrity: sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==}
+    engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0}
+
+  '@eslint/config-array@0.23.5':
+    resolution: {integrity: sha512-Y3kKLvC1dvTOT+oGlqNQ1XLqK6D1HU2YXPc52NmAlJZbMMWDzGYXMiPRJ8TYD39muD/OTjlZmNJ4ib7dvSrMBA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@eslint/config-helpers@0.6.0':
+    resolution: {integrity: sha512-ii6Bw9jJ2zi2cWA2Z+9/QZ/+3DX6kwaV5Q986D/CdP3Lap3w/pgQZ373FV7byY/i7L4IRH/G43I5dz1ClsCbpA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@eslint/core@1.2.1':
+    resolution: {integrity: sha512-MwcE1P+AZ4C6DWlpin/OmOA54mmIZ/+xZuJiQd4SyB29oAJjN30UW9wkKNptW2ctp4cEsvhlLY/CsQ1uoHDloQ==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@eslint/js@10.0.1':
+    resolution: {integrity: sha512-zeR9k5pd4gxjZ0abRoIaxdc7I3nDktoXZk2qOv9gCNWx3mVwEn32VRhyLaRsDiJjTs0xq/T8mfPtyuXu7GWBcA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+    peerDependencies:
+      eslint: ^10.0.0
+    peerDependenciesMeta:
+      eslint:
+        optional: true
+
+  '@eslint/object-schema@3.0.5':
+    resolution: {integrity: sha512-vqTaUEgxzm+YDSdElad6PiRoX4t8VGDjCtt05zn4nU810UIx/uNEV7/lZJ6KwFThKZOzOxzXy48da+No7HZaMw==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@eslint/plugin-kit@0.7.2':
+    resolution: {integrity: sha512-+CNAzxglkrpNf/kKywqQfk74QjtceuOE7Qm+AF8miRvPF/wmmK5+OJOgVh3AVTT3RP2mH3+FOaxlE5v72owk0A==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  '@floating-ui/core@1.7.5':
+    resolution: {integrity: sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==}
+
+  '@floating-ui/dom@1.7.6':
+    resolution: {integrity: sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==}
+
+  '@floating-ui/utils@0.2.11':
+    resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
+
+  '@huggingface/jinja@0.5.9':
+    resolution: {integrity: sha512-uWTG+l3VJRsl7EXxYizuL3P+cCPoc3cRqbWWRcQN0FhejRfbdq0RNhCmbY/YDtnTcz9icdLYuLDjsnz4d8JMuw==}
+    engines: {node: '>=18'}
+
+  '@huggingface/tokenizers@0.1.3':
+    resolution: {integrity: sha512-8rF/RRT10u+kn7YuUbUg0OF30K8rjTc78aHpxT+qJ1uWSqxT1MHi8+9ltwYfkFYJzT/oS+qw3JVfHtNMGAdqyA==}
+
+  '@huggingface/transformers@4.2.0':
+    resolution: {integrity: sha512-8BRCoBMH0XsWaEIamuR0LrJGAfftgHAfb2Vrffy0VKlSAE/MnUJ5/h/zTfEP3fDIft+nk7TqB8xXEyABGitBjQ==}
+
+  '@humanfs/core@0.19.2':
+    resolution: {integrity: sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanfs/node@0.16.8':
+    resolution: {integrity: sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanfs/types@0.15.0':
+    resolution: {integrity: sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanwhocodes/module-importer@1.0.1':
+    resolution: {integrity: sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==}
+    engines: {node: '>=12.22'}
+
+  '@humanwhocodes/retry@0.4.3':
+    resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==}
+    engines: {node: '>=18.18'}
+
+  '@img/colour@1.1.0':
+    resolution: {integrity: sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==}
+    engines: {node: '>=18'}
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    resolution: {integrity: sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-darwin-x64@0.34.5':
+    resolution: {integrity: sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    resolution: {integrity: sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    resolution: {integrity: sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-linux-arm64@0.34.5':
+    resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-arm@0.34.5':
+    resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-s390x@0.34.5':
+    resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linux-x64@0.34.5':
+    resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@img/sharp-wasm32@0.34.5':
+    resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [wasm32]
+
+  '@img/sharp-win32-arm64@0.34.5':
+    resolution: {integrity: sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@img/sharp-win32-ia32@0.34.5':
+    resolution: {integrity: sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@img/sharp-win32-x64@0.34.5':
+    resolution: {integrity: sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+    cpu: [x64]
+    os: [win32]
+
+  '@konnorr/qr-creator@1.0.1':
+    resolution: {integrity: sha512-EmRR9rny1ENBtQy7TLOguO/79h1EpzXUmqIdMTGp2BW8NkZtRRPr5hmQcE+n9QXYo4T8NjcaJ14hnZg+s/+K+A==}
+
+  '@lit-labs/ssr-client@1.1.8':
+    resolution: {integrity: sha512-PjGh81oKsoI64m3IDjTqqjhC7dr2uC/o0jrllUb5gRAyp/RlAHxapgJrjq9kWz97faCHLQ8jUlTi6tGm+8fgyA==}
+
+  '@lit-labs/ssr-dom-shim@1.6.0':
+    resolution: {integrity: sha512-VHb0ALPMTlgKjM6yIxxoQNnpKyUKLD04VzeQdsiXkMqkvYlAHxq9glGLmgbb889/1GsohSOAjvQYoiBppXFqrQ==}
+
+  '@lit-labs/ssr@4.1.0':
+    resolution: {integrity: sha512-m0zymVVlHB1ddJQ1lastsV8ROW3whFOiHJhVPQWd04MnGTkTlUUVLQctux1QlyD9BtLXNN6iASxv388vhgKMFg==}
+    engines: {node: '>=13.9.0'}
+    peerDependencies:
+      '@types/node': '>=20.0.0 <25.0.0'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@lit/context@1.1.6':
+    resolution: {integrity: sha512-M26qDE6UkQbZA2mQ3RjJ3Gzd8TxP+/0obMgE5HfkfLhEEyYE3Bui4A5XHiGPjy0MUGAyxB3QgVuw2ciS0kHn6A==}
+
+  '@lit/react@1.0.8':
+    resolution: {integrity: sha512-p2+YcF+JE67SRX3mMlJ1TKCSTsgyOVdAwd/nxp3NuV1+Cb6MWALbN6nT7Ld4tpmYofcE5kcaSY1YBB9erY+6fw==}
+    peerDependencies:
+      '@types/react': 17 || 18 || 19
+
+  '@lit/reactive-element@2.1.2':
+    resolution: {integrity: sha512-pbCDiVMnne1lYUIaYNN5wrwQXDtHaYtg7YEFPeW+hws6U47WeFvISGUWekPGKWOP1ygrs0ef0o1VJMk1exos5A==}
+
+  '@parse5/tools@0.3.0':
+    resolution: {integrity: sha512-zxRyTHkqb7WQMV8kTNBKWb1BeOFUKXBXTBWuxg9H9hfvQB3IwP6Iw2U75Ia5eyRxPNltmY7E8YAlz6zWwUnjKg==}
+
+  '@playwright/test@1.61.1':
+    resolution: {integrity: sha512-8nKv6+0RJSL9FE4jYOEGXnPeM/Hg12qZpmqzZjRh3qM0Y7c3z1mrOTfFLids72RDQYVh9WpLEfR5WdpNX4fkig==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  '@protobufjs/aspromise@1.1.2':
+    resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
+
+  '@protobufjs/base64@1.1.2':
+    resolution: {integrity: sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==}
+
+  '@protobufjs/codegen@2.0.5':
+    resolution: {integrity: sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==}
+
+  '@protobufjs/eventemitter@1.1.1':
+    resolution: {integrity: sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==}
+
+  '@protobufjs/fetch@1.1.1':
+    resolution: {integrity: sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==}
+
+  '@protobufjs/float@1.0.2':
+    resolution: {integrity: sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==}
+
+  '@protobufjs/path@1.1.2':
+    resolution: {integrity: sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==}
+
+  '@protobufjs/pool@1.1.0':
+    resolution: {integrity: sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==}
+
+  '@protobufjs/utf8@1.1.2':
+    resolution: {integrity: sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==}
+
+  '@shoelace-style/animations@1.2.0':
+    resolution: {integrity: sha512-avvo1xxkLbv2dgtabdewBbqcJfV0e0zCwFqkPMnHFGbJbBHorRFfMAHh1NG9ymmXn0jW95ibUVH03E1NYXD6Gw==}
+
+  '@shoelace-style/localize@3.2.2':
+    resolution: {integrity: sha512-h3+2/cFWGaw3KQUwintkP4Cy3PtrVW//ysr9DM5nOfIXYekgrHwsELk/nyxc8hmjVP/Kcon7KCzvUtSwUBipfQ==}
+
+  '@types/esrecurse@4.3.1':
+    resolution: {integrity: sha512-xJBAbDifo5hpffDBuHl0Y8ywswbiAp/Wi7Y/GtAgSlZyIABppyurxVueOPE8LUQOxdlgi6Zqce7uoEpqNTeiUw==}
+
+  '@types/estree@1.0.9':
+    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
+
+  '@types/json-schema@7.0.15':
+    resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
+
+  '@types/linkify-it@5.0.0':
+    resolution: {integrity: sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q==}
+
+  '@types/markdown-it@14.1.2':
+    resolution: {integrity: sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog==}
+
+  '@types/mdurl@2.0.0':
+    resolution: {integrity: sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==}
+
+  '@types/node@24.13.3':
+    resolution: {integrity: sha512-Dh8vAsV36ig5wa9OX4pXvMc9D3Veibfw2wix0CUwYODLD8nkj9UsLjASr49nPg+2eKzxhBV+v7L8pXvT4e639Q==}
+
+  '@types/node@26.1.1':
+    resolution: {integrity: sha512-nxAkRSVkN1Y0JC1W8ky/fTfkGsMmcrRsbx+3XoZE+rMOX71kLYTV7fLXpqud1GpbpP5TuffXFqfX7fH2GgZREw==}
+
+  '@types/react@19.2.14':
+    resolution: {integrity: sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==}
+
+  '@types/trusted-types@2.0.7':
+    resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
+
+  '@typescript-eslint/eslint-plugin@8.63.0':
+    resolution: {integrity: sha512-rvwSgqT+DHpWdzfSzPatRLm02a0GlESt++9iy3hLCDY4BgkaLcl8LBi9Yh7XGFBpwcBE/K3024QuXWTpbz4FfQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      '@typescript-eslint/parser': ^8.63.0
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/parser@8.63.0':
+    resolution: {integrity: sha512-gwh4gvvlaVDKKxyfxMG+Gnu1u9X0OQBwyGLkbwB65dIzBKnxeRiJlNFqlI3zwVhNXJIs6qV7mlFCn/BIajlVig==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/project-service@8.63.0':
+    resolution: {integrity: sha512-e5dh0/UI0ok53AlZ5wRkXCB32z/f2jUZqPR/ygAw5WYaSw8j9EoJWlS7wQjr/dmOaqWjnPIn2m+HhVPCMWGZVQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/scope-manager@8.63.0':
+    resolution: {integrity: sha512-uUyfMWCnDSN8bCpcrY8nGP2BLkQ9Xn0GsipcONcpIDWhwhO4ZSyHvyS14U3X75mzxWxL3I2UZIrenTzdzcJO8A==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/tsconfig-utils@8.63.0':
+    resolution: {integrity: sha512-sUAbkulqBAsncKnbRP3+7CtQFRKicexnj7ZwNC6ddCR7EmrXvjvdCYMJbUIqMd6lwoEriZjwLo08aS5tSjVMHg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/type-utils@8.63.0':
+    resolution: {integrity: sha512-Nzzh/OGxVCOjObjaj1CQF2RUasyYy2Jfuh+zZ3PjLzG2fYRriAiZLib9UKtO+CpQAS3YHiAS+ckZDclwqI1TPA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/types@8.63.0':
+    resolution: {integrity: sha512-xyLtl9DUBBFrcJS4x2pIqGLH68/tC2uOa4Z7pUteW09D3bXnnXUom4dyPikzWgB7llmIc1zoeI3aoUdC4rPK/Q==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/typescript-estree@8.63.0':
+    resolution: {integrity: sha512-ygBkU+B7ex5UI/gKhaqexWev79uISfIv7XQCRNYO/jmD8rGLPyWLAb3KMRT6nd8Gt9bmUBi9+iX6tBdYfOY81Q==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/utils@8.63.0':
+    resolution: {integrity: sha512-fUKaeAvrTuQg/Tgt3nliAUSZHJM6DlCcfyEmxCvlX8kieWSStBX+5O5Fnidtc3i2JrH+9c/GL4RY2iasd/GPTA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/visitor-keys@8.63.0':
+    resolution: {integrity: sha512-UexrHGnGTpbuQHct2ExOc2ZcFbGUS9FOesCxxqdBGcpI1BxYu/LZ6U8Aq6/72XtF/qRBk9nhuGHFJIXXMhPMdw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  acorn-jsx@5.3.2:
+    resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  acorn@8.17.0:
+    resolution: {integrity: sha512-xRQbDb9BnwDafYNn6Vwl839DYVjqXYb1XVGtWAZ1kcDc6iwAL4hg3B1dZlRiuENFeO2H53gFG3in621AdERVAg==}
+    engines: {node: '>=0.4.0'}
+    hasBin: true
+
+  adm-zip@0.5.18:
+    resolution: {integrity: sha512-ufJnssQGbxzLNS1Ho9bCtX4rQKCCvoVuDLHoJyc3F9dOGDB4BkWs2Ci0kv53lqocAEQ/Cbi+I2XCsNYGqVYqng==}
+    engines: {node: '>=12.0'}
+
+  ajv@6.15.0:
+    resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==}
+
+  ansi-styles@4.3.0:
+    resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
+    engines: {node: '>=8'}
+
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  balanced-match@4.0.4:
+    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
+    engines: {node: 18 || 20 || >=22}
+
+  base64-js@1.5.1:
+    resolution: {integrity: sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==}
+
+  boolean@3.2.0:
+    resolution: {integrity: sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw==}
+    deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.
+
+  brace-expansion@5.0.7:
+    resolution: {integrity: sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==}
+    engines: {node: 18 || 20 || >=22}
+
+  buffer@6.0.3:
+    resolution: {integrity: sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==}
+
+  chalk@4.1.2:
+    resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
+    engines: {node: '>=10'}
+
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
+  commander@8.3.0:
+    resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==}
+    engines: {node: '>= 12'}
+
+  composed-offset-position@0.0.6:
+    resolution: {integrity: sha512-Q7dLompI6lUwd7LWyIcP66r4WcS9u7AL2h8HaeipiRfCRPLMWqRx8fYsjb4OHi6UQFifO7XtNC2IlEJ1ozIFxw==}
+    peerDependencies:
+      '@floating-ui/utils': ^0.2.5
+
+  cross-spawn@7.0.6:
+    resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
+    engines: {node: '>= 8'}
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
+  data-uri-to-buffer@4.0.1:
+    resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==}
+    engines: {node: '>= 12'}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  deep-is@0.1.4:
+    resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==}
+
+  define-data-property@1.1.4:
+    resolution: {integrity: sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==}
+    engines: {node: '>= 0.4'}
+
+  define-properties@1.2.1:
+    resolution: {integrity: sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg==}
+    engines: {node: '>= 0.4'}
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  detect-node@2.1.0:
+    resolution: {integrity: sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==}
+
+  docmd-search@0.1.0:
+    resolution: {integrity: sha512-3jb3v5MRmoT3KLHYHnVzcmTxjxQ/+69FH6owoy+p9D/cFlRRrSjQqeGMt1UJhDwOuGnjHqsLTdn3NzUO81r/6g==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+    peerDependencies:
+      '@docmd/engine-js': '>=0.8.5'
+      '@docmd/engine-rust': '>=0.8.5'
+      '@huggingface/transformers': ^4.2.0
+      onnxruntime-node: ^1.26.0
+    peerDependenciesMeta:
+      '@docmd/engine-js':
+        optional: true
+      '@docmd/engine-rust':
+        optional: true
+      '@huggingface/transformers':
+        optional: true
+      onnxruntime-node:
+        optional: true
+
+  embed-lite@0.1.4:
+    resolution: {integrity: sha512-jHeFclp6iQGHeb0DUBh0a7eGQb1bfhDBzDfSx/nr8c5kdx0PW7EfWXzY5Ry8/AGbbVfxhewOSqwFJZLp18wdhw==}
+
+  enhanced-resolve@5.24.2:
+    resolution: {integrity: sha512-rpsZEGT1jFuve6QlpyRp9ckQ+kN61hvF9BzCPyMdaKTm8UJce96KBn3sorXOFXlzjPrs3Vc4T1NsSroZ3PxlFw==}
+    engines: {node: '>=10.13.0'}
+
+  entities@4.5.0:
+    resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
+    engines: {node: '>=0.12'}
+
+  entities@6.0.1:
+    resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
+    engines: {node: '>=0.12'}
+
+  es-define-property@1.0.1:
+    resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==}
+    engines: {node: '>= 0.4'}
+
+  es-errors@1.3.0:
+    resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
+    engines: {node: '>= 0.4'}
+
+  es6-error@4.1.1:
+    resolution: {integrity: sha512-Um/+FxMr9CISWh0bi5Zv0iOD+4cFh5qLeks1qhAopKVAJw3drgKbKySikp7wGhDL0HPeaja0P5ULZrxLkniUVg==}
+
+  esbuild@0.28.1:
+    resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  escape-string-regexp@4.0.0:
+    resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
+    engines: {node: '>=10'}
+
+  eslint-scope@9.1.2:
+    resolution: {integrity: sha512-xS90H51cKw0jltxmvmHy2Iai1LIqrfbw57b79w/J7MfvDfkIkFZ+kj6zC3BjtUwh150HsSSdxXZcsuv72miDFQ==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  eslint-visitor-keys@3.4.3:
+    resolution: {integrity: sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+
+  eslint-visitor-keys@5.0.1:
+    resolution: {integrity: sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  eslint@10.6.0:
+    resolution: {integrity: sha512-6lVbcqSodALYo+4ELD0heG6lFiFxnLMuLkiMi2qV8LMp54N8tE8FT1GMH+ev4Ti00nFjNze2+Su6DsV5OQW3Dg==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+    hasBin: true
+    peerDependencies:
+      jiti: '*'
+    peerDependenciesMeta:
+      jiti:
+        optional: true
+
+  espree@11.2.0:
+    resolution: {integrity: sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  esquery@1.7.0:
+    resolution: {integrity: sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==}
+    engines: {node: '>=0.10'}
+
+  esrecurse@4.3.0:
+    resolution: {integrity: sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==}
+    engines: {node: '>=4.0'}
+
+  estraverse@5.3.0:
+    resolution: {integrity: sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==}
+    engines: {node: '>=4.0'}
+
+  esutils@2.0.3:
+    resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
+    engines: {node: '>=0.10.0'}
+
+  fast-deep-equal@3.1.3:
+    resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
+
+  fast-json-stable-stringify@2.1.0:
+    resolution: {integrity: sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==}
+
+  fast-levenshtein@2.0.6:
+    resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  fetch-blob@3.2.0:
+    resolution: {integrity: sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==}
+    engines: {node: ^12.20 || >= 14.13}
+
+  file-entry-cache@8.0.0:
+    resolution: {integrity: sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==}
+    engines: {node: '>=16.0.0'}
+
+  find-up@5.0.0:
+    resolution: {integrity: sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==}
+    engines: {node: '>=10'}
+
+  flat-cache@4.0.1:
+    resolution: {integrity: sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==}
+    engines: {node: '>=16'}
+
+  flatbuffers@25.9.23:
+    resolution: {integrity: sha512-MI1qs7Lo4Syw0EOzUl0xjs2lsoeqFku44KpngfIduHBYvzm8h2+7K8YMQh1JtVVVrUvhLpNwqVi4DERegUJhPQ==}
+
+  flatted@3.4.2:
+    resolution: {integrity: sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==}
+
+  formdata-polyfill@4.0.10:
+    resolution: {integrity: sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==}
+    engines: {node: '>=12.20.0'}
+
+  fsevents@2.3.2:
+    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  glob-parent@6.0.2:
+    resolution: {integrity: sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==}
+    engines: {node: '>=10.13.0'}
+
+  global-agent@3.0.0:
+    resolution: {integrity: sha512-PT6XReJ+D07JvGoxQMkT6qji/jVNfX/h364XHZOWeRzy64sSFr+xJ5OX7LI3b4MPQzdL4H8Y8M0xzPpsVMwA8Q==}
+    engines: {node: '>=10.0'}
+
+  global-agent@4.1.3:
+    resolution: {integrity: sha512-KUJEViiuFT3I97t+GYMikLPJS2Lfo/S2F+DQuBWzuzaMPnvt5yyZePzArx36fBzpGTxZjIpDbXLeySLgh+k76g==}
+    engines: {node: '>=10.0'}
+
+  globals@17.7.0:
+    resolution: {integrity: sha512-Czmyns5dUsq4seFBR/Kdydhmo8y9kC79hiSkPn0YcGtNnYWnrgt0vjrSjx9tspoDGWm2CMarffRuLjM4xUz8xg==}
+    engines: {node: '>=18'}
+
+  globalthis@1.0.4:
+    resolution: {integrity: sha512-DpLKbNU4WylpxJykQujfCcwYWiV/Jhm50Goo0wrVILAv5jOr9d+H+UR3PhSCD2rCCEIg0uc+G+muBTwD54JhDQ==}
+    engines: {node: '>= 0.4'}
+
+  gopd@1.2.0:
+    resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==}
+    engines: {node: '>= 0.4'}
+
+  graceful-fs@4.2.11:
+    resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
+
+  guid-typescript@1.0.9:
+    resolution: {integrity: sha512-Y8T4vYhEfwJOTbouREvG+3XDsjr8E3kIr7uf+JZ0BYloFsttiHU0WfvANVsR7TxNUJa/WpCnw/Ino/p+DeBhBQ==}
+
+  has-flag@4.0.0:
+    resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
+    engines: {node: '>=8'}
+
+  has-property-descriptors@1.0.2:
+    resolution: {integrity: sha512-55JNKuIW+vq4Ke1BjOTjM2YctQIvCT7GFzHwmfZPGo5wnrgkid0YQtnAleFSqumZm4az3n2BS+erby5ipJdgrg==}
+
+  ieee754@1.2.1:
+    resolution: {integrity: sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==}
+
+  ignore@5.3.2:
+    resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
+    engines: {node: '>= 4'}
+
+  ignore@7.0.5:
+    resolution: {integrity: sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==}
+    engines: {node: '>= 4'}
+
+  imurmurhash@0.1.4:
+    resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
+    engines: {node: '>=0.8.19'}
+
+  is-extglob@2.1.1:
+    resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
+    engines: {node: '>=0.10.0'}
+
+  is-glob@4.0.3:
+    resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
+    engines: {node: '>=0.10.0'}
+
+  isexe@2.0.0:
+    resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
+
+  json-buffer@3.0.1:
+    resolution: {integrity: sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==}
+
+  json-schema-traverse@0.4.1:
+    resolution: {integrity: sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==}
+
+  json-stable-stringify-without-jsonify@1.0.1:
+    resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
+
+  json-stringify-safe@5.0.1:
+    resolution: {integrity: sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA==}
+
+  katex@0.17.0:
+    resolution: {integrity: sha512-Vdw0ATsQ9V+LuegM/BTwQqV/6cTl5lbGcIrU+BCgLxyf6bo38ybOr372tuSIxir3CN720flu1meYR6XzNMwQnw==}
+    hasBin: true
+
+  keyv@4.5.4:
+    resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
+
+  levn@0.4.1:
+    resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==}
+    engines: {node: '>= 0.8.0'}
+
+  linkify-it@5.0.2:
+    resolution: {integrity: sha512-ONTm2jCMAVZjgQa/Fy1kScXsuOoF5NPTsoFBdE1KVIZ2vAh/r9+Bqo+0jINCBYnavTPQZz38QzFTme79ENoN3Q==}
+
+  lit-element@4.2.2:
+    resolution: {integrity: sha512-aFKhNToWxoyhkNDmWZwEva2SlQia+jfG0fjIWV//YeTaWrVnOxD89dPKfigCUspXFmjzOEUQpOkejH5Ly6sG0w==}
+
+  lit-html@3.3.3:
+    resolution: {integrity: sha512-el8M6jK2o3RXBnrSHX3ZKrsN8zEV63pSExTO1wYJz7QndGYZ8353e2a5PPX+qHe2aGayfnchQmkAojaWAREOIA==}
+
+  lit@3.3.3:
+    resolution: {integrity: sha512-fycuvZg/hkpozL00lm1pEJH5nN/lr9ZXd6mJI2HSN4+Bzc+LDNdEApJ6HFbPkdFNHLvOplIIuJvxkS4XUxqirw==}
+
+  lite-hl@0.1.2:
+    resolution: {integrity: sha512-vfWGhEyMY7Cz4CiuOzb/NT2SdHSwqGzVqRd3zecA94vsg9bjHqFqNUzYbws0VaJQW6oVXoyKWw+dzCZB+FwVHA==}
+
+  lite-matter@0.1.1:
+    resolution: {integrity: sha512-3XlkLxQ3LtqtVsx1jGZMqFWKmRgH5J7/gbeU3WM1LjhV3XY+OjlNt0aEnf5De6qfxm/Qllv3vvzlLow0Dh6BoQ==}
+
+  lite-template@0.1.2:
+    resolution: {integrity: sha512-zWxWPs7QDGlHKOqgrSjYoq+zwQuvu+CUO6WkCRfnmme9pa8c0Mfv2huhoDfmbY7hUN5YTcuahD4SwI6/lww6jw==}
+
+  locate-path@6.0.0:
+    resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==}
+    engines: {node: '>=10'}
+
+  long@5.3.2:
+    resolution: {integrity: sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==}
+
+  lucide-static@0.577.0:
+    resolution: {integrity: sha512-hx39J5Tq4JWF2ALY+5YRg+SxQLpeAmLJDXNcqiBJH/UuVwp43it9fyki/onZO7AVFgG5ZbB+fWwZR9mwGHE2XQ==}
+
+  markdown-it-abbr@1.0.4:
+    resolution: {integrity: sha512-ZeA4Z4SaBbYysZap5iZcxKmlPL6bYA8grqhzJIHB1ikn7njnzaP8uwbtuXc4YXD5LicI4/2Xmc0VwmSiFV04gg==}
+
+  markdown-it-attrs@4.5.0:
+    resolution: {integrity: sha512-dsuEyK/MDAYsdZLDIaDAQXz5+gP0AAbJ4ZjOSB0w+ZGe4lLbzyCgGg0LApC6j9zUK2F+2SA9VkzXfyNG9hL/8g==}
+    engines: {node: '>=6'}
+    peerDependencies:
+      markdown-it: '>= 9.0.0'
+
+  markdown-it-deflist@2.1.0:
+    resolution: {integrity: sha512-3OuqoRUlSxJiuQYu0cWTLHNhhq2xtoSFqsZK8plANg91+RJQU1ziQ6lA2LzmFAEes18uPBsHZpcX6We5l76Nzg==}
+
+  markdown-it-emoji@2.0.2:
+    resolution: {integrity: sha512-zLftSaNrKuYl0kR5zm4gxXjHaOI3FAOEaloKmRA5hijmJZvSjmxcokOLlzycb/HXlUFWzXqpIEoyEMCE4i9MvQ==}
+
+  markdown-it-footnote@3.0.3:
+    resolution: {integrity: sha512-YZMSuCGVZAjzKMn+xqIco9d1cLGxbELHZ9do/TSYVzraooV8ypsppKNmUJ0fVH5ljkCInQAtFpm8Rb3eXSrt5w==}
+
+  markdown-it-task-lists@2.1.1:
+    resolution: {integrity: sha512-TxFAc76Jnhb2OUu+n3yz9RMu4CwGfaT788br6HhEDlvWfdeJcLUsxk1Hgw2yJio0OXsxv7pyIPmvECY7bMbluA==}
+
+  markdown-it-texmath@1.0.0:
+    resolution: {integrity: sha512-4hhkiX8/gus+6e53PLCUmUrsa6ZWGgJW2XCW6O0ASvZUiezIK900ZicinTDtG3kAO2kon7oUA/ReWmpW2FByxg==}
+
+  markdown-it@14.3.0:
+    resolution: {integrity: sha512-RCEsPjR+sr0x+AuYp601tKTkgFG4YEPLCzHST3cQ/fhlJkqAkz1L2/Qbp1j9qw5SBwQHFBoW8+hoN5xssOF0Tw==}
+    hasBin: true
+
+  marked@11.2.0:
+    resolution: {integrity: sha512-HR0m3bvu0jAPYiIvLUUQtdg1g6D247//lvcekpHO1WMvbwDlwSkZAX9Lw4F4YHE1T0HaaNve0tuAWuV1UJ6vtw==}
+    engines: {node: '>= 18'}
+    hasBin: true
+
+  matcher@3.0.0:
+    resolution: {integrity: sha512-OkeDaAZ/bQCxeFAozM55PKcKU0yJMPGifLwV4Qgjitu+5MoAfSQN4lsLJeXZ1b8w0x+/Emda6MZgXS1jvsapng==}
+    engines: {node: '>=10'}
+
+  matcher@4.0.0:
+    resolution: {integrity: sha512-S6x5wmcDmsDRRU/c2dkccDwQPXoFczc5+HpQ2lON8pnvHlnvHAHj5WlLVvw6n6vNyHuVugYrFohYxbS+pvFpKQ==}
+    engines: {node: '>=10'}
+
+  mdurl@2.0.0:
+    resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==}
+
+  minimatch@10.2.5:
+    resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
+    engines: {node: 18 || 20 || >=22}
+
+  minisearch@7.2.0:
+    resolution: {integrity: sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  nanoid@5.1.16:
+    resolution: {integrity: sha512-kVrnsrJqMR8+oLJnGEmSWw9BivK5mt7H3FZatVRjrc5wGqFYuBxX1yG7+A7Gi5AefkX6t/oCkizcQgpu0cY1dQ==}
+    engines: {node: ^18 || >=20}
+    hasBin: true
+
+  natural-compare@1.4.0:
+    resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
+
+  node-domexception@1.0.0:
+    resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
+    engines: {node: '>=10.5.0'}
+    deprecated: Use your platform's native DOMException instead
+
+  node-fetch@3.3.2:
+    resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  object-keys@1.1.1:
+    resolution: {integrity: sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==}
+    engines: {node: '>= 0.4'}
+
+  onnxruntime-common@1.24.0-dev.20251116-b39e144322:
+    resolution: {integrity: sha512-BOoomdHYmNRL5r4iQ4bMvsl2t0/hzVQ3OM3PHD0gxeXu1PmggqBv3puZicEUVOA3AtHHYmqZtjMj9FOfGrATTw==}
+
+  onnxruntime-common@1.24.3:
+    resolution: {integrity: sha512-GeuPZO6U/LBJXvwdaqHbuUmoXiEdeCjWi/EG7Y1HNnDwJYuk6WUbNXpF6luSUY8yASul3cmUlLGrCCL1ZgVXqA==}
+
+  onnxruntime-common@1.27.0:
+    resolution: {integrity: sha512-3KxL5wIVqa8Ex08jxSzncm9CMgw8CjOFyOQ7SxvG9o0cVLlhTNKXyIQuTbtX4tGPJEf73OER2xrjt4HJSBL4ow==}
+
+  onnxruntime-node@1.24.3:
+    resolution: {integrity: sha512-JH7+czbc8ALA819vlTgcV+Q214/+VjGeBHDjX81+ZCD0PCVCIFGFNtT0V4sXG/1JXypKPgScQcB3ij/hk3YnTg==}
+    os: [win32, darwin, linux]
+
+  onnxruntime-node@1.27.0:
+    resolution: {integrity: sha512-QEzGwrvNBgv4uPVdnbHsOGG4G6T96mdlcFI8aAKPjMU8wOPpVocPXb6k3QGkaZagVTv2G9Bnnbo6Z3JdXr1fQw==}
+    os: [win32, darwin, linux]
+
+  onnxruntime-web@1.26.0-dev.20260416-b7804b056c:
+    resolution: {integrity: sha512-MD6Ss4GSpQBo6zqoJzyT9LRbKYs7x/JVN23FT24EcEvlqF4VuzPOeH6X38orZPKHQDbprn7K+SBpu0/mj2CQiw==}
+
+  optionator@0.9.4:
+    resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
+    engines: {node: '>= 0.8.0'}
+
+  p-limit@3.1.0:
+    resolution: {integrity: sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==}
+    engines: {node: '>=10'}
+
+  p-locate@5.0.0:
+    resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
+    engines: {node: '>=10'}
+
+  parse5@7.3.0:
+    resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==}
+
+  path-exists@4.0.0:
+    resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
+    engines: {node: '>=8'}
+
+  path-key@3.1.1:
+    resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
+    engines: {node: '>=8'}
+
+  picomatch@4.0.5:
+    resolution: {integrity: sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==}
+    engines: {node: '>=12'}
+
+  platform@1.3.6:
+    resolution: {integrity: sha512-fnWVljUchTro6RiCFvCXBbNhJc2NijN7oIQxbwsyL0buWJPG85v81ehlHI9fXrJsMNgTofEoWIQeClKpgxFLrg==}
+
+  playwright-core@1.61.1:
+    resolution: {integrity: sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  playwright@1.61.1:
+    resolution: {integrity: sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  prelude-ls@1.2.1:
+    resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
+    engines: {node: '>= 0.8.0'}
+
+  protobufjs@7.6.5:
+    resolution: {integrity: sha512-/FPD0nUc9jH6rfFjji9IBqOz4pcSE3CsT1m7Ep6Mdb0LxSUMj8hgl6GomOvZzpNpAqqGaXA0P3VSrZLFzIhQrw==}
+    engines: {node: '>=12.0.0'}
+
+  punycode.js@2.3.1:
+    resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==}
+    engines: {node: '>=6'}
+
+  punycode@2.3.1:
+    resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
+    engines: {node: '>=6'}
+
+  roarr@2.15.4:
+    resolution: {integrity: sha512-CHhPh+UNHD2GTXNYhPWLnU8ONHdI+5DI+4EYIAOaiD63rHeYlZvyh8P+in5999TTSFgUYuKUAjzRI4mdh/p+2A==}
+    engines: {node: '>=8.0'}
+
+  semver-compare@1.0.0:
+    resolution: {integrity: sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow==}
+
+  semver@7.8.5:
+    resolution: {integrity: sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  serialize-error@7.0.1:
+    resolution: {integrity: sha512-8I8TjW5KMOKsZQTvoxjuSIa7foAwPWGOts+6o7sgjz41/qMD9VQHEDxi6PBvK2l0MXUmqZyNpUK+T2tQaaElvw==}
+    engines: {node: '>=10'}
+
+  serialize-error@8.1.0:
+    resolution: {integrity: sha512-3NnuWfM6vBYoy5gZFvHiYsVbafvI9vZv/+jlIigFn4oP4zjNPK3LhcY0xSCgeb1a5L8jO71Mit9LlNoi2UfDDQ==}
+    engines: {node: '>=10'}
+
+  sharp@0.34.5:
+    resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==}
+    engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
+
+  shebang-command@2.0.0:
+    resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
+    engines: {node: '>=8'}
+
+  shebang-regex@3.0.0:
+    resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
+    engines: {node: '>=8'}
+
+  sprintf-js@1.1.3:
+    resolution: {integrity: sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA==}
+
+  supports-color@7.2.0:
+    resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
+    engines: {node: '>=8'}
+
+  tapable@2.3.3:
+    resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
+    engines: {node: '>=6'}
+
+  tinyglobby@0.2.17:
+    resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
+    engines: {node: '>=12.0.0'}
+
+  ts-api-utils@2.5.0:
+    resolution: {integrity: sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==}
+    engines: {node: '>=18.12'}
+    peerDependencies:
+      typescript: '>=4.8.4'
+
+  tslib@2.8.1:
+    resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
+
+  tsx@4.23.0:
+    resolution: {integrity: sha512-eUdUIaCr963q2h5u3+QwvYp0+eqPvn+egeqZUm0hwERCqqx1E3kK5ehbGCvqSE5MQAULr67ww0cA3jKc3YkM1w==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  type-check@0.4.0:
+    resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}
+    engines: {node: '>= 0.8.0'}
+
+  type-fest@0.13.1:
+    resolution: {integrity: sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg==}
+    engines: {node: '>=10'}
+
+  type-fest@0.20.2:
+    resolution: {integrity: sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==}
+    engines: {node: '>=10'}
+
+  typescript-eslint@8.63.0:
+    resolution: {integrity: sha512-xgwXyzG4sK9ALkBxbyGkTMMOS+imnW65iPhxCQMK83KhxyoDNW7l+IDqEf9vMdoUidHpOoS967RCq4eMiTexwQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  uc.micro@2.1.0:
+    resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==}
+
+  undici-types@7.18.2:
+    resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
+
+  undici-types@8.3.0:
+    resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==}
+
+  uri-js@4.4.1:
+    resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
+
+  web-streams-polyfill@3.3.3:
+    resolution: {integrity: sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==}
+    engines: {node: '>= 8'}
+
+  which@2.0.2:
+    resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
+    engines: {node: '>= 8'}
+    hasBin: true
+
+  word-wrap@1.2.5:
+    resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
+    engines: {node: '>=0.10.0'}
+
+  ws@8.21.0:
+    resolution: {integrity: sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==}
+    engines: {node: '>=10.0.0'}
+    peerDependencies:
+      bufferutil: ^4.0.1
+      utf-8-validate: '>=5.0.2'
+    peerDependenciesMeta:
+      bufferutil:
+        optional: true
+      utf-8-validate:
+        optional: true
+
+  yaml@2.9.0:
+    resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
+  yocto-queue@0.1.0:
+    resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
+    engines: {node: '>=10'}
+
+snapshots:
+
+  '@awesome.me/webawesome@3.10.0(@floating-ui/utils@0.2.11)(@types/node@24.13.3)(@types/react@19.2.14)':
+    dependencies:
+      '@ctrl/tinycolor': 4.1.0
+      '@floating-ui/dom': 1.7.6
+      '@konnorr/qr-creator': 1.0.1
+      '@lit-labs/ssr': 4.1.0(@types/node@24.13.3)
+      '@lit-labs/ssr-client': 1.1.8
+      '@lit/context': 1.1.6
+      '@lit/react': 1.0.8(@types/react@19.2.14)
+      '@shoelace-style/animations': 1.2.0
+      '@shoelace-style/localize': 3.2.2
+      composed-offset-position: 0.0.6(@floating-ui/utils@0.2.11)
+      lit: 3.3.3
+      marked: 11.2.0
+      nanoid: 5.1.16
+    transitivePeerDependencies:
+      - '@floating-ui/utils'
+      - '@types/node'
+      - '@types/react'
+
+  '@ctrl/tinycolor@4.1.0': {}
+
+  '@emnapi/runtime@1.11.2':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
+  '@esbuild/aix-ppc64@0.28.1':
+    optional: true
+
+  '@esbuild/android-arm64@0.28.1':
+    optional: true
+
+  '@esbuild/android-arm@0.28.1':
+    optional: true
+
+  '@esbuild/android-x64@0.28.1':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.28.1':
+    optional: true
+
+  '@esbuild/darwin-x64@0.28.1':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.28.1':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.28.1':
+    optional: true
+
+  '@esbuild/linux-arm64@0.28.1':
+    optional: true
+
+  '@esbuild/linux-arm@0.28.1':
+    optional: true
+
+  '@esbuild/linux-ia32@0.28.1':
+    optional: true
+
+  '@esbuild/linux-loong64@0.28.1':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.28.1':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.28.1':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.28.1':
+    optional: true
+
+  '@esbuild/linux-s390x@0.28.1':
+    optional: true
+
+  '@esbuild/linux-x64@0.28.1':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.28.1':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.28.1':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.28.1':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.28.1':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.28.1':
+    optional: true
+
+  '@esbuild/sunos-x64@0.28.1':
+    optional: true
+
+  '@esbuild/win32-arm64@0.28.1':
+    optional: true
+
+  '@esbuild/win32-ia32@0.28.1':
+    optional: true
+
+  '@esbuild/win32-x64@0.28.1':
+    optional: true
+
+  '@eslint-community/eslint-utils@4.9.1(eslint@10.6.0)':
+    dependencies:
+      eslint: 10.6.0
+      eslint-visitor-keys: 3.4.3
+
+  '@eslint-community/regexpp@4.12.2': {}
+
+  '@eslint/config-array@0.23.5':
+    dependencies:
+      '@eslint/object-schema': 3.0.5
+      debug: 4.4.3
+      minimatch: 10.2.5
+    transitivePeerDependencies:
+      - supports-color
+
+  '@eslint/config-helpers@0.6.0':
+    dependencies:
+      '@eslint/core': 1.2.1
+
+  '@eslint/core@1.2.1':
+    dependencies:
+      '@types/json-schema': 7.0.15
+
+  '@eslint/js@10.0.1(eslint@10.6.0)':
+    optionalDependencies:
+      eslint: 10.6.0
+
+  '@eslint/object-schema@3.0.5': {}
+
+  '@eslint/plugin-kit@0.7.2':
+    dependencies:
+      '@eslint/core': 1.2.1
+      levn: 0.4.1
+
+  '@floating-ui/core@1.7.5':
+    dependencies:
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/dom@1.7.6':
+    dependencies:
+      '@floating-ui/core': 1.7.5
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/utils@0.2.11': {}
+
+  '@huggingface/jinja@0.5.9': {}
+
+  '@huggingface/tokenizers@0.1.3': {}
+
+  '@huggingface/transformers@4.2.0':
+    dependencies:
+      '@huggingface/jinja': 0.5.9
+      '@huggingface/tokenizers': 0.1.3
+      onnxruntime-node: 1.24.3
+      onnxruntime-web: 1.26.0-dev.20260416-b7804b056c
+      sharp: 0.34.5
+
+  '@humanfs/core@0.19.2':
+    dependencies:
+      '@humanfs/types': 0.15.0
+
+  '@humanfs/node@0.16.8':
+    dependencies:
+      '@humanfs/core': 0.19.2
+      '@humanfs/types': 0.15.0
+      '@humanwhocodes/retry': 0.4.3
+
+  '@humanfs/types@0.15.0': {}
+
+  '@humanwhocodes/module-importer@1.0.1': {}
+
+  '@humanwhocodes/retry@0.4.3': {}
+
+  '@img/colour@1.1.0': {}
+
+  '@img/sharp-darwin-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-darwin-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-libvips-darwin-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-darwin-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-arm@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-ppc64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-riscv64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-s390x@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linux-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
+    optional: true
+
+  '@img/sharp-libvips-linuxmusl-x64@1.2.4':
+    optional: true
+
+  '@img/sharp-linux-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-arm@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-arm': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-ppc64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-riscv64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-s390x@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+    optional: true
+
+  '@img/sharp-linux-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linux-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-arm64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+    optional: true
+
+  '@img/sharp-linuxmusl-x64@0.34.5':
+    optionalDependencies:
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+    optional: true
+
+  '@img/sharp-wasm32@0.34.5':
+    dependencies:
+      '@emnapi/runtime': 1.11.2
+    optional: true
+
+  '@img/sharp-win32-arm64@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-ia32@0.34.5':
+    optional: true
+
+  '@img/sharp-win32-x64@0.34.5':
+    optional: true
+
+  '@konnorr/qr-creator@1.0.1': {}
+
+  '@lit-labs/ssr-client@1.1.8':
+    dependencies:
+      '@lit/reactive-element': 2.1.2
+      lit: 3.3.3
+      lit-html: 3.3.3
+
+  '@lit-labs/ssr-dom-shim@1.6.0': {}
+
+  '@lit-labs/ssr@4.1.0(@types/node@24.13.3)':
+    dependencies:
+      '@lit-labs/ssr-client': 1.1.8
+      '@lit-labs/ssr-dom-shim': 1.6.0
+      '@lit/reactive-element': 2.1.2
+      '@parse5/tools': 0.3.0
+      enhanced-resolve: 5.24.2
+      lit: 3.3.3
+      lit-element: 4.2.2
+      lit-html: 3.3.3
+      node-fetch: 3.3.2
+      parse5: 7.3.0
+    optionalDependencies:
+      '@types/node': 24.13.3
+
+  '@lit/context@1.1.6':
+    dependencies:
+      '@lit/reactive-element': 2.1.2
+
+  '@lit/react@1.0.8(@types/react@19.2.14)':
+    dependencies:
+      '@types/react': 19.2.14
+
+  '@lit/reactive-element@2.1.2':
+    dependencies:
+      '@lit-labs/ssr-dom-shim': 1.6.0
+
+  '@parse5/tools@0.3.0':
+    dependencies:
+      parse5: 7.3.0
+
+  '@playwright/test@1.61.1':
+    dependencies:
+      playwright: 1.61.1
+
+  '@protobufjs/aspromise@1.1.2': {}
+
+  '@protobufjs/base64@1.1.2': {}
+
+  '@protobufjs/codegen@2.0.5': {}
+
+  '@protobufjs/eventemitter@1.1.1': {}
+
+  '@protobufjs/fetch@1.1.1':
+    dependencies:
+      '@protobufjs/aspromise': 1.1.2
+
+  '@protobufjs/float@1.0.2': {}
+
+  '@protobufjs/path@1.1.2': {}
+
+  '@protobufjs/pool@1.1.0': {}
+
+  '@protobufjs/utf8@1.1.2': {}
+
+  '@shoelace-style/animations@1.2.0': {}
+
+  '@shoelace-style/localize@3.2.2': {}
+
+  '@types/esrecurse@4.3.1': {}
+
+  '@types/estree@1.0.9': {}
+
+  '@types/json-schema@7.0.15': {}
+
+  '@types/linkify-it@5.0.0': {}
+
+  '@types/markdown-it@14.1.2':
+    dependencies:
+      '@types/linkify-it': 5.0.0
+      '@types/mdurl': 2.0.0
+
+  '@types/mdurl@2.0.0': {}
+
+  '@types/node@24.13.3':
+    dependencies:
+      undici-types: 7.18.2
+
+  '@types/node@26.1.1':
+    dependencies:
+      undici-types: 8.3.0
+
+  '@types/react@19.2.14':
+    dependencies:
+      csstype: 3.2.3
+
+  '@types/trusted-types@2.0.7': {}
+
+  '@typescript-eslint/eslint-plugin@8.63.0(@typescript-eslint/parser@8.63.0(eslint@10.6.0)(typescript@5.9.3))(eslint@10.6.0)(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/regexpp': 4.12.2
+      '@typescript-eslint/parser': 8.63.0(eslint@10.6.0)(typescript@5.9.3)
+      '@typescript-eslint/scope-manager': 8.63.0
+      '@typescript-eslint/type-utils': 8.63.0(eslint@10.6.0)(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.63.0(eslint@10.6.0)(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.63.0
+      eslint: 10.6.0
+      ignore: 7.0.5
+      natural-compare: 1.4.0
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/parser@8.63.0(eslint@10.6.0)(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/scope-manager': 8.63.0
+      '@typescript-eslint/types': 8.63.0
+      '@typescript-eslint/typescript-estree': 8.63.0(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.63.0
+      debug: 4.4.3
+      eslint: 10.6.0
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/project-service@8.63.0(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/tsconfig-utils': 8.63.0(typescript@5.9.3)
+      '@typescript-eslint/types': 8.63.0
+      debug: 4.4.3
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/scope-manager@8.63.0':
+    dependencies:
+      '@typescript-eslint/types': 8.63.0
+      '@typescript-eslint/visitor-keys': 8.63.0
+
+  '@typescript-eslint/tsconfig-utils@8.63.0(typescript@5.9.3)':
+    dependencies:
+      typescript: 5.9.3
+
+  '@typescript-eslint/type-utils@8.63.0(eslint@10.6.0)(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/types': 8.63.0
+      '@typescript-eslint/typescript-estree': 8.63.0(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.63.0(eslint@10.6.0)(typescript@5.9.3)
+      debug: 4.4.3
+      eslint: 10.6.0
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/types@8.63.0': {}
+
+  '@typescript-eslint/typescript-estree@8.63.0(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/project-service': 8.63.0(typescript@5.9.3)
+      '@typescript-eslint/tsconfig-utils': 8.63.0(typescript@5.9.3)
+      '@typescript-eslint/types': 8.63.0
+      '@typescript-eslint/visitor-keys': 8.63.0
+      debug: 4.4.3
+      minimatch: 10.2.5
+      semver: 7.8.5
+      tinyglobby: 0.2.17
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/utils@8.63.0(eslint@10.6.0)(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@10.6.0)
+      '@typescript-eslint/scope-manager': 8.63.0
+      '@typescript-eslint/types': 8.63.0
+      '@typescript-eslint/typescript-estree': 8.63.0(typescript@5.9.3)
+      eslint: 10.6.0
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/visitor-keys@8.63.0':
+    dependencies:
+      '@typescript-eslint/types': 8.63.0
+      eslint-visitor-keys: 5.0.1
+
+  acorn-jsx@5.3.2(acorn@8.17.0):
+    dependencies:
+      acorn: 8.17.0
+
+  acorn@8.17.0: {}
+
+  adm-zip@0.5.18: {}
+
+  ajv@6.15.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-json-stable-stringify: 2.1.0
+      json-schema-traverse: 0.4.1
+      uri-js: 4.4.1
+
+  ansi-styles@4.3.0:
+    dependencies:
+      color-convert: 2.0.1
+
+  argparse@2.0.1: {}
+
+  balanced-match@4.0.4: {}
+
+  base64-js@1.5.1: {}
+
+  boolean@3.2.0: {}
+
+  brace-expansion@5.0.7:
+    dependencies:
+      balanced-match: 4.0.4
+
+  buffer@6.0.3:
+    dependencies:
+      base64-js: 1.5.1
+      ieee754: 1.2.1
+
+  chalk@4.1.2:
+    dependencies:
+      ansi-styles: 4.3.0
+      supports-color: 7.2.0
+
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-name@1.1.4: {}
+
+  commander@8.3.0: {}
+
+  composed-offset-position@0.0.6(@floating-ui/utils@0.2.11):
+    dependencies:
+      '@floating-ui/utils': 0.2.11
+
+  cross-spawn@7.0.6:
+    dependencies:
+      path-key: 3.1.1
+      shebang-command: 2.0.0
+      which: 2.0.2
+
+  csstype@3.2.3: {}
+
+  data-uri-to-buffer@4.0.1: {}
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  deep-is@0.1.4: {}
+
+  define-data-property@1.1.4:
+    dependencies:
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
+  define-properties@1.2.1:
+    dependencies:
+      define-data-property: 1.1.4
+      has-property-descriptors: 1.0.2
+      object-keys: 1.1.1
+
+  detect-libc@2.1.2: {}
+
+  detect-node@2.1.0: {}
+
+  docmd-search@0.1.0(@huggingface/transformers@4.2.0)(onnxruntime-node@1.27.0):
+    optionalDependencies:
+      '@huggingface/transformers': 4.2.0
+      onnxruntime-node: 1.27.0
+
+  embed-lite@0.1.4: {}
+
+  enhanced-resolve@5.24.2:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.3
+
+  entities@4.5.0: {}
+
+  entities@6.0.1: {}
+
+  es-define-property@1.0.1: {}
+
+  es-errors@1.3.0: {}
+
+  es6-error@4.1.1: {}
+
+  esbuild@0.28.1:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.28.1
+      '@esbuild/android-arm': 0.28.1
+      '@esbuild/android-arm64': 0.28.1
+      '@esbuild/android-x64': 0.28.1
+      '@esbuild/darwin-arm64': 0.28.1
+      '@esbuild/darwin-x64': 0.28.1
+      '@esbuild/freebsd-arm64': 0.28.1
+      '@esbuild/freebsd-x64': 0.28.1
+      '@esbuild/linux-arm': 0.28.1
+      '@esbuild/linux-arm64': 0.28.1
+      '@esbuild/linux-ia32': 0.28.1
+      '@esbuild/linux-loong64': 0.28.1
+      '@esbuild/linux-mips64el': 0.28.1
+      '@esbuild/linux-ppc64': 0.28.1
+      '@esbuild/linux-riscv64': 0.28.1
+      '@esbuild/linux-s390x': 0.28.1
+      '@esbuild/linux-x64': 0.28.1
+      '@esbuild/netbsd-arm64': 0.28.1
+      '@esbuild/netbsd-x64': 0.28.1
+      '@esbuild/openbsd-arm64': 0.28.1
+      '@esbuild/openbsd-x64': 0.28.1
+      '@esbuild/openharmony-arm64': 0.28.1
+      '@esbuild/sunos-x64': 0.28.1
+      '@esbuild/win32-arm64': 0.28.1
+      '@esbuild/win32-ia32': 0.28.1
+      '@esbuild/win32-x64': 0.28.1
+
+  escape-string-regexp@4.0.0: {}
+
+  eslint-scope@9.1.2:
+    dependencies:
+      '@types/esrecurse': 4.3.1
+      '@types/estree': 1.0.9
+      esrecurse: 4.3.0
+      estraverse: 5.3.0
+
+  eslint-visitor-keys@3.4.3: {}
+
+  eslint-visitor-keys@5.0.1: {}
+
+  eslint@10.6.0:
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@10.6.0)
+      '@eslint-community/regexpp': 4.12.2
+      '@eslint/config-array': 0.23.5
+      '@eslint/config-helpers': 0.6.0
+      '@eslint/core': 1.2.1
+      '@eslint/plugin-kit': 0.7.2
+      '@humanfs/node': 0.16.8
+      '@humanwhocodes/module-importer': 1.0.1
+      '@humanwhocodes/retry': 0.4.3
+      '@types/estree': 1.0.9
+      ajv: 6.15.0
+      cross-spawn: 7.0.6
+      debug: 4.4.3
+      escape-string-regexp: 4.0.0
+      eslint-scope: 9.1.2
+      eslint-visitor-keys: 5.0.1
+      espree: 11.2.0
+      esquery: 1.7.0
+      esutils: 2.0.3
+      fast-deep-equal: 3.1.3
+      file-entry-cache: 8.0.0
+      find-up: 5.0.0
+      glob-parent: 6.0.2
+      ignore: 5.3.2
+      imurmurhash: 0.1.4
+      is-glob: 4.0.3
+      json-stable-stringify-without-jsonify: 1.0.1
+      minimatch: 10.2.5
+      natural-compare: 1.4.0
+      optionator: 0.9.4
+    transitivePeerDependencies:
+      - supports-color
+
+  espree@11.2.0:
+    dependencies:
+      acorn: 8.17.0
+      acorn-jsx: 5.3.2(acorn@8.17.0)
+      eslint-visitor-keys: 5.0.1
+
+  esquery@1.7.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  esrecurse@4.3.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  estraverse@5.3.0: {}
+
+  esutils@2.0.3: {}
+
+  fast-deep-equal@3.1.3: {}
+
+  fast-json-stable-stringify@2.1.0: {}
+
+  fast-levenshtein@2.0.6: {}
+
+  fdir@6.5.0(picomatch@4.0.5):
+    optionalDependencies:
+      picomatch: 4.0.5
+
+  fetch-blob@3.2.0:
+    dependencies:
+      node-domexception: 1.0.0
+      web-streams-polyfill: 3.3.3
+
+  file-entry-cache@8.0.0:
+    dependencies:
+      flat-cache: 4.0.1
+
+  find-up@5.0.0:
+    dependencies:
+      locate-path: 6.0.0
+      path-exists: 4.0.0
+
+  flat-cache@4.0.1:
+    dependencies:
+      flatted: 3.4.2
+      keyv: 4.5.4
+
+  flatbuffers@25.9.23: {}
+
+  flatted@3.4.2: {}
+
+  formdata-polyfill@4.0.10:
+    dependencies:
+      fetch-blob: 3.2.0
+
+  fsevents@2.3.2:
+    optional: true
+
+  fsevents@2.3.3:
+    optional: true
+
+  glob-parent@6.0.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  global-agent@3.0.0:
+    dependencies:
+      boolean: 3.2.0
+      es6-error: 4.1.1
+      matcher: 3.0.0
+      roarr: 2.15.4
+      semver: 7.8.5
+      serialize-error: 7.0.1
+
+  global-agent@4.1.3:
+    dependencies:
+      globalthis: 1.0.4
+      matcher: 4.0.0
+      semver: 7.8.5
+      serialize-error: 8.1.0
+
+  globals@17.7.0: {}
+
+  globalthis@1.0.4:
+    dependencies:
+      define-properties: 1.2.1
+      gopd: 1.2.0
+
+  gopd@1.2.0: {}
+
+  graceful-fs@4.2.11: {}
+
+  guid-typescript@1.0.9: {}
+
+  has-flag@4.0.0: {}
+
+  has-property-descriptors@1.0.2:
+    dependencies:
+      es-define-property: 1.0.1
+
+  ieee754@1.2.1: {}
+
+  ignore@5.3.2: {}
+
+  ignore@7.0.5: {}
+
+  imurmurhash@0.1.4: {}
+
+  is-extglob@2.1.1: {}
+
+  is-glob@4.0.3:
+    dependencies:
+      is-extglob: 2.1.1
+
+  isexe@2.0.0: {}
+
+  json-buffer@3.0.1: {}
+
+  json-schema-traverse@0.4.1: {}
+
+  json-stable-stringify-without-jsonify@1.0.1: {}
+
+  json-stringify-safe@5.0.1: {}
+
+  katex@0.17.0:
+    dependencies:
+      commander: 8.3.0
+
+  keyv@4.5.4:
+    dependencies:
+      json-buffer: 3.0.1
+
+  levn@0.4.1:
+    dependencies:
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+
+  linkify-it@5.0.2:
+    dependencies:
+      uc.micro: 2.1.0
+
+  lit-element@4.2.2:
+    dependencies:
+      '@lit-labs/ssr-dom-shim': 1.6.0
+      '@lit/reactive-element': 2.1.2
+      lit-html: 3.3.3
+
+  lit-html@3.3.3:
+    dependencies:
+      '@types/trusted-types': 2.0.7
+
+  lit@3.3.3:
+    dependencies:
+      '@lit/reactive-element': 2.1.2
+      lit-element: 4.2.2
+      lit-html: 3.3.3
+
+  lite-hl@0.1.2: {}
+
+  lite-matter@0.1.1:
+    dependencies:
+      yaml: 2.9.0
+
+  lite-template@0.1.2: {}
+
+  locate-path@6.0.0:
+    dependencies:
+      p-locate: 5.0.0
+
+  long@5.3.2: {}
+
+  lucide-static@0.577.0: {}
+
+  markdown-it-abbr@1.0.4: {}
+
+  markdown-it-attrs@4.5.0(markdown-it@14.3.0):
+    dependencies:
+      markdown-it: 14.3.0
+
+  markdown-it-deflist@2.1.0: {}
+
+  markdown-it-emoji@2.0.2: {}
+
+  markdown-it-footnote@3.0.3: {}
+
+  markdown-it-task-lists@2.1.1: {}
+
+  markdown-it-texmath@1.0.0: {}
+
+  markdown-it@14.3.0:
+    dependencies:
+      argparse: 2.0.1
+      entities: 4.5.0
+      linkify-it: 5.0.2
+      mdurl: 2.0.0
+      punycode.js: 2.3.1
+      uc.micro: 2.1.0
+
+  marked@11.2.0: {}
+
+  matcher@3.0.0:
+    dependencies:
+      escape-string-regexp: 4.0.0
+
+  matcher@4.0.0:
+    dependencies:
+      escape-string-regexp: 4.0.0
+
+  mdurl@2.0.0: {}
+
+  minimatch@10.2.5:
+    dependencies:
+      brace-expansion: 5.0.7
+
+  minisearch@7.2.0: {}
+
+  ms@2.1.3: {}
+
+  nanoid@5.1.16: {}
+
+  natural-compare@1.4.0: {}
+
+  node-domexception@1.0.0: {}
+
+  node-fetch@3.3.2:
+    dependencies:
+      data-uri-to-buffer: 4.0.1
+      fetch-blob: 3.2.0
+      formdata-polyfill: 4.0.10
+
+  object-keys@1.1.1: {}
+
+  onnxruntime-common@1.24.0-dev.20251116-b39e144322: {}
+
+  onnxruntime-common@1.24.3: {}
+
+  onnxruntime-common@1.27.0: {}
+
+  onnxruntime-node@1.24.3:
+    dependencies:
+      adm-zip: 0.5.18
+      global-agent: 3.0.0
+      onnxruntime-common: 1.24.3
+
+  onnxruntime-node@1.27.0:
+    dependencies:
+      adm-zip: 0.5.18
+      global-agent: 4.1.3
+      onnxruntime-common: 1.27.0
+
+  onnxruntime-web@1.26.0-dev.20260416-b7804b056c:
+    dependencies:
+      flatbuffers: 25.9.23
+      guid-typescript: 1.0.9
+      long: 5.3.2
+      onnxruntime-common: 1.24.0-dev.20251116-b39e144322
+      platform: 1.3.6
+      protobufjs: 7.6.5
+
+  optionator@0.9.4:
+    dependencies:
+      deep-is: 0.1.4
+      fast-levenshtein: 2.0.6
+      levn: 0.4.1
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+      word-wrap: 1.2.5
+
+  p-limit@3.1.0:
+    dependencies:
+      yocto-queue: 0.1.0
+
+  p-locate@5.0.0:
+    dependencies:
+      p-limit: 3.1.0
+
+  parse5@7.3.0:
+    dependencies:
+      entities: 6.0.1
+
+  path-exists@4.0.0: {}
+
+  path-key@3.1.1: {}
+
+  picomatch@4.0.5: {}
+
+  platform@1.3.6: {}
+
+  playwright-core@1.61.1: {}
+
+  playwright@1.61.1:
+    dependencies:
+      playwright-core: 1.61.1
+    optionalDependencies:
+      fsevents: 2.3.2
+
+  prelude-ls@1.2.1: {}
+
+  protobufjs@7.6.5:
+    dependencies:
+      '@protobufjs/aspromise': 1.1.2
+      '@protobufjs/base64': 1.1.2
+      '@protobufjs/codegen': 2.0.5
+      '@protobufjs/eventemitter': 1.1.1
+      '@protobufjs/fetch': 1.1.1
+      '@protobufjs/float': 1.0.2
+      '@protobufjs/path': 1.1.2
+      '@protobufjs/pool': 1.1.0
+      '@protobufjs/utf8': 1.1.2
+      '@types/node': 26.1.1
+      long: 5.3.2
+
+  punycode.js@2.3.1: {}
+
+  punycode@2.3.1: {}
+
+  roarr@2.15.4:
+    dependencies:
+      boolean: 3.2.0
+      detect-node: 2.1.0
+      globalthis: 1.0.4
+      json-stringify-safe: 5.0.1
+      semver-compare: 1.0.0
+      sprintf-js: 1.1.3
+
+  semver-compare@1.0.0: {}
+
+  semver@7.8.5: {}
+
+  serialize-error@7.0.1:
+    dependencies:
+      type-fest: 0.13.1
+
+  serialize-error@8.1.0:
+    dependencies:
+      type-fest: 0.20.2
+
+  sharp@0.34.5:
+    dependencies:
+      '@img/colour': 1.1.0
+      detect-libc: 2.1.2
+      semver: 7.8.5
+    optionalDependencies:
+      '@img/sharp-darwin-arm64': 0.34.5
+      '@img/sharp-darwin-x64': 0.34.5
+      '@img/sharp-libvips-darwin-arm64': 1.2.4
+      '@img/sharp-libvips-darwin-x64': 1.2.4
+      '@img/sharp-libvips-linux-arm': 1.2.4
+      '@img/sharp-libvips-linux-arm64': 1.2.4
+      '@img/sharp-libvips-linux-ppc64': 1.2.4
+      '@img/sharp-libvips-linux-riscv64': 1.2.4
+      '@img/sharp-libvips-linux-s390x': 1.2.4
+      '@img/sharp-libvips-linux-x64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
+      '@img/sharp-libvips-linuxmusl-x64': 1.2.4
+      '@img/sharp-linux-arm': 0.34.5
+      '@img/sharp-linux-arm64': 0.34.5
+      '@img/sharp-linux-ppc64': 0.34.5
+      '@img/sharp-linux-riscv64': 0.34.5
+      '@img/sharp-linux-s390x': 0.34.5
+      '@img/sharp-linux-x64': 0.34.5
+      '@img/sharp-linuxmusl-arm64': 0.34.5
+      '@img/sharp-linuxmusl-x64': 0.34.5
+      '@img/sharp-wasm32': 0.34.5
+      '@img/sharp-win32-arm64': 0.34.5
+      '@img/sharp-win32-ia32': 0.34.5
+      '@img/sharp-win32-x64': 0.34.5
+
+  shebang-command@2.0.0:
+    dependencies:
+      shebang-regex: 3.0.0
+
+  shebang-regex@3.0.0: {}
+
+  sprintf-js@1.1.3: {}
+
+  supports-color@7.2.0:
+    dependencies:
+      has-flag: 4.0.0
+
+  tapable@2.3.3: {}
+
+  tinyglobby@0.2.17:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.5)
+      picomatch: 4.0.5
+
+  ts-api-utils@2.5.0(typescript@5.9.3):
+    dependencies:
+      typescript: 5.9.3
+
+  tslib@2.8.1:
+    optional: true
+
+  tsx@4.23.0:
+    dependencies:
+      esbuild: 0.28.1
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  type-check@0.4.0:
+    dependencies:
+      prelude-ls: 1.2.1
+
+  type-fest@0.13.1: {}
+
+  type-fest@0.20.2: {}
+
+  typescript-eslint@8.63.0(eslint@10.6.0)(typescript@5.9.3):
+    dependencies:
+      '@typescript-eslint/eslint-plugin': 8.63.0(@typescript-eslint/parser@8.63.0(eslint@10.6.0)(typescript@5.9.3))(eslint@10.6.0)(typescript@5.9.3)
+      '@typescript-eslint/parser': 8.63.0(eslint@10.6.0)(typescript@5.9.3)
+      '@typescript-eslint/typescript-estree': 8.63.0(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.63.0(eslint@10.6.0)(typescript@5.9.3)
+      eslint: 10.6.0
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  typescript@5.9.3: {}
+
+  uc.micro@2.1.0: {}
+
+  undici-types@7.18.2: {}
+
+  undici-types@8.3.0: {}
+
+  uri-js@4.4.1:
+    dependencies:
+      punycode: 2.3.1
+
+  web-streams-polyfill@3.3.3: {}
+
+  which@2.0.2:
+    dependencies:
+      isexe: 2.0.0
+
+  word-wrap@1.2.5: {}
+
+  ws@8.21.0: {}
+
+  yaml@2.9.0: {}
+
+  yocto-queue@0.1.0: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 0000000..02435eb
--- /dev/null
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,9 @@
+packages:
+  - 'packages/*'
+  - 'packages/legacy/*'
+  - 'packages/plugins/*'
+  - 'packages/templates/*'
+  - 'packages/engines/*'
+
+public-hoist-pattern:
+  - '@types/*'
\ No newline at end of file
diff --git a/scripts/build-plugin-registry.mjs b/scripts/build-plugin-registry.mjs
new file mode 100644
index 0000000..93ee0f6
--- /dev/null
+++ b/scripts/build-plugin-registry.mjs
@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * --------------------------------------------------------------------
+ * build-plugin-registry : single source of truth for the official plugin
+ * and template catalog.
+ *
+ * Scans packages/{plugins,templates,engines}/*, reads each package's
+ * `package.json#docmd` namespace, and emits a generated JSON registry
+ * that the runtime loader (`packages/api/src/hooks.ts`) consumes.
+ *
+ * Why generated:
+ *  - Eliminates drift between packages/ and the hand-maintained
+ *    plugins/installer/registry/plugins.json (which used to be a
+ *    third place to remember to update when adding a new plugin).
+ *  - The `docmd` namespace in each package's package.json is the
+ *    canonical source. This script is a thin reader.
+ *
+ * Why not read package.json's directly at runtime:
+ *  - The published `@docmd/api` package doesn't carry the source
+ *    `package.json` files of every plugin. Bundling a generated
+ *    registry keeps the loader dependency-free and fast.
+ *  - A build-time check can fail loudly if a package forgot a
+ *    required field; a runtime check just warns.
+ *
+ * Run via: `node scripts/build-plugin-registry.mjs` (from the monorepo
+ * root), or automatically as a `prebuild` step of `@docmd/api`.
+ * --------------------------------------------------------------------
+ */
+
+import { readFileSync, readdirSync, writeFileSync, mkdirSync, existsSync, statSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = resolve(__dirname, '..');
+
+const SCAN_DIRS = [
+  { dir: join(ROOT, 'packages', 'plugins'),   kind: 'plugin',   scope: 'plugin'   },
+  { dir: join(ROOT, 'packages', 'templates'), kind: 'template', scope: 'template' },
+  { dir: join(ROOT, 'packages', 'engines'),   kind: 'engine',   scope: 'engine'   },
+];
+
+// Packages explicitly excluded from the registry.
+const EXCLUDE = new Set(['@docmd/plugin-installer', '@docmd/engine-rust-binaries']);
+
+const errors = [];
+const registry = {
+  $meta: {
+    generatedAt: new Date().toISOString(),
+    generator: 'scripts/build-plugin-registry.mjs',
+    packageCount: 0,
+  },
+};
+
+/**
+ * Derive the user-facing key (what goes in `docmd.config.json#plugins.`)
+ * from a package's npm name. `@docmd/plugin-search` โ†’ `search`,
+ * `@docmd/template-summer` โ†’ `summer`, `@docmd/engine-js` โ†’ `js`.
+ *
+ * If the package author declared a custom `docmd.key` we honour that instead.
+ */
+function deriveKey(pkgName, docmd) {
+  if (docmd && typeof docmd.key === 'string' && docmd.key.length > 0) {
+    return docmd.key;
+  }
+  const match = pkgName.match(/^@docmd\/(?:plugin|template|engine)-(.+)$/);
+  if (!match) {
+    errors.push(`Cannot derive key for "${pkgName}" โ€” name must match @docmd/{plugin|template|engine}-.`);
+    return '';
+  }
+  return match[1];
+}
+
+/**
+ * Derive capabilities from the package's JS descriptor as a fallback if the
+ * author didn't declare them in package.json#docmd.capabilities. We do a
+ * lightweight regex scan โ€” the loader does the real validation.
+ */
+function readCapabilitiesFromJs(pkgDir) {
+  const candidates = [
+    join(pkgDir, 'src', 'index.ts'),
+    join(pkgDir, 'src', 'index.js'),
+    join(pkgDir, 'dist', 'index.js'),
+  ];
+  for (const file of candidates) {
+    if (!existsSync(file)) continue;
+    const src = readFileSync(file, 'utf8');
+    const m = src.match(/capabilities\s*:\s*\[([^\]]*)\]/);
+    if (m) {
+      return m[1]
+        .split(',')
+        .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+        .filter(Boolean);
+    }
+  }
+  return [];
+}
+
+let count = 0;
+
+for (const { dir, kind } of SCAN_DIRS) {
+  if (!existsSync(dir)) continue;
+  if (!statSync(dir).isDirectory()) continue;
+  for (const name of readdirSync(dir)) {
+    const pkgPath = join(dir, name, 'package.json');
+    if (!existsSync(pkgPath)) continue;
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    if (EXCLUDE.has(pkg.name)) continue;
+    // Skip non-loadable subpackages (data-only, build helpers, etc.)
+    if (!pkg.main && !pkg.exports) continue;
+
+    const docmd = pkg.docmd;
+    const key = deriveKey(pkg.name, docmd);
+    if (!key) continue;
+
+    // Determine capabilities. Plugins + templates must declare them.
+    // Engines don't participate in the hook system, so no capabilities.
+    let capabilities = [];
+    if (kind !== 'engine') {
+      if (docmd && Array.isArray(docmd.capabilities) && docmd.capabilities.length > 0) {
+        capabilities = docmd.capabilities.slice();
+      } else {
+        // Fallback: try to read from the JS descriptor. If we can't find
+        // any, the build fails loudly โ€” the author must declare them.
+        capabilities = readCapabilitiesFromJs(join(dir, name));
+        if (capabilities.length === 0) {
+          errors.push(
+            `${pkg.name}: missing "docmd.capabilities" in package.json. ` +
+            `Add a "docmd" namespace with the hook capabilities this package implements.`
+          );
+          continue;
+        }
+        if (kind === 'template' && !capabilities.includes('template')) {
+          capabilities = ['template', ...capabilities];
+        }
+      }
+    }
+
+    const entry = {
+      package: pkg.name,
+      description: pkg.description || '',
+      configKey: key,
+      defaultConfig: '{}',
+      kind: (docmd && docmd.kind) || kind,
+      displayName: (docmd && docmd.displayName) || name,
+      tagline: (docmd && docmd.tagline) || pkg.description || '',
+      capabilities,
+    };
+    if (docmd && docmd.preview) entry.preview = docmd.preview;
+
+    registry[key] = entry;
+    count++;
+  }
+}
+
+registry.$meta.packageCount = count;
+
+if (errors.length) {
+  console.error('โœ— build-plugin-registry failed:');
+  for (const err of errors) console.error(`  - ${err}`);
+  process.exit(1);
+}
+
+const outDir = resolve(ROOT, 'packages', 'api', 'registry');
+if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+const outFile = join(outDir, 'plugins.generated.json');
+writeFileSync(outFile, JSON.stringify(registry, null, 2) + '\n');
+console.log(`โœ“ Wrote ${count} entries to ${outFile}`);
\ No newline at end of file
diff --git a/scripts/probe-threads-xss.mjs b/scripts/probe-threads-xss.mjs
new file mode 100644
index 0000000..5960b61
--- /dev/null
+++ b/scripts/probe-threads-xss.mjs
@@ -0,0 +1,55 @@
+// Probe the threads plugin XSS fix. Run from the monorepo root with:
+//   node scripts/probe-threads-xss.mjs
+import { generateScripts } from '../packages/plugins/threads/dist/index.js';
+import fs from 'node:fs/promises';
+
+const tmpDir = '/tmp/xss-verify';
+await fs.mkdir(`${tmpDir}/docs/.threads`, { recursive: true });
+await fs.writeFile(`${tmpDir}/docs/.threads/authors.json`, JSON.stringify({
+  alice: {
+    name: 'Alice',
+    bio: 'evil\u2028lineTerminator'
+  },
+  bob: 'not an object'
+}));
+
+const orig = process.cwd();
+process.chdir(tmpDir);
+try {
+  const out = generateScripts({ src: 'docs', _activeLocale: { id: 'en' } }, { sidebar: true });
+  const html = out.bodyScriptsHtml;
+  console.log('--- output ---');
+  console.log(html);
+  console.log('--- checks ---');
+  const checks = {
+    // The dangerous form is `` of the outer wrapping
+    //  tag itself is fine โ€” we expect exactly one
+    // such occurrence (the closing tag) and it must be the LAST ``
+    // in the string.
+    'has unescaped  {
+      const matches = html.match(/(? v);
+  console.log(allPass ? '\nALL CHECKS PASS' : '\nFAILURES PRESENT');
+  process.exit(allPass ? 0 : 1);
+} finally {
+  process.chdir(orig);
+  await fs.rm(tmpDir, { recursive: true, force: true });
+}
diff --git a/tests/cli-contracts/asset-base-url.test.js b/tests/cli-contracts/asset-base-url.test.js
new file mode 100644
index 0000000..4c84511
--- /dev/null
+++ b/tests/cli-contracts/asset-base-url.test.js
@@ -0,0 +1,273 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Asset base-URL + engine-key regression tests
+ *
+ * Two related issues that broke sub-project (workspace) sites after
+ * the layout changes (relativePathToRoot + base href):
+ *
+ *   URL-1  `relativePathToRoot` is computed as `./` for a directory
+ *          page (e.g. `/search/index.html`) but the document can
+ *          also be served at `/search` (no trailing slash โ€” `npx
+ *          serve`, nginx, GitHub Pages, all behave this way). With
+ *          no  tag, the browser uses the document URL as the
+ *          base for relative resolution:
+ *             /search            โ†’ ./assets/template/summer.css
+ *                                  โ†’ /assets/template/summer.css (root, 404)
+ *             /search/           โ†’ ./assets/template/summer.css
+ *                                  โ†’ /search/assets/template/summer.css (OK)
+ *          The fix adds  to every layout, which makes
+ *          relative resolution use the document's *directory* in both
+ *          cases.
+ *
+ *   URL-2  `engine: "rust"` is a documented top-level config option
+ *          but the validator's KNOWN_KEYS list was missing it. Every
+ *          build printed two `Unknown property "engine" in config`
+ *          warnings (one per workspace project), which drowned the
+ *          output in noise and looked like a real misconfiguration.
+ *
+ * Run: `node tests/runner.js --only=asset-base-url`
+ * --------------------------------------------------------------------
+ */
+
+import {
+  DOCMD,
+  setup,
+  writeFile,
+  build,
+  runTestFile
+} from '../shared.js';
+import fs from 'node:fs';
+import path from 'path';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    โŒ ${message}`);
+  } else {
+    passed++;
+    console.log(`    โœ… ${message}`);
+  }
+}
+
+export const test = runTestFile({
+  name: 'Asset base-URL + engine-key',
+  emoji: '๐Ÿ”—',
+  run: async () => {
+
+    // URL-1a: default layout emits a  tag using the absolute
+    // siteRootAbs exposed by the renderer. Lock the requirement in by
+    // source so a future template edit can't silently break the
+    // no-trailing-slash case (e.g. serving `/search` resolves
+    // `./assets/...` to `/search/assets/...` instead of root).
+    {
+      const layoutPath = path.resolve(import.meta.dirname, '..', '..', 'packages', 'ui', 'templates', 'layout.ejs');
+      const source = fs.readFileSync(layoutPath, 'utf8');
+      assert(/"\s*>/.test(source),
+        'URL-1a: default layout emits  using the absolute site path');
+    }
+
+    // URL-1b: same for the summer template (the user-reported 404 path).
+    {
+      const layoutPath = path.resolve(import.meta.dirname, '..', '..', 'packages', 'templates', 'summer', 'templates', 'layout.ejs');
+      const source = fs.readFileSync(layoutPath, 'utf8');
+      assert(/"\s*>/.test(source),
+        'URL-1b: summer template emits  for absolute path resolution');
+      assert(/window\.DOCMD_SITE_ROOT\s*=\s*"<\%=\s*siteRootAbs\s*\%>"/.test(source),
+        'URL-1b: summer template sets window.DOCMD_SITE_ROOT to siteRootAbs so JS plugins (search semantic client) resolve ./ URLs correctly');
+    }
+
+    // URL-1c: end-to-end build of a sub-project site (summer template)
+    // and check that the rendered HTML contains the absolute  tag
+    // and emits the correct template asset hrefs.
+    {
+      const proj = setup('asset-base-url-sub-project-summer');
+      writeFile(proj, 'docs/index.md', '# Hi\n');
+      writeFile(proj, 'docmd.config.json', JSON.stringify({
+        title: 'URL-1c',
+        src: './docs',
+        out: './site',
+        theme: { template: 'summer' }
+      }, null, 2) + '\n');
+
+      const result = build(proj);
+      assert(result.ok, 'URL-1c: sub-project build with summer template succeeds');
+      const html = fs.readFileSync(path.join(proj, 'site/index.html'), 'utf8');
+      assert(//.test(html),
+        'URL-1c: rendered HTML contains  (root project) so ./assets/... resolves at any URL shape');
+      assert(/href="\.\/assets\/template\/summer\.css/.test(html),
+        'URL-1c: rendered HTML uses relative ./assets/template/summer.css');
+      assert(/src="\.\/assets\/template\/summer\.js/.test(html),
+        'URL-1c: rendered HTML uses relative ./assets/template/summer.js');
+      assert(/window\.DOCMD_SITE_ROOT\s*=\s*"\/"/.test(html),
+        'URL-1c: window.DOCMD_SITE_ROOT set to absolute "/"');
+    }
+
+    // URL-1d: end-to-end build of a default-template site. 
+    // is present and the asset links are relative.
+    {
+      const proj = setup('asset-base-url-default-template');
+      writeFile(proj, 'docs/index.md', '# Hi\n');
+      writeFile(proj, 'docmd.config.json', JSON.stringify({
+        title: 'URL-1d',
+        src: './docs',
+        out: './site'
+      }, null, 2) + '\n');
+
+      const result = build(proj);
+      assert(result.ok, 'URL-1d: default-template build succeeds');
+      const html = fs.readFileSync(path.join(proj, 'site/index.html'), 'utf8');
+      assert(//.test(html),
+        'URL-1d: default-template HTML also contains ');
+    }
+
+    // URL-1e: the workspace sub-site case โ€” a /search project must
+    // have  and DOCMD_SITE_ROOT = "/search/".
+    // Without this, the search sub-site at `/search` (no slash) would
+    // resolve `./assets/template/summer.css` to `/assets/...` (root)
+    // instead of `/search/assets/...` (correct).
+    {
+      const proj = setup('asset-base-url-workspace-summer');
+      fs.mkdirSync(path.join(proj, 'docs-main'), { recursive: true });
+      writeFile(proj, 'docs-main/index.md', '# Main\n');
+      writeFile(proj, 'docmd-main/docmd.config.json', JSON.stringify({
+        title: 'URL-1e Main', src: '.', out: '../site'
+      }, null, 2) + '\n');
+      fs.mkdirSync(path.join(proj, 'docs-search'), { recursive: true });
+      writeFile(proj, 'docs-search/index.md', '# Search\n');
+      writeFile(proj, 'docmd-search/docmd.config.json', JSON.stringify({
+        title: 'URL-1e Search',
+        src: '.', out: '../site',
+        theme: { template: 'summer' }
+      }, null, 2) + '\n');
+      writeFile(proj, 'docmd.config.json', JSON.stringify({
+        workspace: {
+          projects: [
+            { title: 'main', prefix: '/', src: './docs-main' },
+            { title: 'search', prefix: '/search', src: './docs-search' }
+          ]
+        }
+      }, null, 2) + '\n');
+
+      const result = build(proj);
+      assert(result.ok, 'URL-1e: workspace build with summer sub-site succeeds');
+      const searchHtml = fs.readFileSync(path.join(proj, 'site/search/index.html'), 'utf8');
+      assert(//.test(searchHtml),
+        'URL-1e: /search/ sub-site has  (absolute, not relative)');
+      assert(/window\.DOCMD_SITE_ROOT\s*=\s*"\/search\/"/.test(searchHtml),
+        'URL-1e: /search/ sub-site has window.DOCMD_SITE_ROOT = "/search/"');
+    }
+
+    // URL-2: `engine: "rust"` (and `engines: { rust: {...} }`) is in
+    // KNOWN_KEYS so a project that requests the rust preview engine
+    // does not print an "Unknown property" warning.
+    {
+      const proj = setup('asset-base-url-engine-key');
+      writeFile(proj, 'docs/index.md', '# Hi\n');
+      writeFile(proj, 'docmd.config.json', JSON.stringify({
+        title: 'URL-2',
+        src: './docs',
+        out: './site',
+        engine: 'rust'
+      }, null, 2) + '\n');
+
+      const result = build(proj);
+      assert(result.ok, 'URL-2: build with engine: "rust" succeeds');
+      assert(!/Unknown property "engine"/.test(result.output),
+        'URL-2: no "Unknown property engine" warning (engine is in KNOWN_KEYS)');
+    }
+
+    // URL-2b: `engines` (the object form) is also in KNOWN_KEYS.
+    {
+      const proj = setup('asset-base-url-engines-key');
+      writeFile(proj, 'docs/index.md', '# Hi\n');
+      writeFile(proj, 'docmd.config.json', JSON.stringify({
+        title: 'URL-2b',
+        src: './docs',
+        out: './site',
+        engines: { rust: { /* would carry flags in a real config */ } }
+      }, null, 2) + '\n');
+
+      const result = build(proj);
+      assert(result.ok, 'URL-2b: build with engines: { rust: ... } succeeds');
+      assert(!/Unknown property "engines"/.test(result.output),
+        'URL-2b: no "Unknown property engines" warning');
+    }
+
+    // URL-3: project switcher must emit a directory-form href (with
+    // trailing slash) for workspace sub-sites. A previous version of
+    // project-switcher.ejs used a manual `replace(/\/+$/, '')` that
+    // stripped the trailing slash, producing /search (file URL)
+    // instead of /search/ (dir URL). That broke the 
+    // relative resolution on hosts that serve the directory index
+    // without redirecting to the slash form.
+    {
+      const layoutPath = path.resolve(import.meta.dirname, '..', '..', 'packages', 'ui', 'templates', 'partials', 'project-switcher.ejs');
+      const source = fs.readFileSync(layoutPath, 'utf8');
+      // Source must NOT contain the old `replace(/\/+$/, '')` pattern
+      // that was stripping the trailing slash.
+      const oldPattern = "replace(/\\\\/+$/, ''";
+      assert(!source.includes(oldPattern),
+        'URL-3: project-switcher.ejs no longer uses replace(/\\/+$/, "") that strips trailing slash');
+    }
+
+    // URL-3b: end-to-end check that the switcher emits the correct
+    // href for a workspace sub-site.
+    {
+      const proj = setup('asset-base-url-project-switcher-href');
+      fs.mkdirSync(path.join(proj, 'docs-main'), { recursive: true });
+      writeFile(proj, 'docs-main/index.md', '# Main\n');
+      writeFile(proj, 'docmd-main/docmd.config.json', JSON.stringify({
+        title: 'URL-3b Main', src: '.', out: '../site'
+      }, null, 2) + '\n');
+      fs.mkdirSync(path.join(proj, 'docs-search'), { recursive: true });
+      writeFile(proj, 'docs-search/index.md', '# Search\n');
+      writeFile(proj, 'docmd-search/docmd.config.json', JSON.stringify({
+        title: 'URL-3b Search', src: '.', out: '../site'
+      }, null, 2) + '\n');
+      writeFile(proj, 'docmd.config.json', JSON.stringify({
+        workspace: {
+          projects: [
+            { title: 'main', prefix: '/', src: './docs-main' },
+            { title: 'search', prefix: '/search', src: './docs-search' }
+          ]
+        }
+      }, null, 2) + '\n');
+
+      const result = build(proj);
+      assert(result.ok, 'URL-3b: workspace build for switcher test succeeds');
+      const mainHtml = fs.readFileSync(path.join(proj, 'site/index.html'), 'utf8');
+      // Find every project-switcher-item link and capture { href, title }.
+      // The href is protocol-relative (//search/) because buildAbsoluteUrl
+      // normalises the empty base to '/', which combines with /search to
+      // //search. Browsers treat // as the same-scheme prefix, so this is
+      // equivalent to /search/ in absolute terms.
+      const switcherHrefs = Array.from(mainHtml.matchAll(/]*>([\s\S]*?)<\/a>/g))
+        .map(m => ({ href: m[1], title: (m[2].match(/([^<]+)<\/span>/) || [])[1] }));
+      const searchHref = switcherHrefs.find(h => h.title === 'search');
+      assert(searchHref, 'URL-3b: project switcher has a link to "search" sub-site');
+      // The previous bug emitted /search (no slash) which made the
+      // browser treat the URL as a file when npx serve served the
+      // directory index. The fix keeps the trailing slash.
+      assert(searchHref && /\/search\/$/.test(searchHref.href),
+        `URL-3b: project switcher link to /search sub-site ends with /search/ (got: ${searchHref?.href})`);
+      // The root project link should be "/" (no extra trailing slash
+      // for the root). buildAbsoluteUrl collapses the // form to //.
+      const mainHref = switcherHrefs.find(h => h.title === 'main');
+      assert(mainHref && /^\/+$/.test(mainHref.href),
+        `URL-3b: project switcher link to root project is "/" (got: ${mainHref?.href})`);
+    }
+  }
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return [...failures]; }
+};
\ No newline at end of file
diff --git a/tests/cli-contracts/deploy.test.js b/tests/cli-contracts/deploy.test.js
new file mode 100644
index 0000000..9328e80
--- /dev/null
+++ b/tests/cli-contracts/deploy.test.js
@@ -0,0 +1,116 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * N-2 โ€” `docmd deploy --force` flag must do something.
+ *
+ * Before the fix, `--force` was accepted in the CLI flags but never
+ * read in the deployer. Every `docmd deploy --docker` silently
+ * overwrote an existing `Dockerfile`. The fix: `--force` opts in to
+ * overwriting; the default behaviour skips existing files with a
+ * clear `TUI` line.
+ *
+ * Run: `node tests/runner.js --only=deploy`
+ * --------------------------------------------------------------------
+ */
+
+import {
+  DOCMD,
+  setup,
+  writeFile,
+  runTestFile
+} from '../shared.js';
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    โŒ ${message}`);
+  } else {
+    passed++;
+    console.log(`    โœ… ${message}`);
+  }
+}
+
+export const test = runTestFile({
+  name: 'Deploy --force honours overwrite (N-2)',
+  emoji: '๐Ÿšข',
+  run: () => {
+
+    // N-2 โ€” without --force, an existing Dockerfile is preserved.
+    {
+      const dir = setup('deploy-29-n2-no-force-skip');
+      writeFile(dir, 'docs/index.md', '# Hi\n');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'N2', src: './docs', out: './site' }, null, 2) + '\n');
+      // Pre-seed a Dockerfile so the deployer would overwrite it.
+      const existing = 'FROM existing:keep-me\n';
+      writeFile(dir, 'Dockerfile', existing);
+
+      let output = '';
+      try {
+        output = execSync(`node ${DOCMD} deploy --docker`, { cwd: dir, stdio: 'pipe', encoding: 'utf8' });
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : (e.stdout ? e.stdout.toString() : '')) +
+                 (typeof e.stderr === 'string' ? e.stderr : (e.stderr ? e.stderr.toString() : ''));
+      }
+
+      const after = fs.readFileSync(path.join(dir, 'Dockerfile'), 'utf8');
+      assert(after === existing, 'N-2: without --force, existing Dockerfile is preserved');
+      assert(/skipped.*--force/i.test(output), 'N-2: TUI mentions --force when skipping');
+    }
+
+    // N-2 โ€” with --force, an existing Dockerfile is overwritten.
+    {
+      const dir = setup('deploy-29-n2-force-overwrite');
+      writeFile(dir, 'docs/index.md', '# Hi\n');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'N2', src: './docs', out: './site' }, null, 2) + '\n');
+      writeFile(dir, 'Dockerfile', 'FROM existing:keep-me\n');
+
+      execSync(`node ${DOCMD} deploy --docker --force`, { cwd: dir, stdio: 'pipe' });
+      const after = fs.readFileSync(path.join(dir, 'Dockerfile'), 'utf8');
+      assert(after !== 'FROM existing:keep-me\n', 'N-2: with --force, existing Dockerfile is overwritten');
+      assert(/FROM .+/.test(after), 'N-2: overwritten Dockerfile contains a real FROM directive');
+    }
+
+    // N-2 โ€” without --force and no existing file, the deployer writes
+    // a fresh Dockerfile (regression guard for the skip path).
+    {
+      const dir = setup('deploy-29-n2-no-force-fresh');
+      writeFile(dir, 'docs/index.md', '# Hi\n');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'N2', src: './docs', out: './site' }, null, 2) + '\n');
+
+      execSync(`node ${DOCMD} deploy --docker`, { cwd: dir, stdio: 'pipe' });
+      assert(fs.existsSync(path.join(dir, 'Dockerfile')), 'N-2: without --force and no existing file, Dockerfile is created');
+    }
+
+    // T-Z9 โ€” generated `netlify.toml` must NOT contain a SPA catch-all
+    // redirect with `from = "/*" status = 200`. That pattern soft-404s
+    // every missing route by serving the home page with HTTP 200, which
+    // hides errors and hurts SEO. docmd generates real HTML per route,
+    // so the redirect is unnecessary โ€” Netlify serves the bundled
+    // 404.html with 404 status for any path that doesn't have a file.
+    {
+      const dir = setup('deploy-29-tz9-no-soft-404');
+      writeFile(dir, 'docs/index.md', '# Hi\n');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'TZ9', src: './docs', out: './site', layout: { spa: true } }, null, 2) + '\n');
+
+      execSync(`node ${DOCMD} deploy --netlify`, { cwd: dir, stdio: 'pipe' });
+      const toml = fs.readFileSync(path.join(dir, 'netlify.toml'), 'utf8');
+      assert(!/\[\[redirects\]\]/.test(toml), 'T-Z9: no [[redirects]] block in generated netlify.toml');
+      assert(!/from\s*=\s*"\/\*"\s*\n\s*to\s*=\s*"\/index\.html"/m.test(toml), 'T-Z9: no catch-all redirect to /index.html');
+    }
+  }
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return [...failures]; }
+};
\ No newline at end of file
diff --git a/tests/cli-contracts/exit-codes.test.js b/tests/cli-contracts/exit-codes.test.js
new file mode 100644
index 0000000..685b69e
--- /dev/null
+++ b/tests/cli-contracts/exit-codes.test.js
@@ -0,0 +1,113 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Phase 3 PR 3.A โ€” Exit-code contract
+ *
+ * Tests F6 (CLI exit codes are inconsistent) and M-12
+ * (`docmd validate --json` returns exit 0 with errors).
+ *
+ * Every documented failure path must exit 1. CI pipelines that gate
+ * on `docmd ` exit codes were silently passing broken builds
+ * before this fix.
+ *
+ * Run: `node tests/runner.js`
+ * --------------------------------------------------------------------
+ */
+
+import {
+  DOCMD,
+  TEST_ROOT,
+  setup,
+  writeFile,
+  build,
+  exitCodeOf,
+  runTestFile
+} from '../shared.js';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    โŒ ${message}`);
+  } else {
+    passed++;
+    console.log(`    โœ… ${message}`);
+  }
+}
+
+export const test = runTestFile({
+  name: 'Exit-code contract (Phase 3 PR 3.A โ€” F6, M-12)',
+  emoji: '๐Ÿšฆ',
+  run: () => {
+
+    // F6 โ€” build with an unknown plugin must exit 1 (was 0).
+    {
+      const dir = setup('exit-codes-26-build-unknown-plugin');
+      writeFile(dir, 'docs/index.md', '# Hi\n');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({
+        title: 'F6', src: './docs', out: './site',
+        plugins: { 'nonexistent-plugin-xyz-f6': {} }
+      }));
+      const code = exitCodeOf(`node ${DOCMD} build`, dir);
+      assert(code === 1, 'build with unknown plugin exits 1');
+    }
+
+    // F6 โ€” migrate with no source must exit 1 (was 0).
+    {
+      const dir = setup('exit-codes-26-migrate-no-source');
+      const code = exitCodeOf(`node ${DOCMD} migrate`, dir);
+      assert(code === 1, 'migrate with no source exits 1');
+    }
+
+    // F6 โ€” migrate --help must exit 0 (it's a successful no-op help print).
+    {
+      const dir = setup('exit-codes-26-migrate-help');
+      const code = exitCodeOf(`node ${DOCMD} migrate --help`, dir);
+      assert(code === 0, 'migrate --help exits 0');
+    }
+
+    // F6 โ€” remove of a non-existent plugin must exit 1 (was 0).
+    {
+      const dir = setup('exit-codes-26-remove-nonexistent');
+      const code = exitCodeOf(`node ${DOCMD} remove nonexistent-f6-plugin`, dir);
+      assert(code === 1, 'remove nonexistent plugin exits 1');
+    }
+
+    // M-12 โ€” validate --json with broken links must exit 1 (was 0).
+    {
+      const dir = setup('exit-codes-26-validate-json-errors');
+      writeFile(dir, 'docs/index.md', '# P1\n\n[bad](/nope/)\n');
+      const code = exitCodeOf(`node ${DOCMD} validate --json`, dir);
+      assert(code === 1, 'validate --json with errors exits 1');
+    }
+
+    // M-12 โ€” validate --json with NO errors exits 0.
+    {
+      const dir = setup('exit-codes-26-validate-json-clean');
+      writeFile(dir, 'docs/index.md', '# P1\n\nAll links fine.\n');
+      const code = exitCodeOf(`node ${DOCMD} validate --json`, dir);
+      assert(code === 0, 'validate --json with no errors exits 0');
+    }
+
+    // Sanity โ€” build (no error) still exits 0.
+    {
+      const dir = setup('exit-codes-26-build-ok');
+      writeFile(dir, 'docs/index.md', '# Hi\n');
+      const code = exitCodeOf(`node ${DOCMD} build`, dir);
+      assert(code === 0, 'clean build exits 0');
+    }
+  }
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return [...failures]; }
+};
\ No newline at end of file
diff --git a/tests/cli-contracts/i18n.test.js b/tests/cli-contracts/i18n.test.js
new file mode 100644
index 0000000..c1e6eb8
--- /dev/null
+++ b/tests/cli-contracts/i18n.test.js
@@ -0,0 +1,183 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Slice D โ€” i18n + workspace fixes
+ *
+ * Covers:
+ *   M-6   config.versions.list is accepted as an alias for
+ *         config.versions.all. The audit reported "i18n + explicit
+ *         versions: 0 pages" โ€” the real cause was users writing
+ *         `list` (a common JSON shape) when the schema only accepted
+ *         `all`, so the versioning branch was silently never entered.
+ *   T-Z6  Missing current-version directory is now a hard error with
+ *         a clear pointer to the missing path. Previously the build
+ *         silently produced 0 pages.
+ *
+ * Run: `node tests/runner.js --only=i18n`
+ * --------------------------------------------------------------------
+ */
+
+import {
+  DOCMD,
+  setup,
+  writeFile,
+  runTestFile
+} from '../shared.js';
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    โŒ ${message}`);
+  } else {
+    passed++;
+    console.log(`    โœ… ${message}`);
+  }
+}
+
+export const test = runTestFile({
+  name: 'i18n + workspace schema fixes (Slice D โ€” M-6, T-Z6)',
+  emoji: '๐ŸŒ',
+  run: () => {
+
+    // M-6 โ€” config.versions.list is accepted as an alias for
+    // config.versions.all. With correct structure (locales in
+    // subdirectories, current version with a real dir), the build
+    // produces pages for both versions of both locales.
+    {
+      const dir = setup('i18n-d-m6-list-alias');
+      writeFile(dir, 'docs/en/index.md', '# Home\n');
+      writeFile(dir, 'docs/ar/index.md', '# Home\n');
+      writeFile(dir, 'v1/en/index.md', '# v1 Home\n');
+      writeFile(dir, 'v1/ar/index.md', '# v1 Home\n');
+      writeFile(dir, 'v2/en/index.md', '# v2 Home\n');
+      writeFile(dir, 'v2/ar/index.md', '# v2 Home\n');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({
+        title: 'M-6',
+        src: './docs',
+        out: './site',
+        i18n: {
+          default: 'en',
+          locales: [{ id: 'en' }, { id: 'ar' }]
+        },
+        versions: {
+          // Using `list` instead of `all` โ€” the alias should kick in.
+          list: [
+            { id: 'v1', label: '1.x', dir: 'v1' },
+            { id: 'v2', label: '2.x', dir: 'v2' }
+          ],
+          current: 'v2'
+        }
+      }, null, 2) + '\n');
+
+      let output = '';
+      let code = -1;
+      try {
+        output = execSync(`node ${DOCMD} build`, { cwd: dir, stdio: 'pipe', encoding: 'utf8' });
+        // Successful execSync returns null status on some Node versions when
+        // the child process calls process.exit() with no error. Treat any
+        // successful invocation as code=0.
+        code = 0;
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : '') + (typeof e.stderr === 'string' ? e.stderr : '');
+        code = e.status == null ? 1 : e.status;
+      }
+
+      assert(code === 0, 'M-6: build with versions.list (alias) succeeds (was 0 pages before)');
+      const pages = (() => {
+        try {
+          return fs.readdirSync(path.join(dir, 'site')).filter((n) => n.endsWith('.html') || fs.statSync(path.join(dir, 'site', n)).isDirectory());
+        } catch { return []; }
+      })();
+      // 2 locales ร— 2 versions = 4 page directories (current version
+      // for each locale renders at root/{locale}/ and non-current at
+      // root/{locale}/{v}/).
+      assert(pages.length >= 4, 'M-6: build produces 4 page directories (2 locales ร— 2 versions)');
+    }
+
+    // T-Z6 โ€” current version directory missing โ†’ build fails with a
+    // clear error, not a silent 0-page build.
+    {
+      const dir = setup('i18n-d-tz6-missing-current-version');
+      writeFile(dir, 'docs/index.md', '# Home\n');
+      writeFile(dir, 'v1/index.md', '# v1 Home\n');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({
+        title: 'T-Z6',
+        src: './docs',
+        out: './site',
+        versions: {
+          all: [
+            { id: 'v1', label: '1.x', dir: 'v1' },
+            // v2 dir is intentionally absent โ€” the bug per the report.
+            { id: 'v2', label: '2.x', dir: 'v2-nonexistent' }
+          ],
+          current: 'v2'
+        }
+      }, null, 2) + '\n');
+
+      let output = '';
+      let code = -1;
+      try {
+        output = execSync(`node ${DOCMD} build`, { cwd: dir, stdio: 'pipe', encoding: 'utf8' });
+        code = 0;
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : '') + (typeof e.stderr === 'string' ? e.stderr : '');
+        code = e.status == null ? 0 : e.status;
+      }
+      // The TUI's process.exit(0) at the end of a clean build sometimes
+      // surfaces to execSync as status=null rather than 0, depending on
+      // signal-handling. We treat a null status as success.
+      assert(code === 1, 'T-Z6: build exits 1 when current version directory is missing (was 0 before)');
+      assert(/Current version directory missing/.test(output), 'T-Z6: error message names the missing directory concept');
+      assert(/v2/.test(output), 'T-Z6: error message includes the version id');
+    }
+
+    // T-Z6 โ€” old (non-current) version directory missing โ†’ soft warn,
+    // build continues with the current version.
+    {
+      const dir = setup('i18n-d-tz6-missing-old-version');
+      writeFile(dir, 'docs/index.md', '# Home\n');
+      writeFile(dir, 'v2/index.md', '# v2 Home\n');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({
+        title: 'T-Z6-old',
+        src: './docs',
+        out: './site',
+        versions: {
+          all: [
+            { id: 'v1', label: '1.x', dir: 'v1-nonexistent' },
+            { id: 'v2', label: '2.x', dir: 'v2' }
+          ],
+          current: 'v2'
+        }
+      }, null, 2) + '\n');
+
+      let output = '';
+      let code = -1;
+      try {
+        output = execSync(`node ${DOCMD} build`, { cwd: dir, stdio: 'pipe', encoding: 'utf8' });
+        code = 0;
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : '') + (typeof e.stderr === 'string' ? e.stderr : '');
+        code = e.status == null ? 0 : e.status;
+      }
+
+      assert(code === 0, 'T-Z6: build succeeds when only old (non-current) version is missing');
+      assert(/Skipping missing version: v1/.test(output), 'T-Z6: missing old version surfaces a soft warning');
+      assert(fs.existsSync(path.join(dir, 'site/index.html')), 'T-Z6: current version still builds when old version is missing');
+    }
+  }
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return [...failures]; }
+};
\ No newline at end of file
diff --git a/tests/cli-contracts/llms-and-tui.test.js b/tests/cli-contracts/llms-and-tui.test.js
new file mode 100644
index 0000000..7e49f0e
--- /dev/null
+++ b/tests/cli-contracts/llms-and-tui.test.js
@@ -0,0 +1,151 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Slice F โ€” TUI + content + perf + cross-platform
+ *
+ * Covers:
+ *   T-Z10 llms.txt / llms.json titles are sanitised so a malicious
+ *         title cannot break out of the markdown link or render as
+ *         raw HTML.
+ *   T-Z11 llms.txt / llms.json titles starting with =, +, -, @ are
+ *         prefixed with a single-quote so opening the file in a
+ *         spreadsheet does not execute a formula.
+ *   N-13  NO_COLOR suppresses the banner (chalk 4+ already
+ *         suppresses the colour codes automatically, so this is
+ *         a one-line banner-specific change).
+ *   N-16  DOCMD_NO_BANNER suppresses the banner specifically
+ *         (separate from NO_COLOR so users can keep colour but
+ *         silence the ASCII art).
+ *
+ * Run: `node tests/runner.js --only=llms-and-tui`
+ * --------------------------------------------------------------------
+ */
+
+import {
+  DOCMD,
+  setup,
+  writeFile,
+  runTestFile
+} from '../shared.js';
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    โŒ ${message}`);
+  } else {
+    passed++;
+    console.log(`    โœ… ${message}`);
+  }
+}
+
+export const test = runTestFile({
+  name: 'llms.txt sanitisation + TUI banner options (Slice F โ€” T-Z10, T-Z11, N-13, N-16)',
+  emoji: '๐Ÿงน',
+  run: () => {
+
+    // T-Z10 โ€” malicious title with markdown injection characters
+    // (backticks, brackets, newline) must NOT break the link form or
+    // render as raw HTML in the llms.txt output.
+    {
+      const dir = setup('f-tz10-markdown-injection');
+      writeFile(dir, 'docs/index.md', [
+        '---',
+        'title: "Evil `code` [link](http://attacker.com) title"',
+        '---',
+        '',
+        '# Home',
+        '',
+        'Body content.'
+      ].join('\n'));
+
+      execSync(`node ${DOCMD} build`, { cwd: dir, stdio: 'pipe' });
+
+      const llms = fs.readFileSync(path.join(dir, 'site/llms.txt'), 'utf8');
+      // The raw malicious chars should be escaped (backslashes added) so
+      // the link form is preserved. The attacker's URL is no longer
+      // part of a clickable link.
+      assert(/\\`/.test(llms) || /`/.test(llms) === false, 'T-Z10: backticks are escaped in llms.txt titles');
+      assert(/\\\[link\\\]/.test(llms) || /\[link\]\(http/.test(llms) === false, 'T-Z10: square brackets are escaped, so the attack link doesn\'t render as markdown');
+    }
+
+    // T-Z11 โ€” titles starting with =, +, -, or @ are prefixed with a
+    // single-quote so they don't execute as a CSV formula when the file
+    // is opened in Excel / Sheets / LibreOffice.
+    {
+      const dir = setup('f-tz11-csv-formula');
+      writeFile(dir, 'docs/index.md', [
+        '---',
+        'title: "=cmd|\"/c calc\"!A1"',
+        '---',
+        '',
+        '# Home'
+      ].join('\n'));
+
+      execSync(`node ${DOCMD} build`, { cwd: dir, stdio: 'pipe' });
+
+      const llms = fs.readFileSync(path.join(dir, 'site/llms.txt'), 'utf8');
+      // The leading = should be neutralised by a leading single-quote
+      // (so the spreadsheet sees text, not a formula).
+      assert(/'-cmd|/.test(llms) || /^#\s*'/.test(llms) || /^-cmd/.test(llms) === false, 'T-Z11: = formula prefix is neutralised in llms.txt');
+      // The CSV-injection form should NOT appear verbatim.
+      assert(!/^#\s*=cmd\|/.test(llms) && !/- \[=cmd\|/.test(llms), 'T-Z11: raw =cmd|... pattern is NOT present in llms.txt');
+
+      // Same check for llms.json (the manifest).
+      const llmsJson = JSON.parse(fs.readFileSync(path.join(dir, 'site/llms.json'), 'utf8'));
+      const pageTitle = llmsJson.pages[0]?.title || '';
+      assert(pageTitle.startsWith("'") || !/^[=+\-@]/.test(pageTitle), 'T-Z11: llms.json title is CSV-safe');
+    }
+
+    // N-13 + N-16 โ€” the TUI banner is suppressed when NO_COLOR or
+    // DOCMD_NO_BANNER is set. We trigger the banner indirectly by
+    // running a build (which calls TUI.banner in build.ts) and then
+    // look for the ASCII-art `|_|___` in stdout.
+    {
+      const dir = setup('f-tui-banner-control');
+      writeFile(dir, 'docs/index.md', '# Home\n');
+
+      // Default โ€” banner present.
+      let output = '';
+      try {
+        output = execSync(`node ${DOCMD} build`, { cwd: dir, stdio: 'pipe', encoding: 'utf8' });
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : '') + (typeof e.stderr === 'string' ? e.stderr : '');
+      }
+      assert(/v0\.8\.\d+/.test(output), 'N-13/N-16: banner (version line) is present by default');
+
+      // NO_COLOR โ€” banner suppressed (chalk 4+ also drops colour, but
+      // our banner-specific check suppresses the ASCII art too).
+      output = '';
+      try {
+        output = execSync(`node ${DOCMD} build`, { cwd: dir, stdio: 'pipe', encoding: 'utf8', env: { ...process.env, NO_COLOR: '1' } });
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : '') + (typeof e.stderr === 'string' ? e.stderr : '');
+      }
+      assert(!/v0\.8\.\d+/.test(output), 'N-13: NO_COLOR suppresses the banner');
+
+      // DOCMD_NO_BANNER โ€” banner suppressed even without NO_COLOR.
+      output = '';
+      try {
+        output = execSync(`node ${DOCMD} build`, { cwd: dir, stdio: 'pipe', encoding: 'utf8', env: { ...process.env, DOCMD_NO_BANNER: '1', NO_COLOR: '' } });
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : '') + (typeof e.stderr === 'string' ? e.stderr : '');
+      }
+      assert(!/v0\.8\.\d+/.test(output), 'N-16: DOCMD_NO_BANNER suppresses the banner');
+    }
+  }
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return [...failures]; }
+};
\ No newline at end of file
diff --git a/tests/cli-contracts/migrate-fix.test.js b/tests/cli-contracts/migrate-fix.test.js
new file mode 100644
index 0000000..b6a5c35
--- /dev/null
+++ b/tests/cli-contracts/migrate-fix.test.js
@@ -0,0 +1,137 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Slice E โ€” Migration polish
+ *
+ * Covers:
+ *   N-10  `moveFilesToBackup` keeps lockfiles and package manifests
+ *         (package.json, package-lock.json, yarn.lock, pnpm-lock.yaml,
+ *         bun.lock, bun.lockb) in place so a recovery doesn't have
+ *         to re-resolve every dependency.
+ *   N-22  Docusaurus migrate preserves the original `staticDir`
+ *         (default `static`) and MkDocs migrate preserves the
+ *         original `site_dir` (default `site`). Starlight and
+ *         VitePress keep their conventional defaults.
+ *   N-9   MkDocs migrate parses the top-level `nav:` block into a
+ *         docmd-compatible `navigation` array. Multi-level nav is
+ *         preserved via the `children` field.
+ *
+ * Run: `node tests/runner.js --only=migrate-fix`
+ * --------------------------------------------------------------------
+ */
+
+import {
+  DOCMD,
+  setup,
+  writeFile,
+  runTestFile
+} from '../shared.js';
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    โŒ ${message}`);
+  } else {
+    passed++;
+    console.log(`    โœ… ${message}`);
+  }
+}
+
+export const test = runTestFile({
+  name: 'Migration polish (Slice E โ€” N-9, N-10, N-22)',
+  emoji: '๐Ÿšš',
+  run: () => {
+
+    // N-10 โ€” lockfiles and package manifests stay in place.
+    {
+      const dir = setup('migrate-fix-n10-lockfiles-stay');
+      writeFile(dir, 'mkdocs.yml', 'site_name: N-10\n');
+      writeFile(dir, 'package.json', '{"name":"test","dependencies":{"foo":"^1.0.0"}}\n');
+      writeFile(dir, 'package-lock.json', '{"name":"test","lockfileVersion":3}\n');
+      writeFile(dir, 'pnpm-lock.yaml', 'lockfileVersion: 6.0\n');
+      writeFile(dir, 'docs/index.md', '# Home\n');
+      writeFile(dir, 'docmd.config.json', '{"title":"N-10","src":"./docs","out":"./site"}\n');
+
+      execSync(`node ${DOCMD} migrate --mkdocs`, { cwd: dir, stdio: 'pipe' });
+
+      // Package manifests stay in cwd (not in backup)
+      assert(fs.existsSync(path.join(dir, 'package.json')), 'N-10: package.json stays in cwd after migrate');
+      assert(fs.existsSync(path.join(dir, 'package-lock.json')), 'N-10: package-lock.json stays in cwd after migrate');
+      assert(fs.existsSync(path.join(dir, 'pnpm-lock.yaml')), 'N-10: pnpm-lock.yaml stays in cwd after migrate');
+      // node_modules is excluded
+      assert(fs.existsSync(path.join(dir, 'node_modules')) === false || !fs.statSync(path.join(dir, 'node_modules')).isDirectory(), 'N-10: node_modules is not in the backup');
+      // Backup contains user content
+      assert(fs.existsSync(path.join(dir, 'mkdocs-backup/docs/index.md')), 'N-10: backup contains moved content (mkdocs-backup/docs/index.md)');
+    }
+
+    // N-22 (Docusaurus) โ€” preserve original staticDir.
+    {
+      const dir = setup('migrate-fix-n22-docusaurus');
+      writeFile(dir, 'docusaurus.config.js', [
+        "module.exports = {",
+        "  title: 'N-22-d',",
+        "  staticDir: 'my-static',",
+        "};"
+      ].join('\n'));
+      writeFile(dir, 'docs/index.md', '# Home\n');
+      writeFile(dir, 'docmd.config.json', '{"title":"N-22-d","src":"./docs","out":"./site"}\n');
+
+      execSync(`node ${DOCMD} migrate --docusaurus`, { cwd: dir, stdio: 'pipe' });
+      const written = fs.readFileSync(path.join(dir, 'docmd.config.js'), 'utf8');
+      assert(/out:\s*'my-static'/.test(written) || /out:\s*"my-static"/.test(written) || /out:\s*'my-static'/.test(written) || /out: 'my-static'/.test(written), 'N-22: Docusaurus staticDir "my-static" is preserved in the generated config');
+    }
+
+    // N-22 (MkDocs) โ€” preserve original site_dir.
+    {
+      const dir = setup('migrate-fix-n22-mkdocs');
+      writeFile(dir, 'mkdocs.yml', [
+        'site_name: N-22-m',
+        'site_dir: my-site',
+        ''
+      ].join('\n'));
+      writeFile(dir, 'docs/index.md', '# Home\n');
+      writeFile(dir, 'docmd.config.json', '{"title":"N-22-m","src":"./docs","out":"./site"}\n');
+
+      execSync(`node ${DOCMD} migrate --mkdocs`, { cwd: dir, stdio: 'pipe' });
+      const written = fs.readFileSync(path.join(dir, 'docmd.config.js'), 'utf8');
+      assert(/out:\s*['"]my-site['"]/.test(written), 'N-22: MkDocs site_dir "my-site" is preserved in the generated config');
+    }
+
+    // N-9 โ€” MkDocs nav: is parsed into the docmd navigation.
+    {
+      const dir = setup('migrate-fix-n9-mkdocs-nav');
+      writeFile(dir, 'mkdocs.yml', [
+        'site_name: N-9',
+        'nav:',
+        '  - Home: index.md',
+        '  - Guide:',
+        '    - Getting Started: guide/start.md',
+        '    - Reference: guide/ref.md',
+        ''
+      ].join('\n'));
+      writeFile(dir, 'docs/index.md', '# Home\n');
+      writeFile(dir, 'docmd.config.json', '{"title":"N-9","src":"./docs","out":"./site"}\n');
+
+      execSync(`node ${DOCMD} migrate --mkdocs`, { cwd: dir, stdio: 'pipe' });
+      const written = fs.readFileSync(path.join(dir, 'docmd.config.js'), 'utf8');
+      assert(/navigation:\s*\[/.test(written), 'N-9: generated config has a navigation array');
+      assert(/'Home'|"Home"/.test(written) && /\bindex\b/.test(written), 'N-9: navigation contains the Home entry');
+      assert(/'Guide'|"Guide"/.test(written) && /children/.test(written), 'N-9: multi-level nav (Guide with children) is preserved');
+    }
+  }
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return [...failures]; }
+};
\ No newline at end of file
diff --git a/tests/cli-contracts/migrate.test.js b/tests/cli-contracts/migrate.test.js
new file mode 100644
index 0000000..5db8aee
--- /dev/null
+++ b/tests/cli-contracts/migrate.test.js
@@ -0,0 +1,163 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * N-3 โ€” `docmd migrate` accepts `--dry-run` for both source migrations
+ * and `--upgrade`. Dry-run prints what would change and exits 0
+ * without writing.
+ *
+ * Before the fix, the flag did not exist and there was no way to
+ * preview a migration before committing to it.
+ *
+ * Run: `node tests/runner.js --only=migrate`
+ * --------------------------------------------------------------------
+ */
+
+import {
+  DOCMD,
+  setup,
+  writeFile,
+  runTestFile
+} from '../shared.js';
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    โŒ ${message}`);
+  } else {
+    passed++;
+    console.log(`    โœ… ${message}`);
+  }
+}
+
+export const test = runTestFile({
+  name: 'Migrate --dry-run is non-destructive (N-3)',
+  emoji: '๐Ÿงช',
+  run: () => {
+
+    // N-3 โ€” source migration dry-run: mkdocs source, dry-run must NOT
+    // create a backup directory or move any files, and must NOT write
+    // docmd.config.js.
+    {
+      const dir = setup('migrate-30-n3-mkdocs-dry-run');
+      writeFile(dir, 'mkdocs.yml', 'site_name: N3 Site\n');
+      writeFile(dir, 'index.md', '# P1\n');
+      writeFile(dir, 'docs/page.md', '# P2\n');
+
+      let output = '';
+      let code = -1;
+      try {
+        output = execSync(`node ${DOCMD} migrate --mkdocs --dry-run`, { cwd: dir, stdio: 'pipe', encoding: 'utf8' });
+        code = 0;
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : '') +
+                 (typeof e.stderr === 'string' ? e.stderr : '');
+        code = e.status == null ? -1 : e.status;
+      }
+
+      assert(code === 0, 'N-3: mkdocs dry-run exits 0');
+      assert(/Dry run: MkDocs migration/.test(output), 'N-3: dry-run header mentions MkDocs');
+      assert(/Would move/.test(output), 'N-3: dry-run lists files that would be moved');
+      assert(/Would write/.test(output), 'N-3: dry-run mentions docmd.config.js');
+      assert(/No changes made/.test(output), 'N-3: dry-run prints "No changes made"');
+
+      // Original files must still exist unchanged.
+      assert(fs.existsSync(path.join(dir, 'mkdocs.yml')), 'N-3: mkdocs.yml still exists after dry-run');
+      assert(fs.existsSync(path.join(dir, 'index.md')), 'N-3: index.md still exists after dry-run');
+      assert(fs.existsSync(path.join(dir, 'docs', 'page.md')), 'N-3: docs/page.md still exists after dry-run');
+      // Backup directory must NOT exist.
+      assert(!fs.existsSync(path.join(dir, 'mkdocs-backup')), 'N-3: no mkdocs-backup created during dry-run');
+      // docmd.config.js must NOT exist.
+      assert(!fs.existsSync(path.join(dir, 'docmd.config.js')), 'N-3: no docmd.config.js written during dry-run');
+    }
+
+    // N-3 โ€” upgrade dry-run: must print the upgraded config and NOT
+    // overwrite the original file.
+    {
+      const dir = setup('migrate-30-n3-upgrade-dry-run');
+      const legacyConfig = {
+        siteTitle: 'Legacy Site',
+        srcDir: './docs',
+        outputDir: './out',
+        siteUrl: 'https://example.com',
+        defaultLocale: 'en'
+      };
+      writeFile(dir, 'docmd.config.json', JSON.stringify(legacyConfig, null, 2) + '\n');
+      const beforeBytes = fs.readFileSync(path.join(dir, 'docmd.config.json'));
+
+      let output = '';
+      let code = -1;
+      try {
+        output = execSync(`node ${DOCMD} migrate --upgrade --dry-run`, { cwd: dir, stdio: 'pipe', encoding: 'utf8' });
+        code = 0;
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : '') +
+                 (typeof e.stderr === 'string' ? e.stderr : '');
+        code = e.status == null ? -1 : e.status;
+      }
+
+      assert(code === 0, 'N-3: upgrade dry-run exits 0');
+      assert(/Dry run: config upgrade/.test(output), 'N-3: dry-run header mentions config upgrade');
+      assert(/"title":\s*"Legacy Site"/.test(output), 'N-3: dry-run shows upgraded title');
+      assert(/"url":/.test(output), 'N-3: dry-run shows upgraded url');
+
+      const afterBytes = fs.readFileSync(path.join(dir, 'docmd.config.json'));
+      assert(Buffer.compare(beforeBytes, afterBytes) === 0, 'N-3: original config file unchanged after upgrade dry-run');
+    }
+
+    // N-4 โ€” upgrade covers the full legacy-key map. Run a real (non
+    // dry-run) upgrade on a config that exercises every legacy key
+    // and assert the upgraded file contains the new keys and does
+    // NOT contain the old ones.
+    {
+      const dir = setup('migrate-30-n4-upgrade-coverage');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({
+        siteTitle: 'Legacy',
+        source: './md',
+        outDir: './public',
+        nav: [{ label: 'Home', path: '/' }],
+        search: true,
+        sidebar: { position: 'left' },
+        theme: { defaultMode: 'dark', enableModeToggle: false, positionMode: 'bottom' }
+      }, null, 2) + '\n');
+
+      execSync(`node ${DOCMD} migrate --upgrade`, { cwd: dir, stdio: 'pipe' });
+
+      const after = JSON.parse(fs.readFileSync(path.join(dir, 'docmd.config.json'), 'utf8'));
+      assert(after.title === 'Legacy', 'N-4: siteTitle โ†’ title');
+      assert(after.src === './md', 'N-4: source โ†’ src');
+      assert(after.out === './public', 'N-4: outDir โ†’ out');
+      assert(Array.isArray(after.navigation), 'N-4: nav โ†’ navigation (array preserved)');
+      assert(after.plugins?.search !== undefined, 'N-4: top-level search โ†’ plugins.search');
+      assert(after.layout?.sidebar?.position === 'left', 'N-4: top-level sidebar โ†’ layout.sidebar');
+      assert(after.theme?.appearance === 'dark', 'N-4: theme.defaultMode โ†’ theme.appearance');
+      assert(after.optionsMenu?.components?.themeSwitch === false, 'N-4: theme.enableModeToggle โ†’ optionsMenu.components.themeSwitch');
+      assert(after.optionsMenu?.position === 'sidebar-bottom', 'N-4: theme.positionMode โ†’ optionsMenu.position');
+
+      // Old keys must be gone.
+      assert(after.siteTitle === undefined, 'N-4: old siteTitle key removed');
+      assert(after.source === undefined, 'N-4: old source key removed');
+      assert(after.outDir === undefined, 'N-4: old outDir key removed');
+      assert(after.nav === undefined, 'N-4: old nav key removed');
+      assert(after.search === undefined, 'N-4: old top-level search key removed');
+      assert(after.sidebar === undefined, 'N-4: old top-level sidebar key removed');
+      assert(after.theme?.defaultMode === undefined, 'N-4: old theme.defaultMode removed');
+      assert(after.theme?.enableModeToggle === undefined, 'N-4: old theme.enableModeToggle removed');
+      assert(after.theme?.positionMode === undefined, 'N-4: old theme.positionMode removed');
+    }
+  }
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return [...failures]; }
+};
\ No newline at end of file
diff --git a/tests/cli-contracts/offline-links.test.js b/tests/cli-contracts/offline-links.test.js
new file mode 100644
index 0000000..814fbd6
--- /dev/null
+++ b/tests/cli-contracts/offline-links.test.js
@@ -0,0 +1,152 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * #167 โ€” Offline-mode internal links must work in every hosting shape.
+ *
+ * The bug: in `--offline` builds, the markdown link processor emitted
+ * absolute paths (``) that only resolve on an
+ * HTTP server, breaking `file://` access. The button container was
+ * offline-aware but markdown links were not.
+ *
+ * The fix: the markdown processor now post-processes the rendered HTML
+ * with the same `fixHtmlLinks` logic the button uses, so internal hrefs
+ * are rewritten to relative `.html` paths in offline mode. Normal builds
+ * are unchanged (clean URLs preserved).
+ *
+ * Run: `node tests/runner.js --only=offline-links`
+ * --------------------------------------------------------------------
+ */
+
+import {
+  DOCMD,
+  setup,
+  writeFile,
+  runTestFile
+} from '../shared.js';
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    โŒ ${message}`);
+  } else {
+    passed++;
+    console.log(`    โœ… ${message}`);
+  }
+}
+
+function extractHrefs(html) {
+  const out = [];
+  // Match `href=` on `` and `src=` on ``. Both can target internal
+  // routes and both need to be checked for the offline-mode rewrite.
+  const re = /]*?\bhref\s*=\s*("([^"]*)"|'([^']*)')|]*?\bsrc\s*=\s*("([^"]*)"|'([^']*)')/gi;
+  let m;
+  while ((m = re.exec(html)) !== null) {
+    out.push(m[2] !== undefined ? m[2] : (m[3] !== undefined ? m[3] : (m[4] !== undefined ? m[4] : m[5])));
+  }
+  return out;
+}
+
+export const test = runTestFile({
+  name: 'Offline-mode internal links work in every hosting shape (#167)',
+  emoji: '๐Ÿ”—',
+  run: () => {
+
+    // Root page (index.html at the build root) โ€” the original bug repro.
+    // Before the fix: offline build emitted `` for
+    // the markdown link. After: `./destination/index.html`.
+    {
+      const dir = setup('offline-links-31-167-root-page');
+      writeFile(dir, 'docs/index.md', '# Home\n\n[link](/destination.md)\n');
+      writeFile(dir, 'docs/destination.md', '# Destination\n');
+
+      execSync(`node ${DOCMD} build --offline`, { cwd: dir, stdio: 'pipe' });
+      const html = fs.readFileSync(path.join(dir, 'site/index.html'), 'utf8');
+      const hrefs = extractHrefs(html);
+
+      assert(hrefs.includes('./destination/index.html'), 'M-2: root-page markdown link rewritten to relative .html (offline mode)');
+      assert(!hrefs.some((h) => h === '/destination/'), 'M-2: no absolute "/destination/" path leaked into offline HTML');
+
+      // File existence check โ€” the file:// test.
+      const target = path.resolve(dir, 'site/destination/index.html');
+      assert(fs.existsSync(target), 'M-2: rewritten target file actually exists on disk');
+    }
+
+    // Nested page (site/api/index.html) โ€” depth-adjusted relative paths.
+    // The fix must add `../` so the path navigates up correctly from the
+    // subfolder in offline mode.
+    {
+      const dir = setup('offline-links-31-167-nested-page');
+      writeFile(dir, 'docs/api/index.md', '# API\n\n[link](/destination.md)\n');
+      writeFile(dir, 'docs/destination.md', '# Destination\n');
+
+      execSync(`node ${DOCMD} build --offline`, { cwd: dir, stdio: 'pipe' });
+      const html = fs.readFileSync(path.join(dir, 'site/api/index.html'), 'utf8');
+      const hrefs = extractHrefs(html);
+
+      assert(hrefs.includes('../destination/index.html'), 'M-2: nested-page markdown link gets "../" prefix (offline mode)');
+      assert(!hrefs.some((h) => h === '/destination/'), 'M-2: no absolute path on the nested page either');
+
+      const target = path.resolve(dir, 'site/destination/index.html');
+      assert(fs.existsSync(target), 'M-2: nested-page target resolves correctly on disk');
+    }
+
+    // Normal (non-offline) build must be UNCHANGED โ€” clean URLs preserved.
+    // The fix must not regress HTTP-server deployments.
+    {
+      const dir = setup('offline-links-31-167-non-offline-unchanged');
+      writeFile(dir, 'docs/index.md', '# Home\n\n[link](/destination.md)\n');
+      writeFile(dir, 'docs/destination.md', '# Destination\n');
+
+      execSync(`node ${DOCMD} build`, { cwd: dir, stdio: 'pipe' });
+      const html = fs.readFileSync(path.join(dir, 'site/index.html'), 'utf8');
+      const hrefs = extractHrefs(html);
+
+      // In non-offline mode, the markdown link stays as the canonical
+      // clean URL (no .html suffix). The button container may rewrite
+      // its own href to a relative clean URL โ€” both are fine.
+      assert(!hrefs.some((h) => h.endsWith('.html') && !h.includes('#')), 'M-2: non-offline build still emits clean URLs (no .html suffix on internal hrefs)');
+    }
+
+    // External, hash-only, and asset hrefs must NEVER be rewritten.
+    {
+      const dir = setup('offline-links-31-167-passthrough');
+      writeFile(dir, 'docs/index.md', [
+        '# Home',
+        '',
+        '[external](https://example.com/page)',
+        '[anchor](#section)',
+        '![img](/assets/img.png)',
+        '[internal](/destination.md)',
+        ''
+      ].join('\n'));
+      writeFile(dir, 'docs/destination.md', '# Destination\n');
+
+      execSync(`node ${DOCMD} build --offline`, { cwd: dir, stdio: 'pipe' });
+      const html = fs.readFileSync(path.join(dir, 'site/index.html'), 'utf8');
+      const hrefs = extractHrefs(html);
+
+      assert(hrefs.includes('https://example.com/page'), 'M-2: external https URL is unchanged');
+      assert(hrefs.some((h) => h === '#section' || h.startsWith('#section')), 'M-2: hash-only anchor is unchanged');
+      // Asset paths ARE rewritten to relative for offline (file:// needs
+      // relative paths even for images), but the `/` prefix is dropped so
+      // they resolve to a real file on disk.
+      assert(hrefs.some((h) => h.includes('assets/img.png') && !h.startsWith('/assets/')), 'M-2: asset path is rewritten to relative (no leading /) for file://');
+      assert(hrefs.includes('./destination/index.html'), 'M-2: internal href rewritten to relative .html');
+    }
+  }
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return [...failures]; }
+};
\ No newline at end of file
diff --git a/tests/cli-contracts/plugin-add-remove.test.js b/tests/cli-contracts/plugin-add-remove.test.js
new file mode 100644
index 0000000..f788c4c
--- /dev/null
+++ b/tests/cli-contracts/plugin-add-remove.test.js
@@ -0,0 +1,211 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Phase 3 PR 3.B โ€” Plugin add/remove across config formats
+ *
+ * Tests F7 (`remove ` doesn't actually remove the plugin
+ * entry from config) and M-3 (`docmd add ` silently no-ops
+ * for `.ts` / `.mjs` / `.cjs` configs).
+ *
+ * The legacy regex-based injector only matched `module.exports = {...}`.
+ * The brace-balanced scanner in `packages/plugins/installer/src/config-editor.ts`
+ * handles all five supported formats uniformly.
+ *
+ * Run: `node tests/runner.js`
+ * --------------------------------------------------------------------
+ */
+
+import {
+  DOCMD,
+  setup,
+  writeFile,
+  exitCodeOf,
+  runTestFile
+} from '../shared.js';
+import fs from 'node:fs';
+import { execSync } from 'node:child_process';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(condition, message) {
+  if (!condition) {
+    failed++;
+    failures.push(message);
+    console.log(`    โŒ ${message}`);
+  } else {
+    passed++;
+    console.log(`    โœ… ${message}`);
+  }
+}
+
+export const test = runTestFile({
+  name: 'Plugin add/remove across config formats (Phase 3 PR 3.B โ€” F7, M-3)',
+  emoji: '๐Ÿ”Œ',
+  run: () => {
+
+    // M-3 โ€” `add` must inject the plugin entry into a TS config (was no-op).
+    // Uses 'math' (a non-core plugin from the installer registry) so the
+    // add/remove gate allows it. Core plugins (search, seo, llms, โ€ฆ)
+    // ship with @docmd/core and are now blocked from add/remove โ€” they're
+    // opted out via `plugins.: false` instead.
+    {
+      const dir = setup('plugin-add-remove-27-m3-add-ts');
+      writeFile(dir, 'docs/index.md', '# Hi\n');
+      writeFile(dir, 'docmd.config.ts', [
+        "import { defineConfig } from '@docmd/api';",
+        '',
+        'export default defineConfig({',
+        '  title: \'M3 TS\',',
+        '  src: \'./docs\',',
+        '  out: \'./site\',',
+        '  plugins: {}',
+        '});',
+        ''
+      ].join('\n'));
+      // Use execSync (the brute-style) for the assertion below.
+      execSync(`node ${DOCMD} add math`, { cwd: dir, stdio: 'pipe' });
+      const after = fs.readFileSync(`${dir}/docmd.config.ts`, 'utf8');
+      assert(/['"]math['"]\s*:\s*\{\s*\}/.test(after), 'M-3: TS config gets math entry after add');
+    }
+
+    // M-3 โ€” same for MJS
+    {
+      const dir = setup('plugin-add-remove-27-m3-add-mjs');
+      writeFile(dir, 'docs/index.md', '# Hi\n');
+      writeFile(dir, 'docmd.config.mjs', [
+        "import { defineConfig } from '@docmd/api';",
+        '',
+        'export default defineConfig({',
+        '  title: \'M3 MJS\',',
+        '  plugins: {}',
+        '});',
+        ''
+      ].join('\n'));
+      execSync(`node ${DOCMD} add math`, { cwd: dir, stdio: 'pipe' });
+      const after = fs.readFileSync(`${dir}/docmd.config.mjs`, 'utf8');
+      assert(/['"]math['"]\s*:\s*\{\s*\}/.test(after), 'M-3: MJS config gets math entry after add');
+    }
+
+    // F7 โ€” `remove` must remove the plugin entry from a TS config (was no-op).
+    {
+      const dir = setup('plugin-add-remove-27-f7-remove-ts');
+      writeFile(dir, 'docmd.config.ts', [
+        "import { defineConfig } from '@docmd/api';",
+        '',
+        'export default defineConfig({',
+        '  title: \'F7 TS\',',
+        '  plugins: {',
+        '    math: {}',
+        '  }',
+        '});',
+        ''
+      ].join('\n'));
+      execSync(`node ${DOCMD} remove math`, { cwd: dir, stdio: 'pipe' });
+      const after = fs.readFileSync(`${dir}/docmd.config.ts`, 'utf8');
+      assert(!/math\s*:/.test(after), 'F7: TS config math entry removed');
+      assert(/plugins\s*:/.test(after), 'F7: TS config plugins block still present');
+    }
+
+    // F7 โ€” same for JSON
+    {
+      const dir = setup('plugin-add-remove-27-f7-remove-json');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'F7 JSON', plugins: { math: {} } }, null, 2) + '\n');
+      execSync(`node ${DOCMD} remove math`, { cwd: dir, stdio: 'pipe' });
+      const after = fs.readFileSync(`${dir}/docmd.config.json`, 'utf8');
+      assert(!/"math"\s*:/.test(after), 'F7: JSON config math entry removed');
+    }
+
+    // Idempotency โ€” adding a plugin that's already configured must NOT
+    // create a duplicate entry.
+    {
+      const dir = setup('plugin-add-remove-27-idempotent');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'Idem', plugins: { math: {} } }, null, 2) + '\n');
+      execSync(`node ${DOCMD} add math`, { cwd: dir, stdio: 'pipe' });
+      const after = JSON.parse(fs.readFileSync(`${dir}/docmd.config.json`, 'utf8'));
+      const keys = Object.keys(after.plugins);
+      assert(keys.filter((k) => k === 'math').length === 1, 'idempotent: only one math entry after re-add');
+    }
+
+    // No-plugins-block JS config โ€” `add` should CREATE the plugins block.
+    {
+      const dir = setup('plugin-add-remove-27-js-no-plugins');
+      writeFile(dir, 'docmd.config.js', [
+        'module.exports = {',
+        '  title: \'JS no plugins\',',
+        '  src: \'./docs\',',
+        '  out: \'./site\'',
+        '};',
+        ''
+      ].join('\n'));
+      execSync(`node ${DOCMD} add math`, { cwd: dir, stdio: 'pipe' });
+      const after = fs.readFileSync(`${dir}/docmd.config.js`, 'utf8');
+      assert(/plugins\s*:\s*\{/.test(after), 'JS no-plugins: plugins block created');
+      assert(/['"]math['"]\s*:\s*\{\s*\}/.test(after), 'JS no-plugins: math entry present');
+      // No stray newline-comma in the output (regression guard).
+      assert(!/,\s*\n\s*plugins/.test(after) || /,\n\s*plugins/.test(after), 'JS no-plugins: no stray \",\\n\" between last key and plugins');
+    }
+
+    // Core plugin gate โ€” `add ` must abort with exit 1 and
+    // not modify the config. Core plugins ship with @docmd/core and are
+    // opted out via plugins.: false, not installed/removed
+    // manually.
+    {
+      const dir = setup('plugin-add-remove-27-core-gate');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'Core Gate', plugins: {} }, null, 2) + '\n');
+      const code = exitCodeOf(`node ${DOCMD} add okf`, dir);
+      assert(code === 1, 'core plugin add rejected with exit 1');
+      const after = fs.readFileSync(`${dir}/docmd.config.json`, 'utf8');
+      assert(!/okf/.test(after), 'core plugin add did not modify config');
+    }
+    {
+      const dir = setup('plugin-add-remove-27-core-gate-remove');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'Core Gate', plugins: { okf: {} } }, null, 2) + '\n');
+      const code = exitCodeOf(`node ${DOCMD} remove okf`, dir);
+      assert(code === 1, 'core plugin remove rejected with exit 1');
+      const after = fs.readFileSync(`${dir}/docmd.config.json`, 'utf8');
+      assert(/"okf"\s*:/.test(after), 'core plugin remove did not modify config');
+    }
+
+    // M-14 โ€” `docmd add` for an already-configured plugin must NOT
+    // claim "Plugin successfully installed and activated". The plugin
+    // is already there; nothing was installed. The final message must
+    // reflect what actually happened.
+    {
+      const dir = setup('plugin-add-remove-27-m14-already-installed-message');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'M14', plugins: { math: {} } }, null, 2) + '\n');
+      let output = '';
+      try {
+        output = execSync(`node ${DOCMD} add math`, { cwd: dir, stdio: 'pipe', encoding: 'utf8' });
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : (e.stdout ? e.stdout.toString() : '')) +
+                 (typeof e.stderr === 'string' ? e.stderr : (e.stderr ? e.stderr.toString() : ''));
+      }
+      assert(/already (configured|installed)/i.test(output), 'M-14: already-installed message appears');
+      assert(!/successfully installed and activated/i.test(output), 'M-14: no false "successfully installed and activated" message');
+    }
+
+    // M-14 โ€” companion: first install of a fresh plugin still shows
+    // the success message (regression guard).
+    {
+      const dir = setup('plugin-add-remove-27-m14-fresh-install-message');
+      writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'M14 fresh', plugins: {} }, null, 2) + '\n');
+      let output = '';
+      try {
+        output = execSync(`node ${DOCMD} add math`, { cwd: dir, stdio: 'pipe', encoding: 'utf8' });
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : (e.stdout ? e.stdout.toString() : '')) +
+                 (typeof e.stderr === 'string' ? e.stderr : (e.stderr ? e.stderr.toString() : ''));
+      }
+      assert(/successfully installed and activated/i.test(output), 'M-14: fresh install still shows success message');
+    }
+  }
+});
+
+export const results = {
+  get passed() { return passed; },
+  get failed() { return failed; },
+  get failures() { return [...failures]; }
+};
diff --git a/tests/cli-contracts/plugin-assets-pipeline.test.js b/tests/cli-contracts/plugin-assets-pipeline.test.js
new file mode 100644
index 0000000..7534b85
--- /dev/null
+++ b/tests/cli-contracts/plugin-assets-pipeline.test.js
@@ -0,0 +1,188 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Plugin asset pipeline โ€” async/await + capability regression tests
+ *
+ * Covers the regression bugs that broke plugin CSS/JS loading
+ * after the Slice C.1+C.2 safeCall refactor:
+ *
+ *   PAA-1  getAssets consumer in core/src/commands/build.ts must
+ *          await the async wrapper around getAssetsFn. Without the
+ *          await, `assets` is a Promise and `Array.isArray(assets)`
+ *          is false, so every plugin's `src`/`dest` copy is silently
+ *          skipped โ€” search, git, mermaid, math, openapi CSS/JS never
+ *          land in site/assets/.
+ *
+ *   PAA-2  getAssets consumer in core/src/engine/generator.ts must
+ *          await the same wrapper. Without the await, no '; }",
+        ""
+      ].join('\n'));
+      writeFile(proj, 'docmd.config.json', JSON.stringify({
+        title: 'D-S5',
+        src: './docs',
+        out: './site',
+        plugins: { './plugins/string-scripts': {} }
+      }, null, 2) + '\n');
+
+      let output = '';
+      try {
+        output = execSync(`node ${DOCMD} build`, { cwd: proj, stdio: 'pipe', encoding: 'utf8' });
+      } catch (e) {
+        output = (typeof e.stdout === 'string' ? e.stdout : '') + (typeof e.stderr === 'string' ? e.stderr : '');
+      }
+      const html = fs.readFileSync(path.join(proj, 'site/index.html'), 'utf8');
+      assert(/'
+    ]
+  };`);
+  writeFile(dir, 'docs/index.md', '# Custom Assets');
+  const r = build(dir);
+  assert('builds with custom assets', r.ok);
+  const html = readSite(dir, 'index.html');
+  assert('custom CSS or head injection works', html?.includes('custom.css') || r.ok);
+  assert('custom JS or head injection works', html?.includes('custom.js') || r.ok);
+}
+
+// โ”€โ”€โ”€ TEST 13: Edit links โ”€โ”€โ”€
+console.log('\nโœ๏ธ Test 13: Edit links');
+{
+  const dir = setup('13-edit-links');
+  writeFile(dir, 'docmd.config.js', `module.exports = {
+    title: 'Edit Links',
+    src: 'docs',
+    editLink: {
+      enabled: true,
+      baseUrl: 'https://github.com/test/repo/edit/main/docs',
+      text: 'Edit on GitHub'
+    }
+  };`);
+  writeFile(dir, 'docs/index.md', '# Edit Link Test');
+  const r = build(dir);
+  assert('builds with edit links', r.ok);
+  const html = readSite(dir, 'index.html');
+  assert('edit link in page', html?.includes('Edit on GitHub') || html?.includes('github.com/test/repo'));
+}
+
+// โ”€โ”€โ”€ TEST 14: No-style pages โ”€โ”€โ”€
+console.log('\n๐Ÿงน Test 14: No-style pages');
+{
+  const dir = setup('14-no-style');
+  writeFile(dir, 'docs/index.md', '# Normal Page');
+  writeFile(dir, 'docs/raw.md', '---\nlayout: no-style\n---\n# Raw Page\nNo styling.');
+  const r = build(dir);
+  assert('builds with no-style page', r.ok);
+  assert('no-style page exists', siteExists(dir, 'raw/index.html'));
+  const raw = readSite(dir, 'raw/index.html');
+  assert('no-style page rendered', raw?.includes('Raw Page'));
+}
+
+// โ”€โ”€โ”€ TEST 15: Search index โ”€โ”€โ”€
+console.log('\n๐Ÿ” Test 15: Search index generation');
+{
+  const dir = setup('15-search');
+  writeFile(dir, 'docs/index.md', '# Search Home\nSearchable content here.');
+  writeFile(dir, 'docs/guide.md', '# Guide\nMore searchable content.');
+  const r = build(dir);
+  assert('builds with search', r.ok);
+  assert('search-index.json exists', siteExists(dir, 'search-index.json'));
+  const idx = readSite(dir, 'search-index.json');
+  assert('search index has content', idx && JSON.parse(idx).documentCount >= 2);
+}
+
+// โ”€โ”€โ”€ TEST 16: Sitemap โ”€โ”€โ”€
+console.log('\n๐Ÿ—บ๏ธ Test 16: Sitemap generation');
+{
+  const dir = setup('16-sitemap');
+  writeFile(dir, 'docmd.config.js', `module.exports = {
+    title: 'Sitemap Test',
+    src: 'docs',
+    url: 'https://example.com'
+  };`);
+  writeFile(dir, 'docs/index.md', '# Home');
+  writeFile(dir, 'docs/about.md', '# About');
+  const r = build(dir);
+  assert('builds with sitemap', r.ok);
+  assert('sitemap.xml exists', siteExists(dir, 'sitemap.xml'));
+  const sm = readSite(dir, 'sitemap.xml');
+  assert('sitemap has URLs', sm?.includes('example.com'));
+}
+
+// โ”€โ”€โ”€ TEST 17: EJS content pages โ”€โ”€โ”€
+console.log('\n๐Ÿ”ง Test 17: EJS content pages');
+{
+  const dir = setup('17-ejs');
+  writeFile(dir, 'docs/index.md', '# Home');
+  writeFile(dir, 'docs/dynamic.ejs', `---
+title: Dynamic Page
+---
+# Generated at build time
+
+<% const items = ['one', 'two', 'three']; %>
+<% items.forEach(i => { %>
+- Item: <%= i %>
+<% }); %>
+`);
+  const r = build(dir);
+  assert('builds with EJS pages', r.ok);
+  assert('EJS page rendered', siteExists(dir, 'dynamic/index.html'));
+  const html = readSite(dir, 'dynamic/index.html');
+  assert('EJS content expanded', html?.includes('Item: one') && html?.includes('Item: three'));
+}
+
+// โ”€โ”€โ”€ TEST 18: README.md as index fallback โ”€โ”€โ”€
+console.log('\n๐Ÿ“‹ Test 18: README.md as index fallback');
+{
+  const dir = setup('18-readme');
+  writeFile(dir, 'docs/README.md', '# Welcome\nFrom README.');
+  writeFile(dir, 'docs/guide/README.md', '# Guide\nFrom guide README.');
+  const r = build(dir);
+  assert('builds with README fallback', r.ok);
+  assert('README becomes index', siteExists(dir, 'index.html'));
+  const html = readSite(dir, 'index.html');
+  assert('README content rendered', html?.includes('From README'));
+  assert('nested README becomes index', siteExists(dir, 'guide/index.html'));
+}
+
+// โ”€โ”€โ”€ TEST 19: .markdown extension โ”€โ”€โ”€
+console.log('\n๐Ÿ“„ Test 19: .markdown file extension');
+{
+  const dir = setup('19-markdown-ext');
+  writeFile(dir, 'docs/index.md', '# Home');
+  writeFile(dir, 'docs/about.markdown', '# About\nMarkdown extension.');
+  const r = build(dir);
+  assert('builds with .markdown files', r.ok);
+  assert('.markdown page rendered', siteExists(dir, 'about/index.html'));
+  const html = readSite(dir, 'about/index.html');
+  assert('.markdown content correct', html?.includes('Markdown extension'));
+}
+
+// โ”€โ”€โ”€ TEST 20: Deep nesting โ”€โ”€โ”€
+console.log('\n๐Ÿ—๏ธ Test 20: Deep nested structure');
+{
+  const dir = setup('20-deep-nesting');
+  writeFile(dir, 'docs/index.md', '# Home');
+  writeFile(dir, 'docs/a/b/c/d/deep.md', '# Deep Page\nVery deep.');
+  const r = build(dir);
+  assert('builds with deep nesting', r.ok);
+  assert('deep page exists', siteExists(dir, 'a/b/c/d/deep/index.html'));
+}
+
+// โ”€โ”€โ”€ TEST 21: Zero-config auto-nav accuracy โ”€โ”€โ”€
+console.log('\n๐Ÿงญ Test 21: Zero-config auto-nav accuracy');
+{
+  const dir = setup('21-auto-nav');
+  writeFile(dir, 'docs/index.md', '# Home');
+  writeFile(dir, 'docs/getting-started.md', '# Getting Started');
+  writeFile(dir, 'docs/guide/intro.md', '# Intro');
+  writeFile(dir, 'docs/guide/advanced.md', '# Advanced');
+  const r = build(dir);
+  assert('builds with auto-nav', r.ok);
+  const html = readSite(dir, 'index.html');
+  assert('auto-nav includes Getting Started', html?.includes('Getting Started'));
+  assert('auto-nav includes Guide section', html?.includes('Intro') || html?.includes('Guide'));
+}
+
+// โ”€โ”€โ”€ TEST 22: Title tag auto-append โ”€โ”€โ”€
+console.log('\n๐Ÿท๏ธ Test 22: Title tag auto-append');
+{
+  const dir = setup('22-title-tag');
+  writeFile(dir, 'docmd.config.js', `module.exports = { title: 'MySite', src: 'docs' };`);
+  writeFile(dir, 'docs/index.md', '---\ntitle: Home\n---\n# Home');
+  writeFile(dir, 'docs/about.md', '---\ntitle: About Us\n---\n# About');
+  const r = build(dir);
+  assert('builds with title tags', r.ok);
+  const about = readSite(dir, 'about/index.html');
+  // Title should be "About Us โ€” MySite" or similar
+  const titleMatch = about?.match(/(.*?)<\/title>/s);
+  const titleText = titleMatch?.[1]?.trim();
+  assert('sub-page title includes page + site', titleText?.includes('About') && titleText?.includes('MySite'));
+}
+
+// โ”€โ”€โ”€ TEST 23: OG meta tags โ”€โ”€โ”€
+console.log('\n๐Ÿท๏ธ Test 23: OG meta tags');
+{
+  const dir = setup('23-og-tags');
+  writeFile(dir, 'docmd.config.js', `module.exports = { title: 'OG Test', src: 'docs', url: 'https://example.com' };`);
+  writeFile(dir, 'docs/index.md', '---\ntitle: OG Page\ndescription: OG description\n---\n# OG');
+  const r = build(dir);
+  assert('builds with OG tags', r.ok);
+  const html = readSite(dir, 'index.html');
+  assert('og:title present', html?.includes('og:title'));
+  assert('og:description present', html?.includes('og:description') || html?.includes('OG description'));
+}
+
+// โ”€โ”€โ”€ TEST 24: Redirects โ”€โ”€โ”€
+console.log('\nโ†ฉ๏ธ Test 24: Redirects');
+{
+  const dir = setup('24-redirects');
+  writeFile(dir, 'docmd.config.js', `module.exports = {
+    title: 'Redirects',
+    src: 'docs',
+    redirects: { '/old-page': '/new-page' }
+  };`);
+  writeFile(dir, 'docs/index.md', '# Home');
+  writeFile(dir, 'docs/new-page.md', '# New Page');
+  const r = build(dir);
+  assert('builds with redirects', r.ok);
+  assert('redirect page created', siteExists(dir, 'old-page/index.html'));
+  const redirect = readSite(dir, 'old-page/index.html');
+  assert('redirect has meta refresh', redirect?.includes('new-page') || redirect?.includes('redirect'));
+}
+
+// โ”€โ”€โ”€ TEST 25: Per-page layout override โ”€โ”€โ”€
+console.log('\n๐Ÿ“ Test 25: Per-page layout override');
+{
+  const dir = setup('25-layout-override');
+  writeFile(dir, 'docs/index.md', '# Normal');
+  writeFile(dir, 'docs/landing.md', '---\nlayout: no-style\ntitle: Landing\n---\n# Landing Page\nCustom layout.');
+  const r = build(dir);
+  assert('builds with layout override', r.ok);
+  const normal = readSite(dir, 'index.html');
+  const landing = readSite(dir, 'landing/index.html');
+  assert('normal page has full layout', normal?.includes('sidebar') || normal?.includes('nav'));
+  assert('landing page rendered', landing?.includes('Landing Page'));
+}
+
+// โ”€โ”€โ”€ TEST 26: URL Consistency (No Double Slashes) โ”€โ”€โ”€
+console.log('\n๐Ÿ”— Test 26: URL Consistency (No Double Slashes)');
+{
+  const dir = setup('26-url-consistency');
+  writeFile(dir, 'docmd.config.js', `module.exports = {
+    title: 'URL Test',
+    url: 'https://example.com',
+    src: 'docs',
+    navigation: [
+      { title: 'Home', path: '/' },
+      { title: 'Guide', path: '/guide/' },
+      { title: 'Nested', path: '/deep/nested/' }
+    ]
+  };`);
+  writeFile(dir, 'docs/index.md', '# Home\n[Go to Guide](guide/)\n[Go to Nested](deep/nested/)');
+  writeFile(dir, 'docs/guide.md', '# Guide\n[Back Home](/)');
+  writeFile(dir, 'docs/deep/nested.md', '# Nested\n[Back Home](/)');
+  const r = build(dir);
+  assert('builds with navigation', r.ok);
+  
+  const idx = readSite(dir, 'index.html');
+  const guide = readSite(dir, 'guide/index.html');
+  const nested = readSite(dir, 'deep/nested/index.html');
+  
+  // Check for double slashes in href attributes (excluding protocol://)
+  const hasDoubleSlashHref = (html) => /href="[^"]*([^:])\/\//.test(html);
+  assert('index has no double-slash hrefs', !hasDoubleSlashHref(idx));
+  assert('guide has no double-slash hrefs', !hasDoubleSlashHref(guide));
+  assert('nested has no double-slash hrefs', !hasDoubleSlashHref(nested));
+  
+  // Check sitemap URLs
+  const sitemap = readSite(dir, 'sitemap.xml');
+  const hasDoubleSlash = (html) => /([^:])\/\//.test(html);
+  assert('sitemap has no double slashes', !hasDoubleSlash(sitemap));
+  assert('sitemap has correct root URL', sitemap?.includes('https://example.com/'));
+  assert('sitemap has correct guide URL', sitemap?.includes('https://example.com/guide/'));
+}
+
+// โ”€โ”€โ”€ TEST 27: Search Index URL Format โ”€โ”€โ”€
+console.log('\n๐Ÿ” Test 27: Search Index URL Format');
+{
+  const dir = setup('27-search-urls');
+  writeFile(dir, 'docs/index.md', '---\ntitle: Home\n---\n# Welcome');
+  writeFile(dir, 'docs/guide/intro.md', '---\ntitle: Introduction\n---\n# Getting Started');
+  const r = build(dir);
+  assert('builds with search', r.ok);
+  
+  const searchIdx = readSite(dir, 'search-index.json');
+  const parsed = JSON.parse(searchIdx);
+  const storedFields = parsed.storedFields || {};
+  const ids = Object.values(storedFields).map((f) => f.id);
+  
+  // IDs should be clean slugs without leading slashes (except root)
+  assert('root page has clean ID', ids.some(id => id === '/'));
+  assert('nested page has clean ID', ids.some(id => id === 'guide/intro/' || id === '/guide/intro/'));
+  // No double slashes in any ID
+  assert('no double slashes in search IDs', !ids.some(id => id.includes('//')));
+}
+
+// โ”€โ”€โ”€ TEST 28: i18n URL Prefixes โ”€โ”€โ”€
+console.log('\n๐ŸŒ Test 28: i18n URL Prefixes');
+{
+  const dir = setup('28-i18n-urls');
+  writeFile(dir, 'docmd.config.js', `module.exports = {
+    title: 'i18n URLs',
+    url: 'https://example.com',
+    src: 'docs',
+    i18n: { default: 'en', locales: [
+      { id: 'en', label: 'English' },
+      { id: 'de', label: 'Deutsch' }
+    ]}
+  };`);
+  writeFile(dir, 'docs/en/index.md', '# English Home\n[German](/de/)');
+  writeFile(dir, 'docs/en/guide.md', '# English Guide');
+  writeFile(dir, 'docs/en/navigation.json', '[{"title":"Home","path":"/"},{"title":"Guide","path":"/guide/"}]');
+  writeFile(dir, 'docs/de/index.md', '# German Home\n[English](/)');
+  writeFile(dir, 'docs/de/navigation.json', '[{"title":"Startseite","path":"/"}]');
+  const r = build(dir);
+  assert('builds with i18n', r.ok);
+  
+  // Check that nav links have correct prefixes
+  const enIdx = readSite(dir, 'index.html');
+  const deIdx = readSite(dir, 'de/index.html');
+  
+  // English root should have links without double slashes
+  const hasDoubleSlash = (html) => /href="[^"]*([^:])\/\//.test(html);
+  assert('EN index has no double-slash hrefs', !hasDoubleSlash(enIdx));
+  assert('DE index has no double-slash hrefs', !hasDoubleSlash(deIdx));
+  
+  // Check sitemap has both locales
+  const sitemap = readSite(dir, 'sitemap.xml');
+  assert('sitemap has EN URLs', sitemap?.includes('example.com/'));
+  assert('sitemap has DE URLs', sitemap?.includes('example.com/de/'));
+  
+  // Check hreflang tags don't have duplicate locale prefixes
+  const deIdxHreflang = readSite(dir, 'de/index.html');
+  const hreflangPattern = /hreflang="[^"]*" href="([^"]*)"/g;
+  const hreflangUrls = [...deIdxHreflang.matchAll(hreflangPattern)].map(m => m[1]);
+  assert('hreflang EN points to root', hreflangUrls.some(u => u === '/'));
+  assert('hreflang DE points to /de/', hreflangUrls.some(u => u === '/de/'));
+  assert('no duplicate locale in hreflang', !hreflangUrls.some(u => u.includes('/de/de/')));
+}
+
+// โ”€โ”€โ”€ TEST 29: Hreflang Tags Consistency โ”€โ”€โ”€
+console.log('\n๐Ÿท๏ธ Test 29: Hreflang Tags Consistency');
+{
+  const dir = setup('29-hreflang-tags');
+  writeFile(dir, 'docmd.config.js', `module.exports = {
+    title: 'Hreflang Test',
+    url: 'https://example.com',
+    src: 'docs',
+    i18n: { default: 'en', locales: [
+      { id: 'en', label: 'English' },
+      { id: 'fr', label: 'Franรงais' }
+    ]}
+  };`);
+  writeFile(dir, 'docs/en/index.md', '# English Home');
+  writeFile(dir, 'docs/en/guide.md', '# English Guide');
+  writeFile(dir, 'docs/en/navigation.json', '[{"title":"Home","path":"/"},{"title":"Guide","path":"/guide/"}]');
+  writeFile(dir, 'docs/fr/index.md', '# French Home');
+  writeFile(dir, 'docs/fr/guide.md', '# French Guide');
+  writeFile(dir, 'docs/fr/navigation.json', '[{"title":"Accueil","path":"/"},{"title":"Guide","path":"/guide/"}]');
+  const r = build(dir);
+  assert('builds with i18n', r.ok);
+  
+  // Check hreflang on English root
+  const enIdx = readSite(dir, 'index.html');
+  assert('EN root has hreflang for EN', enIdx?.includes('hreflang="en" href="/"'));
+  assert('EN root has hreflang for FR', enIdx?.includes('hreflang="fr" href="/fr/"'));
+  assert('EN root has x-default', enIdx?.includes('hreflang="x-default"'));
+  
+  // Check hreflang on French root
+  const frIdx = readSite(dir, 'fr/index.html');
+  assert('FR root has hreflang for EN', frIdx?.includes('hreflang="en" href="/"'));
+  assert('FR root has hreflang for FR', frIdx?.includes('hreflang="fr" href="/fr/"'));
+  
+  // Check hreflang on nested pages
+  const enGuide = readSite(dir, 'guide/index.html');
+  const frGuide = readSite(dir, 'fr/guide/index.html');
+  assert('EN guide has correct hreflang', enGuide?.includes('hreflang="fr" href="/fr/guide/"'));
+  assert('FR guide has correct hreflang', frGuide?.includes('hreflang="en" href="/guide/"'));
+  
+  // Ensure no duplicate locale prefixes
+  assert('no /fr/fr/ in FR hreflang', !frIdx?.includes('/fr/fr/'));
+  assert('no /fr/fr/ in FR guide hreflang', !frGuide?.includes('/fr/fr/'));
+}
+
+// โ”€โ”€โ”€ TEST 30: Workspaces (multi-project) โ”€โ”€โ”€
+// Two sub-projects compiled into one site via a root workspace config.
+// Replaces the standalone "Mega Integration" test file that lived at
+// tests/mega-integration.test.js (deleted). The new Tests 30 + 31 cover
+// what used to be in the legacy failsafe's "Mega Integration" section
+// but inline alongside the other feature tests so the runner shows
+// nine sections, not ten.
+
+{
+  const dir = setup('features-30-workspaces');
+  fs.mkdirSync(path.join(dir, 'main/docs'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'api/docs'), { recursive: true });
+  writeFile(dir, 'main/docmd.config.js',
+    `export default { title: 'Main Docs', src: 'docs' }`);
+  writeFile(dir, 'main/docs/index.md', '# Main Home\n');
+  writeFile(dir, 'api/docmd.config.js',
+    `export default { title: 'API Reference', src: 'docs' }`);
+  writeFile(dir, 'api/docs/index.md', '# API Index\n');
+  writeFile(dir, 'docmd.config.js',
+    `export default {
+       workspace: {
+         projects: [
+           { prefix: '/', src: 'main' },
+           { prefix: '/api', src: 'api' }
+         ]
+       }
+     }`);
+
+  build(dir);
+
+  assert('workspaces: main root built',
+    fs.existsSync(path.join(dir, 'site/index.html')));
+  assert('workspaces: api root built',
+    fs.existsSync(path.join(dir, 'site/api/index.html')));
+  const mainIdx = readSite(dir, 'index.html');
+  assert('workspaces: main page has its title',
+    mainIdx?.includes('Main Docs'));
+  const apiIdx = readSite(dir, 'api/index.html');
+  assert('workspaces: api page has its title',
+    apiIdx?.includes('API Reference'));
+}
+
+// โ”€โ”€โ”€ TEST 31: Mega integration (workspaces + i18n + versioning + plugins) โ”€โ”€โ”€
+// One project that exercises EVERY docmd feature at once. Equivalent to
+// the legacy failsafe's "Mega Integration Test (V5.0)" โ€” assertions
+// cover the artefacts every common plugin is supposed to produce and
+// the cross-feature interactions (i18n + versioning + workspaces).
+
+{
+  const dir = setup('features-31-mega');
+  fs.mkdirSync(path.join(dir, 'main/docs/en'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'main/docs/fr'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'main/docs-v1/en'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'main/assets/css'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'api/docs'), { recursive: true });
+
+  writeFile(dir, 'main/docmd.config.js',
+    `export default {
+       title: 'Mega Docs',
+       url: 'https://example.com',
+       src: 'docs',
+       out: 'site',
+       plugins: { math: {}, sitemap: {}, llms: {}, seo: {}, pwa: {} },
+       versions: { current: 'v2', all: [
+         { id: 'v2', dir: 'docs' },
+         { id: 'v1', dir: 'docs-v1', label: 'v1.0' }
+       ]},
+       i18n: { default: 'en', locales: [
+         { id: 'en', label: 'English' },
+         { id: 'fr', label: 'Franรงais' }
+       ]}
+     }`);
+  writeFile(dir, 'api/docmd.config.js',
+    `export default {
+       title: 'API Reference',
+       url: 'https://example.com/api',
+       src: 'docs',
+       navigation: [{ title: 'Home', path: '/' }],
+       plugins: { search: {}, mermaid: {} }
+     }`);
+  writeFile(dir, 'docmd.config.js',
+    `export default {
+       workspace: {
+         projects: [
+           { prefix: '/', src: 'main' },
+           { prefix: '/api', src: 'api' }
+         ]
+       }
+     }`);
+
+  writeFile(dir, 'main/docs/en/index.md',
+    '---\ntitle: Home\n---\n# Home\nWelcome.');
+  writeFile(dir, 'main/docs/en/guide.md',
+    '---\ntitle: Guide\n---\n# Guide\n## Steps\n');
+  writeFile(dir, 'main/docs/en/math.md',
+    '---\ntitle: Math\n---\n# Math\nInline $E = mc^2$.');
+  writeFile(dir, 'main/docs/en/mermaid.md',
+    '---\ntitle: Diagrams\n---\n# Diagrams\n```mermaid\ngraph TD\n  A --> B\n```\n');
+  writeFile(dir, 'main/docs/fr/index.md', '# Accueil\n');
+  writeFile(dir, 'main/docs-v1/en/index.md', '# v1 Home\nOld.');
+  writeFile(dir, 'api/docs/index.md',
+    '---\ntitle: API\n---\n# API\n## Endpoints\n');
+  writeFile(dir, 'main/assets/css/custom.css', '.x{color:red}');
+
+  build(dir);
+
+  assert('mega: main index built',
+    fs.existsSync(path.join(dir, 'site/index.html')));
+  assert('mega: main guide built',
+    fs.existsSync(path.join(dir, 'site/guide/index.html')));
+  assert('mega: api index built',
+    fs.existsSync(path.join(dir, 'site/api/index.html')));
+  assert('mega: French locale index built',
+    fs.existsSync(path.join(dir, 'site/fr/index.html')));
+  assert('mega: v1 index built',
+    fs.existsSync(path.join(dir, 'site/v1/index.html')));
+  assert('mega: v1 guide absent',
+    !fs.existsSync(path.join(dir, 'site/v1/guide/index.html')));
+  assert('mega: search-index generated',
+    fs.existsSync(path.join(dir, 'site/search-index.json')));
+  assert('mega: sitemap generated',
+    fs.existsSync(path.join(dir, 'site/sitemap.xml')));
+  assert('mega: llms.txt generated',
+    fs.existsSync(path.join(dir, 'site/llms.txt')));
+  assert('mega: llms-full.txt generated',
+    fs.existsSync(path.join(dir, 'site/llms-full.txt')));
+  assert('mega: PWA manifest generated',
+    fs.existsSync(path.join(dir, 'site/manifest.webmanifest')) ||
+    fs.existsSync(path.join(dir, 'site/manifest.json')));
+  assert('mega: service worker generated',
+    fs.existsSync(path.join(dir, 'site/service-worker.js')) ||
+    fs.existsSync(path.join(dir, 'site/sw.js')));
+  assert('mega: sitemap has root URL',
+    readSite(dir, 'sitemap.xml')?.includes('example.com'));
+  assert('mega: sitemap has French URL',
+    readSite(dir, 'sitemap.xml')?.includes('/fr/'));
+  assert('mega: llms.txt has links',
+    readSite(dir, 'llms.txt')?.includes('[') &&
+    readSite(dir, 'llms.txt')?.includes(']('));
+  assert('mega: math page has katex',
+    readSite(dir, 'math/index.html')?.includes('katex'));
+  assert('mega: mermaid page has diagram',
+    readSite(dir, 'mermaid/index.html')?.includes('class="mermaid"'));
+  assert('mega: index has SEO meta tags',
+    !!readSite(dir, 'index.html')?.match(/<meta\s+name=["']description["']/i));
+  assert('mega: custom assets copied',
+    fs.existsSync(path.join(dir, 'site/assets/css/custom.css')));
+}
+
+// โ”€โ”€โ”€ SUMMARY โ”€โ”€โ”€
+console.log('\n' + 'โ•'.repeat(50));
+console.log(`  ${passed} passed, ${failed} failed out of ${passed + failed} assertions`);
+if (failures.length > 0) {
+  console.log(`\n  Failures:`);
+  failures.forEach(f => console.log(`    ${FAIL} ${f}`));
+}
+console.log('โ•'.repeat(50) + '\n');
+
+process.exit(failed > 0 ? 1 : 0);
diff --git a/tests/package.json b/tests/package.json
new file mode 100644
index 0000000..aead43d
--- /dev/null
+++ b/tests/package.json
@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}
\ No newline at end of file
diff --git a/tests/runner.js b/tests/runner.js
new file mode 100644
index 0000000..73c7a5c
--- /dev/null
+++ b/tests/runner.js
@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Categorised test runner
+ *
+ * Replaces the monolithic `scripts/brute-test.js` +
+ * `scripts/brute-test-security.js` (now `tests/feature-integration.test.js`
+ * and `tests/security.test.js` after the scripts/ โ†’ tests/ move)
+ * with a set of smaller, focused test files under `tests/`. Each file
+ * exports a `test` object (created via `runTestFile()`) and a `results`
+ * object with `passed`, `failed`, `failures` getters.
+ *
+ * The runner:
+ *   1. Imports every test file in declared order.
+ *   2. For each file, prints a TUI section header (`<emoji>  <name>`).
+ *   3. Calls `test.run()` and reads the per-file `results` object to
+ *      print pass/fail counts.
+ *   4. Aggregates pass/fail across all files into a final summary.
+ *   5. Exits 1 if any file failed, 0 otherwise.
+ *
+ * Wired into `tools/prep.js` (called by `pnpm prep` via the status
+ * pipeline) so a single `pnpm prep` runs the entire categorised suite.
+ *
+ * The legacy feature-integration scenarios (zero-config, i18n,
+ * versioning, containers, code blocks, etc.) still run.
+ *
+ * Run: `node tests/runner.js`
+ * Or:  `node tests/runner.js --only=exit-codes,plugin-add-remove` (filter)
+ * --------------------------------------------------------------------
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CYAN = (s) => `\x1b[36m${s}\x1b[0m`;
+const GREEN = (s) => `\x1b[32m${s}\x1b[0m`;
+const RED = (s) => `\x1b[31m${s}\x1b[0m`;
+const DIM = (s) => `\x1b[2m${s}\x1b[0m`;
+const BOLD = (s) => `\x1b[1m${s}\x1b[0m`;
+
+const args = process.argv.slice(2);
+const only = (() => {
+  const flag = args.find((a) => a.startsWith('--only='));
+  if (!flag) return null;
+  return flag.slice('--only='.length).split(',').filter(Boolean);
+})();
+
+// `tools/verify.js` forwards `--skip-setup` to the runner in CI
+// (the install + build steps run before verify). The runner does
+// not need any setup work itself, so this is a no-op โ€” we just
+// drop it from the arg list so it does not leak into test files
+// or show up as an unrecognised flag. Add other verify-only flags
+// here as the verify script grows.
+const _SKIP_FLAGS = new Set(['--skip-setup']);
+for (const f of _SKIP_FLAGS) {
+  const i = args.indexOf(f);
+  if (i !== -1) args.splice(i, 1);
+}
+
+// ---------------------------------------------------------------------------
+// Test file registry โ€” order matters.
+//   - For in-process tests, the entry is the imported module.
+//   - For external tests, the entry has `{ external: true, command, args }`.
+//   - When `id` matches the `--only` filter, only those entries run.
+// ---------------------------------------------------------------------------
+
+const testFiles = [];
+
+function addInProcess(id, name, module) {
+  if (only && !only.includes(id)) return;
+  testFiles.push({ id, name, module });
+}
+
+function addExternal(id, name, command, args) {
+  if (only && !only.includes(id)) return;
+  testFiles.push({ id, name, module: { external: true, command, args } });
+}
+
+// --- Section 1: CLI contracts (Phase 3 PR 3.A / 3.B / 3.C) -----------------
+addInProcess(
+  'exit-codes',
+  'Exit-code contract (F6, M-12)',
+  await import('./cli-contracts/exit-codes.test.js')
+);
+addInProcess(
+  'plugin-add-remove',
+  'Plugin add/remove across config formats (F7, M-3)',
+  await import('./cli-contracts/plugin-add-remove.test.js')
+);
+addInProcess(
+  'validate-workspace',
+  'Validate rewrite + workspace errors + init example (F8, F9, M-1)',
+  await import('./cli-contracts/validate-workspace.test.js')
+);
+addInProcess(
+  'deploy',
+  'Deploy --force honours overwrite (N-2)',
+  await import('./cli-contracts/deploy.test.js')
+);
+addInProcess(
+  'stop',
+  'Stop sends SIGTERM and waits for graceful exit (M-11)',
+  await import('./cli-contracts/stop.test.js')
+);
+addInProcess(
+  'migrate',
+  'Migrate --dry-run is non-destructive (N-3)',
+  await import('./cli-contracts/migrate.test.js')
+);
+addInProcess(
+  'offline-links',
+  'Offline-mode internal links work in every hosting shape (#167)',
+  await import('./cli-contracts/offline-links.test.js')
+);
+addInProcess(
+  'plugin-contract',
+  'Plugin contract + public API fixes (Slice C.1 + C.2)',
+  await import('./cli-contracts/plugin-contract.test.js')
+);
+addInProcess(
+  'source-tools',
+  'Source tools + page shape consistency (Slice C.3)',
+  await import('./cli-contracts/source-tools.test.js')
+);
+addInProcess(
+  'i18n',
+  'i18n + workspace schema fixes (Slice D โ€” M-6, T-Z6)',
+  await import('./cli-contracts/i18n.test.js')
+);
+addInProcess(
+  'llms-and-tui',
+  'llms.txt sanitisation + TUI banner options (Slice F โ€” T-Z10, T-Z11, N-13, N-16)',
+  await import('./cli-contracts/llms-and-tui.test.js')
+);
+addInProcess(
+  'migrate-fix',
+  'Migration polish (Slice E โ€” N-9, N-10, N-22)',
+  await import('./cli-contracts/migrate-fix.test.js')
+);
+addInProcess(
+  'plugin-assets-pipeline',
+  'Plugin asset pipeline (PAA-1, PAA-2, PAA-3 โ€” async/await + capability)',
+  await import('./cli-contracts/plugin-assets-pipeline.test.js')
+);
+addInProcess(
+  'asset-base-url',
+  'Asset base-URL + engine-key (URL-1, URL-2 โ€” <base> + KNOWN_KEYS)',
+  await import('./cli-contracts/asset-base-url.test.js')
+);
+addInProcess(
+  'runtime-deps',
+  'Runtime-deps shared auto-install pipeline (RD-1..RD-CWE, CWE-78 fix)',
+  await import('./cli-contracts/runtime-deps.test.js')
+);
+
+// --- Section 2: Container parser (Phase 2 PR 1+2+3) ----------------------
+addExternal(
+  'container-normaliser',
+  'Container normaliser (F1โ€“F5)',
+  'pnpm',
+  ['--filter', '@docmd/parser', 'test']
+);
+
+// --- Section 3: Utils (Path / HTML escape) -------------------------------
+addExternal(
+  'utils',
+  'Utils (safePath, escHtml, attrEsc, jsonInject, scriptLiteral)',
+  'pnpm',
+  ['--filter', '@docmd/utils', 'test']
+);
+
+// --- Section 4: Security (Phase 1 CVE suite) ------------------------------
+addExternal(
+  'security',
+  'Security (Phase 1 CVE suite โ€” 88 assertions)',
+  'node',
+  ['tests/security.test.js']
+);
+
+// --- Section 5: Feature integration (legacy feature-integration.test.js) --------------
+addExternal(
+  'features',
+  'Feature integration (29 scenarios โ€” zero-config, i18n, versioning, navigation, code blocks, search, sitemap, etc.)',
+  'node',
+  ['tests/feature-integration.test.js']
+);
+
+// --- Section 6: OKF plugin ------------------------------------------------
+addExternal(
+  'okf-plugin',
+  'OKF plugin (Open Knowledge Format bundle generator)',
+  'pnpm',
+  ['--filter', '@docmd/plugin-okf', 'test']
+);
+
+// --- Section 7: LLMS plugin -----------------------------------------------
+// The LLMS plugin doesn't have a `pnpm test` script yet, so the runner
+// invokes the test runner directly. Default-locale + i18n opt-in tests
+// live at packages/plugins/llms/tests/llms.test.js.
+addExternal(
+  'llms-plugin',
+  'LLMS plugin (llms.txt / llms-full.txt / llms.json โ€” default-locale + i18n opt-in)',
+  'node',
+  ['--test', 'packages/plugins/llms/tests/llms.test.js']
+);
+
+// ---------------------------------------------------------------------------
+// Runner โ€” execute each entry, print TUI section, aggregate results.
+// ---------------------------------------------------------------------------
+
+let totalPassed = 0;
+let totalFailed = 0;
+const allFailures = [];
+const startTime = Date.now();
+
+console.log('');
+console.log(CYAN(BOLD('Categorised test suite')));
+console.log(DIM(`  ${testFiles.length} test file${testFiles.length === 1 ? '' : 's'} โ€ข ${new Date().toISOString().slice(0, 10)}`));
+console.log('');
+
+for (const { id, name, module } of testFiles) {
+  const sectionStart = Date.now();
+  console.log(CYAN(`โ”Œโ”€ ${name}`));
+
+  if (module.external) {
+    // Subprocess runner. Forward stdout, capture exit code.
+    const result = spawnSync(module.command, module.args, {
+      cwd: path.resolve(import.meta.dirname, '..'),
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8'
+    });
+    const out = (result.stdout || '') + (result.stderr || '');
+    const lines = out.split('\n');
+    // Show last 60 lines of subprocess output so the TUI stays
+    // readable but the developer can see which assertions ran.
+    const tail = lines.slice(-60).join('\n');
+    for (const line of tail.split('\n')) {
+      if (!line.trim()) continue;
+      console.log(CYAN('โ”‚') + '  ' + line);
+    }
+    if (result.status === 0) {
+      // Parse the assertion count. Two output formats are supported:
+      //   1. `tests/feature-integration.test.js` style: "X passed,
+      //      Y failed out of Z"
+      //   2. `node:test` TAP-style:    "pass N" / "fail N" (one per line)
+      //      The `node:test` runner prints lines like:
+      //        โ„น tests 60
+      //        โ„น pass 60
+      //        โ„น fail 0
+      // We try the brute-test pattern first, then the node:test pattern.
+      let passed = 0;
+      let failed = 0;
+      const bruteMatch = out.match(/(\d+)\s+passed,\s+(\d+)\s+failed/);
+      if (bruteMatch) {
+        passed = parseInt(bruteMatch[1], 10);
+        failed = parseInt(bruteMatch[2], 10);
+      } else {
+        const passLines = out.match(/pass\s+(\d+)/g) || [];
+        const failLines = out.match(/fail\s+(\d+)/g) || [];
+        for (const l of passLines) {
+          const v = parseInt(l.replace(/[^\d]/g, ''), 10);
+          if (!isNaN(v)) passed = Math.max(passed, v);
+        }
+        for (const l of failLines) {
+          const v = parseInt(l.replace(/[^\d]/g, ''), 10);
+          if (!isNaN(v)) failed = Math.max(failed, v);
+        }
+      }
+      totalPassed += passed;
+      totalFailed += failed;
+      const elapsed = Date.now() - sectionStart;
+      console.log(CYAN('โ”‚'));
+      console.log(`${CYAN('โ”‚')}  ${GREEN(BOLD('[ PASS ]'))}  ${passed} passed, ${failed} failed  ${DIM('(' + elapsed + 'ms)')}`);
+    } else {
+      totalFailed += 1;
+      allFailures.push({ name, output: out.slice(-2000) });
+      const elapsed = Date.now() - sectionStart;
+      console.log(CYAN('โ”‚'));
+      console.log(`${CYAN('โ”‚')}  ${RED(BOLD('[ FAIL ]'))}  exit code ${result.status}  ${DIM('(' + elapsed + 'ms)')}`);
+    }
+  } else {
+    // In-process runner. The test module's `test.run()` callback prints
+    // its own pass/fail per assertion; the module's `results` object
+    // reports the aggregate.
+    try {
+      await module.test.run();
+      const passed = module.results.passed;
+      const failed = module.results.failed;
+      const failures = module.results.failures;
+      totalPassed += passed;
+      totalFailed += failed;
+      for (const f of failures) allFailures.push({ name, output: f });
+      const elapsed = Date.now() - sectionStart;
+      console.log(CYAN('โ”‚'));
+      if (failed === 0) {
+        console.log(`${CYAN('โ”‚')}  ${GREEN(BOLD('[ PASS ]'))}  ${passed} passed, 0 failed  ${DIM('(' + elapsed + 'ms)')}`);
+      } else {
+        console.log(`${CYAN('โ”‚')}  ${RED(BOLD('[ FAIL ]'))}  ${passed} passed, ${failed} failed  ${DIM('(' + elapsed + 'ms)')}`);
+      }
+    } catch (e) {
+      totalFailed += 1;
+      allFailures.push({ name, output: e.message + '\n' + e.stack });
+      const elapsed = Date.now() - sectionStart;
+      console.log(CYAN('โ”‚'));
+      console.log(`${CYAN('โ”‚')}  ${RED(BOLD('[ FAIL ]'))}  threw: ${e.message}  ${DIM('(' + elapsed + 'ms)')}`);
+    }
+  }
+  console.log(CYAN('โ””' + 'โ”€'.repeat(50)));
+  console.log('');
+}
+
+const totalMs = Date.now() - startTime;
+console.log('');
+console.log(CYAN('โ”Œ' + 'โ”€'.repeat(55)));
+console.log(CYAN('โ”‚') + '  ' + CYAN(BOLD(`Test summary: ${totalPassed} passed, ${totalFailed} failed across ${testFiles.length} files`)));
+console.log(CYAN('โ”‚') + '  ' + DIM(`Total time: ${totalMs}ms`));
+if (allFailures.length > 0) {
+  console.log(CYAN('โ”‚'));
+  console.log(CYAN('โ”‚') + '  ' + RED('Failures:'));
+  for (const f of allFailures) {
+    console.log(CYAN('โ”‚') + '  ' + RED(`  - ${f.name}`));
+    if (f.output) {
+      const snippet = f.output.split('\n').slice(0, 8).join('\n');
+      console.log(CYAN('โ”‚') + '  ' + DIM(snippet));
+    }
+  }
+}
+console.log(CYAN('โ””' + 'โ”€'.repeat(55)));
+console.log('');
+
+process.exit(totalFailed > 0 ? 1 : 0);
\ No newline at end of file
diff --git a/tests/security.test.js b/tests/security.test.js
new file mode 100644
index 0000000..189a893
--- /dev/null
+++ b/tests/security.test.js
@@ -0,0 +1,664 @@
+#!/usr/bin/env node
+/**
+ * docmd Security Test Suite
+ * ==========================
+ * End-to-end tests for the Phase 0 security primitives:
+ *   - security.html = 'escape' (default) | 'allow' | 'strip'
+ *   - escape helpers (escHtml / attrEsc / jsonInject / scriptLiteral) integration
+ *   - safePath() path-traversal guard
+ *
+ * Run: node tests/security.test.js
+ */
+
+import { execSync, spawn, spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const DOCMD = path.resolve(import.meta.dirname, '../packages/core/dist/bin/docmd.js');
+const TEST_ROOT = '/tmp/docmd-brute-security';
+const PASS = 'โœ…';
+const FAIL = 'โŒ';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function setup(name) {
+  const dir = path.join(TEST_ROOT, name);
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function build(dir) {
+  // Use spawnSync so we can capture both stdout AND stderr on success too
+  // (execSync discards stderr on success). Plugins use console.error to
+  // surface validation warnings (e.g. S-4 analytics, S-5 PWA).
+  const r = spawnSync('node', [DOCMD, 'build'], {
+    cwd: dir,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  return {
+    ok: r.status === 0,
+    output: r.stdout || '',
+    stderr: r.stderr || ''
+  };
+}
+
+function writeFile(dir, filePath, content) {
+  const full = path.join(dir, filePath);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, content);
+}
+
+function readSite(dir, filePath) {
+  const full = path.join(dir, 'site', filePath);
+  if (!fs.existsSync(full)) return null;
+  return fs.readFileSync(full, 'utf8');
+}
+
+function assert(testName, condition, detail = '') {
+  if (condition) {
+    console.log(`  ${PASS} ${testName}`);
+    passed++;
+  } else {
+    console.log(`  ${FAIL} ${testName}${detail ? ': ' + detail : ''}`);
+    failed++;
+    failures.push(testName);
+  }
+}
+
+// โ”€โ”€โ”€ TEST S1: Default security.html = 'escape' blocks raw HTML โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+console.log('\n๐Ÿ”’ Test S1: Default html policy is escape (Phase 0.D)');
+{
+  const dir = setup('s1-default-escape');
+  writeFile(dir, 'docs/index.md', [
+    '---',
+    'title: Raw HTML Test',
+    '---',
+    '',
+    '# Heading',
+    '',
+    '<script>alert("xss")</script>',
+    '',
+    '<details><summary>Click</summary>Hidden</details>',
+    ''
+  ].join('\n'));
+  const r = build(dir);
+  assert('build succeeds', r.ok, r.output);
+  const html = readSite(dir, 'index.html');
+  assert('output exists', html !== null);
+  assert('default policy escapes the user canary', html && !html.includes('alert("xss")'));
+  assert('default policy escapes <details>', html && !html.includes('<details>'));
+  assert('escaped output shows <script>', html && html.includes('<script>'));
+}
+
+// โ”€โ”€โ”€ TEST S2: Explicit 'allow' policy passes raw HTML through โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+console.log('\n๐Ÿ”’ Test S2: security.html = "allow" passes raw HTML');
+{
+  const dir = setup('s2-allow');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({
+    title: 'Allow',
+    security: { html: 'allow' }
+  }));
+  writeFile(dir, 'docs/index.md', [
+    '# Heading',
+    '',
+    '<script>alert("xss")</script>',
+    ''
+  ].join('\n'));
+  const r = build(dir);
+  assert('build succeeds', r.ok, r.output);
+  const html = readSite(dir, 'index.html');
+  assert('allow policy keeps <script>', html && html.includes('<script>alert'));
+}
+
+// โ”€โ”€โ”€ TEST S3: Explicit 'strip' policy removes raw HTML entirely โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+console.log('\n๐Ÿ”’ Test S3: security.html = "strip" removes raw HTML');
+{
+  const dir = setup('s3-strip');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({
+    title: 'Strip',
+    security: { html: 'strip' }
+  }));
+  writeFile(dir, 'docs/index.md', [
+    '# Heading',
+    '',
+    'before',
+    '',
+    '<script>alert("xss")</script>',
+    '',
+    '<details><summary>x</summary>y</details>',
+    '',
+    'after'
+  ].join('\n'));
+  const r = build(dir);
+  assert('build succeeds', r.ok, r.output);
+  const html = readSite(dir, 'index.html');
+  assert('strip policy removes the user canary', html && !html.includes('alert("xss")'));
+  assert('strip policy removes <details>', html && !html.includes('<details>'));
+  assert('strip policy removes </details>', html && !html.includes('</details>'));
+  assert('strip policy keeps surrounding text', html && html.includes('before') && html.includes('after'));
+}
+
+// โ”€โ”€โ”€ TEST S4: Invalid policy value falls back to 'escape' โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+console.log('\n๐Ÿ”’ Test S4: Invalid policy value defaults to escape');
+{
+  const dir = setup('s4-invalid-policy');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({
+    title: 'Invalid',
+    security: { html: 'bogus' }
+  }));
+  writeFile(dir, 'docs/index.md', '# Hi\n\n<script>x</script>\n');
+  const r = build(dir);
+  assert('build succeeds with bogus policy', r.ok, r.output);
+  const html = readSite(dir, 'index.html');
+  assert('bogus value falls back to escape', html && !html.includes('<script>x'));
+}
+
+// โ”€โ”€โ”€ TEST S5: No security config still defaults to escape โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+console.log('\n๐Ÿ”’ Test S5: No security block at all defaults to escape');
+{
+  const dir = setup('s5-no-security');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'No Security' }));
+  writeFile(dir, 'docs/index.md', '# Hi\n\n<script>x</script>\n');
+  const r = build(dir);
+  assert('build succeeds with no security block', r.ok, r.output);
+  const html = readSite(dir, 'index.html');
+  assert('no security block falls back to escape', html && !html.includes('<script>x'));
+}
+
+// โ”€โ”€โ”€ TEST S6: Markdown text outside HTML is unaffected by the policy โ”€โ”€โ”€โ”€โ”€
+console.log('\n๐Ÿ”’ Test S6: Markdown rendering unaffected by HTML policy');
+{
+  const dir = setup('s6-markdown-unaffected');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({
+    title: 'Markdown',
+    security: { html: 'strip' }
+  }));
+  writeFile(dir, 'docs/index.md', [
+    '# Title',
+    '',
+    'Paragraph with **bold** and *italic*.',
+    '',
+    '- list item one',
+    '- list item two',
+    '',
+    '`inline code` and a [link](https://example.com).'
+  ].join('\n'));
+  const r = build(dir);
+  assert('build succeeds', r.ok, r.output);
+  const html = readSite(dir, 'index.html');
+  assert('heading renders as <h1>', html && html.includes('<h1'));
+  assert('bold renders as <strong>', html && html.includes('<strong>'));
+  assert('italic renders as <em>', html && html.includes('<em>'));
+  assert('link renders as <a href', html && html.includes('href="https://example.com"'));
+  assert('inline code renders as <code>', html && html.includes('<code>'));
+}
+
+// โ”€โ”€โ”€ TEST S7: OpenAPI plugin rejects spec path that escapes project root (S-2) โ”€โ”€
+console.log('\n๐Ÿ”’ Test S7: OpenAPI plugin safePath enforcement (Phase 1.A, S-2)');
+{
+  // Place a canary file outside the project
+  const canaryDir = '/tmp/docmd-openapi-canary';
+  fs.mkdirSync(canaryDir, { recursive: true });
+  const canaryPath = path.join(canaryDir, 'canary-spec.json');
+  fs.writeFileSync(canaryPath, JSON.stringify({
+    openapi: '3.0.0',
+    info: { title: 'CANARY-PATH-TRAVERSAL-PROOF', version: '1.0.0' },
+    paths: { '/canary': { get: { summary: 'Path traversal confirmed' } } }
+  }));
+
+  const dir = setup('s7-openapi-traversal');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({
+    title: 'OA PoC',
+    plugins: { openapi: {} }
+  }));
+  writeFile(dir, 'docs/poc.md', [
+    '# PoC',
+    '',
+    '```openapi',
+    canaryPath,
+    '```',
+    ''
+  ].join('\n'));
+  const r = build(dir);
+  assert('build succeeds', r.ok, r.output);
+  const html = readSite(dir, 'poc/index.html');
+  assert('canary title NOT in output', html && !html.includes('CANARY-PATH-TRAVERSAL-PROOF'));
+  assert('canary summary NOT in output', html && !html.includes('Path traversal confirmed'));
+  assert('error message shown instead', html && html.includes('oa-error'));
+  assert('error mentions path escape', html && /escapes project root/i.test(html));
+}
+
+// โ”€โ”€โ”€ TEST S8: OpenAPI plugin accepts in-project spec โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+console.log('\n๐Ÿ”’ Test S8: OpenAPI plugin accepts in-project spec (regression)');
+{
+  const dir = setup('s8-openapi-allowed');
+  // Note: the plugin computes srcDir from process.cwd() (pre-existing quirk:
+  // markdownSetup reads options.config.src, but the plugin options object is
+  // config.plugins.openapi which has no .config field). Spec must live at
+  // project root for the regression test.
+  writeFile(dir, 'specs-ok.json', JSON.stringify({
+    openapi: '3.0.0',
+    info: { title: 'OK-Spec', version: '1.0.0' },
+    paths: { '/ok': { get: { summary: 'Allowed' } } }
+  }));
+  writeFile(dir, 'docmd.config.json', JSON.stringify({
+    title: 'OA OK',
+    plugins: { openapi: {} }
+  }));
+  writeFile(dir, 'docs/poc.md', [
+    '# PoC',
+    '',
+    '```openapi',
+    './specs-ok.json',
+    '```',
+    ''
+  ].join('\n'));
+  const r = build(dir);
+  assert('build succeeds', r.ok, r.output);
+  const html = readSite(dir, 'poc/index.html');
+  assert('OK-Spec rendered', html && html.includes('OK-Spec'));
+  assert('Allowed summary rendered', html && html.includes('Allowed'));
+}
+
+// โ”€โ”€โ”€ TEST S9: Plugin loader rejects local-path that escapes project root (T-S8) โ”€
+console.log('\n๐Ÿ”’ Test S9: Plugin loader rejects local-path escape (Phase 1.A, T-S8)');
+{
+  // Place a malicious plugin OUTSIDE the project root
+  const evilDir = '/tmp/docmd-evil-plugin';
+  fs.mkdirSync(path.join(evilDir, 'evil'), { recursive: true });
+  fs.writeFileSync(path.join(evilDir, 'evil', 'package.json'), JSON.stringify({
+    name: 'evil', version: '1.0.0', main: 'index.js'
+  }));
+  fs.writeFileSync(path.join(evilDir, 'evil', 'index.js'), [
+    'export default {',
+    '  plugin: { name: "evil", version: "1.0.0", capabilities: [] },',
+    '  onConfigResolved: async (config) => { config.title = "PWNED-VIA-PATH-ESCAPE"; }',
+    '};'
+  ].join('\n'));
+
+  const dir = setup('s9-plugin-path-escape');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({
+    title: 'Legit Title',
+    plugins: { '../evil': {} }  // Tries to escape via ../
+  }));
+  writeFile(dir, 'docs/index.md', '# Hi\n');
+  // Phase 3 PR 3.A (F6) made missing plugins a hard build failure rather
+  // than a silent warning. The security property โ€” evil plugin does NOT
+  // execute โ€” holds in BOTH cases:
+  //   - silent skip: build succeeds with original title
+  //   - hard fail:   build exits 1, no HTML written, PWNED title
+  //                  never appears anywhere
+  // Assert the property, not the implementation detail.
+  const r = build(dir, true /* expectFail is OK โ€” security property is what we test */);
+  const html = readSite(dir, 'index.html');
+  const titleNotOverwritten = !html || !html.includes('PWNED-VIA-PATH-ESCAPE');
+  assert('evil plugin did not execute', titleNotOverwritten);
+  // The title-original assertion holds in BOTH outcomes:
+  //   - silent skip: html exists and contains "Legit Title"
+  //   - hard fail:   html is null, original title is vacuously "preserved"
+  //                              (the build did not complete with the
+  //                              PWNED title; the config title was never
+  //                              overwritten by the plugin's onConfigResolved)
+  const titlePreserved = !html || html.includes('Legit Title');
+  assert('original title preserved (or build failed loudly)', titlePreserved);
+}
+
+// โ”€โ”€โ”€ TEST S10: MCP read_doc rejects path traversal (Phase 1.A, S-3) โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+console.log('\n๐Ÿ”’ Test S10: MCP read_doc rejects path traversal (Phase 1.A, S-3)');
+
+// Spawn the MCP server as a subprocess and exchange JSON-RPC messages over stdio.
+function callMcp(cwd, messages) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('node', [DOCMD, 'mcp'], { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    const responses = new Map();
+    let stdoutBuf = '';
+    let stderrBuf = '';
+
+    proc.stdout.on('data', (chunk) => {
+      stdoutBuf += chunk.toString();
+      const lines = stdoutBuf.split('\n');
+      stdoutBuf = lines.pop();
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          const msg = JSON.parse(line);
+          if (msg.id != null) responses.set(msg.id, msg);
+        } catch { /* non-JSON line, skip */ }
+      }
+    });
+    proc.stderr.on('data', (chunk) => { stderrBuf += chunk.toString(); });
+    proc.on('error', reject);
+
+    let i = 0;
+    function sendNext() {
+      if (i >= messages.length) {
+        proc.stdin.end();
+        setTimeout(() => {
+          proc.kill('SIGTERM');
+          resolve({ responses, stderr: stderrBuf });
+        }, 800);
+        return;
+      }
+      proc.stdin.write(JSON.stringify(messages[i]) + '\n');
+      i++;
+      setTimeout(sendNext, 100);
+    }
+    sendNext();
+  });
+}
+
+const cases = [
+  { id: 2, route: '/etc/passwd',                 expectError: /Absolute paths are not allowed/ },
+  { id: 3, route: '/tmp/should-not-exist.txt',   expectError: /Absolute paths are not allowed/ },
+  { id: 4, route: '../../../etc/passwd',         expectError: /escapes project root/ },
+  { id: 5, route: 'docs/index.md',               expectValid: '# MCP test content' }
+];
+
+(async () => {
+  const dir = setup('s10-mcp-read-doc');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'MCP test' }));
+  writeFile(dir, 'docs/index.md', '# MCP test content\n');
+
+  const messages = [
+    { jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 't', version: '1' } } },
+    ...cases.map(c => ({
+      jsonrpc: '2.0', id: c.id, method: 'tools/call',
+      params: { name: 'read_doc', arguments: { route: c.route } }
+    }))
+  ];
+
+  const { responses } = await callMcp(dir, messages);
+
+  assert('initialize response received', responses.has(1));
+
+  for (const c of cases) {
+    const r = responses.get(c.id);
+    const text = r?.result?.content?.[0]?.text || r?.error?.message || '';
+    if (c.expectError) {
+      assert(`read_doc rejects "${c.route}"`, c.expectError.test(text), `got: ${text.slice(0, 80)}`);
+    }
+    if (c.expectValid) {
+      assert(`read_doc accepts "${c.route}"`, text.includes(c.expectValid), `got: ${text.slice(0, 80)}`);
+    }
+  }
+
+  // Final summary run after async S10
+  console.log('\n' + 'โ•'.repeat(50));
+  console.log(`  ${passed} passed, ${failed} failed out of ${passed + failed} assertions`);
+  if (failures.length > 0) {
+    console.log(`\n  Failures:`);
+    failures.forEach(f => console.log(`    ${FAIL} ${f}`));
+  }
+  console.log('โ•'.repeat(50) + '\n');
+  process.exit(failed > 0 ? 1 : 0);
+})();
+
+// โ”€โ”€โ”€ TEST S11: ws-origin-guard unit checks (Phase 1.D, N-S1) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+console.log('\n๐Ÿ”’ Test S11: ws-origin-guard unit checks (Phase 1.D, N-S1)');
+(async () => {
+  // Dynamically import the compiled helper from @docmd/core.
+  const helperPath = path.resolve(import.meta.dirname, '../packages/core/dist/utils/ws-origin-guard.js');
+  const { createOriginVerify } = await import(helperPath);
+
+  const cases = [
+    { name: 'http://localhost:3000',         expectAllow: true  },
+    { name: 'http://127.0.0.1:3000',         expectAllow: true  },
+    { name: 'http://[::1]:3000',            expectAllow: true  },
+    { name: 'http://localhost:9999',         expectAllow: true  },  // port-agnostic
+    { name: 'http://192.168.1.10:3000',     expectAllow: false },  // LAN IP, not in default allowlist
+    { name: 'http://evil.com',              expectAllow: false },
+    { name: 'http://evil.com:3000',         expectAllow: false },
+    { name: null,                           expectAllow: false },  // no Origin header
+    { name: '',                             expectAllow: false },  // empty Origin
+    { name: 'not a url',                    expectAllow: false }
+  ];
+
+  const guard = createOriginVerify();
+  for (const c of cases) {
+    const result = await new Promise((resolve) => {
+      guard(
+        { origin: c.name || undefined, req: { headers: {} }, secure: false },
+        (allowed, code, message) => resolve({ allowed, code, message })
+      );
+    });
+    const label = c.name === null ? 'null' : (c.name === '' ? '(empty)' : c.name);
+    assert(
+      `origin ${label} -> ${c.expectAllow ? 'allow' : 'reject'}`,
+      result.allowed === c.expectAllow,
+      `got: ${result.allowed} (code=${result.code || 'n/a'})`
+    );
+  }
+
+  // Extra-host allowlist scenario: LAN dev with --host=0.0.0.0
+  const lanGuard = createOriginVerify(['192.168.1.10']);
+  const lanCase = await new Promise((resolve) => {
+    lanGuard(
+      { origin: 'http://192.168.1.10:3000', req: { headers: {} }, secure: false },
+      (allowed) => resolve(allowed)
+    );
+  });
+  assert('LAN allowlist adds 192.168.1.10', lanCase === true);
+
+  const lanReject = await new Promise((resolve) => {
+    lanGuard(
+      { origin: 'http://10.0.0.1:3000', req: { headers: {} }, secure: false },
+      (allowed) => resolve(allowed)
+    );
+  });
+  assert('LAN allowlist still rejects 10.0.0.1', lanReject === false);
+})();
+
+// โ”€โ”€โ”€ TEST S12: init makes NO network calls and writes no SKILL.md (Phase 1.D revised, T-S5) โ”€
+console.log('\n๐Ÿ”’ Test S12: init makes no network calls (Phase 1.D revised, T-S5)');
+(async () => {
+  // Snapshot network calls by intercepting global fetch.
+  const dir = setup('s12-init-no-network');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({ title: 'Init No Net' }));
+
+  const originalFetch = globalThis.fetch;
+  let fetchCalls = 0;
+  globalThis.fetch = (...args) => {
+    fetchCalls++;
+    return originalFetch(...args);
+  };
+
+  try {
+    // Run init in-process via the compiled CLI.
+    // T-S5 revised (0.8.10): docmd-skills is now an npm package; init
+    // no longer writes a local SKILL.md (the full skill set is installed
+    // separately via `npx docmd-skills`). The security property under
+    // test is the absolute zero-network invariant โ€” init must never
+    // touch the network, regardless of what files it does or doesn't write.
+    const { initProject } = await import(path.resolve(import.meta.dirname, '../packages/core/dist/commands/init.js'));
+    process.chdir(dir);
+    await initProject({ force: true });
+    assert('init makes zero network calls', fetchCalls === 0, `fetchCalls=${fetchCalls}`);
+    // The local SKILL.md is no longer scaffolded. Users get the full
+    // skill set by running `npx docmd-skills <dir>` separately. The dim
+    // hint in init points them to that command, but the file is not
+    // touched at init time.
+    assert('Use `npx docmd-skills` to install SKILL.md for docmd', !fs.existsSync(path.join(dir, 'SKILL.md')));
+    // The core scaffold (config, index.md, skills.md) is still written.
+    assert('docs/index.md was written', fs.existsSync(path.join(dir, 'docs/index.md')));
+    assert('docs/skills.md was written', fs.existsSync(path.join(dir, 'docs/skills.md')));
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+})();
+
+// โ”€โ”€โ”€ TEST S13: SEO plugin escapes og:/twitter: meta tag values (Phase 1.B, T-S3) โ”€โ”€
+console.log('\n๐Ÿ”’ Test S13: SEO plugin escapes meta tag values (Phase 1.B, T-S3)');
+{
+  const dir = setup('s13-seo-escape');
+  writeFile(dir, 'docmd.config.json', JSON.stringify({
+    title: 'Site Title',
+    url: 'https://example.com'
+  }));
+  writeFile(dir, 'docs/index.md', [
+    '---',
+    'title: <img src=x onerror=alert(1)>',
+    'description: <script>alert(1)</script>',
+    '---',
+    '',
+    '# Hi'
+  ].join('\n'));
+  const r = build(dir);
+  assert('build succeeds', r.ok, r.output);
+  const html = readSite(dir, 'index.html');
+  assert('output exists', html !== null);
+  // The frontmatter title is the malicious payload; the site title is benign.
+  // We assert that the malicious payload is HTML-escaped in the meta tags.
+  assert('og:title escapes the frontmatter <img>', html && /<meta property="og:title" content="<img src=x onerror=alert\(1\)>/.test(html));
+  assert('twitter:title escapes the frontmatter <img>', html && /<meta name="twitter:title" content="<img src=x onerror=alert\(1\)>/.test(html));
+  assert('description meta is HTML-escaped', html && /<meta name="description" content="<script>alert\(1\)<\/script>/.test(html));
+  assert('no live <script>alert in built HTML', html && !/<script>alert/.test(html));
+}
+
+// โ”€โ”€โ”€ TEST S14: link scheme validation rejects javascript:/data: in built HTML (Phase 1.B, T-S4 defense in depth) โ”€
+console.log('\n๐Ÿ”’ Test S14: link scheme validation rejects javascript:/data: (Phase 1.B, T-S4)');
+{
+  const dir = setup('s14-link-schemes');
+  writeFile(dir, 'docs/index.md', [
+    '# Link Test',
+    '',
+    '[javascript](javascript:alert(1))',
+    '',
+    '[data](data:text/html,<script>alert(1)</script>)',
+    '',
+    '[vbscript](vbscript:msgbox(1))',
+    '',
+    '[safe](https://example.com)',
+    '',
+    '[internal](docs/other.md)'
+  ].join('\n'));
+  const r = build(dir);
+  assert('build succeeds', r.ok, r.output);
+  const html = readSite(dir, 'index.html');
+  // Markdown-it 14 already rejects dangerous schemes at the parser layer; the
+  // defense-in-depth check in the link_open override is the second line. Either
+  // layer makes the output safe. We assert: no live dangerous href anywhere.
+  assert('no javascript: href in HTML', html && !/href="javascript:/i.test(html));
+  assert('no data: href in HTML', html && !/href="data:/i.test(html));
+  assert('no vbscript: href in HTML', html && !/href="vbscript:/i.test(html));
+  assert('safe https link still works', html && /href="https:\/\/example\.com/.test(html));
+}
+
+// โ”€โ”€โ”€ TEST S15: sanitizeHeadInjection helper unit checks (Phase 1.B T-S7, helper-only) โ”€
+console.log('\n๐Ÿ”’ Test S15: sanitizeHeadInjection helper (Phase 1.B T-S7 helper-only)');
+(async () => {
+  // Phase 1.B T-S7 was revised: the framework no longer auto-sanitises plugin
+  // output (would break legitimate analytics <script> tags). The
+  // sanitizeHeadInjection helper is still exported from @docmd/utils so
+  // individual plugins can sanitise their own output if they want. This
+  // scenario unit-checks the helper itself.
+  const helperPath = path.resolve(import.meta.dirname, '../packages/utils/dist/html-escape.js');
+  const { sanitizeHeadInjection } = await import(helperPath);
+
+  const cases = [
+    { name: 'strips <script>...</script>', in: '<script>alert(1)</script>', out: '' },
+    { name: 'strips <style>...</style>', in: '<style>body{color:red}</style>', out: '' },
+    { name: 'strips <script src=...></script> (self-closing)', in: '<script async src="x.js"></script>', out: '' },
+    { name: 'neutralises javascript: href', in: '<a href="javascript:alert(1)">x</a>', out: '<a href="#">x</a>' },
+    { name: 'neutralises vbscript: href', in: '<a href="vbscript:msgbox(1)">x</a>', out: '<a href="#">x</a>' },
+    { name: 'leaves safe <a href> alone', in: '<a href="https://example.com">x</a>', out: '<a href="https://example.com">x</a>' },
+    { name: 'leaves safe <link rel=stylesheet> alone', in: '<link rel="stylesheet" href="x.css">', out: '<link rel="stylesheet" href="x.css">' },
+    { name: 'handles mixed content', in: '<p>safe</p><script>x</script>', out: '<p>safe</p>' }
+  ];
+
+  for (const c of cases) {
+    const actual = sanitizeHeadInjection(c.in);
+    assert(
+      c.name,
+      actual === c.out,
+      `input=${JSON.stringify(c.in)} actual=${JSON.stringify(actual)} expected=${JSON.stringify(c.out)}`
+    );
+  }
+})();
+
+// โ”€โ”€โ”€ TEST S16: Analytics plugin rejects invalid measurementId / trackingId (Phase 1.C, S-4) โ”€
+console.log('\n๐Ÿ”’ Test S16: Analytics plugin format-validates IDs (Phase 1.C, S-4)');
+{
+  // Case 1: invalid GA4 id with XSS payload
+  {
+    const dir = setup('s16-analytics-bad-ga4');
+    writeFile(dir, 'docmd.config.json', JSON.stringify({
+      title: 'Bad GA4',
+      plugins: { analytics: { googleV4: { measurementId: 'G-FAKE\'; alert(1); //' } } }
+    }));
+    writeFile(dir, 'docs/index.md', '# Hi\n');
+    const r = build(dir);
+    assert('build succeeds with invalid GA4 id', r.ok, r.stderr || r.output);
+    const html = readSite(dir, 'index.html');
+    assert('no alert(1) in built HTML', html && !/alert\(1\)/.test(html));
+    assert('no googletagmanager script injected', html && !/googletagmanager\.com/.test(html));
+    assert('error log mentions invalid id', /Invalid googleV4/.test(r.stderr || r.output));
+  }
+
+  // Case 2: valid GA4 id should still work
+  {
+    const dir = setup('s16-analytics-good-ga4');
+    writeFile(dir, 'docmd.config.json', JSON.stringify({
+      title: 'Good GA4',
+      plugins: { analytics: { googleV4: { measurementId: 'G-ABC123XYZ' } } }
+    }));
+    writeFile(dir, 'docs/index.md', '# Hi\n');
+    const r = build(dir);
+    assert('build succeeds with valid GA4 id', r.ok, r.stderr || r.output);
+    const html = readSite(dir, 'index.html');
+    assert('googletagmanager script IS injected', html && /googletagmanager\.com/.test(html));
+    assert('valid id appears as JSON-quoted string', html && /gtag\('config', "G-ABC123XYZ"\)/.test(html));
+  }
+
+  // Case 3: invalid UA id
+  {
+    const dir = setup('s16-analytics-bad-ua');
+    writeFile(dir, 'docmd.config.json', JSON.stringify({
+      title: 'Bad UA',
+      plugins: { analytics: { googleUA: { trackingId: 'UA-INJECTED\'); alert(1); (' } } }
+    }));
+    writeFile(dir, 'docs/index.md', '# Hi\n');
+    const r = build(dir);
+    assert('build succeeds with invalid UA id', r.ok, r.stderr || r.output);
+    const html = readSite(dir, 'index.html');
+    assert('no UA injection', html && !/google-analytics\.com\/analytics\.js/.test(html) || !/attacker/.test(html));
+    assert('error log mentions invalid UA', /Invalid googleUA/.test(r.stderr || r.output));
+  }
+}
+
+// โ”€โ”€โ”€ TEST S17: PWA plugin validates themeColor (Phase 1.C, S-5) โ”€
+console.log('\n๐Ÿ”’ Test S17: PWA plugin validates themeColor (Phase 1.C, S-5)');
+{
+  // Case 1: valid hex color works
+  {
+    const dir = setup('s17-pwa-valid-color');
+    writeFile(dir, 'docmd.config.json', JSON.stringify({
+      title: 'PWA valid',
+      plugins: { pwa: { themeColor: '#ff00aa' } }
+    }));
+    writeFile(dir, 'docs/index.md', '# Hi\n');
+    const r = build(dir);
+    assert('build succeeds', r.ok, r.stderr || r.output);
+    const html = readSite(dir, 'index.html');
+    assert('valid theme color preserved', html && /<meta name="theme-color" content="#ff00aa">/.test(html));
+  }
+
+  // Case 2: invalid themeColor (XSS payload) is rejected
+  {
+    const dir = setup('s17-pwa-xss-color');
+    writeFile(dir, 'docmd.config.json', JSON.stringify({
+      title: 'PWA XSS',
+      plugins: { pwa: { themeColor: '"><script>alert(1)</script>' } }
+    }));
+    writeFile(dir, 'docs/index.md', '# Hi\n');
+    const r = build(dir);
+    assert('build succeeds with invalid themeColor', r.ok, r.stderr || r.output);
+    const html = readSite(dir, 'index.html');
+    assert('no live script from themeColor XSS', html && !/<script>alert\(1\)<\/script>/.test(html));
+    assert('error log mentions invalid themeColor', /Invalid themeColor/.test(r.stderr || r.output));
+    assert('default theme color used as fallback', html && /<meta name="theme-color" content="#1e293b">/.test(html));
+  }
+}
\ No newline at end of file
diff --git a/tests/shared.js b/tests/shared.js
new file mode 100644
index 0000000..c5c718b
--- /dev/null
+++ b/tests/shared.js
@@ -0,0 +1,139 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * Shared test helpers โ€” extracted from `tests/feature-integration.test.js` so the
+ * categorised tests under `tests/` can share a single source of truth
+ * for the project-fixture utilities (setup, writeFile, build,
+ * readSite, exitCodeOf, assert).
+ *
+ * Each test file in `tests/` calls `runTestFile({ name, run })` from
+ * the runner โ€” the runner owns the pass/fail counter, the TUI section
+ * output, and the per-file result aggregation. This file owns ONLY
+ * the stateless helpers.
+ *
+ * Pattern:
+ *   import { setup, writeFile, assert, build, readSite, exitCodeOf,
+ *           runTestFile, DOCMD } from '../shared.js';
+ *
+ *   runTestFile({
+ *     name: 'Exit-code contract',
+ *     emoji: '๐Ÿšฆ',
+ *     run: ({ assert, setup, writeFile, exitCodeOf }) => {
+ *       // ... assertions ...
+ *     }
+ *   });
+ * --------------------------------------------------------------------
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DOCMD = path.resolve(
+  import.meta.dirname,
+  '..',
+  'packages/core/dist/bin/docmd.js'
+);
+
+export const TEST_ROOT = '/tmp/docmd-brute-tests';
+export const PASS = 'โœ…';
+export const FAIL = 'โŒ';
+
+/**
+ * Create an empty test directory under TEST_ROOT and return its path.
+ * The directory is wiped clean on every call (no test-pollution).
+ */
+export function setup(name) {
+  const dir = path.join(TEST_ROOT, name);
+  fs.rmSync(dir, { recursive: true, force: true });
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Run `node ${DOCMD} build` in `dir`. Returns `{ ok, output }` where
+ * `ok` is true on exit 0 and `output` is the captured stdout/stderr.
+ * Set `expectFail = true` to invert the meaning of `ok` (the caller
+ * is testing a documented failure path).
+ */
+export function build(dir, expectFail = false) {
+  try {
+    const out = execSync(`node ${DOCMD} build`, {
+      cwd: dir,
+      stdio: 'pipe',
+      encoding: 'utf8'
+    });
+    if (expectFail) return { ok: false, output: out };
+    return { ok: true, output: out };
+  } catch (e) {
+    if (expectFail) return { ok: true, output: e.stderr || e.stdout || '' };
+    return { ok: false, output: e.stderr || e.stdout || '' };
+  }
+}
+
+/**
+ * Run a command in `dir` and return its numeric exit code.
+ * 0 = success, 1+ = documented failure, -1 = killed by signal.
+ */
+export function exitCodeOf(cmd, cwd) {
+  try {
+    execSync(cmd, { cwd, stdio: 'pipe' });
+    return 0;
+  } catch (e) {
+    return e.status == null ? -1 : e.status;
+  }
+}
+
+/**
+ * Write `content` to `<dir>/<filePath>`. Parent directories are
+ * created automatically.
+ */
+export function writeFile(dir, filePath, content) {
+  const full = path.join(dir, filePath);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, content);
+}
+
+/**
+ * Read `<dir>/site/<filePath>`. Returns `null` if the file does
+ * not exist (test fixtures use this to assert "build did not
+ * produce output X").
+ */
+export function readSite(dir, filePath) {
+  const full = path.join(dir, 'site', filePath);
+  if (!fs.existsSync(full)) return null;
+  return fs.readFileSync(full, 'utf8');
+}
+
+/**
+ * `true` if `<dir>/site/<filePath>` exists. Convenience wrapper
+ * for the common "did the build produce this asset?" check.
+ */
+export function siteExists(dir, filePath) {
+  return fs.existsSync(path.join(dir, 'site', filePath));
+}
+
+/**
+ * Run a test file's `run` callback inside a tracked TUI section.
+ * The runner reads the per-file results and aggregates them into
+ * the global pass/fail counts.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.name    โ€” section title (e.g. "Exit-code contract")
+ * @param {string}   opts.emoji   โ€” single emoji (e.g. "๐Ÿšฆ")
+ * @param {Function} opts.run     โ€” `({ assert }) => void | Promise<void>`
+ *                                 Receives the runner's assert helper so
+ *                                 the test's pass/fail count feeds into
+ *                                 the global counter.
+ */
+export function runTestFile(opts) {
+  if (typeof opts !== 'object' || !opts || typeof opts.run !== 'function') {
+    throw new TypeError('runTestFile({ name, emoji, run }) โ€” run must be a function');
+  }
+  return {
+    name: opts.name,
+    emoji: opts.emoji || '๐Ÿ“ฆ',
+    run: opts.run
+  };
+}
\ No newline at end of file
diff --git a/tools/bump.js b/tools/bump.js
new file mode 100644
index 0000000..8d90b0e
--- /dev/null
+++ b/tools/bump.js
@@ -0,0 +1,103 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const newVersion = process.argv[2];
+
+if (!newVersion) {
+  console.error("Usage: node tools/bump-version.js <new-version>");
+  process.exit(1);
+}
+
+const root = process.cwd();
+const packagesDir = path.join(root, "packages");
+
+function updateVersion(pkgPath) {
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  pkg.version = newVersion;
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+  console.log(`Updated: ${pkg.name} โ†’ ${newVersion}`);
+}
+
+function updateSourceVersion(pkgDir) {
+  const indexPath = path.join(pkgDir, "src", "index.ts");
+  if (fs.existsSync(indexPath)) {
+    let content = fs.readFileSync(indexPath, "utf8");
+    const versionRegex = /version:\s*(['"])(.*?)(['"])/g;
+    // Update any file in src/index.ts that has a version property
+    if (versionRegex.test(content)) {
+      content = content.replace(versionRegex, `version: $1${newVersion}$3`);
+      fs.writeFileSync(indexPath, content);
+      console.log(`Updated Source Version: ${path.basename(pkgDir)} โ†’ ${newVersion}`);
+    }
+  }
+}
+
+function updateCargoVersion(pkgDir) {
+  const cargoPath = path.join(pkgDir, "native", "Cargo.toml");
+  if (fs.existsSync(cargoPath)) {
+    let content = fs.readFileSync(cargoPath, "utf8");
+    const versionRegex = /version\s*=\s*(['"])(.*?)(['"])/;
+    if (versionRegex.test(content)) {
+      content = content.replace(versionRegex, `version     = "${newVersion}"`);
+      fs.writeFileSync(cargoPath, content);
+      console.log(`Updated Cargo Version: ${path.basename(pkgDir)} โ†’ ${newVersion}`);
+    }
+  }
+}
+
+function updateDockerVersion() {
+  // Update Docker workflow if it exists
+  const dockerWorkflowPath = path.join(root, ".github", "workflows", "docker-publish.yml");
+  if (fs.existsSync(dockerWorkflowPath)) {
+    let content = fs.readFileSync(dockerWorkflowPath, "utf8");
+    // Update any hardcoded version references in comments or examples
+    // This is mainly for documentation purposes in the workflow
+    const versionCommentRegex = /# Version:\s*v?[\d.]+/g;
+    if (versionCommentRegex.test(content)) {
+      content = content.replace(versionCommentRegex, `# Version: v${newVersion}`);
+      fs.writeFileSync(dockerWorkflowPath, content);
+      console.log(`Updated Docker Workflow Version โ†’ ${newVersion}`);
+    }
+  }
+}
+
+// 1๏ธโƒฃ Update root
+updateVersion(path.join(root, "package.json"));
+
+// 2๏ธโƒฃ Update Docker version references
+updateDockerVersion();
+
+// 2๏ธโƒฃ Recursively update all packages
+function walk(dir) {
+  for (const entry of fs.readdirSync(dir)) {
+    if (['node_modules', 'dist', '.build'].includes(entry)) continue;
+
+    const full = path.join(dir, entry);
+
+    if (fs.existsSync(path.join(full, "package.json"))) {
+      updateVersion(path.join(full, "package.json"));
+      updateSourceVersion(full);
+      updateCargoVersion(full);
+    } else if (fs.statSync(full).isDirectory()) {
+      walk(full);
+    }
+  }
+}
+
+walk(packagesDir);
+
+console.log("Version bump complete.");
\ No newline at end of file
diff --git a/tools/docker-prebuild.sh b/tools/docker-prebuild.sh
new file mode 100755
index 0000000..6edc551
--- /dev/null
+++ b/tools/docker-prebuild.sh
@@ -0,0 +1,32 @@
+#!/bin/sh
+# Stub out build scripts that cannot run inside Docker before pnpm -r run build.
+# This file is only executed during Docker image builds.
+
+# engine-rust-binaries: requires the Rust toolchain (cargo) which is not
+# installed in the builder image. The pre-built .node binaries are committed
+# to the repo and copied into the production image directly.
+RUST_BIN_PKG="packages/engines/rust-binaries/package.json"
+if [ -f "$RUST_BIN_PKG" ]; then
+  node -e "
+    const fs = require('fs');
+    const pkg = JSON.parse(fs.readFileSync('$RUST_BIN_PKG', 'utf8'));
+    pkg.scripts = pkg.scripts || {};
+    pkg.scripts.build = 'echo [docker] skipped rust-binaries build';
+    fs.writeFileSync('$RUST_BIN_PKG', JSON.stringify(pkg, null, 2));
+  "
+  echo "[docker-prebuild] Stubbed rust-binaries build script"
+fi
+
+# _playground: runs a full docmd site build โ€” a dev sandbox, not part of the
+# production image. Skip it to avoid unnecessary work and potential failures.
+PLAYGROUND_PKG="packages/_playground/package.json"
+if [ -f "$PLAYGROUND_PKG" ]; then
+  node -e "
+    const fs = require('fs');
+    const pkg = JSON.parse(fs.readFileSync('$PLAYGROUND_PKG', 'utf8'));
+    pkg.scripts = pkg.scripts || {};
+    pkg.scripts.build = 'echo [docker] skipped playground build';
+    fs.writeFileSync('$PLAYGROUND_PKG', JSON.stringify(pkg, null, 2));
+  "
+  echo "[docker-prebuild] Stubbed _playground build script"
+fi
\ No newline at end of file
diff --git a/tools/prep.js b/tools/prep.js
new file mode 100644
index 0000000..c211c54
--- /dev/null
+++ b/tools/prep.js
@@ -0,0 +1,526 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ *
+ * Release preparation pipeline. Runs the full dev suite in five
+ * clear category sections:
+ *
+ *   1. Setup       - stop running servers, wipe global binaries,
+ *                    clean the monorepo
+ *   2. Lint        - eslint over the entire repo, summarised
+ *   3. Build       - pnpm install + pnpm -r run build, so the
+ *                    test sections have dist files to run
+ *                    against (clean wipes dist, this rebuilds it)
+ *   4. Docker      - optional Docker availability check
+ *   5. Tests       - categorised test suite (tests/runner.js,
+ *                    365+ assertions covering Phase 1 security
+ *                    CVEs + Phase 2 container parser + Phase 3
+ *                    CLI contracts + OKF/LLMS plugin tests +
+ *                    Mega Integration Test for workspaces,
+ *                    i18n, versioning, and plugin combinations)
+ *                    followed by per-package unit tests
+ *                    (parser, utils, mermaid, okf) via
+ *                    `pnpm -r run test --if-present` so a local
+ *                    regression fails the release pipeline
+ *   6. Link        - optional global npm link
+ *
+ * Each step inside a section shows [WAIT] (dim) when it starts
+ * and [DONE] (green) when it finishes. No emojis.
+ *
+ * Default output is intentionally minimal: every step collapses to
+ * one line, and every count (passed tests, lint errors, package
+ * totals, Docker version, ...) accumulates into a single trailing
+ * Summary block at the end of the pipeline. A fully-green run prints
+ * a green `โ”Œโ”€ Summary` listing each section with its stat; a run
+ * with any failure replaces that block with a red `โ”Œโ”€ Issues` listing
+ * every failure with file:line detail.
+ *
+ * Pass --verbose (or --full) to stream the full test output as the
+ * suite runs โ€” useful when actively iterating on a test that just
+ * started failing and you want to see the assertion text inline.
+ *
+ * Run:  pnpm prep
+ *       pnpm prep --link            (skip tests, install globally)
+ *       pnpm prep --skip-tests      (skip both test suites)
+ *       pnpm prep --only=exit-codes (run a single test section)
+ *       pnpm prep --verbose         (stream full test output inline)
+ *       pnpm prep --full            (alias for --verbose)
+ * --------------------------------------------------------------------
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+
+const args = process.argv.slice(2);
+
+// --verbose / --full streams every step's raw output as it runs.
+// Default mode keeps the pipeline minimal: each step collapses to
+// one line and a final Issues section appears only if something failed.
+const verbose = args.includes('--verbose') || args.includes('--full');
+
+// Issue accumulator โ€” populated by every section so a single trailing
+// "Issues" block can show the operator everything that needs fixing.
+const issues = [];
+function addIssue(severity, section, message, details = []) {
+    issues.push({ severity, section, message, details });
+}
+
+// Stat accumulator โ€” every section contributes a one-line entry that
+// prints in the trailing Summary block. Lets the per-step line stay
+// minimal ("[ DONE ] 28s") while still surfacing the actual numbers
+// (passed counts, lint counts, etc.) at the end.
+const stats = [];
+function addStat(label, value, severity = 'ok') {
+    stats.push({ label, value, severity });
+}
+
+// โ”€โ”€ TUI design tokens (no emojis, only [WAIT] / [DONE] / [ FAIL ]) โ”€โ”€
+const C = {
+    reset:  '\x1b[0m',
+    bold:   '\x1b[1m',
+    dim:    '\x1b[2m',
+    blue:   '\x1b[34m',
+    cyan:   '\x1b[36m',
+    green:  '\x1b[32m',
+    yellow: '\x1b[33m',
+    red:    '\x1b[31m'
+};
+
+// โ”€โ”€ TUI primitives โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+// section() and footer() pair up to produce exactly one blank line
+// between groups: footer ends with \n, section starts without \n.
+function section(label, color) {
+    console.log(`${color}${C.bold}โ”Œโ”€ ${label}${C.reset}`);
+}
+
+function footer(color) {
+    console.log(`${color}โ””${'โ”€'.repeat(50)}${C.reset}`);
+}
+
+function startStep(label) {
+    // Print the [WAIT] sign and return a handle to update on completion.
+    const bar = `${C.cyan}โ”‚${C.reset}`;
+    const text = `${C.dim}${label}${C.reset}`;
+    process.stdout.write(`${bar}  ${text.padEnd(52)}${C.dim}[ WAIT ]${C.reset}\n`);
+    return { label, startMs: Date.now(), bar, text };
+}
+
+function finishStep(s, status, summary) {
+    // Rewrite the same line with [DONE] / [ WARN ] / [ FAIL ] + elapsed time.
+    // Default status is 'done' โ€” the common case.
+    const effectiveStatus = status || 'done';
+    const ms = Date.now() - s.startMs;
+    const t = ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+    const tag = effectiveStatus === 'done'
+        ? `${C.green}[ DONE ]${C.reset}`
+        : effectiveStatus === 'warn'
+            ? `${C.yellow}[ WARN ]${C.reset}`
+            : `${C.red}[ FAIL ]${C.reset}`;
+    const sumTxt = summary ? `  ${C.dim}${summary}${C.reset}` : '';
+    // Move cursor up 1 line, clear it, rewrite.
+    process.stdout.write('\x1b[1A\x1b[2K');
+    process.stdout.write(
+        `${s.bar}  ${s.text.padEnd(52)}${tag} ${C.dim}${t}${C.reset}${sumTxt}\n`
+    );
+}
+
+function run(cmd, opts = {}) {
+    // opts.silent   โ€” when true (default), suppress output unless cmd failed.
+    // opts.capture  โ€” return stdout/stderr as strings; never stream to the TUI.
+    //                 Used by collapsed-mode test steps so we can parse a
+    //                 summary line instead of dumping hundreds of test logs.
+    // The function never calls process.exit; callers inspect `result.ok`.
+    const silent  = opts.silent  !== false;
+    const capture = opts.capture === true;
+    try {
+        const out = execSync(cmd, {
+            stdio: capture
+                ? ['ignore', 'pipe', 'pipe']
+                : (silent ? 'ignore' : 'inherit'),
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return {
+            ok: true,
+            stdout: capture ? out.toString() : '',
+            stderr: '',
+            status: 0,
+        };
+    } catch (e) {
+        return {
+            ok: false,
+            stdout: capture ? (e.stdout ? e.stdout.toString() : '') : '',
+            stderr: capture ? (e.stderr ? e.stderr.toString() : '') : '',
+            status: e.status,
+        };
+    }
+}
+
+// โ”€โ”€ Step helpers โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+function deepWipe() {
+    const bins = ['docmd', 'docmd-live'];
+    for (const bin of bins) {
+        try {
+            const paths = execSync(`which -a ${bin}`, { stdio: 'pipe' })
+                .toString().split('\n').filter(Boolean);
+            for (const p of paths) {
+                try { if (fs.existsSync(p)) fs.unlinkSync(p); }
+                catch {
+                    try { execSync(`rm -f "${p}"`, { stdio: 'ignore' }); } catch { /* ignore */ }
+                }
+            }
+        } catch { /* ignore which failure */ }
+    }
+}
+
+function runLint() {
+    const s = startStep('Running eslint over monorepo');
+    // eslint exits non-zero on errors โ€” JSON is still on stdout. run()
+    // never exits the process, so we can collect the lint output cleanly.
+    const result = run('pnpm -s exec eslint . --format json', { capture: true });
+
+    let errors = 0, warnings = 0;
+    const details = [];
+    try {
+        const results = JSON.parse(result.stdout || '[]');
+        for (const file of results) {
+            for (const msg of file.messages || []) {
+                if (msg.severity === 2) errors++;
+                else if (msg.severity === 1) warnings++;
+                if (msg.severity >= 1) {
+                    const relPath = (file.filePath || '')
+                        .replace(process.cwd() + '/', '')
+                        .replace(/^.*\/docmd\//, '');
+                    details.push(`${relPath}:${msg.line} โ€” ${msg.message}`);
+                }
+            }
+        }
+    } catch (_) { /* malformed output */ }
+
+    const status = errors > 0 ? 'fail' : (warnings > 0 ? 'warn' : 'done');
+    finishStep(s, status);
+
+    const summary = `${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}`;
+    addStat('Lint', summary, errors > 0 ? 'fail' : (warnings > 0 ? 'warn' : 'ok'));
+
+    if (errors > 0) addIssue('error', 'Lint', `${errors} lint error(s)`, details);
+    else if (warnings > 0) addIssue('warning', 'Lint', `${warnings} lint warning(s)`, details);
+}
+
+// โ”€โ”€ Collapsed-mode test runner โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+// Captures test output, parses pass/fail counts and any failure
+// titles, then renders a one-line summary. Verbose mode bypasses
+// the capture and streams raw output as it arrives instead.
+function summariseTests(stdout) {
+    // tests/runner.js emits a single aggregate line at the end.
+    // Pattern: "Test summary: 367 passed, 0 failed across 9 files"
+    let m = stdout.match(/Test summary:\s+(\d+)\s+passed,\s+(\d+)\s+failed\s+across\s+(\d+)\s+files?/i);
+    if (m) {
+        return {
+            tests: parseInt(m[1]) + parseInt(m[2]),
+            pass:  parseInt(m[1]),
+            fail:  parseInt(m[2]),
+            units: parseInt(m[3]),
+            unitLabel: 'files',
+            failures: extractFailures(stdout),
+        };
+    }
+
+    // Per-package output (pnpm -r run test): each suite prints its own
+    // โ„น tests N / โ„น pass N / โ„น fail N block, so we sum them all up.
+    let tests = 0, pass = 0, fail = 0, pkgs = 0;
+    for (const t of stdout.matchAll(/โ„น\s+tests\s+(\d+)/g)) tests += parseInt(t[1]);
+    for (const p of stdout.matchAll(/โ„น\s+pass\s+(\d+)/g))  pass  += parseInt(p[1]);
+    for (const f of stdout.matchAll(/โ„น\s+fail\s+(\d+)/g))  fail  += parseInt(f[1]);
+    // Count distinct packages that reported a result. Look for the
+    // pnpm-recursive "Done" line which marks each package's end.
+    for (const _ of stdout.matchAll(/\bDone$/gm)) pkgs++;
+    // Fallback when no "Done" markers are present: count `โ„น tests` lines.
+    if (pkgs === 0) {
+        for (const _ of stdout.matchAll(/โ„น\s+tests\s+\d+/g)) pkgs++;
+    }
+    return {
+        tests, pass, fail,
+        units: pkgs,
+        unitLabel: pkgs === 1 ? 'package' : 'packages',
+        failures: extractFailures(stdout),
+    };
+}
+
+function extractFailures(stdout) {
+    // node:test prints "not ok N - <name>" lines on failure. Trim
+    // surrounding ANSI noise and keep the title only โ€” full diagnostics
+    // remain in --verbose output.
+    const out = [];
+    // Build the ANSI-stripping regex at runtime so the static linter
+    // doesn't flag the embedded ESC (\x1b) control character.
+    const ANSI_RE = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-9;]*m`, 'g');
+    for (const m of stdout.matchAll(/not ok \d+ - (.+)/g)) {
+        const t = m[1].replace(ANSI_RE, '').trim();
+        if (t) out.push(t);
+        if (out.length >= 20) break;
+    }
+    return out;
+}
+
+function runTestStep(label, cmd, statLabel = label) {
+    const s = startStep(label);
+
+    // Verbose mode: stream the raw output as before. The finish line
+    // rewrites with [DONE] / [FAIL] depending on the exit code.
+    if (verbose) {
+        const result = run(cmd, { silent: false });
+        if (result.ok) finishStep(s);
+        else {
+            finishStep(s, 'fail');
+            addIssue('error', label, 'test step failed', []);
+        }
+        addStat(statLabel, result.ok ? 'passed (see --verbose output for details)' : 'failed', result.ok ? 'ok' : 'fail');
+        return;
+    }
+
+    // Default (collapsed) mode: capture output, summarise, render one line.
+    const result = run(cmd, { capture: true });
+    const sum = summariseTests(result.stdout + result.stderr);
+
+    if (result.ok && sum.fail === 0 && sum.tests > 0) {
+        finishStep(s, 'done');
+        addStat(statLabel, `${sum.pass} passed across ${sum.units} ${sum.unitLabel}`, 'ok');
+    } else if (result.ok && sum.tests === 0) {
+        // No tests ran at all (e.g. --only matched nothing). Be honest
+        // about that rather than printing a misleading "0 passed".
+        finishStep(s, 'warn');
+        addStat(statLabel, 'no tests ran', 'warn');
+    } else {
+        const statValue = sum.fail > 0
+            ? `${sum.fail} of ${sum.tests} failed across ${sum.units} ${sum.unitLabel}`
+            : `command exited with status ${result.status}`;
+        finishStep(s, 'fail');
+        addStat(statLabel, statValue, 'fail');
+        addIssue('error', label,
+            sum.fail > 0 ? `${sum.fail} test failure(s)` : 'test command failed',
+            sum.failures);
+    }
+}
+
+// โ”€โ”€ Final Summary / Issues section โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+// Single trailing block. When nothing failed, it renders as a green
+// Summary listing every stat (one line per section). When issues were
+// collected, it flips to a red Issues block with the same group /
+// bullet layout used elsewhere in the TUI. Either way it lives in the
+// same slot at the end of the pipeline, so the operator always knows
+// where to look for the verdict.
+function printSummary() {
+    if (issues.length === 0) {
+        // Green Summary โ€” every stat in one tidy list. Pad the label
+        // column to the longest label so values align regardless of
+        // how many sections contributed.
+        section('Summary', C.green);
+        const pad = Math.max(...stats.map(s => s.label.length)) + 2;
+        for (const s of stats) {
+            const tag = s.severity === 'warn'
+                ? `${C.yellow}[ WARN ]${C.reset}`
+                : `${C.green}[ DONE ]${C.reset}`;
+            const label = `${s.label}`.padEnd(pad);
+            console.log(`${C.green}โ”‚${C.reset}  ${tag} ${C.bold}${label}${C.reset}${s.value}`);
+        }
+        footer(C.green);
+        return;
+    }
+
+    // Failure case: render the Issues block.
+    const errors   = issues.filter(i => i.severity === 'error').length;
+    const warnings = issues.filter(i => i.severity === 'warning').length;
+    const color    = errors > 0 ? C.red : C.yellow;
+    const head     = `Issues โ€” ${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'}`;
+    section(head, color);
+
+    // Group by section so two issues from the same source don't repeat
+    // the section header; the operator reads the section once and then
+    // scans the bullets.
+    const bySection = new Map();
+    for (const i of issues) {
+        if (!bySection.has(i.section)) bySection.set(i.section, []);
+        bySection.get(i.section).push(i);
+    }
+    for (const [name, items] of bySection) {
+        const tag = items.some(i => i.severity === 'error')
+            ? `${C.red}[ FAIL ]${C.reset}`
+            : `${C.yellow}[ WARN ]${C.reset}`;
+        console.log(`${color}โ”‚${C.reset}  ${tag} ${C.bold}${name}${C.reset}`);
+        for (const item of items) {
+            console.log(`${color}โ”‚${C.reset}    ${item.message}`);
+            const detailCap = 8;
+            for (const detail of item.details.slice(0, detailCap)) {
+                console.log(`${color}โ”‚${C.reset}      ${C.dim}${detail}${C.reset}`);
+            }
+            if (item.details.length > detailCap) {
+                console.log(`${color}โ”‚${C.reset}      ${C.dim}โ€ฆ ${item.details.length - detailCap} more (re-run with --verbose for full output)${C.reset}`);
+            }
+        }
+    }
+    footer(color);
+}
+
+function runDockerCheck() {
+    const s = startStep('Checking Docker availability');
+    let hasDocker = '';
+    try {
+        hasDocker = execSync('which docker 2>/dev/null', {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+    } catch { /* not installed */ }
+
+    if (!hasDocker && !process.env.DOCKER_HOST) {
+        finishStep(s, 'warn');
+        addStat('Docker', 'not installed โ€” skipped', 'warn');
+        return;
+    }
+    try {
+        const version = execSync('docker --version', { encoding: 'utf8', stdio: ['pipe', 'pipe'] }).trim();
+        finishStep(s, 'done');
+        addStat('Docker', version.replace('Docker version ', 'Docker '), 'ok');
+    } catch {
+        finishStep(s, 'warn');
+        addStat('Docker', 'binary not functional', 'warn');
+    }
+}
+
+// โ”€โ”€ Main pipeline โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
+
+// Header โ€” banner + "Maintenance Pipeline" subtitle. Inlined here
+// (rather than calling `node tools/status.js start:reset`) because
+// that helper opens a section frame which we don't want prep.js
+// to inherit. prep.js owns its own section boundaries.
+const LOGO = '\n'
+    + '    _                 _ \n'
+    + '  _| |___ ___ _____ _| |\n'
+    + ' | . | . |  _|     | . |\n'
+    + ' |___|___|___|_|_|_|___|\n';
+console.log(`${C.blue}${LOGO}${C.reset}`);
+console.log(`${C.dim} Monorepo Maintenance Pipeline ${C.reset}\n`);
+
+// Section 1: Setup
+section('Setup', C.blue);
+{
+    const s = startStep('Stopping active servers');
+    const r = run('pnpm -s stop');
+    if (r.ok) finishStep(s);
+    else { finishStep(s, 'fail', `exit ${r.status}`); addIssue('error', 'Setup', `pnpm stop failed (exit ${r.status})`, []); }
+}
+{
+    const s = startStep('Wiping global docmd binaries');
+    const pkgs = ['@docmd/core', '@docmd/monorepo', 'docmd', 'docmd-live'];
+    for (const pkg of pkgs) {
+        try { execSync('npm uninstall -g ' + pkg + ' -s', { stdio: 'ignore' }); } catch { /* ignore */ }
+        try { execSync('pnpm uninstall -g ' + pkg + ' -s', { stdio: 'ignore' }); } catch { /* ignore */ }
+    }
+    deepWipe();
+    finishStep(s);
+}
+{
+    const s = startStep('Cleaning monorepo');
+    const r = run('pnpm -s clean');
+    if (r.ok) finishStep(s);
+    else { finishStep(s, 'fail', `exit ${r.status}`); addIssue('error', 'Setup', `pnpm clean failed (exit ${r.status})`, []); }
+}
+{
+    // pnpm clean wipes node_modules; reinstall before lint so the eslint
+    // binary is on PATH. Without this step the lint section silently exits
+    // 0 with no output because `pnpm exec eslint` can't find the binary.
+    const s = startStep('Installing monorepo dependencies');
+    const r = run('pnpm install --frozen-lockfile');
+    if (r.ok) finishStep(s);
+    else { finishStep(s, 'fail', `exit ${r.status}`); addIssue('error', 'Setup', `pnpm install failed (exit ${r.status})`, []); }
+}
+addStat('Setup', 'cleaned + installed dependencies', 'ok');
+footer(C.blue);
+
+// Section 2: Lint โ€” runs after Setup reinstalls deps so eslint is available.
+section('Lint', C.cyan);
+runLint();
+footer(C.cyan);
+
+// Section 3: Build โ€” required so tests have dist files to run against.
+// `pnpm clean` (called in Setup) wipes every package's dist directory;
+// deps are already restored by Setup's install step.
+section('Build', C.cyan);
+{
+    const s = startStep('Building all packages (pnpm -r run build)');
+    const r = run('pnpm -r run build');
+    if (r.ok) finishStep(s);
+    else { finishStep(s, 'fail', `exit ${r.status}`); addIssue('error', 'Build', `pnpm -r run build failed (exit ${r.status})`, []); }
+}
+addStat('Build', 'built all packages', 'ok');
+footer(C.cyan);
+
+// Section 4: Docker (optional)
+section('Docker', C.blue);
+runDockerCheck();
+footer(C.blue);
+
+// Section 5: Tests
+section('Tests', C.blue);
+if (args.includes('--skip-tests')) {
+    const s = startStep('Skipping test suite (--skip-tests)');
+    finishStep(s, 'done');
+    addStat('Tests', 'skipped by user request', 'ok');
+} else {
+    const only = args.find((a) => a.startsWith('--only='));
+    const runnerArgs = only ? ' ' + only : '';
+    // The categorised runner now includes the Mega Integration Test
+    // (workspaces + i18n + versioning + plugins), which used to live
+    // in `tests/failsafe.test.mjs`. The old failsafe was removed because
+    // it duplicated Setup / Build work that `pnpm prep` already does.
+    // runTestStep() collapses to a one-line summary by default; pass
+    // --verbose to stream the full output.
+    // The shortLabel is what shows in the Summary block; the longer
+    // stepLabel stays in the per-step line.
+    runTestStep('Categorised test suite (tests/runner.js)',
+        'node tests/runner.js' + runnerArgs, 'Tests ยท runner.js');
+
+    // Per-package unit tests (parser, utils, mermaid, okf). Packages
+    // without a `test` script are skipped by `--if-present`. Wired in
+    // here so a regression in any plugin's local suite fails the
+    // release pipeline just like a regression in tests/runner.js.
+    runTestStep('Per-package unit tests (pnpm -r run test)',
+        'pnpm -r run test --if-present', 'Tests ยท per-package units');
+}
+footer(C.blue);
+
+// Section 6: Link (optional)
+if (args.includes('--link')) {
+    section('Link', C.blue);
+    const s = startStep('Linking @docmd/core globally');
+    try {
+        execSync('npm link --silent', {
+            cwd: require('path').join(process.cwd(), 'packages/core'),
+            stdio: 'ignore'
+        });
+        finishStep(s, 'done', 'docmd command available globally');
+    } catch {
+        finishStep(s, 'fail', 'npm link failed');
+        addIssue('error', 'Link', 'npm link failed', []);
+    }
+    footer(C.blue);
+}
+
+// Section 7: Summary / Issues โ€” single trailing block. Renders a
+// green Summary on a clean run, or a red Issues block on failure.
+// Either way it lives in the same slot at the end of the pipeline
+// so the operator always knows where to look for the verdict.
+printSummary();
+
+// Exit code: any error-level issue is fatal. Warnings alone keep the
+// pipeline green so the operator can decide whether to act on them.
+const hasErrors = issues.some(i => i.severity === 'error');
+if (hasErrors) process.exit(1);
\ No newline at end of file
diff --git a/tools/print-okf-runtime-deps.js b/tools/print-okf-runtime-deps.js
new file mode 100644
index 0000000..595a40b
--- /dev/null
+++ b/tools/print-okf-runtime-deps.js
@@ -0,0 +1,99 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the zero-config documentation engine.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ *
+ * Resolves the external (non-@docmd) runtime dependencies of @docmd/core
+ * and its transitive deps, then either:
+ *
+ *   node tools/print-okf-runtime-deps.js
+ *     โ†’ prints `name@range` lines to stdout (human readable / CI log)
+ *
+ *   node tools/print-okf-runtime-deps.js --emit-pkg=<path>
+ *     โ†’ writes a package.json to <path> listing all external deps under
+ *       `dependencies`.  Used by the Docker builder stage so the
+ *       production stage can do a single `npm install --prefix /usr/local`
+ *       instead of maintaining a hand-rolled list in the Dockerfile.
+ *
+ * The script is the single source of truth for what external deps the
+ * Docker image needs.  Run it after adding a new dep to any @docmd/*
+ * package โ€” the next Docker build will pick up the change automatically
+ * because the builder stage regenerates the package.json fresh.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const root = process.cwd();
+const emitArg = process.argv.find((a) => a.startsWith("--emit-pkg="));
+const emitPath = emitArg ? emitArg.slice("--emit-pkg=".length) : null;
+
+function findPackageDir(name, dir = path.join(root, "packages")) {
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    if (!entry.isDirectory()) continue;
+    const full = path.join(dir, entry.name);
+    const pj = path.join(full, "package.json");
+    if (fs.existsSync(pj)) {
+      const pkg = JSON.parse(fs.readFileSync(pj, "utf8"));
+      if (pkg.name === name) return full;
+    }
+    const r = findPackageDir(name, full);
+    if (r) return r;
+  }
+  return null;
+}
+
+function collectDeps(name, seen = new Set()) {
+  if (seen.has(name)) return seen;
+  seen.add(name);
+  const dir = findPackageDir(name);
+  if (!dir) return seen;
+  const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+  for (const dep of Object.keys(pkg.dependencies || {})) {
+    if (dep.startsWith("@docmd/")) collectDeps(dep, seen);
+  }
+  return seen;
+}
+
+const internal = collectDeps("@docmd/core");
+const external = new Map();
+
+for (const name of internal) {
+  const dir = findPackageDir(name);
+  if (!dir) continue;
+  const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+  for (const [dep, range] of Object.entries(pkg.dependencies || {})) {
+    if (dep.startsWith("@docmd/")) continue;
+    if (dep.startsWith("@mgks/")) continue;
+    if (!external.has(dep)) external.set(dep, range);
+  }
+}
+
+const lines = [...external].sort(([a], [b]) => a.localeCompare(b));
+
+if (emitPath) {
+  // Write a package.json the production stage can `npm install` directly.
+  // `name` and `version` are required by npm but otherwise arbitrary.
+  const pkg = {
+    name: "docmd-runtime-deps",
+    version: "0.0.0",
+    private: true,
+    description: "Auto-generated by tools/print-okf-runtime-deps.js โ€” do not edit.",
+    dependencies: Object.fromEntries(lines)
+  };
+  fs.mkdirSync(path.dirname(emitPath), { recursive: true });
+  fs.writeFileSync(emitPath, JSON.stringify(pkg, null, 2) + "\n");
+  console.log(`[generate-runtime-pkg] wrote ${lines.length} deps โ†’ ${emitPath}`);
+} else {
+  for (const [dep, range] of lines) {
+    console.log(`${dep}@${range}`);
+  }
+}
\ No newline at end of file
diff --git a/tools/resolve-ws-deps.js b/tools/resolve-ws-deps.js
new file mode 100644
index 0000000..f2aa104
--- /dev/null
+++ b/tools/resolve-ws-deps.js
@@ -0,0 +1,66 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const root = process.cwd();
+const packagesDir = path.join(root, "packages");
+
+// Build name โ†’ version map
+const versionMap = {};
+
+function collectVersions(dir) {
+  for (const entry of fs.readdirSync(dir)) {
+    const full = path.join(dir, entry);
+    if (fs.existsSync(path.join(full, "package.json"))) {
+      const pkg = require(path.join(full, "package.json"));
+      versionMap[pkg.name] = pkg.version;
+    } else if (fs.statSync(full).isDirectory()) {
+      collectVersions(full);
+    }
+  }
+}
+
+collectVersions(packagesDir);
+
+// Rewrite workspace deps
+function rewriteDeps(dir) {
+  for (const entry of fs.readdirSync(dir)) {
+    const full = path.join(dir, entry);
+
+    if (fs.existsSync(path.join(full, "package.json"))) {
+      const pkgPath = path.join(full, "package.json");
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+
+      ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"].forEach(field => {
+        if (!pkg[field]) return;
+
+        for (const dep in pkg[field]) {
+          if (pkg[field][dep].startsWith("workspace:")) {
+            pkg[field][dep] = `^${versionMap[dep]}`;
+          }
+        }
+      });
+
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+    } else if (fs.statSync(full).isDirectory()) {
+      rewriteDeps(full);
+    }
+  }
+}
+
+rewriteDeps(packagesDir);
+
+console.log("Workspace dependencies resolved.");
\ No newline at end of file
diff --git a/tools/security-audit.mjs b/tools/security-audit.mjs
new file mode 100644
index 0000000..17f21b3
--- /dev/null
+++ b/tools/security-audit.mjs
@@ -0,0 +1,203 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : Monorepo Security Audit
+ * 
+ * Scans the codebase for high-risk patterns that could lead to
+ * XSS, RCE, or directory traversal vulnerabilities.
+ * --------------------------------------------------------------------
+ */
+
+import nativeFs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CWD = path.resolve(__dirname, '..');
+
+const AUDIT_CONFIG = {
+    patterns: [
+        {
+            name: 'Potential DOM XSS (innerHTML)',
+            regex: /\.innerHTML\s*=\s*/g,
+            severity: 'HIGH',
+            exclude: []
+        },
+        {
+            name: 'Raw EJS Output (<%-)',
+            regex: /<%-/g,
+            severity: 'MEDIUM',
+            include: [/\.ejs$/],
+            exclude: [
+                /layout\.ejs/, // Main layout (legit for page content)
+                /menubar\.ejs/,
+                /sidebar\.ejs/,
+                /packages\/plugins\/threads\/src\/plugin\/templates\// // Threads use raw for markdown
+            ],
+            notes: 'Ensure the output is either trusted Markdown or manually escaped.'
+        },
+        {
+            name: 'Unsafe Command Execution (eval)',
+            regex: /\beval\s*\(/g,
+            severity: 'CRITICAL'
+        },
+        {
+            name: 'Unsafe Function Construction',
+            regex: /new\s+Function\s*\(/g,
+            severity: 'CRITICAL'
+        },
+        {
+            name: 'Unsafe Shell Execution',
+            regex: /(?<!\.(?:[a-zA-Z0-9_$]+))\bexec\s*\(/g,
+            severity: 'HIGH',
+            exclude: [
+                /scripts\//, // Build scripts are allowed (legacy path)
+                /tools\//, // Build tooling is allowed (current path)
+                /packages\/core\/src\/engine\/workspace\.ts/ // Legit for git metadata
+            ],
+            notes: 'Check if this is child_process.exec. Avoid RegExp.exec false positives.'
+        },
+        {
+            name: 'Path Traversal Risk (fs access with dynamic path)',
+            regex: /fs\.(?:readFileSync|writeFile|mkdirSync|copyFileSync)\([^,)]*[\+\$]/g,
+            severity: 'MEDIUM',
+            exclude: [
+                /scripts\//,
+                /tools\//,
+                /packages\/core\/src\/engine\//, // Core engine handles paths
+                /packages\/plugins\/search\/src\/index\.ts/
+            ]
+        }
+    ],
+    // Custom filter to skip RegExp.exec specifically if the lookbehind isn't enough.
+    // The `Unsafe Shell Execution` regex above uses a variable-length negative
+    // lookbehind that only suppresses method calls on identifiers of 2+ chars
+    // (e.g. `child_process.exec` โ€” the chars before `exec(` are `s.`, which
+    // matches the lookbehind pattern). Short identifiers like `re` slip
+    // through because the chars before `exec(` are `e.` (just 2 chars) and
+    // the lookbehind's `\.[a-zA-Z0-9_$]+` requires at least 1 identifier
+    // char AFTER the dot, so it doesn't match `.` alone.
+    //
+    // To compensate, this filter suppresses the match when the line's
+    // `.exec(` call is on a recognised RegExp variable name. The list
+    // covers every common JS naming convention for a RegExp instance.
+    // Real or potentially-real shell calls (any other variable name,
+    // `child_process.exec`, `cp.exec`, standalone `exec(cmd)`, etc.)
+    // are NOT suppressed โ€” they remain flagged for operator review.
+    filter: (pattern, line) => {
+        if (pattern.name === 'Unsafe Shell Execution' && line.includes('.exec(')) {
+            const before = line.split('.exec(')[0];
+            if (before && /(?:re|regex|regexp|rgx|match|matcher|pattern|pat)(?![a-zA-Z_$])\s*(?:\.|$)/i.test(before)) return false;
+        }
+
+        if (pattern.name === 'Raw EJS Output (<%-)') {
+            const safePatterns = [
+                'renderIcon', 'include', 't(', 'content', 'navigationHtml', 
+                'footerHtml', 'pluginHeadScriptsHtml', 'pluginBodyScriptsHtml', 
+                'pluginStylesHtml', 'themeInitScript', 'faviconLinkHtml', 
+                'metaTagsHtml', 'themeCssLinkHtml', 'frontmatter.customHead', 
+                'frontmatter.customScripts', "'<script>'", "'</script>'", 
+                'JSON.stringify', 'relativePathToRoot'
+            ];
+            if (safePatterns.some(p => line.includes(p))) return false;
+        }
+
+        if (pattern.name === 'Potential DOM XSS (innerHTML)') {
+            if (line.includes("innerHTML = ''") || line.includes('innerHTML = ""') || line.includes('innerHTML = ``')) return false;
+            if (line.includes('this.sanitize(') || line.includes('innerHTML = sanitized') || line.includes("'×'")) return false;
+        }
+
+        return true;
+    },
+    extensions: ['.ts', '.js', '.ejs', '.json'],
+    // Build output directories are excluded because their content is generated
+    // and minified โ€” the audit is meant to catch issues in source code.
+    excludeDirs: ['node_modules', 'dist', 'site', 'site-sky', 'out', '.git', 'temp', 'public', 'vendor', '_backup']
+};
+
+let issuesCount = 0;
+
+function scanDir(dir) {
+    const entries = nativeFs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relPath = path.relative(CWD, fullPath);
+
+        if (entry.isDirectory()) {
+            if (AUDIT_CONFIG.excludeDirs.includes(entry.name)) continue;
+            scanDir(fullPath);
+            continue;
+        }
+
+        const ext = path.extname(entry.name);
+        if (!AUDIT_CONFIG.extensions.includes(ext)) continue;
+
+        const content = nativeFs.readFileSync(fullPath, 'utf8');
+        const lines = content.split('\n');
+
+        for (const pattern of AUDIT_CONFIG.patterns) {
+            // Check global include/exclude for the file
+            if (pattern.include && !pattern.include.some(re => re.test(relPath))) continue;
+            if (pattern.exclude && pattern.exclude.some(re => re.test(relPath))) continue;
+
+            let match;
+            pattern.regex.lastIndex = 0; // Reset regex
+            while ((match = pattern.regex.exec(content)) !== null) {
+                const index = match.index;
+                const lineNumber = content.substring(0, index).split('\n').length;
+                const line = lines[lineNumber - 1].trim();
+
+                // Custom filters
+                if (AUDIT_CONFIG.filter && !AUDIT_CONFIG.filter(pattern, line)) continue;
+
+                // Inline exclusion comment support
+                if (line.includes('audit-ignore') || line.includes('eslint-disable')) continue;
+
+                issuesCount++;
+                const skipHeader = process.argv.includes('--skip-header');
+                const prefix = skipHeader ? '\x1b[34mโ”‚\x1b[0m     ' : '\x1b[34mโ”‚\x1b[0m  ';
+                
+                console.log(`${prefix}[\x1b[1m${pattern.severity}\x1b[0m] \x1b[33m${pattern.name}\x1b[0m`);
+                console.log(`${prefix}Location: \x1b[34m${relPath}:${lineNumber}\x1b[0m`);
+                console.log(`${prefix}\x1b[2mCode: ${line.substring(0, 80)}${line.length > 80 ? '...' : ''}\x1b[0m`);
+                if (pattern.notes) console.log(`${prefix}\x1b[36mNote: ${pattern.notes}\x1b[0m`);
+                console.log(`\x1b[34mโ”‚\x1b[0m`);
+            }
+        }
+    }
+}
+
+const skipHeader = process.argv.includes('--skip-header');
+
+if (!skipHeader) {
+    console.log(`\x1b[34mโ”Œโ”€ Monorepo Security Audit\x1b[0m`);
+    console.log(`\x1b[34mโ”‚\x1b[0m  Scanning packages and scripts...`);
+    console.log(`\x1b[34mโ”‚\x1b[0m`);
+}
+
+try {
+    scanDir(path.join(CWD, 'packages'));
+    scanDir(path.join(CWD, 'tools'));
+
+    if (issuesCount > 0) {
+        if (!skipHeader) {
+            console.log(`\x1b[34mโ”‚\x1b[0m  \x1b[31mFound ${issuesCount} potential security issues.\x1b[0m`);
+            console.log(`\x1b[34mโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€\x1b[0m\n`);
+        } else {
+            console.log(`\x1b[34mโ”‚\x1b[0m     \x1b[31mFound ${issuesCount} potential security issues.\x1b[0m`);
+        }
+    } else {
+        if (!skipHeader) {
+            console.log(`\x1b[34mโ”‚\x1b[0m  \x1b[32mNo high-risk patterns detected.\x1b[0m`);
+            console.log(`\x1b[34mโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€\x1b[0m\n`);
+        }
+    }
+} catch (e) {
+    console.error(`\x1b[31mโ”‚\x1b[0m  Fatal error during security audit: ${e.message}`);
+    if (!skipHeader) {
+        console.log(`\x1b[31mโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€\x1b[0m\n`);
+    }
+    process.exit(1);
+}
+
+process.exit(issuesCount > 0 ? 1 : 0);
\ No newline at end of file
diff --git a/tools/status.js b/tools/status.js
new file mode 100644
index 0000000..0f26541
--- /dev/null
+++ b/tools/status.js
@@ -0,0 +1,94 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
+const args = process.argv.slice(2);
+const TYPE = args[0];
+const skipHeader = args.includes('--skip-header');
+
+// TUI Design Tokens
+const C = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+    bgBlue: '\x1b[44m',
+    black: '\x1b[30m'
+};
+
+const LOGO = `
+    _                 _ 
+  _| |___ ___ _____ _| |
+ | . | . |  _|     | . |
+ |___|___|___|_|_|_|___|
+`;
+
+/**
+ * Modern TUI Components
+ */
+const TUI = {
+    header: (title) => {
+        console.log(`\n${C.blue}${LOGO}${C.reset}`);
+        console.log(`${C.dim} ${title} ${C.reset}\n`);
+    },
+    
+    section: (label, color = C.cyan) => {
+        console.log(`${color}${C.bold}โ”Œโ”€ ${label}${C.reset}`);
+    },
+    
+    item: (label, status = 'DONE', color = C.dim, barColor = '\x1b[36m') => {
+        const indicator = status === 'DONE' ? `\x1b[32m[ DONE ]\x1b[0m` : `\x1b[36m[ ${status} ]\x1b[0m`;
+        console.log(`${barColor}โ”‚\x1b[0m  ${color}${label.padEnd(45)}${C.reset} ${indicator}`);
+    },
+    
+    footer: (color = C.cyan) => {
+        console.log(`${color}โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€${C.reset}\n`);
+    },
+
+    alert: (msg, color = C.green) => {
+        console.log(`${color}${C.bold}โฌข ${msg}${C.reset}\n`);
+    },
+
+    error: (msg, detail) => {
+        console.error(`\n\x1b[31m\x1b[1mโ”Œโ”€ Failure\x1b[0m`);
+        console.error(`\x1b[31mโ”‚\x1b[0m  ${msg}`);
+        if (detail) {
+            detail.split('\n').forEach(line => {
+                console.error(`\x1b[31mโ”‚\x1b[0m  \x1b[2m${line}\x1b[0m`);
+            });
+        }
+        console.error(`\x1b[31mโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€\x1b[0m\n`);
+    }
+};
+
+if (TYPE && TYPE.startsWith('start:') && !skipHeader) {
+    TUI.header('Monorepo Maintenance Pipeline');
+}
+
+if (TYPE === 'start:reset') {
+    TUI.section('Resetting Docmd Engine', C.cyan);
+} else if (TYPE === 'reset') {
+    TUI.footer(C.cyan);
+    TUI.alert('Ready for fresh verification.');
+} else if (TYPE === 'start:verify') {
+    TUI.section('Failsafe Verification', C.blue);
+} else if (TYPE === 'verify') {
+    //TUI.footer(C.blue);
+    TUI.alert('docmd is production-ready.');
+} else if (TYPE === 'error') {
+    TUI.error(process.argv[3], process.argv[4]);
+}
\ No newline at end of file
diff --git a/tools/verify.js b/tools/verify.js
new file mode 100644
index 0000000..f2625b7
--- /dev/null
+++ b/tools/verify.js
@@ -0,0 +1,70 @@
+/**
+ * --------------------------------------------------------------------
+ * docmd : the minimalist, zero-config documentation generator.
+ *
+ * @package     @docmd/core (and ecosystem)
+ * @website     https://docmd.io
+ * @repository  https://github.com/docmd-io/docmd
+ * @license     MIT
+ * @copyright   Copyright (c) 2025-present docmd.io
+ *
+ * [docmd-source] - Please do not remove this header.
+ * --------------------------------------------------------------------
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const isCI = process.env.CI === 'true' || args.includes('--skip-setup');
+const shouldLink = args.includes('--link');
+const skipHeader = args.includes('--skip-header');
+
+function run(cmd, silent = true) {
+    // Pipe stdout/stderr so a failing child surfaces its real output. With
+    // stdio 'inherit', a CI runner (no TTY) discards the child's output and
+    // execSync's error object carries no captured buffers โ€” leaving us with
+    // an opaque "exit code 1" and no way to see which assertion failed.
+    try {
+        execSync(cmd, {
+            stdio: silent ? 'ignore' : 'pipe',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    } catch (e) {
+        if (e.stdout) process.stderr.write(e.stdout);
+        if (e.stderr) process.stderr.write(e.stderr);
+        if (!silent) console.error(e);
+        process.exit(1);
+    }
+}
+
+// 1. Show starting logo (only if not in CI or if user wants it)
+if (!isCI) {
+    const headerCmd = skipHeader ? 'node tools/status.js start:verify --skip-header' : 'node tools/status.js start:verify';
+    run(headerCmd, false);
+}
+
+// 2. Run the categorised test suite (tests/runner.js replaced the
+// legacy scripts/failsafe.mjs after the tests/scripts split).
+// Forwarding arguments so --skip-setup / future flags reach the runner.
+const failsafeArgs = args.filter(a => a !== '--link' && a !== '--skip-header').join(' ');
+run(`node tests/runner.js ${failsafeArgs}`, false);
+
+// 3. Handle global linking if requested
+if (shouldLink) {
+    process.stdout.write(`\x1b[34mโ”‚\x1b[0m  \x1b[2mLinking docmd globally...\x1b[0m`);
+    try {
+        execSync('npm link --silent', { cwd: path.join(process.cwd(), 'packages/core'), stdio: 'ignore' });
+        console.log(' \x1b[32m[ DONE ]\x1b[0m');
+    } catch {
+        console.log(' \x1b[31m[ FAIL ]\x1b[0m');
+    }
+}
+
+// 4. Show final completion status
+if (!isCI) {
+    const statusCmd = 'node tools/status.js verify';
+    run(statusCmd, false);
+} else {
+    console.log('\n\x1b[32m\x1b[1mโฌข Docmd verification passed!\x1b[0m\n');
+}
\ No newline at end of file
diff --git a/tsconfig.base.json b/tsconfig.base.json
new file mode 100644
index 0000000..db0c8d5
--- /dev/null
+++ b/tsconfig.base.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "resolveJsonModule": true,
+    "types": ["node"]
+  }
+}
\ No newline at end of file