@klarkxy/dsh-dev-index 0.1.7 → 0.2.1

package/README.md

@@ -1,5 +1,8 @@
 # DSH Docs
 
+<!-- release-state-note -->
+The [repository registry](../../README.md#plugin-lifecycle) tracks Draft → Testing → Published, moving forward only. Fixes, testing and version updates keep published packages Published; each update still passes release checks. First publication explicitly selects Testing packages and records Published only after npm archive verification. See the [release guide](../../RELEASING.md).
+
 [简体中文](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.
@@ -23,7 +26,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-memory", 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.
 

package/README.zh-CN.md

@@ -1,5 +1,8 @@
 # DSH 文档
 
+<!-- release-state-note -->
+插件生命周期见[仓库状态清单](../../README.zh-CN.md#插件生命周期)：草稿 → 测试中 → 已发布，只向前推进。已发布插件的修复、测试和升版保持已发布；每次更新仍须通过发布检查。首次发布须明确选择测试中的包，并在 npm 归档验证成功后登记。详见[发布规则](../../RELEASING.zh-CN.md)。
+
 [简体中文](README.zh-CN.md) | [English](README.md)
 
 **运行环境**：Node `^22.19.0 || >=24.0.0`、DSH `>=0.1.7-rc.2`。文档阅读器是 DSH Web 客户端；四个只读工具和创造模式指引运行在宿主里。
@@ -23,7 +26,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-memory", 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`。
 

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,13 +1,16 @@
 {
   "id": "@klarkxy/dsh-dev-index",
-  "version": "0.1.7",
+  "version": "0.2.1",
   "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": {
-    "dsh": ">=0.1.7-rc.2"
+    "dsh": ">=0.2.0-rc.2"
   },
   "contributes": {
-    "tools": ["dsh_docs_search", "dsh_docs_fetch"],
+    "tools": [
+      "dsh_docs_search",
+      "dsh_docs_fetch"
+    ],
     "skills": []
   }
 }

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.1.7",
+  "version": "0.2.1",
   "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,14 +50,14 @@
   ],
   "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"
   },
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.1.7-rc.2"
+    "dsh": ">=0.2.0-rc.2"
   },
   "license": "SEE LICENSE IN LICENSE",
   "dsh": {
@@ -72,11 +73,14 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent-preset-registry": ">=0.1.7-rc.2",
-    "@deepseek-ai/dsh-system-prompt": ">=0.1.7-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-tools": ">=0.1.7-rc.2"
+    "@deepseek-ai/cordis": ">=4.0.4",
+    "@deepseek-ai/dsh-agent-preset-registry": ">=0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": ">=0.2.0-rc.2",
+    "@deepseek-ai/schemastery": ">=3.18.4",
+    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.2"
+  },
+  "dependencies": {
+    "@klarkxy/dsh-plugin-kit": "0.3.0"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-agent-preset-registry": {
@@ -92,18 +96,17 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/schemastery": "3.18.4",
-    "@deepseek-ai/dsh-client-ui-primitives": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-agent-preset-registry": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-scope": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-invariants": "0.1.7-rc.2"
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-agent-preset-registry": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.2"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "dshRelease": {
-    "contentHash": "0778ecf2ce276ea3ebc49c845fb1a980ad8c1d041faee741cff1f63045d2a9f8"
+    "contentHash": "3a0b6e7fd1e2c97ad944581ca989658034c02bd300be660e5445e976d54f6e0d"
   }
 }

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;