@trim21/personal-pi-extensions 0.1.697 → 0.1.699

package/README.md

@@ -330,7 +330,7 @@ bwrap 已集成进 bash 工具实现（opencode 风格 `bash` 位于 `src/openco
 
 命令失败（`gh` 未登录 / 不在 PATH）时该服务器启动失败并报错。
 
-启动时才能算出的值（例如项目把 `typescript` alias 成 `@typescript/typescript6` 时，要去 pnpm store 里找真实的 `tsserver.js`）用 `initializationOptionsCommand`，避免把绝对路径写死在配置里：
+启动时才能算出的值（例如项目把 `typescript` alias 成 `@typescript/typescript6` 时，要去 pnpm store 或 `@typescript/*` 里找真实的 `tsserver.js`）用 `initializationOptionsCommand`，避免把绝对路径写死在配置里。这类现算脚本随包提供了一个：`bin/typescript-options.mjs`（复制到 `~/.pi/agent/lsp/` 后由下面这行调用，标准 typescript 依赖的项目输出空对象、不做覆盖）：
 
 ```jsonc
 {
@@ -340,7 +340,7 @@ bwrap 已集成进 bash 工具实现（opencode 风格 `bash` 位于 `src/openco
       "args": ["--stdio"],
       "initializationOptions": { "tsserver": { "logVerbosity": "verbose" } },
       // 脚本 stdout 的 JSON 对象与上面的静态值深合并（命令优先）
-      "initializationOptionsCommand": ["node", "{root}/.pi/lsp/ts-options.mjs"],
+      "initializationOptionsCommand": ["node", "/home/<user>/.pi/agent/lsp/typescript-options.mjs"],
     },
   },
 }

package/bin/typescript-options.mjs

@@ -0,0 +1,146 @@
+// 给 typescript-language-server 计算 initializationOptions.tsserver.path。
+//
+// 用法：把这个文件复制到 ~/.pi/agent/lsp/，在 lsp.json 的 typescript server 上配
+//   "initializationOptionsCommand": ["node", "/home/<user>/.pi/agent/lsp/typescript-options.mjs"]
+// 引擎在 spawn 服务器前执行它（cwd = 服务器 root），stdout 的 JSON 对象与静态
+// initializationOptions 深合并，且用户显式给出的值优先。
+//
+// 只在 workspace 里的 typescript 不可用时才需要干预：
+//   - 项目把 typescript alias 成 @typescript/typescript6 这类 shim 包时，
+//     node_modules/typescript/lib 下只有转发 stub、没有 tsserver.js，
+//     typescript-language-server 的 workspace 探测会失败并直接报错退出；
+//     真实 typescript 在哪取决于包管理器与链接方式：
+//       npm 提升／pnpm hoisted：node_modules/@typescript/<包>/lib/tsserver.js
+//       npm 嵌套：node_modules/typescript/node_modules/@typescript/<包>/lib/tsserver.js
+//       pnpm store：node_modules/.pnpm/<typescript@版本 或 @typescript+包@版本>/
+//                   node_modules/{typescript,@typescript/<包>}/lib/tsserver.js
+//   - 项目里是标准 typescript 依赖时 workspace 探测本来就能命中，脚本输出空对象，
+//     不做任何覆盖，保持服务器自己的解析结果（版本随项目走）。
+//
+// 沿 node_modules 链向上找（与语言服务器的 workspace 探测一致），每级先看标准位置，
+// 再看上面几种落法，取带 tsserver.js 的最高版本（typescript@7 是 native 包，
+// 没有 tsserver.js，会被过滤掉）。
+//
+// 独立可执行脚本：只用 node 内置模块、不依赖扩展运行时，因此用同步 fs API。
+
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import process from "node:process";
+
+/** cwd 到根的所有 node_modules 目录（含自身）。 */
+function nodeModulesChain(dir) {
+  const chain = [];
+  let current = dir;
+  for (;;) {
+    chain.push(join(current, "node_modules"));
+    const parent = dirname(current);
+    if (parent === current) {
+      return chain;
+    }
+    current = parent;
+  }
+}
+
+/** 版本段转数字；非数字段（如 `0-beta`）当 0。 */
+function versionPart(segment = "0") {
+  const parsed = Number(segment);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+/** 版本号降序比较；只认前导数字段，足够比对 `typescript@<版本>` 这类目录名。 */
+function compareVersions(a, b) {
+  const left = a.split(".");
+  const right = b.split(".");
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const na = versionPart(left[i]);
+    const nb = versionPart(right[i]);
+    if (na !== nb) {
+      return na - nb;
+    }
+  }
+  return 0;
+}
+
+/** 目录下的子目录名；不存在或读不了给空数组。 */
+function listDirs(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+      .map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}
+
+/** package.json 的 version；读不到或不是字符串时给 "0"（只用于排序，不影响可用性）。 */
+function packageVersion(dir) {
+  try {
+    const version = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+    return typeof version === "string" ? version : "0";
+  } catch {
+    return "0";
+  }
+}
+
+/** 包目录（typescript 或 @typescript/<包>）带 tsserver.js 时的候选。 */
+function candidate(packageDir) {
+  const path = join(packageDir, "lib/tsserver.js");
+  return existsSync(path) ? { version: packageVersion(packageDir), path } : undefined;
+}
+
+/** dir/@typescript/<包> 下的候选（顶层与嵌套层共用）。 */
+function scopedCandidates(dir) {
+  return listDirs(join(dir, "@typescript")).map((name) =>
+    candidate(join(dir, "@typescript", name)),
+  );
+}
+
+/** 该级 node_modules 下所有带 tsserver.js 的候选：npm（提升/嵌套）与 pnpm（store/hoisted）都覆盖。 */
+function levelCandidates(nodeModules) {
+  const candidates = [
+    candidate(join(nodeModules, "typescript")),
+    ...scopedCandidates(nodeModules),
+    // npm 把 shim 自己的依赖嵌在它下面（顶层放不下时）
+    candidate(join(nodeModules, "typescript", "node_modules", "typescript")),
+    ...scopedCandidates(join(nodeModules, "typescript", "node_modules")),
+  ];
+  // pnpm store：虚拟 store 里真实 typescript 与 alias 出来的 shim 兄弟包
+  for (const name of listDirs(join(nodeModules, ".pnpm"))) {
+    if (!name.startsWith("typescript@") && !name.startsWith("@typescript+")) {
+      continue;
+    }
+    const store = join(nodeModules, ".pnpm", name, "node_modules");
+    candidates.push(candidate(join(store, "typescript")), ...scopedCandidates(store));
+  }
+  return candidates.filter((value) => value !== undefined);
+}
+
+/** 该级 node_modules 下带 tsserver.js 的最高版本 tsserver 路径；没有则 undefined。 */
+function levelTsserver(nodeModules) {
+  return levelCandidates(nodeModules).toSorted((a, b) => compareVersions(b.version, a.version))[0]
+    ?.path;
+}
+
+/** 解析该 workspace 该用的 tsserver 路径；标准依赖可由服务器自己解析时不返回路径。 */
+function resolveTsserver(cwd) {
+  for (const nodeModules of nodeModulesChain(cwd)) {
+    // 标准依赖：语言服务器自己就能解析到，别覆盖（否则会把项目锁到别的 TS 版本）
+    try {
+      const real = realpathSync(join(nodeModules, "typescript"));
+      if (existsSync(join(real, "lib/tsserver.js"))) {
+        return;
+      }
+    } catch {
+      // 没有这个包，继续
+    }
+    const found = levelTsserver(nodeModules);
+    if (found) {
+      return found;
+    }
+  }
+}
+
+const tsserverPath = resolveTsserver(process.cwd());
+process.stdout.write(
+  `${JSON.stringify(tsserverPath ? { tsserver: { path: tsserverPath } } : {})}\n`,
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.697",
+  "version": "0.1.699",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -13,6 +13,7 @@
   },
   "files": [
     "src",
+    "bin/typescript-options.mjs",
     "README.md"
   ],
   "publishConfig": {

package/src/codemode/tool.ts

@@ -107,9 +107,12 @@ function buildDescription(tools: readonly CallableTool[]): string {
     "- Call tools with `await call(name, args)`. Arguments and results make a JSON round trip,",
     "  and a failing tool rejects with a `CallFailedError` you can catch.",
     "- Only what the script passes to `text(value)` / `console.log(...)` and its `return` value enter",
-    "  this conversation; nested calls and their results stay out of it.",
-    "- Pass only necessary content to `text(value)`: print the content the next step needs, not whole",
-    "  tool results or data you will not use.",
+    "  this conversation; nested calls and their results stay out of it. Print what the next step needs,",
+    "  nothing else.",
+    "- Every `call` overload below declares that tool's return shape: read it, then project just the",
+    "  fields you need into `text(value)` / `return` — e.g. `text(result.items.map((item) => item.title))`.",
+    "- Do not stringify whole results (`JSON.stringify(result)`) or print every field the tool happened to",
+    "  return: urls, ids and metadata you will not use cost context and buy nothing.",
     "- `store.set(key, value)`, `store.get(key)` and `store.list()` are a small key/value store that",
     "  persists across codemode calls in this session; `store.set(key, undefined)` removes a key.",
     "- The sandbox has no file system, network, timers or Node APIs: calling tools is its only",

package/src/skills/lsp-config/SKILL.md

@@ -163,9 +163,30 @@ typescript-language-server **不内置 TypeScript**（零依赖）。启动时
 
 `tsserver.path` 必须指向 **`typescript/lib/tsserver.js` 或 `typescript/lib/` 目录的绝对路径**（或 PATH 可执行名）；因为初始化字符串不支持 `{root}` 模板，无法用相对 workspace 的表达式。
 
-**alias 依赖坑**：当项目把 typescript 写成 `npm:@typescript/typescript6`（alias stub）时，`node_modules/typescript/lib/` 下只有转发 stub（`typescript.js`/`tsserverlibrary.js`/`tsc.js`），**没有 `tsserver.js`** → workspace 探测失效；实体 tsserver 在 pnpm 虚拟 store：`node_modules/.pnpm/typescript@<真实版本>/node_modules/typescript/lib/tsserver.js`（目录名无 peer 后缀、相对稳定；**升级 typescript 版本后要同步更新路径**）。依赖为标准 `typescript` 包时 `node_modules/typescript` 直接是完整包，workspace 探测即命中、无需配 path。
+**alias 依赖坑**：当项目把 typescript 写成 `npm:@typescript/typescript6`（alias stub）时，`node_modules/typescript/lib/` 下只有转发 stub（`typescript.js`/`tsserverlibrary.js`/`tsc.js`），**没有 `tsserver.js`** → workspace 探测失效。真实 tsserver 在哪取决于包管理器与链接方式：
 
-这种项目里把路径写死会随 typescript 升级失效，用 `initializationOptionsCommand` 让脚本现算更稳。因为 servers 按 id 整条覆盖，本地 `.pi/lsp.json` 要写完整条目：
+| 布局                    | 真实 tsserver 位置                                                                                                                                    |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 标准 typescript 依赖    | `<root>/node_modules/typescript/lib/tsserver.js`（workspace 探测即命中，不需要任何配置）                                                              |
+| npm 提升 / pnpm hoisted | `node_modules/@typescript/<包>/lib/tsserver.js`（如 `@typescript/old`，是 shim 自己的依赖被提到顶层）                                                 |
+| npm 嵌套                | `node_modules/typescript/node_modules/@typescript/<包>/lib/tsserver.js`（顶层放不下时 shim 的依赖嵌在它下面）                                         |
+| pnpm store              | `node_modules/.pnpm/{typescript@<版本>,@typescript+<包>@<版本>}/node_modules/{typescript,@typescript/<包>}/lib/tsserver.js`（含带 peer 后缀的目录名） |
+
+`@typescript/native`（typescript@7）是 native 包、**没有 `tsserver.js`**，不能当候选；TS6 项目要的是 `@typescript/old` 里的那份。
+
+不用自己写脚本：扩展随包提供 `bin/typescript-options.mjs`（纯 node 内置模块、无依赖、无需构建），它按上表的布局现算路径，标准依赖命中时输出 `{}`（不覆盖，版本随项目走），找不到也输出 `{}`。把它复制到本机固定位置，然后在 server 上配一行：
+
+```bash
+cp <package>/bin/typescript-options.mjs ~/.pi/agent/lsp/typescript-options.mjs
+```
+
+```json
+"initializationOptionsCommand": ["node", "/home/<user>/.pi/agent/lsp/typescript-options.mjs"]
+```
+
+命令的 argv 只支持 `{root}` / `{cwd}` 模板与 `${VAR}` 插值，没有指向包内路径的模板，所以这里写绝对路径；脚本升级后重新复制一次。
+
+因为 servers 按 id 整条覆盖，本地 `.pi/lsp.json` 里写 `typescript` 要写完整条目（否则全局那条被整体替换）：
 
 ```json
 {
@@ -180,54 +201,12 @@ typescript-language-server **不内置 TypeScript**（零依赖）。启动时
         ".js": "javascript",
         ".jsx": "javascriptreact"
       },
-      "initializationOptionsCommand": ["node", "{root}/.pi/lsp/ts-options.mjs"]
+      "initializationOptionsCommand": ["node", "/home/<user>/.pi/agent/lsp/typescript-options.mjs"]
     }
   }
 }
 ```
 
-```js
-// .pi/lsp/ts-options.mjs：项目能解析到 typescript/lib/tsserver.js（标准依赖 / hoisted）时输出 {}，
-// 让服务器按 workspace 解析、版本随项目走；只有 alias shim（解析不到）才去 pnpm store 里找真实 tsserver。
-import { existsSync, readdirSync } from "node:fs";
-import { createRequire } from "node:module";
-import { join } from "node:path";
-
-const requireFromProject = createRequire(join(process.cwd(), "package.json"));
-
-// workspace 里可用的 tsserver：解析得到就不干预（hoisted 的依赖也能解析到）
-function workspaceHasTsserver() {
-  try {
-    requireFromProject.resolve("typescript/lib/tsserver.js");
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// store 里带 tsserver.js 的最高版本：typescript@7 是 native 包、没有 tsserver.js，会被筛掉
-function storeTsserver() {
-  const store = join(process.cwd(), "node_modules/.pnpm");
-  let entries;
-  try {
-    entries = readdirSync(store);
-  } catch {
-    return undefined;
-  }
-  return entries
-    .map((name) => /^typescript@(\d[^/]*)$/.exec(name)?.[1])
-    .filter(Boolean)
-    .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }))
-    .map((version) =>
-      join(store, `typescript@${version}`, "node_modules/typescript/lib/tsserver.js"),
-    )
-    .find((path) => existsSync(path));
-}
-
-const path = workspaceHasTsserver() ? undefined : storeTsserver();
-console.log(JSON.stringify(path ? { tsserver: { path } } : {}));
-```
-
 只在某台机器上临时用、路径不常变时，也可以直接写静态值（同样要整条覆盖）：
 
 ```json
@@ -249,10 +228,10 @@ console.log(JSON.stringify(path ? { tsserver: { path } } : {}));
 
 ## 常见排查
 
-| 现象                                                                          | 原因与修法                                                                                                                                                                              |
-| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| notify `failed to start …: binary not found`                                  | `bin` 不在 PATH（测试场景二进制缺失时整组跳过）                                                                                                                                         |
-| `… provides no tsserver.js. No other valid TypeScript installation was found` | workspace 的 `node_modules/typescript` 是 alias stub：用 `initializationOptionsCommand` 算 `.pnpm` 里的实体路径、写静态 `initializationOptions.tsserver.path`，或换标准 typescript 依赖 |
-| notify `failed to start …: initializationOptions command …`                   | 脚本非零退出 / 空输出 / stdout 不是 JSON 对象（报错里带具体命令、退出码与 stderr）                                                                                                      |
-| 诊断一直为空且无任何报错                                                      | 服务器没匹配到文件（`include`/扩展名）、在 broken 冷却中、或文件在调用 cwd 之外（LSP 只在工作目录内启用）                                                                               |
-| 读取配置直接抛错                                                              | typebox 严格校验拒绝：字段类型不符 / 非法时长格式（未知字段只是 warning，不拒绝）                                                                                                       |
+| 现象                                                                          | 原因与修法                                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| notify `failed to start …: binary not found`                                  | `bin` 不在 PATH（测试场景二进制缺失时整组跳过）                                                                                                                                                                             |
+| `… provides no tsserver.js. No other valid TypeScript installation was found` | workspace 的 `node_modules/typescript` 是 alias stub：复制随包脚本 `bin/typescript-options.mjs` 到 `~/.pi/agent/lsp/` 并在该 server 上配 `initializationOptionsCommand`，或直接写静态 `initializationOptions.tsserver.path` |
+| notify `failed to start …: initializationOptions command …`                   | 脚本非零退出 / 空输出 / stdout 不是 JSON 对象（报错里带具体命令、退出码与 stderr）                                                                                                                                          |
+| 诊断一直为空且无任何报错                                                      | 服务器没匹配到文件（`include`/扩展名）、在 broken 冷却中、或文件在调用 cwd 之外（LSP 只在工作目录内启用）                                                                                                                   |
+| 读取配置直接抛错                                                              | typebox 严格校验拒绝：字段类型不符 / 非法时长格式（未知字段只是 warning，不拒绝）                                                                                                                                           |