@klarkxy/dsh-dev-index 0.2.0 → 0.2.2

package/README.md

@@ -1,8 +1,10 @@
 # DSH Docs
 
+<!-- release-state-note -->
+
 [简体中文](README.zh-CN.md) | [English](README.md)
 
-Runtime: Node `^22.19.0 || >=24.0.0` and DSH `>=0.1.7-rc.2`. The documentation reader is a DSH Web client; the four read-only tools and the Creator-mode guidance run in the host.
+Runtime: Node `^22.19.0 || >=24.0.0` (26 verified) and DSH `>=0.1.7-rc.2`. The documentation reader is a DSH Web client; the four read-only tools and the Creator-mode guidance run in the host.
 
 Read the official DSH documentation without leaving DSH. The Plugins page embeds the official docs, and Creator mode also gets four native read-only tools: `dsh_docs_search` and `dsh_docs_fetch` to look up documentation, `dsh_plugins_search` and `dsh_plugins_fetch` to check a plugin's npm metadata. Installing and removing plugins stays with the official plugin manager; this plugin never installs anything.
 
@@ -23,7 +25,7 @@ The host half adds one system-prompt section when the session uses the `cordis`
 - `dsh_docs_search({ query: "plugin", language: "en" })` searches the live official `llms.txt` directory: titles, categories and paths. This is a directory search, not full-text search; an empty result does not establish that a topic is absent from the document bodies, so try broader Chinese or English keywords.
 - `dsh_docs_fetch({ id: "en/develop/basic/tool.md" })` reads a document ID returned by search. Results include the source URL, fetch time, content revision and `nextOffset`. Continue with that offset and the same `revision`; if the document changes, restart from offset zero. The default page size is 12,000 characters, at most 16,000.
 - `dsh_plugins_search({ query: "memory" })` finds candidate plugins. The default `catalog` source searches the curated klarkxy Chinese/English plugin catalog; `source: "npm"` searches npm's `dsh-plugin` keyword more broadly. Neither source is exhaustive, and a hit is a candidate rather than verified compatibility.
-- `dsh_plugins_fetch({ package: "@klarkxy/dsh-mood", version: "latest" })` reads npm registry metadata for an exact package name: dist-tags, published versions in publication-time order, and the selected version's bundle declaration, DSH/Node engine ranges, dependencies and deprecation. `version` accepts an exact release or a dist-tag; ranges are rejected.
+- `dsh_plugins_fetch({ package: "@klarkxy/dsh-current-title", version: "latest" })` reads npm registry metadata for an exact package name: dist-tags, published versions in publication-time order, and the selected version's bundle declaration, DSH/Node engine ranges, dependencies and deprecation. `version` accepts an exact release or a dist-tag; ranges are rejected.
 
 The plugin-registry tools are read-only metadata lookups: nothing is downloaded, installed or executed, and a declared engines range is not runtime compatibility proof. GitHub-installed plugins have no registry metadata; install those directly with the official plugin manager as `github:owner/repo#commit`, and review their `package.json` yourself.
 
@@ -51,7 +53,7 @@ The published npm package includes the built `lib/` files.
 dsh plugin --profile web add "github:klarkxy/dsh-plugins#path:/plugins/dsh-dev-index"
 ```
 
-A Git install runs `prepare`, which builds `lib/`. pnpm blocks that script until the profile allowlists it, and the DSH 0.1.7-rc.2 CLI prints the exact key to add under `allowBuilds` in `$DSH_HOME/profiles/web/pnpm-workspace.yaml`:
+A Git install runs `prepare`, which builds `lib/`. pnpm blocks that script until the profile allowlists it; the DSH CLI prints the exact key to add under `allowBuilds` in `$DSH_HOME/profiles/web/pnpm-workspace.yaml`:
 
 ```yaml
 allowBuilds:
@@ -60,25 +62,7 @@ allowBuilds:
 
 Run the add command again: that allowance executes this package's build on your machine. Pin a commit when the plugin source must not move.
 
-Peer ranges on `@deepseek-ai/dsh-system-prompt` and `@deepseek-ai/dsh-agent-preset-registry` are checked against the running `dsh` version. This package requires DSH `>=0.1.7-rc.2`, and the loader does not enforce `engines.dsh`.
-
-## Install from this checkout
-
-```bash
-pnpm install
-pnpm --filter @klarkxy/dsh-dev-index build
-dsh plugin --profile web add ./plugins/dsh-dev-index
-```
-
-Restart the profile, or let HMR apply the new bundle. Then:
-
-```bash
-dsh --profile web --dump-config
-```
-
-The composition should contain a `dsh-dev-index` row. Start a new Creator-mode session to pick up the documentation guidance automatically.
-
-There is no configuration: the patch inserts the plugin and sets no keys.
+Peer ranges on `@deepseek-ai/dsh-system-prompt` and `@deepseek-ai/dsh-agent-preset-registry` are checked against the running `dsh` version. The loader does not enforce `engines.dsh`.
 
 ## License
 

package/README.zh-CN.md

@@ -1,8 +1,10 @@
-# DSH 文档
+# DSH 文档
+
+<!-- release-state-note -->
 
 [简体中文](README.zh-CN.md) | [English](README.md)
 
-**运行环境**：Node `^22.19.0 || >=24.0.0`、DSH `>=0.1.7-rc.2`。文档阅读器是 DSH Web 客户端；四个只读工具和创造模式指引运行在宿主里。
+**运行环境**：Node `^22.19.0 || >=24.0.0`（已验证 26）、DSH `>=0.1.7-rc.2`。文档阅读器是 DSH Web 客户端；四个只读工具和创造模式指引运行在宿主里。
 
 不离开 DSH 就能读到官方文档：插件页内嵌官方文档站，创造模式另外拿到四个原生只读工具——`dsh_docs_search` 和 `dsh_docs_fetch` 检索文档，`dsh_plugins_search` 和 `dsh_plugins_fetch` 查核插件的 npm 元数据。安装和卸载插件始终由官方插件管理器负责，本插件不安装任何东西。
 
@@ -23,7 +25,7 @@
 - `dsh_docs_search({ query: "插件", language: "zh" })` 在线读取官方 `llms.txt`，搜索标题、分类和路径。这是目录搜索，不是全文搜索；没有命中不代表正文不含相关内容，可以改用更宽泛的中文或英文关键词。
 - `dsh_docs_fetch({ id: "develop/basic/tool.md" })` 读取搜索结果中的文档 ID。结果包含来源、获取时间、内容修订值和 `nextOffset`。长文用该偏移量和相同的 `revision` 继续读取；正文更新时需要从头重读。默认每次返回 12,000 字符，上限 16,000。
 - `dsh_plugins_search({ query: "记忆" })` 查找候选插件。默认 `catalog` 数据源搜索 klarkxy 维护的中英文插件目录；`source: "npm"` 用 npm 的 `dsh-plugin` 关键词做更宽的发现。两个源都不是全量目录，命中结果只是候选，不代表兼容性已验证。
-- `dsh_plugins_fetch({ package: "@klarkxy/dsh-mood", version: "latest" })` 按确切包名读取 npm 注册表元数据：dist-tags、按发布时间排序的版本列表，以及选定版本的组合包声明、DSH／Node 版本要求、依赖和弃用说明。`version` 可填精确版本或标签，不接受范围。
+- `dsh_plugins_fetch({ package: "@klarkxy/dsh-current-title", version: "latest" })` 按确切包名读取 npm 注册表元数据：dist-tags、按发布时间排序的版本列表，以及选定版本的组合包声明、DSH／Node 版本要求、依赖和弃用说明。`version` 可填精确版本或标签，不接受范围。
 
 插件注册表工具是只读元数据查询：不下载、不安装、不执行任何代码，声明的 engines 范围也不是运行时兼容性证明。从 GitHub 安装的插件没有注册表元数据，直接用官方插件管理器以 `github:owner/repo#commit` 安装，并自行审阅其 `package.json`。
 
@@ -51,7 +53,7 @@ npm 包包含已构建的 `lib/`。
 dsh plugin --profile web add "github:klarkxy/dsh-plugins#path:/plugins/dsh-dev-index"
 ```
 
-Git 安装会运行 `prepare` 来构建 `lib/`。pnpm 在允许之前会拦住这个脚本，DSH 0.1.7-rc.2 的 CLI 会打印出要写进 `$DSH_HOME/profiles/web/pnpm-workspace.yaml` 里 `allowBuilds` 的确切包名：
+Git 安装会运行 `prepare` 来构建 `lib/`。pnpm 在允许之前会拦住这个脚本，DSH CLI 会打印出要写进 `$DSH_HOME/profiles/web/pnpm-workspace.yaml` 里 `allowBuilds` 的确切包名：
 
 ```yaml
 allowBuilds:
@@ -60,25 +62,7 @@ allowBuilds:
 
 然后再执行一次 add：该许可会在本机执行这个包的构建。需要固定插件来源时请钉住 commit。
 
-`@deepseek-ai/dsh-system-prompt` 和 `@deepseek-ai/dsh-agent-preset-registry` 的 peer 范围会对照正在运行的 `dsh` 版本检查。本包要求 DSH `>=0.1.7-rc.2`；加载器不强制 `engines.dsh`。
-
-## 从本仓库安装
-
-```bash
-pnpm install
-pnpm --filter @klarkxy/dsh-dev-index build
-dsh plugin --profile web add ./plugins/dsh-dev-index
-```
-
-安装后重启该 profile，或让 HMR 应用新 bundle。然后：
-
-```bash
-dsh --profile web --dump-config
-```
-
-组合结果里应有 `dsh-dev-index` 这一行。新建创造模式会话即可自动收到文档指引。
-
-没有配置项：补丁只插入插件，不设置任何键。
+`@deepseek-ai/dsh-system-prompt` 和 `@deepseek-ai/dsh-agent-preset-registry` 的 peer 范围会对照正在运行的 `dsh` 版本检查。加载器不强制 `engines.dsh`。
 
 ## 许可证
 

package/client.js

@@ -85,18 +85,17 @@ const css = `
     const hostLanguage = locale => locale.getSnapshot().active.startsWith('zh') ? 'zh' : 'en';
 
     function DocumentationBrowser({ hostLocale }) {
-      const [language, setLanguage] = React.useState(() => hostLanguage(hostLocale));
+      const subscribe = React.useCallback(listener => hostLocale.subscribe(listener), [hostLocale]);
+      const snapshot = React.useCallback(() => hostLanguage(hostLocale), [hostLocale]);
+      const uiLanguage = React.useSyncExternalStore(subscribe, snapshot, snapshot);
+      const [selectedLanguage, setLanguage] = React.useState(uiLanguage);
       /* Once the reader picks a language, the host locale stops driving it. */
       const [pinned, setPinned] = React.useState(false);
       const [revision, setRevision] = React.useState(0);
       const [status, setStatus] = React.useState('loading');
+      const language = pinned ? selectedLanguage : uiLanguage;
       const url = language === 'zh' ? pages : `${pages}en/`;
-      const chinese = language === 'zh';
-
-      React.useEffect(() => {
-        if (pinned) return undefined;
-        return hostLocale.subscribe(() => setLanguage(hostLanguage(hostLocale)));
-      }, [hostLocale, pinned]);
+      const chinese = uiLanguage === 'zh';
 
       React.useEffect(() => {
         setStatus('loading');
@@ -107,7 +106,7 @@ const css = `
       function reload() { setRevision(value => value + 1); }
       function choose(nextLanguage) {
         setPinned(true);
-        if (nextLanguage !== language) setLanguage(nextLanguage);
+        setLanguage(nextLanguage);
       }
 
       const open = h('a', {

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "@klarkxy/dsh-dev-index",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "main": "lib/index.js",
   "description": "DSH Docs: read the official DSH documentation in the Plugins page; Creator mode searches and fetches it with native tools.",
   "engines": {

package/lib/index.js

@@ -1,4 +1,5 @@
 import z from "@deepseek-ai/schemastery";
+import { CREATOR_PRESET_ID } from "@klarkxy/dsh-plugin-kit/contracts";
 import { CREATOR_GUIDANCE } from "./creator-guidance.js";
 import { DocsClient } from "./docs.js";
 import { docsTools } from "./docs-tools.js";
@@ -30,7 +31,7 @@ export function apply(ctx, config) {
     ctx.effect(() => ctx.systemPrompt.section({
         name: "dsh-dev-index.creator-docs",
         order: 100,
-        text: ({ agent }) => agent !== undefined && ctx.agentPresets.composedPreset(agent.ctx) === "cordis"
+        text: ({ agent }) => agent !== undefined && ctx.agentPresets.composedPreset(agent.ctx) === CREATOR_PRESET_ID
             ? CREATOR_GUIDANCE
             : "",
     }), "dsh-dev-index.creator-docs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klarkxy/dsh-dev-index",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "DSH Docs: read the official DSH documentation in the Plugins page; Creator mode searches docs and checks plugin npm metadata with native tools.",
   "icon": "./icon.svg",
   "keywords": [
@@ -38,6 +38,7 @@
   },
   "files": [
     "icon.svg",
+    "scripts/prepare.mjs",
     "client.js",
     "lib/**/*.js",
     "lib/**/*.d.ts",
@@ -49,7 +50,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "prepare": "pnpm build",
+    "prepare": "node scripts/prepare.mjs",
     "prepack": "pnpm build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run"
@@ -78,6 +79,9 @@
     "@deepseek-ai/schemastery": ">=3.18.4",
     "@deepseek-ai/dsh-tools": ">=0.2.0-rc.2"
   },
+  "dependencies": {
+    "@klarkxy/dsh-plugin-kit": "0.3.1"
+  },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-agent-preset-registry": {
       "optional": true
@@ -103,6 +107,6 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dshRelease": {
-    "contentHash": "535677b4a757c53e81a174500ca1408591b3bc10c5bf6c5969cdcb0863ca8df8"
+    "contentHash": "fda890d3919ae02dff3dcb2f4d33894921a5e36885e019a50ed8705e48124202"
   }
 }

package/scripts/prepare.mjs

@@ -0,0 +1,39 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const packageRoot = new URL('../', import.meta.url);
+
+try {
+  require.resolve('@klarkxy/dsh-plugin-kit/contracts');
+} catch (error) {
+  // Only defer a clean monorepo install. Missing/broken published dependencies
+  // must fail Git installs, not silently produce a package without lib/.
+  const workspaceKit = new URL('../../dsh-plugin-kit/package.json', import.meta.url);
+  const workspaceFile = new URL('../../../pnpm-workspace.yaml', import.meta.url);
+  if (
+    error.code !== 'MODULE_NOT_FOUND' ||
+    !existsSync(workspaceFile) ||
+    !existsSync(workspaceKit) ||
+    realpathSync(require.resolve('@klarkxy/dsh-plugin-kit/package.json')) !== realpathSync(workspaceKit)
+  ) {
+    throw error;
+  }
+  console.log('prepare: deferred until workspace plugin-kit is built; prepack still requires a build');
+  process.exit(0);
+}
+
+// npm and pnpm supply their JS entry point to lifecycle scripts. Launch it
+// through Node so paths with spaces and Windows .cmd wrappers need no shell.
+if (!process.env.npm_execpath) {
+  throw new Error('prepare must run through a package manager (npm_execpath is missing)');
+}
+const result = spawnSync(process.execPath, [process.env.npm_execpath, 'run', 'build'], {
+  cwd: fileURLToPath(packageRoot),
+  stdio: 'inherit',
+});
+if (result.error) throw result.error;
+if (result.signal) throw new Error(`prepare build terminated by ${result.signal}`);
+process.exitCode = result.status ?? 1;