From 973554d5193689c57fe3814db2d13afd7b343411 Mon Sep 17 00:00:00 2001 From: Ghazi Date: Sun, 12 Jul 2026 17:30:52 +0530 Subject: [PATCH 1/2] docs: add project pages subpath deployment section to GitHub Action guide Explains that users only need to set url for GitHub Pages project sites. docmd auto-derives the asset base path from the URL. No manual base config needed. Mentions base override only as a rare edge case. --- docmd-main/v08/en/deployment/github-action.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docmd-main/v08/en/deployment/github-action.md b/docmd-main/v08/en/deployment/github-action.md index 8b6f1d9..c9dba74 100644 --- a/docmd-main/v08/en/deployment/github-action.md +++ b/docmd-main/v08/en/deployment/github-action.md @@ -102,6 +102,25 @@ After this, every push to `main` triggers a deployment automatically. If your `docmd.config.json` lives in a subdirectory — for example, `packages/docs/docmd.config.json` in a monorepo — the action detects it and passes `--cwd` to docmd automatically. No manual path configuration is required. +## Project Pages (Subpath Deployment) + +GitHub Pages serves project sites at `https://.github.io//`, not at the domain root. docmd handles this automatically — set `url` to your full GitHub Pages URL and docmd derives the correct asset paths from it: + +```json "docmd.config.json" +{ + "url": "https://username.github.io/my-repo" +} +``` + +That's it. docmd reads the `/my-repo/` subpath from your URL and uses it for every internal link and asset reference. No additional configuration is needed. + +::: callout tip "How docmd knows your deployment path" +docmd derives the asset base path from your `url` config. The `url` you set for SEO and sitemaps is the same value docmd uses to figure out where your assets live. Set it once, everything follows. + +If your deployment path ever differs from your URL path (rare, e.g. a CDN that strips a prefix), you can override with `base`. docmd normalises slashes for you, so any of these work: +`"my-repo"`, `"/my-repo"`, `"/my-repo/"`. You don't have to remember which slashes are required. +::: + ## Custom Domain To use a custom domain: From bb573017e1341e4ca090a36bfafc97ffda243a4c Mon Sep 17 00:00:00 2001 From: Ghazi Date: Sun, 12 Jul 2026 18:32:06 +0530 Subject: [PATCH 2/2] docs: add v0.8.12 release notes (en/de/zh) + nav entries for 0.8.11 and 0.8.12 --- docmd-main/v08/de/navigation.json | 8 ++++ docmd-main/v08/de/release-notes/0-8-12.md | 57 +++++++++++++++++++++++ docmd-main/v08/en/navigation.json | 8 ++++ docmd-main/v08/en/release-notes/0-8-12.md | 57 +++++++++++++++++++++++ docmd-main/v08/zh/navigation.json | 8 ++++ docmd-main/v08/zh/release-notes/0-8-12.md | 57 +++++++++++++++++++++++ 6 files changed, 195 insertions(+) create mode 100644 docmd-main/v08/de/release-notes/0-8-12.md create mode 100644 docmd-main/v08/en/release-notes/0-8-12.md create mode 100644 docmd-main/v08/zh/release-notes/0-8-12.md diff --git a/docmd-main/v08/de/navigation.json b/docmd-main/v08/de/navigation.json index c1bf376..15ec3a6 100644 --- a/docmd-main/v08/de/navigation.json +++ b/docmd-main/v08/de/navigation.json @@ -623,6 +623,14 @@ "icon": "package-check", "collapsible": true, "children": [ + { + "title": "v0.8.12 - Auto-Install-Härtung und GitHub-Pages-Fix", + "path": "/release-notes/0-8-12" + }, + { + "title": "v0.8.11 - Sicherheits-Updates und Cross-Locale-Routing", + "path": "/release-notes/0-8-11" + }, { "title": "v0.8.10 - CLI-Politur und Workspace-UX", "path": "/release-notes/0-8-10" diff --git a/docmd-main/v08/de/release-notes/0-8-12.md b/docmd-main/v08/de/release-notes/0-8-12.md new file mode 100644 index 0000000..28951cd --- /dev/null +++ b/docmd-main/v08/de/release-notes/0-8-12.md @@ -0,0 +1,57 @@ +--- +title: "v0.8.12 - Auto-Install-Härtung und GitHub-Pages-Fix" +description: "Release-Notes für docmd v0.8.12 - gehärtete Auto-Install-Pipeline (CWE-78), Engine-Auto-Install, korrigierte Core-Abhängigkeiten und automatische Basispfad-Ableitung für GitHub-Pages-Projektseiten." +date: "2026-07-12" +--- + +### ✨ Highlights + +Diese Version behebt eine Regression, die das Laden von Assets auf GitHub-Pages-Projektseiten kaputt gemacht hat (#175), härtet die Auto-Install-Pipeline gegen Shell-Injection (CWE-78) und entfernt `@docmd/plugin-pwa` aus der Standardinstallation (es war nie ein Core-Plugin). + +Keine Breaking Changes. Keine neuen erforderlichen Konfigurationen. Bestehende Configs, Plugins und CI-Pipelines funktionieren unverändert. + +### 🐛 Fix: GitHub-Pages-Projektseiten — alle Assets 404 (#175) + +Benutzer, die auf `https://username.github.io/repo-name/` deployten, sahen nach dem Upgrade von 0.8.9 für jede CSS-, JS- und Bilddatei einen 404. Die Ursache: 0.8.10 fügte ein ``-Tag hinzu, um ein separates Workspace-Problem zu beheben, wodurch der Browser alle relativen URLs gegen den Domain-Root statt gegen den Unterpfad auflöste. + +**Der Fix:** docmd leitet den Asset-Basispfad nun automatisch aus Ihrer `url`-Konfiguration ab. Wenn `url` `https://username.github.io/my-repo` ist, setzt docmd `base` intern auf `/my-repo/`. Es ist keine manuelle `base`-Konfiguration erforderlich. + +```json "docmd.config.json" +{ + "url": "https://username.github.io/my-repo" +} +``` + +Das ist alles. docmd übernimmt den Rest. + +Benutzer, die `base` explizit gesetzt haben, sind nicht betroffen. Die Ableitung istSlash-tolerant bei `url` und `base` — `"my-repo"`, `"/my-repo"` und `"/my-repo/"` funktionieren alle. + +### 🔒 Sicherheit: Shell-Injection im Auto-Install (CWE-78) + +Der Auto-Install-Pfad für Plugins baute einen Shell-String-Befehl, indem der Paketname in `pnpm add ${pkg}` interpoliert wurde. Ein Paketname mit Shell-Metazeichen konnte beliebige Befehle unter dem Benutzerkonto ausführen. + +**Der Fix:** ein neues gemeinsames Modul (`packages/api/src/runtime-deps.ts`) ersetzt den Shell-String durch `spawn(pm, args, { shell: false })` mit einem festen Argument-Array. Ein strenger Regex-Validator und ein Registry-Lookup wirken als Defence-in-Depth. Der Auto-Install-Pfad kann nicht mehr zu einem generischen `npm install`-Loader umfunktioniert werden. + +### 🧰 Gemeinsames runtime-deps-Modul + +Der Plugin-Loader (`hooks.ts`) und der Engine-Loader (`engine.ts`) pflegten jeweils eine eigene Kopie der Auto-Install-Pipeline. Beide nutzen nun `runtime-deps.ts`. Ein Installationsverhalten, überall angewendet. Der TUI-Status-Reporter ist pro Build idempotent, sodass Dev-Server-Rebuilds keine doppelten `[ WAIT ]`- / `[ DONE ]`-Zeilen erzeugen. + +### 🛠 Engine-Auto-Install + +Das Anfordern von `engine: "rust"` in der Konfiguration fiel bisher direkt auf JS zurück, wenn `@docmd/engine-rust` nicht installiert war. Der neue Ablauf versucht, `engine-rust` zuerst zu installieren; schlägt die Installation fehl oder ist die native Binärdatei auf der Plattform nicht verwendbar, wird auf JS zurückgegriffen und der Grund wird in einer `[ FAIL ]`-Zeile angezeigt. + +### 📦 Korrigierte Core-Abhängigkeiten + +`@docmd/plugin-pwa` war als direkte Abhängigkeit von `@docmd/core` gelistet, gehörte aber nie zu `CORE_PLUGINS`. Jedes `npm install @docmd/core` hat es installiert, auch für Benutzer, die PWA nie aktiviert haben. + +**Der Fix:** `@docmd/plugin-pwa` aus `packages/core/package.json#dependencies` entfernt. Es wird nun bei Bedarf installiert, genauso wie `math`, `threads` und alle anderen optionalen Plugins. + +### 📐 Testabdeckung + +51 neue Assertions in `tests/cli-contracts/runtime-deps.test.js`: öffentliche API, Validator (12 positive, 13 negative Fälle inklusive Shell-Metazeichen), Registry-Cache-Idempotenz, Install-Verweigerungs-Pfade und statische Quellcode-Prüfungen. + +### Migration + +Null. Bestehende Configs, Plugins und CI-Pipelines funktionieren unverändert. + +**Vollständiges Changelog**: https://github.com/docmd-io/docmd/compare/0.8.11...0.8.12 diff --git a/docmd-main/v08/en/navigation.json b/docmd-main/v08/en/navigation.json index 6395631..8103b22 100644 --- a/docmd-main/v08/en/navigation.json +++ b/docmd-main/v08/en/navigation.json @@ -623,6 +623,14 @@ "icon": "package-check", "collapsible": true, "children": [ + { + "title": "v0.8.12 - Auto-Install Hardening and GitHub Pages Fix", + "path": "/release-notes/0-8-12" + }, + { + "title": "v0.8.11 - Security Fixes and Cross-Locale Routing", + "path": "/release-notes/0-8-11" + }, { "title": "v0.8.10 - CLI Polish and Workspace UX", "path": "/release-notes/0-8-10" diff --git a/docmd-main/v08/en/release-notes/0-8-12.md b/docmd-main/v08/en/release-notes/0-8-12.md new file mode 100644 index 0000000..d859117 --- /dev/null +++ b/docmd-main/v08/en/release-notes/0-8-12.md @@ -0,0 +1,57 @@ +--- +title: "v0.8.12 - Auto-Install Hardening and GitHub Pages Fix" +description: "Release notes for docmd v0.8.12 - hardened auto-install pipeline (CWE-78), engine auto-install, corrected core dependency manifest, and automatic base path derivation for GitHub Pages project sites." +date: "2026-07-12" +--- + +### ✨ Highlights + +This release fixes a regression that broke asset loading on GitHub Pages project sites (#175), hardens the plugin/template/engine auto-install pipeline against shell injection (CWE-78), and removes `@docmd/plugin-pwa` from the default install (it was never a core plugin). + +No breaking changes. No new required config. Existing configs, plugins, and CI pipelines work unchanged. + +### 🐛 Fix: GitHub Pages project sites 404 on all assets (#175) + +Users deploying to `https://username.github.io/repo-name/` saw every CSS, JS, and image file 404 after upgrading from 0.8.9. The cause: 0.8.10 added a `` tag to fix a separate workspace issue, which made the browser resolve all relative URLs against the domain root instead of the subpath. + +**The fix:** docmd now derives the asset base path from your `url` config automatically. If `url` is `https://username.github.io/my-repo`, docmd sets `base` to `/my-repo/` internally. No manual `base` config is needed. + +```json "docmd.config.json" +{ + "url": "https://username.github.io/my-repo" +} +``` + +That's it. docmd handles the rest. + +Users who explicitly set `base` are unaffected. The derivation is slash-tolerant on both `url` and `base` — `"my-repo"`, `"/my-repo"`, and `"/my-repo/"` all work. + +### 🔒 Security: shell injection in auto-install (CWE-78) + +The plugin auto-install path built a shell-string command by interpolating the package name into `pnpm add ${pkg}`. A package name with shell metacharacters that ever reached this code path would execute arbitrary commands under the user's account. + +**The fix:** a new shared module (`packages/api/src/runtime-deps.ts`) replaces the shell-string with `spawn(pm, args, { shell: false })` using a fixed arg array. A strict regex validator (`/^@docmd\/(plugin|template|engine)-[a-z0-9][a-z0-9.-]*$/`) and a registry lookup act as defence-in-depth. The auto-install path can no longer be turned into a generic `npm install` loader. + +### 🧰 Shared runtime-deps module + +The plugin loader (`hooks.ts`) and the engine loader (`engine.ts`) each used to carry their own copy of the auto-install pipeline. Both now go through `runtime-deps.ts`. One install behaviour, applied everywhere. The TUI status reporter is idempotent per-build, so dev-server rebuilds do not spam duplicate `[ WAIT ]` / `[ DONE ]` lines. + +### 🛠 Engine auto-install + +Requesting `engine: "rust"` in config used to fall straight through to JS if `@docmd/engine-rust` was not installed. The new flow tries to install `engine-rust` first; if the install fails or the native binary is not usable on the platform, it falls back to JS and surfaces the reason in a `[ FAIL ]` line. The same applies to `loadEngine('js')` as a last resort. + +### 📦 Corrected core dependency manifest + +`@docmd/plugin-pwa` was listed as a direct dependency of `@docmd/core` but was never in `CORE_PLUGINS` (the source-of-truth constant that drives auto-loading). Every `npm install @docmd/core` pulled it in, even for users who never enabled PWA. + +**The fix:** removed `@docmd/plugin-pwa` from `packages/core/package.json#dependencies`. It now installs on demand, the same as `math`, `threads`, and every other optional plugin. The dependency list now matches `CORE_PLUGINS` exactly. + +### 📐 Test coverage + +51 new assertions in `tests/cli-contracts/runtime-deps.test.js`: public surface, validator (12 positive, 13 negative cases including shell metacharacters), registry cache idempotency, install refusal paths, and static source checks proving no `execSync` shell-string remains in `hooks.ts` or `engine.ts`. + +### Migration + +Zero. Existing configs, plugins, and CI pipelines work unchanged. + +**Full changelog**: https://github.com/docmd-io/docmd/compare/0.8.11...0.8.12 diff --git a/docmd-main/v08/zh/navigation.json b/docmd-main/v08/zh/navigation.json index 8814e6c..e223c29 100644 --- a/docmd-main/v08/zh/navigation.json +++ b/docmd-main/v08/zh/navigation.json @@ -623,6 +623,14 @@ "icon": "package-check", "collapsible": true, "children": [ + { + "title": "v0.8.12 - 自动安装加固与 GitHub Pages 修复", + "path": "/release-notes/0-8-12" + }, + { + "title": "v0.8.11 - 安全修复与跨语言路由", + "path": "/release-notes/0-8-11" + }, { "title": "v0.8.10 - CLI 打磨与 Workspace UX", "path": "/release-notes/0-8-10" diff --git a/docmd-main/v08/zh/release-notes/0-8-12.md b/docmd-main/v08/zh/release-notes/0-8-12.md new file mode 100644 index 0000000..e596172 --- /dev/null +++ b/docmd-main/v08/zh/release-notes/0-8-12.md @@ -0,0 +1,57 @@ +--- +title: "v0.8.12 - 自动安装加固与 GitHub Pages 修复" +description: "docmd v0.8.12 发布说明 - 加固自动安装管道 (CWE-78)、引擎自动安装、修正核心依赖清单，以及 GitHub Pages 项目页面的自动 base 路径推导。" +date: "2026-07-12" +--- + +### ✨ 亮点 + +本版本修复了 GitHub Pages 项目页面资源加载失败的回归问题 (#175)，加固了插件/模板/引擎自动安装管道以防御 Shell 注入 (CWE-78)，并从默认安装中移除了 `@docmd/plugin-pwa`（它从来不是核心插件）。 + +无破坏性变更。无需新增配置。现有配置、插件和 CI 管道无需修改即可正常工作。 + +### 🐛 修复：GitHub Pages 项目页面所有资源 404 (#175) + +部署到 `https://username.github.io/repo-name/` 的用户在从 0.8.9 升级后发现所有 CSS、JS 和图片文件都返回 404。原因：0.8.10 添加了 `` 标签以修复另一个工作区问题，导致浏览器将所有相对 URL 解析到域名根路径而非子路径。 + +**修复方案：** docmd 现在自动从您的 `url` 配置推导资源基础路径。如果 `url` 为 `https://username.github.io/my-repo`，docmd 会在内部将 `base` 设为 `/my-repo/`。无需手动配置 `base`。 + +```json "docmd.config.json" +{ + "url": "https://username.github.io/my-repo" +} +``` + +就是这样。docmd 会处理其余工作。 + +显式设置 `base` 的用户不受影响。推导对 `url` 和 `base` 的斜杠都容错 — `"my-repo"`、`"/my-repo"` 和 `"/my-repo/"` 都可以正常工作。 + +### 🔒 安全：自动安装中的 Shell 注入 (CWE-78) + +插件自动安装路径通过将包名插入 `pnpm add ${pkg}` 来构建 Shell 字符串命令。包含 Shell 元字符的包名可以在用户账户下执行任意命令。 + +**修复方案：** 新的共享模块 (`packages/api/src/runtime-deps.ts`) 用 `spawn(pm, args, { shell: false })` 替换了 Shell 字符串，使用固定参数数组。严格的正则验证器和注册表查找作为纵深防御。自动安装路径无法再被转为通用的 `npm install` 加载器。 + +### 🧰 共享 runtime-deps 模块 + +插件加载器 (`hooks.ts`) 和引擎加载器 (`engine.ts`) 各自维护一份自动安装管道的副本。两者现在都通过 `runtime-deps.ts`。一处安装行为，处处适用。TUI 状态报告器在每次构建中是幂等的，因此开发服务器重建不会产生重复的 `[ WAIT ]` / `[ DONE ]` 行。 + +### 🛠 引擎自动安装 + +在配置中请求 `engine: "rust"` 时，如果未安装 `@docmd/engine-rust`，以前会直接回退到 JS。新流程会先尝试安装 `engine-rust`；如果安装失败或原生二进制文件在当前平台不可用，则回退到 JS 并在 `[ FAIL ]` 行中显示原因。 + +### 📦 修正核心依赖清单 + +`@docmd/plugin-pwa` 被列为 `@docmd/core` 的直接依赖，但从未包含在 `CORE_PLUGINS` 中。每次 `npm install @docmd/core` 都会安装它，即使用户从未启用 PWA。 + +**修复方案：** 从 `packages/core/package.json#dependencies` 中移除 `@docmd/plugin-pwa`。它现在按需安装，与 `math`、`threads` 及其他可选插件一样。 + +### 📐 测试覆盖 + +`tests/cli-contracts/runtime-deps.test.js` 中新增 51 个断言：公共 API、验证器（12 个正向用例、13 个负向用例，包括 Shell 元字符）、注册表缓存幂等性、安装拒绝路径，以及静态源码检查。 + +### 迁移 + +无需迁移。现有配置、插件和 CI 管道无需修改即可正常工作。 + +**完整变更日志**: https://github.com/docmd-io/docmd/compare/0.8.11...0.8.12